Skip to content

docs(adr): use a generic example command in ADRs 027 and 029 #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jesse23 merged 1 commit into from
Oct 16, 2026
Merged

docs(adr): use a generic example command in ADRs 027 and 029 #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/adrs/027.server.execute-resilience.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,18 +80,18 @@ Option B is chosen because it adds machine-readable error context to the one lin

**Scenario 1 — Command not found (ENOENT)**

1. Agent POSTs `{ cmd: "tc", args: ["search", "*"] }` to `/s/main/execute`.
2. `tc` is not on `PATH`.
1. Agent POSTs `{ cmd: "mytool", args: ["search", "*"] }` to `/s/main/execute`.
2. `mytool` is not on `PATH`.
3. Server spawns the process; Node.js emits `error` on the child with code `ENOENT`.
4. Handler writes `{ stream: "stderr", data: "spawn ENOENT: …\n" }` to the response.
5. Handler writes `{ exit: 1, error: "spawn ENOENT: …", code: "ENOENT" }` and ends.
6. webtty continues serving other requests. Server does not exit.
7. Agent reads `exit: 1, code: "ENOENT"` and surfaces: *"tc is not installed — run: bunx @awc/cli@next …"*
7. Agent reads `exit: 1, code: "ENOENT"` and surfaces: *"mytool is not installed — install it and retry"*

**Scenario 2 — Command exits non-zero**

1. Agent POSTs `{ cmd: "tc", args: ["search", "bad-query"] }`.
2. `tc` runs, returns exit code 2.
1. Agent POSTs `{ cmd: "mytool", args: ["search", "bad-query"] }`.
2. `mytool` runs, returns exit code 2.
3. Handler writes stderr chunks as they arrive, then `{ exit: 2 }`.
4. No `error` or `code` fields on the exit line — this is a command-level failure, not a spawn failure.
5. Agent reads `exit: 2`, inspects stderr, and decides whether to retry or surface the error.
Expand Down
2 changes: 1 addition & 1 deletion docs/adrs/029.cli.exec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ webtty run main cat package.json | jq '.version'
| Session not found | `webtty: session not found: <id>` |
| PTY not running | `webtty: PTY not running for session: <id>` |
| WebSocket connection failed (warm-up) | `webtty: failed to start PTY: <reason>` |
| Spawn failure (ENOENT) | `webtty: spawn tc: No such file or directory` |
| Spawn failure (ENOENT) | `webtty: spawn mytool: No such file or directory` |
| Other HTTP error | `webtty: run failed (<status>)` |

---
Expand Down
Loading