agent-director 0.10.0 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -37
- package/dist/errors.d.ts +19 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +61 -29
- package/dist/internal/argv.d.ts +9 -10
- package/dist/internal/errorMap.d.ts +6 -3
- package/dist/internal/subprocessClient.d.ts +7 -6
- package/dist/internal/verbs.d.ts +3 -3
- package/dist/types.d.ts +193 -46
- package/package.json +1 -1
- package/dist/internal/tilde.d.ts +0 -16
package/README.md
CHANGED
|
@@ -29,8 +29,8 @@ curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/ski
|
|
|
29
29
|
`Client.create()` discovers the installed binary at construction time
|
|
30
30
|
(either at `~/.agent-director/bin/agent-director` or anywhere on
|
|
31
31
|
`$PATH`) and rejects if it cannot find one. Other supported install
|
|
32
|
-
mechanisms — `install.sh --binary <path>` with
|
|
33
|
-
|
|
32
|
+
mechanisms — `install.sh --binary <path> --admin-binary <path>` with
|
|
33
|
+
locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
|
|
34
34
|
[repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
|
|
35
35
|
|
|
36
36
|
## Supported platforms
|
|
@@ -65,7 +65,7 @@ try {
|
|
|
65
65
|
}
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults.
|
|
68
|
+
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
|
|
69
69
|
|
|
70
70
|
`ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
|
|
71
71
|
|
|
@@ -73,6 +73,14 @@ All constructor options are optional. Omitted fields fall back to the CLI binary
|
|
|
73
73
|
- `home` → `--home`
|
|
74
74
|
- `tmuxCommand` → `--tmux-command`
|
|
75
75
|
|
|
76
|
+
The CLI, not the client, expands a `~` in them, against `HOME` and nothing
|
|
77
|
+
else (never the passwd entry's home). It applies `home` first, so with `home`
|
|
78
|
+
set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
|
|
79
|
+
`HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
|
|
80
|
+
`ErrInvalidFlags`, and with no `home` either, every call that opens the store
|
|
81
|
+
is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
|
|
82
|
+
expand its config path `~/.agent-director/config.toml`.
|
|
83
|
+
|
|
76
84
|
Set them only when the consumer needs to override the CLI's default for that field.
|
|
77
85
|
|
|
78
86
|
## Verb examples
|
|
@@ -120,7 +128,8 @@ for (const spawn of result.spawns) {
|
|
|
120
128
|
|
|
121
129
|
### sendKeys
|
|
122
130
|
|
|
123
|
-
Send text to
|
|
131
|
+
Send text to the agent's own pane, then one Enter to submit it. An empty
|
|
132
|
+
`text` sends the Enter only, submitting what is already typed.
|
|
124
133
|
|
|
125
134
|
```sh
|
|
126
135
|
agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
|
|
@@ -130,14 +139,16 @@ agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
|
|
|
130
139
|
await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
|
|
131
140
|
```
|
|
132
141
|
|
|
133
|
-
Pass `allow_pending: true` to also
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
142
|
+
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
143
|
+
reuse or resume) whose agent has not reported in yet, for example to dismiss a
|
|
144
|
+
prompt the agent shows before it reports in. Keys are delivered only to a
|
|
145
|
+
session started by the row's current launch. `ended` and `missing` rows are
|
|
146
|
+
still rejected. A `pending` row whose launch start or launch token is not recorded, or where
|
|
147
|
+
only a session an earlier launch left behind is found, gets
|
|
148
|
+
`ErrSpawnNotInteractive` and nothing is sent.
|
|
138
149
|
|
|
139
|
-
Send an empty string with `allow_pending: true` to press Enter and dismiss
|
|
140
|
-
|
|
150
|
+
Send an empty string with `allow_pending: true` to press Enter and dismiss such
|
|
151
|
+
a prompt:
|
|
141
152
|
|
|
142
153
|
```ts
|
|
143
154
|
await client.sendKeys({
|
|
@@ -149,7 +160,7 @@ await client.sendKeys({
|
|
|
149
160
|
|
|
150
161
|
### readPane
|
|
151
162
|
|
|
152
|
-
Read the last N lines of
|
|
163
|
+
Read the last N lines of the agent's own pane (default 25).
|
|
153
164
|
|
|
154
165
|
```sh
|
|
155
166
|
agent-director read-pane --claude-instance-id <id> --n-lines 50
|
|
@@ -161,23 +172,37 @@ console.log(result.pane);
|
|
|
161
172
|
```
|
|
162
173
|
|
|
163
174
|
`readPane` has no state guard — it works on `pending`, `ended`, and `missing`
|
|
164
|
-
|
|
175
|
+
rows as well as live ones. The `allow_pending` flag is accepted for symmetry
|
|
165
176
|
with `sendKeys` but has no behavioral effect.
|
|
166
177
|
|
|
167
178
|
---
|
|
168
179
|
|
|
169
180
|
### kill
|
|
170
181
|
|
|
171
|
-
|
|
182
|
+
End the agent of a live Spawn's current launch (`pending` included). `kill`
|
|
183
|
+
resolves only once the agent process is gone, and returns `{ kill_sent }`:
|
|
184
|
+
`true` when a kill was sent to the agent's pane or its session, `false` when
|
|
185
|
+
none was. On a finished Spawn (`ended` or `missing`) `kill` is a no-op that
|
|
186
|
+
resolves with `kill_sent: false`; that is not verification that the agent
|
|
187
|
+
exited. `kill` never changes the row's state: `find-missing` marks the row once
|
|
188
|
+
its agent process is gone.
|
|
172
189
|
|
|
173
190
|
```sh
|
|
174
191
|
agent-director kill --claude-instance-id <id>
|
|
175
192
|
```
|
|
176
193
|
|
|
177
194
|
```ts
|
|
178
|
-
await client.kill({ claude_instance_id: "<id>" });
|
|
195
|
+
const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
|
|
196
|
+
console.log(kill_sent);
|
|
179
197
|
```
|
|
180
198
|
|
|
199
|
+
Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
|
|
200
|
+
retry later), `ErrTmuxSessionConflict` (CONFLICT: a human must look),
|
|
201
|
+
`ErrTmuxNotAvailable` (ENVIRONMENT: an operator must fix the environment) and
|
|
202
|
+
`ErrSpawnNotFound`. None of these means the agent is dead. The caller must run
|
|
203
|
+
as the same user and in the same tmux environment as the agents. See the "tmux
|
|
204
|
+
transport" table under [Errors](#errors).
|
|
205
|
+
|
|
181
206
|
### makeTemplate
|
|
182
207
|
|
|
183
208
|
Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
@@ -276,7 +301,7 @@ The public typed-error surface falls into four groups. Every class named below i
|
|
|
276
301
|
|
|
277
302
|
### Realistic catch-site shortlist
|
|
278
303
|
|
|
279
|
-
Most services only need to route on the "agent-director is sick" set. Alert on these
|
|
304
|
+
Most services only need to route on the "agent-director is sick" set. Alert on these eight:
|
|
280
305
|
|
|
281
306
|
- `ErrSystemInstallNotFound`
|
|
282
307
|
- `ErrSystemInstallTooOld`
|
|
@@ -284,6 +309,10 @@ Most services only need to route on the "agent-director is sick" set. Alert on t
|
|
|
284
309
|
- `ErrCallerCwdUnreachable`
|
|
285
310
|
- `ErrSystemInstallDisappeared`
|
|
286
311
|
- `ErrCallTimeout`
|
|
312
|
+
- `ErrStoreOpen`
|
|
313
|
+
- `ErrConfigMalformed`
|
|
314
|
+
|
|
315
|
+
Also alert on an `ErrUnknownErrorName` whose `unknownName` is `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: the store needs an operator (see the per-call infrastructure table below). Let everything else propagate.
|
|
287
316
|
|
|
288
317
|
Everything else is either **programmer error** (bad arguments — fix the call site, do not retry) or a **normal operational signal** (an expected verb outcome you branch on, like "no such spawn" or "already decided"). `ErrConsumerSignal` sits in between: it is a runtime infrastructure failure, but a routine one during shutdown, so treat it as an operational signal rather than a page.
|
|
289
318
|
|
|
@@ -316,11 +345,11 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
|
|
|
316
345
|
|---|---|---|
|
|
317
346
|
| `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational — include in your "AD is sick" alert set. |
|
|
318
347
|
| `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
|
|
319
|
-
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client
|
|
348
|
+
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for: either the binary is newer than the client, or the name is one the binary emits but the shared catalog leaves out (for example `ErrInternal`, `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`). Carries `unknownName` (the real `err_name`) and `envelope`. | Read `unknownName`. `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: operational — the store needs an operator and no verb ran, so alert, as for `ErrStoreOpen`. A name the binary has and this client lacks because the binary is newer: version error — upgrade the client. |
|
|
320
349
|
|
|
321
350
|
### 4. Catalog-derived (CLI-side validation)
|
|
322
351
|
|
|
323
|
-
These
|
|
352
|
+
These 44 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input, a verb's own state preconditions, or a config or store the CLI cannot open — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
|
|
324
353
|
|
|
325
354
|
**cwd validation** (bad `cwd` argument to `spawn` — programmer error):
|
|
326
355
|
|
|
@@ -338,14 +367,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
338
367
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
339
368
|
| `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
|
|
340
369
|
| `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
|
|
341
|
-
| `ErrInstanceIdCollision` |
|
|
370
|
+
| `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `claude_instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
|
|
342
371
|
|
|
343
|
-
**tmux session naming** (bad
|
|
372
|
+
**tmux session naming** (bad `tmux_session_name` — programmer error):
|
|
344
373
|
|
|
345
374
|
| Error | When it fires |
|
|
346
375
|
|---|---|
|
|
347
|
-
| `ErrTmuxSessionNameEmpty` |
|
|
348
|
-
| `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, an ASCII control character, or is invalid UTF-8. |
|
|
376
|
+
| `ErrTmuxSessionNameEmpty` | `tmux_session_name` was explicitly supplied but empty. |
|
|
377
|
+
| `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character, or is invalid UTF-8. |
|
|
349
378
|
| `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
|
|
350
379
|
|
|
351
380
|
**spawn state / lookup** (verb preconditions — mostly normal operational signals):
|
|
@@ -353,29 +382,35 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
353
382
|
| Error | When it fires |
|
|
354
383
|
|---|---|
|
|
355
384
|
| `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
|
|
356
|
-
| `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected
|
|
385
|
+
| `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
|
|
357
386
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
358
|
-
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry
|
|
359
|
-
| `ErrSpawnNotResumable` |
|
|
360
|
-
| `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — `
|
|
361
|
-
| `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — `
|
|
387
|
+
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
|
|
388
|
+
| `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. If that launch was abandoned or failed, `find-missing` marks the row `missing` once the pending grace period has passed; then a row with a `claude_session_id` (typically a resume's launch) can be resumed, and one without (typically a spawn's or reuse's launch), if `get` still shows no `claude_session_id`, is spawned again with `reuse_finished: true`, as the error says. An agent that reports in late records a `claude_session_id`, and its row, once `missing`, can be resumed instead. Also returned when the row changed after `resume` examined it; nothing is written. |
|
|
389
|
+
| `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
|
|
390
|
+
| `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
|
|
362
391
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
363
|
-
| `ErrProbeUnsupported` |
|
|
392
|
+
| `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
|
|
364
393
|
|
|
365
|
-
**tmux transport** (infrastructure failures at the tmux layer — runtime):
|
|
394
|
+
**tmux transport** (infrastructure failures at the tmux layer — runtime). Each name has a class: GONE (the row's session is not there), UNAVAILABLE (transient; retry later), CONFLICT (permanent until a human looks), ENVIRONMENT (an environment problem for an operator to fix) or LAUNCH FAILURE (the launch failed).
|
|
366
395
|
|
|
367
|
-
| Error | When it fires |
|
|
368
|
-
|
|
369
|
-
| `ErrTmuxNotAvailable` | The `tmux` binary is not on PATH or refuses to execute. |
|
|
370
|
-
| `ErrTmuxSessionCreate` | `tmux
|
|
371
|
-
| `
|
|
372
|
-
| `
|
|
396
|
+
| Error | Class | When it fires |
|
|
397
|
+
|---|---|---|
|
|
398
|
+
| `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
|
|
399
|
+
| `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled; the new row stays `pending`. After tmux answers "duplicate session", `spawn` returns it only when the session holding the requested name was gone by the re-lookup; the new row is then ended (the error says if it was not), and the error names the instance id (a minted one included) and the retry: spawn that `claude_instance_id` again with `reuse_finished: true` once the name is free (if the row was not ended, once `get` shows it `ended` or `missing`), since a plain `spawn` of the id collides with its row. From `resume`, the session could not be created or labelled, or after "duplicate session" no session held the name when it was looked up again; the row is restored to `ended` or `missing` (the error says if it was not). A name found held is never this error. |
|
|
400
|
+
| `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored; if it was not, the error says so and names the next step in place of "retry later": do not retry until `get` shows the row `ended` or `missing`, or, for a removed row, later a `spawn` of the id starts afresh. From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
|
|
401
|
+
| `ErrTmuxSessionConflict` | CONFLICT (permanent until a human looks) | A tmux session conflict that needs a human. From `spawn` with an explicit `claude_instance_id` that has no row: a session of this store still labelled with that id is left over from an earlier life, or labels conflict; nothing is written. From a plain `spawn` whose requested tmux session name is already held (tmux answered "duplicate session"): the holder is a session left over from an earlier life of this id, another row's session, a session of another agent-director store, or one with no valid instance id, or labels conflict; the new row is ended (the error says if it was not) and the error names the blocking session. Another row's or another store's session is another agent and is never ended; the holding session is never read or typed into. From `resume` of a finished row, before anything is written and with no session touched: a session holds the row's session name (another row's session, a session of another agent-director store, or one with no valid instance id), a session is left over from an earlier life of this id, the row's own old session (or its agent process still running with no session) is past the stopping window and the starting-session bound, or labels conflict; the error names the blocking session. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). None of these means the agent is dead. From `kill` on a live row: the session found is not this launch's session (it carries the label of an earlier launch with this row's own id), or labels conflict; no kill was sent. From `readPane`, `sendKeys` and `pause`: the agent's pane was not found, a session an earlier launch left behind is there (for `readPane`, more than one; for `sendKeys`, on a live row), or labels conflict; nothing was read or sent. See "Operator actions" in the agent-director README. |
|
|
402
|
+
| `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry `kill` later; never `delete` the row. |
|
|
403
|
+
| `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
|
|
404
|
+
| `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
|
|
405
|
+
|
|
406
|
+
Only a GONE error means the row's session is not there (for `kill`, GONE is success); no other tmux error ever means the agent is dead.
|
|
373
407
|
|
|
374
408
|
**relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
|
|
375
409
|
|
|
376
410
|
| Error | When it fires |
|
|
377
411
|
|---|---|
|
|
378
|
-
| `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. |
|
|
412
|
+
| `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. Time-bounded: refused until 1 s after every one of the spawn's permission requests' relay windows has elapsed; from then this guard lets `send-keys` through. |
|
|
413
|
+
| `ErrRelayFallenBack` | `decide` was called on an open request whose relay window has run out (from 1 s before it ends); no verdict was recorded. Answer at the pane with `send-keys` once its relay guard releases, 1 s after every request's window (for this request, at most 2 s after the refusal); until then `send-keys` may throw `ErrSendKeysWhileRelayed`. |
|
|
379
414
|
| `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
|
|
380
415
|
| `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
|
|
381
416
|
| `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
|
|
@@ -397,7 +432,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
397
432
|
|
|
398
433
|
| Error | When it fires |
|
|
399
434
|
|---|---|
|
|
400
|
-
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation
|
|
435
|
+
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation, or `spawn` was given an explicit `claude_instance_id` containing an ASCII control character (0x00–0x1f or 0x7f). |
|
|
436
|
+
|
|
437
|
+
**CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational; both are in the "AD is sick" alert set):
|
|
438
|
+
|
|
439
|
+
| Error | When it fires |
|
|
440
|
+
|---|---|
|
|
441
|
+
| `ErrConfigMalformed` | The CLI refused its config file, `~/.agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. Do not retry or act on any agent; alert an operator once, and never read it as an agent being dead. |
|
|
442
|
+
| `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. It says nothing about any agent. |
|
|
401
443
|
|
|
402
444
|
## Architecture
|
|
403
445
|
|
package/dist/errors.d.ts
CHANGED
|
@@ -69,8 +69,10 @@ export declare class ErrCallTimeout extends AgentDirectorError {
|
|
|
69
69
|
/**
|
|
70
70
|
* ErrUnknownErrorName — thrown when a subprocess JSON envelope contains an
|
|
71
71
|
* `err_name` field that is not present in the static catalog-derived error map.
|
|
72
|
-
*
|
|
73
|
-
*
|
|
72
|
+
* Either the binary is newer than this client, or the name is one the binary
|
|
73
|
+
* emits but the shared catalog leaves out (for example ErrInternal or
|
|
74
|
+
* ErrSchemaMismatch; cross-ref: b.cm7). Read `unknownName` for the
|
|
75
|
+
* real err_name.
|
|
74
76
|
*
|
|
75
77
|
* Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
|
|
76
78
|
* - `unknownName` — the unrecognised err_name string from the envelope.
|
|
@@ -237,6 +239,15 @@ export declare class ErrTmuxSendKeys extends AgentDirectorError {
|
|
|
237
239
|
/** Mirrors ErrTmuxCaptureFailed (package: tmux) */
|
|
238
240
|
export declare class ErrTmuxCaptureFailed extends AgentDirectorError {
|
|
239
241
|
}
|
|
242
|
+
/** Mirrors ErrTmuxUnresponsive (package: tmux) */
|
|
243
|
+
export declare class ErrTmuxUnresponsive extends AgentDirectorError {
|
|
244
|
+
}
|
|
245
|
+
/** Mirrors ErrTmuxSessionConflict (package: tmux) */
|
|
246
|
+
export declare class ErrTmuxSessionConflict extends AgentDirectorError {
|
|
247
|
+
}
|
|
248
|
+
/** Mirrors ErrTmuxKillFailed (package: tmux) */
|
|
249
|
+
export declare class ErrTmuxKillFailed extends AgentDirectorError {
|
|
250
|
+
}
|
|
240
251
|
/** Mirrors ErrSpawnNotInteractive (package: api) */
|
|
241
252
|
export declare class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
242
253
|
}
|
|
@@ -306,6 +317,12 @@ export declare class ErrMissingRequestToken extends AgentDirectorError {
|
|
|
306
317
|
/** Mirrors ErrInvalidFlags (package: api) */
|
|
307
318
|
export declare class ErrInvalidFlags extends AgentDirectorError {
|
|
308
319
|
}
|
|
320
|
+
/** Mirrors ErrConfigMalformed (package: clisetup) */
|
|
321
|
+
export declare class ErrConfigMalformed extends AgentDirectorError {
|
|
322
|
+
}
|
|
323
|
+
/** Mirrors ErrStoreOpen (package: clisetup) */
|
|
324
|
+
export declare class ErrStoreOpen extends AgentDirectorError {
|
|
325
|
+
}
|
|
309
326
|
/**
|
|
310
327
|
* errorFromEnvelope creates a typed AgentDirectorError subclass from the
|
|
311
328
|
* subprocess error envelope fields.
|
package/dist/index.d.ts
CHANGED
|
@@ -7,8 +7,8 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
|
|
|
7
7
|
export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
|
|
8
8
|
export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
|
|
9
9
|
ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
|
|
10
|
-
ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
|
|
10
|
+
ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, } from "./errors.js";
|
|
11
11
|
export type { CheckedLocation, UnreachableReason } from "./errors.js";
|
|
12
12
|
export type { ClientOptions, Logger } from "./types.js";
|
|
13
13
|
export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
|
|
14
|
-
export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult,
|
|
14
|
+
export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
|
package/dist/index.js
CHANGED
|
@@ -28,12 +28,15 @@ __export(exports_errors, {
|
|
|
28
28
|
errorFromEnvelope: () => errorFromEnvelope,
|
|
29
29
|
TS_ONLY_ERROR_NAMES: () => TS_ONLY_ERROR_NAMES,
|
|
30
30
|
ErrUnknownErrorName: () => ErrUnknownErrorName,
|
|
31
|
+
ErrTmuxUnresponsive: () => ErrTmuxUnresponsive,
|
|
31
32
|
ErrTmuxSessionNameTooLong: () => ErrTmuxSessionNameTooLong,
|
|
32
33
|
ErrTmuxSessionNameInvalid: () => ErrTmuxSessionNameInvalid,
|
|
33
34
|
ErrTmuxSessionNameEmpty: () => ErrTmuxSessionNameEmpty,
|
|
34
35
|
ErrTmuxSessionCreate: () => ErrTmuxSessionCreate,
|
|
36
|
+
ErrTmuxSessionConflict: () => ErrTmuxSessionConflict,
|
|
35
37
|
ErrTmuxSendKeys: () => ErrTmuxSendKeys,
|
|
36
38
|
ErrTmuxNotAvailable: () => ErrTmuxNotAvailable,
|
|
39
|
+
ErrTmuxKillFailed: () => ErrTmuxKillFailed,
|
|
37
40
|
ErrTmuxCaptureFailed: () => ErrTmuxCaptureFailed,
|
|
38
41
|
ErrTemplateNotFound: () => ErrTemplateNotFound,
|
|
39
42
|
ErrTemplateNameUnsafe: () => ErrTemplateNameUnsafe,
|
|
@@ -43,6 +46,7 @@ __export(exports_errors, {
|
|
|
43
46
|
ErrSystemInstallTooOld: () => ErrSystemInstallTooOld,
|
|
44
47
|
ErrSystemInstallNotFound: () => ErrSystemInstallNotFound,
|
|
45
48
|
ErrSystemInstallDisappeared: () => ErrSystemInstallDisappeared,
|
|
49
|
+
ErrStoreOpen: () => ErrStoreOpen,
|
|
46
50
|
ErrSpawnNotResumable: () => ErrSpawnNotResumable,
|
|
47
51
|
ErrSpawnNotPausable: () => ErrSpawnNotPausable,
|
|
48
52
|
ErrSpawnNotInteractive: () => ErrSpawnNotInteractive,
|
|
@@ -70,6 +74,7 @@ __export(exports_errors, {
|
|
|
70
74
|
ErrCwdNotADirectory: () => ErrCwdNotADirectory,
|
|
71
75
|
ErrCwdMissing: () => ErrCwdMissing,
|
|
72
76
|
ErrConsumerSignal: () => ErrConsumerSignal,
|
|
77
|
+
ErrConfigMalformed: () => ErrConfigMalformed,
|
|
73
78
|
ErrClientClosed: () => ErrClientClosed,
|
|
74
79
|
ErrCallerCwdUnreachable: () => ErrCallerCwdUnreachable,
|
|
75
80
|
ErrCallTimeout: () => ErrCallTimeout,
|
|
@@ -288,6 +293,15 @@ class ErrTmuxSendKeys extends AgentDirectorError {
|
|
|
288
293
|
class ErrTmuxCaptureFailed extends AgentDirectorError {
|
|
289
294
|
}
|
|
290
295
|
|
|
296
|
+
class ErrTmuxUnresponsive extends AgentDirectorError {
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
class ErrTmuxSessionConflict extends AgentDirectorError {
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
class ErrTmuxKillFailed extends AgentDirectorError {
|
|
303
|
+
}
|
|
304
|
+
|
|
291
305
|
class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
292
306
|
}
|
|
293
307
|
|
|
@@ -356,6 +370,12 @@ class ErrMissingRequestToken extends AgentDirectorError {
|
|
|
356
370
|
|
|
357
371
|
class ErrInvalidFlags extends AgentDirectorError {
|
|
358
372
|
}
|
|
373
|
+
|
|
374
|
+
class ErrConfigMalformed extends AgentDirectorError {
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
class ErrStoreOpen extends AgentDirectorError {
|
|
378
|
+
}
|
|
359
379
|
var ERROR_TABLE = {
|
|
360
380
|
ErrCwdMissing,
|
|
361
381
|
ErrCwdNotAPath,
|
|
@@ -377,6 +397,9 @@ var ERROR_TABLE = {
|
|
|
377
397
|
ErrTmuxSessionCreate,
|
|
378
398
|
ErrTmuxSendKeys,
|
|
379
399
|
ErrTmuxCaptureFailed,
|
|
400
|
+
ErrTmuxUnresponsive,
|
|
401
|
+
ErrTmuxSessionConflict,
|
|
402
|
+
ErrTmuxKillFailed,
|
|
380
403
|
ErrSpawnNotInteractive,
|
|
381
404
|
ErrSendKeysWhileRelayed,
|
|
382
405
|
ErrSpawnNotPausable,
|
|
@@ -395,7 +418,9 @@ var ERROR_TABLE = {
|
|
|
395
418
|
ErrTemplateNotFound,
|
|
396
419
|
ErrTemplateMalformed,
|
|
397
420
|
ErrTemplateExists,
|
|
398
|
-
ErrProbeUnsupported
|
|
421
|
+
ErrProbeUnsupported,
|
|
422
|
+
ErrConfigMalformed,
|
|
423
|
+
ErrStoreOpen
|
|
399
424
|
};
|
|
400
425
|
function errorFromEnvelope(verb, err_name, err_description) {
|
|
401
426
|
const Ctor = ERROR_TABLE[err_name];
|
|
@@ -807,19 +832,6 @@ function checkBunVersion() {
|
|
|
807
832
|
import { readFile } from "fs/promises";
|
|
808
833
|
import { statSync as statSync2 } from "fs";
|
|
809
834
|
|
|
810
|
-
// src/internal/tilde.ts
|
|
811
|
-
import * as os from "os";
|
|
812
|
-
function expandTilde(p) {
|
|
813
|
-
if (p === "")
|
|
814
|
-
return "";
|
|
815
|
-
if (p !== "~" && !p.startsWith("~/"))
|
|
816
|
-
return p;
|
|
817
|
-
const home = process.env["HOME"] ?? os.homedir();
|
|
818
|
-
if (p === "~")
|
|
819
|
-
return home;
|
|
820
|
-
return home + p.slice(1);
|
|
821
|
-
}
|
|
822
|
-
|
|
823
835
|
// src/internal/argv.ts
|
|
824
836
|
function buildArgv(cliPath, verb, params, globalOpts) {
|
|
825
837
|
const globalFlags = buildGlobalFlags(globalOpts);
|
|
@@ -864,8 +876,6 @@ function buildVerbFlags(verb, params) {
|
|
|
864
876
|
return buildFindMissing();
|
|
865
877
|
case "expire":
|
|
866
878
|
return buildExpire(params);
|
|
867
|
-
case "delete":
|
|
868
|
-
return buildDelete(params);
|
|
869
879
|
case "make-template":
|
|
870
880
|
return buildMakeTemplate(params);
|
|
871
881
|
case "list":
|
|
@@ -894,6 +904,8 @@ function buildSpawn(p) {
|
|
|
894
904
|
f.push("--relay-mode", p.relay_mode);
|
|
895
905
|
if (p.no_pre_trust === true)
|
|
896
906
|
f.push("--no-pre-trust");
|
|
907
|
+
if (p.reuse_finished === true)
|
|
908
|
+
f.push("--reuse-finished");
|
|
897
909
|
if (p.label) {
|
|
898
910
|
for (const lv of p.label)
|
|
899
911
|
f.push("--label", lv);
|
|
@@ -979,12 +991,6 @@ function buildExpire(p) {
|
|
|
979
991
|
f.push("--older-than", p.older_than);
|
|
980
992
|
return f;
|
|
981
993
|
}
|
|
982
|
-
function buildDelete(p) {
|
|
983
|
-
const f = ["delete"];
|
|
984
|
-
for (const id of p.claude_instance_id)
|
|
985
|
-
f.push("--claude-instance-id", id);
|
|
986
|
-
return f;
|
|
987
|
-
}
|
|
988
994
|
function buildMakeTemplate(p) {
|
|
989
995
|
const f = ["make-template", "--name", p.name];
|
|
990
996
|
if (p.cwd !== undefined)
|
|
@@ -1140,6 +1146,21 @@ var catalog_default = [
|
|
|
1140
1146
|
package: "tmux",
|
|
1141
1147
|
description: ""
|
|
1142
1148
|
},
|
|
1149
|
+
{
|
|
1150
|
+
name: "ErrTmuxUnresponsive",
|
|
1151
|
+
package: "tmux",
|
|
1152
|
+
description: ""
|
|
1153
|
+
},
|
|
1154
|
+
{
|
|
1155
|
+
name: "ErrTmuxSessionConflict",
|
|
1156
|
+
package: "tmux",
|
|
1157
|
+
description: ""
|
|
1158
|
+
},
|
|
1159
|
+
{
|
|
1160
|
+
name: "ErrTmuxKillFailed",
|
|
1161
|
+
package: "tmux",
|
|
1162
|
+
description: ""
|
|
1163
|
+
},
|
|
1143
1164
|
{
|
|
1144
1165
|
name: "ErrSpawnNotInteractive",
|
|
1145
1166
|
package: "api",
|
|
@@ -1254,6 +1275,16 @@ var catalog_default = [
|
|
|
1254
1275
|
name: "ErrAmbiguousRequest",
|
|
1255
1276
|
package: "store",
|
|
1256
1277
|
description: ""
|
|
1278
|
+
},
|
|
1279
|
+
{
|
|
1280
|
+
name: "ErrConfigMalformed",
|
|
1281
|
+
package: "clisetup",
|
|
1282
|
+
description: ""
|
|
1283
|
+
},
|
|
1284
|
+
{
|
|
1285
|
+
name: "ErrStoreOpen",
|
|
1286
|
+
package: "clisetup",
|
|
1287
|
+
description: ""
|
|
1257
1288
|
}
|
|
1258
1289
|
];
|
|
1259
1290
|
|
|
@@ -1317,11 +1348,11 @@ class SubprocessClient {
|
|
|
1317
1348
|
this.#binaryVersion = init.binaryVersion;
|
|
1318
1349
|
const g = {};
|
|
1319
1350
|
if (opts.storePath !== undefined)
|
|
1320
|
-
g.storePath =
|
|
1351
|
+
g.storePath = opts.storePath;
|
|
1321
1352
|
if (opts.tmuxCommand !== undefined)
|
|
1322
|
-
g.tmuxCommand =
|
|
1353
|
+
g.tmuxCommand = opts.tmuxCommand;
|
|
1323
1354
|
if (opts.home !== undefined)
|
|
1324
|
-
g.home =
|
|
1355
|
+
g.home = opts.home;
|
|
1325
1356
|
this.#globalOpts = g;
|
|
1326
1357
|
this.#open = true;
|
|
1327
1358
|
this.#tail = Promise.resolve();
|
|
@@ -1517,10 +1548,6 @@ class SubprocessClient {
|
|
|
1517
1548
|
this.#assertOpen();
|
|
1518
1549
|
return this.#enqueue("expire", params);
|
|
1519
1550
|
}
|
|
1520
|
-
async delete(params) {
|
|
1521
|
-
this.#assertOpen();
|
|
1522
|
-
return this.#enqueue("delete", params);
|
|
1523
|
-
}
|
|
1524
1551
|
async makeTemplate(params) {
|
|
1525
1552
|
this.#assertOpen();
|
|
1526
1553
|
return this.#enqueue("make-template", params);
|
|
@@ -1635,12 +1662,15 @@ export {
|
|
|
1635
1662
|
errorFromEnvelope,
|
|
1636
1663
|
MIN_BINARY_VERSION,
|
|
1637
1664
|
ErrUnknownErrorName,
|
|
1665
|
+
ErrTmuxUnresponsive,
|
|
1638
1666
|
ErrTmuxSessionNameTooLong,
|
|
1639
1667
|
ErrTmuxSessionNameInvalid,
|
|
1640
1668
|
ErrTmuxSessionNameEmpty,
|
|
1641
1669
|
ErrTmuxSessionCreate,
|
|
1670
|
+
ErrTmuxSessionConflict,
|
|
1642
1671
|
ErrTmuxSendKeys,
|
|
1643
1672
|
ErrTmuxNotAvailable,
|
|
1673
|
+
ErrTmuxKillFailed,
|
|
1644
1674
|
ErrTmuxCaptureFailed,
|
|
1645
1675
|
ErrTemplateNotFound,
|
|
1646
1676
|
ErrTemplateNameUnsafe,
|
|
@@ -1650,6 +1680,7 @@ export {
|
|
|
1650
1680
|
ErrSystemInstallTooOld,
|
|
1651
1681
|
ErrSystemInstallNotFound,
|
|
1652
1682
|
ErrSystemInstallDisappeared,
|
|
1683
|
+
ErrStoreOpen,
|
|
1653
1684
|
ErrSpawnNotResumable,
|
|
1654
1685
|
ErrSpawnNotPausable,
|
|
1655
1686
|
ErrSpawnNotInteractive,
|
|
@@ -1677,6 +1708,7 @@ export {
|
|
|
1677
1708
|
ErrCwdNotADirectory,
|
|
1678
1709
|
ErrCwdMissing,
|
|
1679
1710
|
ErrConsumerSignal,
|
|
1711
|
+
ErrConfigMalformed,
|
|
1680
1712
|
ErrClientClosed,
|
|
1681
1713
|
ErrCallerCwdUnreachable,
|
|
1682
1714
|
ErrCallTimeout,
|
package/dist/internal/argv.d.ts
CHANGED
|
@@ -12,11 +12,11 @@
|
|
|
12
12
|
* - Mapping between camelCase method name and kebab CLI verb follows the
|
|
13
13
|
* same mapping in src/internal/verbs.ts.
|
|
14
14
|
* - Optional fields are omitted when undefined / falsy.
|
|
15
|
-
* - Boolean flags (--no-pre-trust, --ansi, --overwrite)
|
|
16
|
-
* when the field is explicitly true.
|
|
15
|
+
* - Boolean flags (--no-pre-trust, --reuse-finished, --ansi, --overwrite)
|
|
16
|
+
* are only appended when the field is explicitly true.
|
|
17
17
|
* - Global flags (b.32k: --store-path, --home, --tmux-command) appear
|
|
18
18
|
* BEFORE the verb token so the CLI's global-flag parser in
|
|
19
|
-
*
|
|
19
|
+
* internal/clisetup/globalflags.go strips them prior to verb dispatch.
|
|
20
20
|
*
|
|
21
21
|
* Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
|
|
22
22
|
*
|
|
@@ -28,15 +28,14 @@ import type { VerbName } from "./verbs.js";
|
|
|
28
28
|
* bug b.32k. Each field is optional; when undefined the corresponding flag
|
|
29
29
|
* is omitted from argv and the CLI's own default-resolution kicks in.
|
|
30
30
|
*
|
|
31
|
-
*
|
|
32
|
-
* construction time via src/internal/tilde.ts).
|
|
31
|
+
* Values are forwarded verbatim; the CLI expands `~` in them (b.38a).
|
|
33
32
|
*/
|
|
34
33
|
export interface GlobalArgvOptions {
|
|
35
|
-
/**
|
|
34
|
+
/** Path forwarded to the CLI as `--store-path`. */
|
|
36
35
|
storePath?: string;
|
|
37
|
-
/**
|
|
36
|
+
/** Path forwarded to the CLI as `--home`. */
|
|
38
37
|
home?: string;
|
|
39
|
-
/**
|
|
38
|
+
/** Path forwarded to the CLI as `--tmux-command`. */
|
|
40
39
|
tmuxCommand?: string;
|
|
41
40
|
}
|
|
42
41
|
/**
|
|
@@ -46,8 +45,8 @@ export interface GlobalArgvOptions {
|
|
|
46
45
|
* [cliPath, ...globalFlags, verbName, ...verbFlags]
|
|
47
46
|
*
|
|
48
47
|
* Global flags are inserted BEFORE the verb token because the CLI's
|
|
49
|
-
* `
|
|
50
|
-
* (see
|
|
48
|
+
* `ParseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
|
|
49
|
+
* (see internal/clisetup/globalflags.go). b.32k.
|
|
51
50
|
*
|
|
52
51
|
* @param cliPath The absolute path to the CLI binary (argv[0]).
|
|
53
52
|
* @param verb The kebab-case verb name (must be a VerbName).
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* errorMap.ts — catalog-driven static error map for the subprocess Client.
|
|
3
3
|
*
|
|
4
4
|
* Builds a `Map<string, ErrConstructor>` at module load time by iterating
|
|
5
|
-
* `pkg/api/errnames/catalog.json` (
|
|
5
|
+
* `pkg/api/errnames/catalog.json` (44 entries). The map
|
|
6
6
|
* keys are the canonical `err_name` strings (e.g. "ErrSpawnNotFound");
|
|
7
7
|
* values are the typed constructors already exported from `src/errors.ts`.
|
|
8
8
|
*
|
|
@@ -10,8 +10,11 @@
|
|
|
10
10
|
* - Looks up `envelope.err_name` in the static map.
|
|
11
11
|
* - Throws the typed subclass when found (carrying verb + envelope fields).
|
|
12
12
|
* - Throws `ErrUnknownErrorName` when the err_name is not in the map
|
|
13
|
-
* (SRD SR-4.3
|
|
14
|
-
* the
|
|
13
|
+
* (SRD SR-4.3): either a Go-side catalog addition that races the TS-side
|
|
14
|
+
* regen, or a name the binary emits but the catalog leaves out —
|
|
15
|
+
* currently ErrInternal, ErrSchemaMismatch, ErrSchemaMigrationRequired,
|
|
16
|
+
* ErrUnknownVerb, ErrJSONMarshal and ErrTrailWrite (tracked in b.cm7).
|
|
17
|
+
* Callers read `unknownName` for the real err_name.
|
|
15
18
|
*
|
|
16
19
|
* Implements SRD SR-4.1 (static module-load-time map), SR-4.2 (throw by
|
|
17
20
|
* constructor with envelope fields), SR-4.3 (ErrUnknownErrorName for
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
* and the timeout was not the cause, ErrConsumerSignal is thrown.
|
|
25
25
|
*/
|
|
26
26
|
import type { ClientOptions } from "../types.js";
|
|
27
|
-
import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult,
|
|
27
|
+
import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
|
|
28
28
|
/**
|
|
29
29
|
* Internal construction parameters. Carries pre-resolved binaryPath +
|
|
30
30
|
* binaryVersion so the runtime constructor doesn't run discovery itself.
|
|
@@ -111,14 +111,15 @@ export declare class SubprocessClient {
|
|
|
111
111
|
decide(params: DecideParams): Promise<DecideResult>;
|
|
112
112
|
/** getPermission — fetch a permission_requests row by request_token. */
|
|
113
113
|
getPermission(params: GetPermissionParams): Promise<GetPermissionResult>;
|
|
114
|
-
/** resume —
|
|
114
|
+
/** resume — relaunch a finished (ended or missing) row. */
|
|
115
115
|
resume(params: ResumeParams): Promise<ResumeResult>;
|
|
116
|
-
/** findMissing —
|
|
116
|
+
/** findMissing — sweep live Spawns, marking each `missing` or leaving it unverified on process and tmux evidence; see FindMissingResult. */
|
|
117
117
|
findMissing(params: FindMissingParams): Promise<FindMissingResult>;
|
|
118
|
-
/**
|
|
118
|
+
/**
|
|
119
|
+
* expire — remove finished rows older than the retention window whose
|
|
120
|
+
* agent is gone, and report the rows it keeps.
|
|
121
|
+
*/
|
|
119
122
|
expire(params: ExpireParams): Promise<ExpireResult>;
|
|
120
|
-
/** delete — hard-delete Spawn rows by id. */
|
|
121
|
-
delete(params: DeleteParams): Promise<DeleteResult>;
|
|
122
123
|
/** makeTemplate — save a reusable spawn preset. */
|
|
123
124
|
makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
|
|
124
125
|
/** list — query Spawns with optional filter params. */
|
package/dist/internal/verbs.d.ts
CHANGED
|
@@ -6,14 +6,14 @@
|
|
|
6
6
|
* pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
|
|
7
7
|
* and excludes the three non-callable verbs (help, serve, hook).
|
|
8
8
|
*
|
|
9
|
-
* Currently
|
|
10
|
-
* kill, decide, get-permission, resume, find-missing, expire,
|
|
9
|
+
* Currently 15 callable verbs: spawn, status, get, send-keys, read-pane,
|
|
10
|
+
* kill, decide, get-permission, resume, find-missing, expire,
|
|
11
11
|
* make-template, list, pause, version.
|
|
12
12
|
*
|
|
13
13
|
* NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
|
|
14
14
|
* intentionally excluded here. The .go source wins.
|
|
15
15
|
*/
|
|
16
16
|
/** All callable verbs in their canonical kebab form (matches manifest). */
|
|
17
|
-
export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "
|
|
17
|
+
export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "make-template", "list", "pause", "version"];
|
|
18
18
|
/** Union type of every callable verb name. */
|
|
19
19
|
export type VerbName = (typeof VERBS)[number];
|
package/dist/types.d.ts
CHANGED
|
@@ -18,14 +18,25 @@ export interface Logger {
|
|
|
18
18
|
* does NOT provide a fallback; it forwards user input verbatim to keep the
|
|
19
19
|
* CLI as the single source of truth for default resolution. See bug b.32k.
|
|
20
20
|
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* leading
|
|
21
|
+
* `storePath`, `home` and `tmuxCommand` are forwarded verbatim; the TS Client
|
|
22
|
+
* does no tilde expansion of its own. The CLI subprocess, which inherits this
|
|
23
|
+
* process's environment, expands `~`: a bare `~` or a leading `~/` in `home`
|
|
24
|
+
* against the inherited `HOME`, then a leading `~/` in `storePath` and
|
|
25
|
+
* `tmuxCommand` (and a bare `~` in `tmuxCommand`) against the resulting
|
|
26
|
+
* `HOME`, which is `home` when set. The CLI never resolves `~` against the
|
|
27
|
+
* passwd home: with `HOME` unset or empty, a `~` or `~/` `home` rejects every
|
|
28
|
+
* call with `ErrInvalidFlags`, and with no `home` either, every call that
|
|
29
|
+
* opens the store is refused. Other values, relative paths included, are
|
|
30
|
+
* forwarded unchanged and the CLI resolves them. b.38a.
|
|
31
|
+
*
|
|
32
|
+
* An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
|
|
33
|
+
* `--store-path ""`); the CLI rejects it on every verb call, which then
|
|
34
|
+
* rejects with `ErrInvalidFlags`. It never falls back to the default. b.pu2.
|
|
24
35
|
*/
|
|
25
36
|
export interface ClientOptions {
|
|
26
37
|
/**
|
|
27
|
-
* Path to the SQLite store file.
|
|
28
|
-
*
|
|
38
|
+
* Path to the SQLite store file. Forwarded verbatim as `--store-path` to the
|
|
39
|
+
* CLI subprocess, which expands a leading `~/`.
|
|
29
40
|
*
|
|
30
41
|
* When omitted, the CLI's three-tier default resolution applies:
|
|
31
42
|
* 1. CLI flag (this field, when set) → 2. cfg.Store.DbPath in
|
|
@@ -36,15 +47,15 @@ export interface ClientOptions {
|
|
|
36
47
|
*/
|
|
37
48
|
storePath?: string;
|
|
38
49
|
/**
|
|
39
|
-
* Override the tmux binary.
|
|
40
|
-
*
|
|
41
|
-
* `tmux` on PATH.
|
|
50
|
+
* Override the tmux binary. Forwarded verbatim as `--tmux-command` to the
|
|
51
|
+
* CLI subprocess, which expands a bare `~` or a leading `~/`. When omitted,
|
|
52
|
+
* the CLI looks up `tmux` on PATH.
|
|
42
53
|
*/
|
|
43
54
|
tmuxCommand?: string;
|
|
44
55
|
/**
|
|
45
56
|
* Override HOME for the duration of every subprocess call this Client
|
|
46
|
-
* issues.
|
|
47
|
-
*
|
|
57
|
+
* issues. Forwarded verbatim as `--home` to the CLI subprocess, which
|
|
58
|
+
* expands a bare `~` or a leading `~/` against the inherited `HOME`.
|
|
48
59
|
*
|
|
49
60
|
* When omitted, the CLI subprocess inherits HOME from the calling process
|
|
50
61
|
* environment (which is the correct default — set HOME at the
|
|
@@ -99,7 +110,12 @@ export interface ListRow {
|
|
|
99
110
|
claude_instance_id: string;
|
|
100
111
|
/** Parent Spawn id (omitted when launched from a plain shell). */
|
|
101
112
|
parent_id?: string;
|
|
102
|
-
/**
|
|
113
|
+
/**
|
|
114
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
115
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
116
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
117
|
+
* prompt. A resumed pending row keeps its session id and history.
|
|
118
|
+
*/
|
|
103
119
|
state: string;
|
|
104
120
|
/** Canonicalized working directory. */
|
|
105
121
|
cwd: string;
|
|
@@ -115,9 +131,24 @@ export interface ListRow {
|
|
|
115
131
|
last_seen_at: string;
|
|
116
132
|
/** Set when state moves to ended (omitted while live). */
|
|
117
133
|
ended_at?: string | null;
|
|
118
|
-
/**
|
|
134
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
135
|
+
launch_started_at?: string | null;
|
|
136
|
+
/**
|
|
137
|
+
* RFC3339 timestamp of the first sweep that left this live row unverified;
|
|
138
|
+
* kept while later sweeps change `liveness_note`. Cleared together with
|
|
139
|
+
* `liveness_note` when a sweep finds the agent process alive; omitted/null
|
|
140
|
+
* while not unverified.
|
|
141
|
+
*/
|
|
119
142
|
liveness_unverified_since?: string | null;
|
|
120
|
-
/**
|
|
143
|
+
/**
|
|
144
|
+
* Reason token of the latest sweep that left this live row unverified (its
|
|
145
|
+
* agent process could not be checked and tmux did not settle it), for
|
|
146
|
+
* example `process_not_seen_session_present`,
|
|
147
|
+
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
148
|
+
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
149
|
+
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
150
|
+
* process alive; omitted/null while not unverified.
|
|
151
|
+
*/
|
|
121
152
|
liveness_note?: string | null;
|
|
122
153
|
}
|
|
123
154
|
/** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
|
|
@@ -142,15 +173,40 @@ export interface SpawnParams {
|
|
|
142
173
|
extra_env?: Record<string, string>;
|
|
143
174
|
/** Pass-through argv to `claude` after --settings. */
|
|
144
175
|
claude_args?: string[];
|
|
145
|
-
/**
|
|
176
|
+
/**
|
|
177
|
+
* Skip pre-writing the folder-trust entry for `cwd` (into
|
|
178
|
+
* `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets `CLAUDE_CONFIG_DIR`,
|
|
179
|
+
* otherwise `~/.claude.json`). The choice is recorded on the row for its life,
|
|
180
|
+
* and every `resume` of that life follows it. The result then reports
|
|
181
|
+
* `pre_trust: "skipped"`. Default false.
|
|
182
|
+
*/
|
|
146
183
|
no_pre_trust?: boolean;
|
|
147
184
|
/** Explicit tmux session name. Auto-derived when absent. */
|
|
148
185
|
tmux_session_name?: string;
|
|
186
|
+
/**
|
|
187
|
+
* Reuse an explicit `claude_instance_id` whose row is `ended` or `missing`;
|
|
188
|
+
* a live row, `pending` included, still collides. No effect without an
|
|
189
|
+
* explicit `claude_instance_id`; applies to this call only. Default false:
|
|
190
|
+
* any existing row with the id collides with `ErrInstanceIdCollision`.
|
|
191
|
+
*/
|
|
192
|
+
reuse_finished?: boolean;
|
|
149
193
|
}
|
|
150
|
-
/**
|
|
194
|
+
/**
|
|
195
|
+
* Mirrors pkg/api/spawn.go::SpawnResult. The row is `pending` from its insert until
|
|
196
|
+
* the agent reports in (Claude Code's SessionStart), then `waiting`.
|
|
197
|
+
*/
|
|
151
198
|
export interface SpawnResult {
|
|
152
199
|
/** The id the new Spawn is tracked under. */
|
|
153
200
|
claude_instance_id: string;
|
|
201
|
+
/**
|
|
202
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
|
|
203
|
+
* written. `"skipped"`: pre-trust was off for this launch because the caller passed
|
|
204
|
+
* `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
|
|
205
|
+
* entry was not written (the `.claude.json` file is missing, or could not be read,
|
|
206
|
+
* parsed or written); the agent may stop at Claude Code's folder-trust prompt.
|
|
207
|
+
* A pre-trust failure never fails the spawn.
|
|
208
|
+
*/
|
|
209
|
+
pre_trust: "ok" | "skipped" | "failed";
|
|
154
210
|
}
|
|
155
211
|
/** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
|
|
156
212
|
export interface StatusParams {
|
|
@@ -159,8 +215,16 @@ export interface StatusParams {
|
|
|
159
215
|
}
|
|
160
216
|
/** Mirrors pkg/api/status.go::StatusResult */
|
|
161
217
|
export interface StatusResult {
|
|
162
|
-
/**
|
|
218
|
+
/**
|
|
219
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
220
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
221
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
222
|
+
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
223
|
+
* from a fresh one by its non-empty `claude_session_id`, shown by `get`.
|
|
224
|
+
*/
|
|
163
225
|
state: string;
|
|
226
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
227
|
+
launch_started_at?: string | null;
|
|
164
228
|
}
|
|
165
229
|
/** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
|
|
166
230
|
export interface GetParams {
|
|
@@ -171,9 +235,18 @@ export interface GetParams {
|
|
|
171
235
|
export interface GetResult {
|
|
172
236
|
claude_instance_id: string;
|
|
173
237
|
parent_id: string;
|
|
238
|
+
/**
|
|
239
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
240
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
241
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
242
|
+
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
243
|
+
* `claude_session_id` tells it from a fresh one.
|
|
244
|
+
*/
|
|
174
245
|
state: string;
|
|
175
246
|
cwd: string;
|
|
176
247
|
tmux_session_name: string;
|
|
248
|
+
/** The tmux socket the row's launch uses; omitted for a row from before this release. */
|
|
249
|
+
tmux_socket?: string | null;
|
|
177
250
|
claude_args: string[];
|
|
178
251
|
relay_mode: string;
|
|
179
252
|
jsonl_path: string;
|
|
@@ -185,9 +258,24 @@ export interface GetResult {
|
|
|
185
258
|
last_seen_at: string;
|
|
186
259
|
/** Set when state moves to ended; omitted while live. */
|
|
187
260
|
ended_at?: string | null;
|
|
188
|
-
/**
|
|
261
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
262
|
+
launch_started_at?: string | null;
|
|
263
|
+
/**
|
|
264
|
+
* RFC3339 timestamp of the first sweep that left this live row unverified;
|
|
265
|
+
* kept while later sweeps change `liveness_note`. Cleared together with
|
|
266
|
+
* `liveness_note` when a sweep finds the agent process alive; omitted/null
|
|
267
|
+
* while not unverified.
|
|
268
|
+
*/
|
|
189
269
|
liveness_unverified_since?: string | null;
|
|
190
|
-
/**
|
|
270
|
+
/**
|
|
271
|
+
* Reason token of the latest sweep that left this live row unverified (its
|
|
272
|
+
* agent process could not be checked and tmux did not settle it), for
|
|
273
|
+
* example `process_not_seen_session_present`,
|
|
274
|
+
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
275
|
+
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
276
|
+
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
277
|
+
* process alive; omitted/null while not unverified.
|
|
278
|
+
*/
|
|
191
279
|
liveness_note?: string | null;
|
|
192
280
|
/** Open permission request; present only when state=check_permission with an undecided row. */
|
|
193
281
|
permission_request?: PermissionRequestInfo | null;
|
|
@@ -196,11 +284,17 @@ export interface GetResult {
|
|
|
196
284
|
export interface SendKeysParams {
|
|
197
285
|
/** Id of the Spawn whose pane will receive the text. */
|
|
198
286
|
claude_instance_id: string;
|
|
199
|
-
/**
|
|
287
|
+
/**
|
|
288
|
+
* Text to deliver to the pane. CR bytes stripped; LF preserved; Enter
|
|
289
|
+
* appended. Empty text sends Enter only: it submits what is already typed,
|
|
290
|
+
* such as a text a failed sendKeys left unsubmitted.
|
|
291
|
+
*/
|
|
200
292
|
text: string;
|
|
201
293
|
/**
|
|
202
|
-
* When true, also
|
|
203
|
-
*
|
|
294
|
+
* When true, also allows a pending row: a launch (spawn, reuse or resume)
|
|
295
|
+
* whose agent has not reported in yet. Keys are delivered only to a
|
|
296
|
+
* session started by the row's current launch. ended and missing rows are
|
|
297
|
+
* still rejected.
|
|
204
298
|
*/
|
|
205
299
|
allow_pending?: boolean;
|
|
206
300
|
}
|
|
@@ -227,13 +321,15 @@ export interface ReadPaneResult {
|
|
|
227
321
|
/** Captured pane text. */
|
|
228
322
|
pane: string;
|
|
229
323
|
}
|
|
230
|
-
/** Mirrors pkg/api.KillParams
|
|
324
|
+
/** Mirrors pkg/api.KillParams. */
|
|
231
325
|
export interface KillParams {
|
|
232
326
|
/** Id of the Spawn to kill. */
|
|
233
327
|
claude_instance_id: string;
|
|
234
328
|
}
|
|
235
|
-
/** Mirrors pkg/api/kill.go::KillResult (
|
|
329
|
+
/** Mirrors pkg/api/kill.go::KillResult (json tags). */
|
|
236
330
|
export interface KillResult {
|
|
331
|
+
/** True exactly when a pane kill or a session kill was sent. */
|
|
332
|
+
kill_sent: boolean;
|
|
237
333
|
}
|
|
238
334
|
/** Mirrors pkg/api.DecideParams (json tags). */
|
|
239
335
|
export interface DecideParams {
|
|
@@ -275,31 +371,66 @@ export interface GetPermissionResult {
|
|
|
275
371
|
}
|
|
276
372
|
/** Mirrors pkg/api.ResumeParams (json tags). */
|
|
277
373
|
export interface ResumeParams {
|
|
278
|
-
/** Id of the
|
|
374
|
+
/** Id of the finished (ended or missing) row to resume. */
|
|
279
375
|
claude_instance_id: string;
|
|
280
376
|
}
|
|
281
|
-
/**
|
|
377
|
+
/**
|
|
378
|
+
* Mirrors pkg/api/resume.go::ResumeResult. Resume moved the row to `pending`, keeping
|
|
379
|
+
* its session id and history, until the agent reports in (Claude Code's SessionStart),
|
|
380
|
+
* then `waiting`.
|
|
381
|
+
*/
|
|
282
382
|
export interface ResumeResult {
|
|
283
|
-
/** Same id that was passed in (
|
|
383
|
+
/** Same id that was passed in (resume preserves it). */
|
|
284
384
|
claude_instance_id: string;
|
|
385
|
+
/**
|
|
386
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
|
|
387
|
+
* written. `"skipped"`: pre-trust was off for this launch because the row records that
|
|
388
|
+
* the spawn that began its life turned it off (`no_pre_trust`); nothing was attempted.
|
|
389
|
+
* `"failed"`: pre-trust was attempted and the entry was not written (the `.claude.json`
|
|
390
|
+
* file is missing, or could not be read, parsed or written); the agent may stop at
|
|
391
|
+
* Claude Code's folder-trust prompt. A pre-trust failure never fails the resume.
|
|
392
|
+
*/
|
|
393
|
+
pre_trust: "ok" | "skipped" | "failed";
|
|
285
394
|
}
|
|
286
|
-
/**
|
|
395
|
+
/** Params for the `find-missing` verb, which takes no CLI flags. */
|
|
287
396
|
export interface FindMissingParams {
|
|
288
|
-
/**
|
|
397
|
+
/**
|
|
398
|
+
* Accepted but not sent: the `find-missing` CLI verb takes no flags, so
|
|
399
|
+
* this value has no effect. The call is bounded by the Client's
|
|
400
|
+
* `callTimeoutMs` like every other verb.
|
|
401
|
+
*/
|
|
289
402
|
timeout_ms?: number;
|
|
290
403
|
}
|
|
291
404
|
/** Mirrors pkg/api/find_missing.go::FindMissingResult */
|
|
292
405
|
export interface FindMissingResult {
|
|
293
|
-
/**
|
|
406
|
+
/**
|
|
407
|
+
* Number of rows this sweep marked `missing` (the length of `ids`). Zero is
|
|
408
|
+
* a normal result when nothing needed marking.
|
|
409
|
+
*/
|
|
294
410
|
count: number;
|
|
295
|
-
/** Sorted ids of rows transitioned to missing. */
|
|
296
|
-
ids: string[];
|
|
297
411
|
/**
|
|
298
|
-
*
|
|
299
|
-
*
|
|
412
|
+
* Sorted ids of rows this sweep marked `missing`, on process or tmux
|
|
413
|
+
* evidence: rows whose agent process (the SessionStart one or the recorded
|
|
414
|
+
* pane's) is dead, and rows whose process could not be checked and tmux
|
|
415
|
+
* found no session or pane of their current launch; a pending row only past
|
|
416
|
+
* the pending grace period. A row whose guarded write found it changed or
|
|
417
|
+
* gone, or failed, is in neither list. `missing` is the sweep's judgement
|
|
418
|
+
* on the evidence available to it, not proof that the agent has exited.
|
|
419
|
+
* Never null; [] when none.
|
|
300
420
|
*/
|
|
421
|
+
ids: string[];
|
|
422
|
+
/** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
|
|
301
423
|
unverified: number;
|
|
302
|
-
/**
|
|
424
|
+
/**
|
|
425
|
+
* Sorted ids of live rows this sweep left unverified with a liveness note,
|
|
426
|
+
* whether it wrote the note or found it already current: rows whose agent
|
|
427
|
+
* process could not be checked and which tmux did not mark, for example
|
|
428
|
+
* because their own session is present, tmux could not tell or was
|
|
429
|
+
* unavailable, or tmux was not called. Never a pending row inside the
|
|
430
|
+
* pending grace period. A row whose guarded write found it changed or gone,
|
|
431
|
+
* or failed, and a row whose note was cleared, is in neither list. Never
|
|
432
|
+
* null; [] when none.
|
|
433
|
+
*/
|
|
303
434
|
unverified_ids: string[];
|
|
304
435
|
}
|
|
305
436
|
/** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
|
|
@@ -312,20 +443,36 @@ export interface ExpireParams {
|
|
|
312
443
|
}
|
|
313
444
|
/** Mirrors pkg/api/expire.go::ExpireResult */
|
|
314
445
|
export interface ExpireResult {
|
|
315
|
-
/**
|
|
446
|
+
/**
|
|
447
|
+
* Number of rows deleted (the length of `ids`): rows deleted after tmux
|
|
448
|
+
* showed no session of the agent (Gone) and its recorded process was not
|
|
449
|
+
* seen running. Zero is a legitimate result when no row was deleted.
|
|
450
|
+
*/
|
|
316
451
|
count: number;
|
|
317
|
-
/**
|
|
452
|
+
/**
|
|
453
|
+
* Sorted ids of the rows deleted after tmux showed no session of the agent
|
|
454
|
+
* (Gone) and its recorded process was not seen running, each only while
|
|
455
|
+
* the row was unchanged since expire examined it. Never null; `[]` when
|
|
456
|
+
* none.
|
|
457
|
+
*/
|
|
318
458
|
ids: string[];
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
459
|
+
/**
|
|
460
|
+
* Number of selected rows kept rather than deleted (the length of
|
|
461
|
+
* `kept_ids`), for example because the agent's process or a session of the
|
|
462
|
+
* agent (its own, or a leftover of an earlier launch) may still run, tmux
|
|
463
|
+
* could not be checked or answered from a different server, the run's tmux
|
|
464
|
+
* time budget (`sweep_budget_seconds`) was spent, or the row changed after
|
|
465
|
+
* it was examined.
|
|
466
|
+
*/
|
|
467
|
+
kept: number;
|
|
468
|
+
/**
|
|
469
|
+
* Sorted ids of the selected rows kept rather than deleted, each reported
|
|
470
|
+
* with its reason in the trail (`ad.expire.kept`). tmux problems and a
|
|
471
|
+
* failed delete of one row never fail the run: the row is kept. A failed
|
|
472
|
+
* read of the selected rows fails the run. A row another caller removed
|
|
473
|
+
* first is in neither list. Never null; `[]` when none.
|
|
474
|
+
*/
|
|
475
|
+
kept_ids: string[];
|
|
329
476
|
}
|
|
330
477
|
/** Mirrors pkg/api.MakeTemplateParams (json tags). */
|
|
331
478
|
export interface MakeTemplateParams {
|
package/package.json
CHANGED
package/dist/internal/tilde.d.ts
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* expandTilde resolves a leading `~` or `~/` to the user's home directory.
|
|
3
|
-
*
|
|
4
|
-
* Resolution order:
|
|
5
|
-
* 1. `process.env.HOME` if set and non-empty.
|
|
6
|
-
* 2. `os.homedir()` from node:os as fallback.
|
|
7
|
-
*
|
|
8
|
-
* Behaviour by input:
|
|
9
|
-
* - `""` → `""` (empty string unchanged)
|
|
10
|
-
* - `"~"` → `"/home/user"` (bare tilde → home directory)
|
|
11
|
-
* - `"~/foo"` → `"/home/user/foo"` (tilde-prefix → home + rest)
|
|
12
|
-
* - `"/abs/path"` → `"/abs/path"` (absolute path unchanged)
|
|
13
|
-
* - `"relative/path"` → `"relative/path"` (relative path unchanged)
|
|
14
|
-
* - `"foo~bar"` → `"foo~bar"` (tilde not at start → unchanged)
|
|
15
|
-
*/
|
|
16
|
-
export declare function expandTilde(p: string): string;
|