agent-director 0.10.0 → 0.11.0
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 +55 -33
- package/dist/errors.d.ts +9 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +36 -13
- package/dist/internal/argv.d.ts +5 -5
- package/dist/internal/subprocessClient.d.ts +7 -6
- package/dist/internal/verbs.d.ts +3 -3
- package/dist/types.d.ts +181 -39
- package/package.json +1 -1
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
|
|
@@ -120,7 +120,8 @@ for (const spawn of result.spawns) {
|
|
|
120
120
|
|
|
121
121
|
### sendKeys
|
|
122
122
|
|
|
123
|
-
Send text to
|
|
123
|
+
Send text to the agent's own pane, then one Enter to submit it. An empty
|
|
124
|
+
`text` sends the Enter only, submitting what is already typed.
|
|
124
125
|
|
|
125
126
|
```sh
|
|
126
127
|
agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
|
|
@@ -130,14 +131,16 @@ agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
|
|
|
130
131
|
await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
|
|
131
132
|
```
|
|
132
133
|
|
|
133
|
-
Pass `allow_pending: true` to also
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
134
|
+
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
135
|
+
reuse or resume) whose agent has not reported in yet, for example to dismiss a
|
|
136
|
+
prompt the agent shows before it reports in. Keys are delivered only to a
|
|
137
|
+
session started by the row's current launch. `ended` and `missing` rows are
|
|
138
|
+
still rejected. A `pending` row whose launch start or launch token is not recorded, or where
|
|
139
|
+
only a session an earlier launch left behind is found, gets
|
|
140
|
+
`ErrSpawnNotInteractive` and nothing is sent.
|
|
138
141
|
|
|
139
|
-
Send an empty string with `allow_pending: true` to press Enter and dismiss
|
|
140
|
-
|
|
142
|
+
Send an empty string with `allow_pending: true` to press Enter and dismiss such
|
|
143
|
+
a prompt:
|
|
141
144
|
|
|
142
145
|
```ts
|
|
143
146
|
await client.sendKeys({
|
|
@@ -149,7 +152,7 @@ await client.sendKeys({
|
|
|
149
152
|
|
|
150
153
|
### readPane
|
|
151
154
|
|
|
152
|
-
Read the last N lines of
|
|
155
|
+
Read the last N lines of the agent's own pane (default 25).
|
|
153
156
|
|
|
154
157
|
```sh
|
|
155
158
|
agent-director read-pane --claude-instance-id <id> --n-lines 50
|
|
@@ -161,23 +164,37 @@ console.log(result.pane);
|
|
|
161
164
|
```
|
|
162
165
|
|
|
163
166
|
`readPane` has no state guard — it works on `pending`, `ended`, and `missing`
|
|
164
|
-
|
|
167
|
+
rows as well as live ones. The `allow_pending` flag is accepted for symmetry
|
|
165
168
|
with `sendKeys` but has no behavioral effect.
|
|
166
169
|
|
|
167
170
|
---
|
|
168
171
|
|
|
169
172
|
### kill
|
|
170
173
|
|
|
171
|
-
|
|
174
|
+
End the agent of a live Spawn's current launch (`pending` included). `kill`
|
|
175
|
+
resolves only once the agent process is gone, and returns `{ kill_sent }`:
|
|
176
|
+
`true` when a kill was sent to the agent's pane or its session, `false` when
|
|
177
|
+
none was. On a finished Spawn (`ended` or `missing`) `kill` is a no-op that
|
|
178
|
+
resolves with `kill_sent: false`; that is not verification that the agent
|
|
179
|
+
exited. `kill` never changes the row's state: `find-missing` marks the row once
|
|
180
|
+
its agent process is gone.
|
|
172
181
|
|
|
173
182
|
```sh
|
|
174
183
|
agent-director kill --claude-instance-id <id>
|
|
175
184
|
```
|
|
176
185
|
|
|
177
186
|
```ts
|
|
178
|
-
await client.kill({ claude_instance_id: "<id>" });
|
|
187
|
+
const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
|
|
188
|
+
console.log(kill_sent);
|
|
179
189
|
```
|
|
180
190
|
|
|
191
|
+
Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
|
|
192
|
+
retry later), `ErrTmuxSessionConflict` (CONFLICT: a human must look),
|
|
193
|
+
`ErrTmuxNotAvailable` (ENVIRONMENT: an operator must fix the environment) and
|
|
194
|
+
`ErrSpawnNotFound`. None of these means the agent is dead. The caller must run
|
|
195
|
+
as the same user and in the same tmux environment as the agents. See the "tmux
|
|
196
|
+
transport" table under [Errors](#errors).
|
|
197
|
+
|
|
181
198
|
### makeTemplate
|
|
182
199
|
|
|
183
200
|
Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
@@ -320,7 +337,7 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
|
|
|
320
337
|
|
|
321
338
|
### 4. Catalog-derived (CLI-side validation)
|
|
322
339
|
|
|
323
|
-
These
|
|
340
|
+
These 42 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 or a verb's own state preconditions — 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
341
|
|
|
325
342
|
**cwd validation** (bad `cwd` argument to `spawn` — programmer error):
|
|
326
343
|
|
|
@@ -338,14 +355,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
338
355
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
339
356
|
| `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
|
|
340
357
|
| `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
|
|
341
|
-
| `ErrInstanceIdCollision` |
|
|
358
|
+
| `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
359
|
|
|
343
|
-
**tmux session naming** (bad
|
|
360
|
+
**tmux session naming** (bad `tmux_session_name` — programmer error):
|
|
344
361
|
|
|
345
362
|
| Error | When it fires |
|
|
346
363
|
|---|---|
|
|
347
|
-
| `ErrTmuxSessionNameEmpty` |
|
|
348
|
-
| `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, an ASCII control character, or is invalid UTF-8. |
|
|
364
|
+
| `ErrTmuxSessionNameEmpty` | `tmux_session_name` was explicitly supplied but empty. |
|
|
365
|
+
| `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character, or is invalid UTF-8. |
|
|
349
366
|
| `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
|
|
350
367
|
|
|
351
368
|
**spawn state / lookup** (verb preconditions — mostly normal operational signals):
|
|
@@ -353,23 +370,28 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
353
370
|
| Error | When it fires |
|
|
354
371
|
|---|---|
|
|
355
372
|
| `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
|
|
373
|
+
| `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
374
|
| `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 — `
|
|
375
|
+
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
|
|
376
|
+
| `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. Also returned when the row changed after `resume` examined it; nothing is written. |
|
|
377
|
+
| `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), 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. |
|
|
378
|
+
| `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
379
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
363
|
-
| `ErrProbeUnsupported` |
|
|
380
|
+
| `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
381
|
|
|
365
|
-
**tmux transport** (infrastructure failures at the tmux layer — runtime):
|
|
382
|
+
**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
383
|
|
|
367
|
-
| Error | When it fires |
|
|
368
|
-
|
|
369
|
-
| `ErrTmuxNotAvailable` | The `tmux` binary is not on PATH or refuses to execute. |
|
|
370
|
-
| `ErrTmuxSessionCreate` | `tmux
|
|
371
|
-
| `
|
|
372
|
-
| `
|
|
384
|
+
| Error | Class | When it fires |
|
|
385
|
+
|---|---|---|
|
|
386
|
+
| `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. |
|
|
387
|
+
| `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. |
|
|
388
|
+
| `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 (the error says if it was not). 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. |
|
|
389
|
+
| `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. |
|
|
390
|
+
| `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. |
|
|
391
|
+
| `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
|
|
392
|
+
| `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
|
|
393
|
+
|
|
394
|
+
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
395
|
|
|
374
396
|
**relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
|
|
375
397
|
|
|
@@ -397,7 +419,7 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
397
419
|
|
|
398
420
|
| Error | When it fires |
|
|
399
421
|
|---|---|
|
|
400
|
-
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation
|
|
422
|
+
| `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). |
|
|
401
423
|
|
|
402
424
|
## Architecture
|
|
403
425
|
|
package/dist/errors.d.ts
CHANGED
|
@@ -237,6 +237,15 @@ export declare class ErrTmuxSendKeys extends AgentDirectorError {
|
|
|
237
237
|
/** Mirrors ErrTmuxCaptureFailed (package: tmux) */
|
|
238
238
|
export declare class ErrTmuxCaptureFailed extends AgentDirectorError {
|
|
239
239
|
}
|
|
240
|
+
/** Mirrors ErrTmuxUnresponsive (package: tmux) */
|
|
241
|
+
export declare class ErrTmuxUnresponsive extends AgentDirectorError {
|
|
242
|
+
}
|
|
243
|
+
/** Mirrors ErrTmuxSessionConflict (package: tmux) */
|
|
244
|
+
export declare class ErrTmuxSessionConflict extends AgentDirectorError {
|
|
245
|
+
}
|
|
246
|
+
/** Mirrors ErrTmuxKillFailed (package: tmux) */
|
|
247
|
+
export declare class ErrTmuxKillFailed extends AgentDirectorError {
|
|
248
|
+
}
|
|
240
249
|
/** Mirrors ErrSpawnNotInteractive (package: api) */
|
|
241
250
|
export declare class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
242
251
|
}
|
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, } 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,
|
|
@@ -288,6 +291,15 @@ class ErrTmuxSendKeys extends AgentDirectorError {
|
|
|
288
291
|
class ErrTmuxCaptureFailed extends AgentDirectorError {
|
|
289
292
|
}
|
|
290
293
|
|
|
294
|
+
class ErrTmuxUnresponsive extends AgentDirectorError {
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
class ErrTmuxSessionConflict extends AgentDirectorError {
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
class ErrTmuxKillFailed extends AgentDirectorError {
|
|
301
|
+
}
|
|
302
|
+
|
|
291
303
|
class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
292
304
|
}
|
|
293
305
|
|
|
@@ -377,6 +389,9 @@ var ERROR_TABLE = {
|
|
|
377
389
|
ErrTmuxSessionCreate,
|
|
378
390
|
ErrTmuxSendKeys,
|
|
379
391
|
ErrTmuxCaptureFailed,
|
|
392
|
+
ErrTmuxUnresponsive,
|
|
393
|
+
ErrTmuxSessionConflict,
|
|
394
|
+
ErrTmuxKillFailed,
|
|
380
395
|
ErrSpawnNotInteractive,
|
|
381
396
|
ErrSendKeysWhileRelayed,
|
|
382
397
|
ErrSpawnNotPausable,
|
|
@@ -814,7 +829,7 @@ function expandTilde(p) {
|
|
|
814
829
|
return "";
|
|
815
830
|
if (p !== "~" && !p.startsWith("~/"))
|
|
816
831
|
return p;
|
|
817
|
-
const home = process.env["HOME"]
|
|
832
|
+
const home = process.env["HOME"] || os.homedir();
|
|
818
833
|
if (p === "~")
|
|
819
834
|
return home;
|
|
820
835
|
return home + p.slice(1);
|
|
@@ -864,8 +879,6 @@ function buildVerbFlags(verb, params) {
|
|
|
864
879
|
return buildFindMissing();
|
|
865
880
|
case "expire":
|
|
866
881
|
return buildExpire(params);
|
|
867
|
-
case "delete":
|
|
868
|
-
return buildDelete(params);
|
|
869
882
|
case "make-template":
|
|
870
883
|
return buildMakeTemplate(params);
|
|
871
884
|
case "list":
|
|
@@ -894,6 +907,8 @@ function buildSpawn(p) {
|
|
|
894
907
|
f.push("--relay-mode", p.relay_mode);
|
|
895
908
|
if (p.no_pre_trust === true)
|
|
896
909
|
f.push("--no-pre-trust");
|
|
910
|
+
if (p.reuse_finished === true)
|
|
911
|
+
f.push("--reuse-finished");
|
|
897
912
|
if (p.label) {
|
|
898
913
|
for (const lv of p.label)
|
|
899
914
|
f.push("--label", lv);
|
|
@@ -979,12 +994,6 @@ function buildExpire(p) {
|
|
|
979
994
|
f.push("--older-than", p.older_than);
|
|
980
995
|
return f;
|
|
981
996
|
}
|
|
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
997
|
function buildMakeTemplate(p) {
|
|
989
998
|
const f = ["make-template", "--name", p.name];
|
|
990
999
|
if (p.cwd !== undefined)
|
|
@@ -1140,6 +1149,21 @@ var catalog_default = [
|
|
|
1140
1149
|
package: "tmux",
|
|
1141
1150
|
description: ""
|
|
1142
1151
|
},
|
|
1152
|
+
{
|
|
1153
|
+
name: "ErrTmuxUnresponsive",
|
|
1154
|
+
package: "tmux",
|
|
1155
|
+
description: ""
|
|
1156
|
+
},
|
|
1157
|
+
{
|
|
1158
|
+
name: "ErrTmuxSessionConflict",
|
|
1159
|
+
package: "tmux",
|
|
1160
|
+
description: ""
|
|
1161
|
+
},
|
|
1162
|
+
{
|
|
1163
|
+
name: "ErrTmuxKillFailed",
|
|
1164
|
+
package: "tmux",
|
|
1165
|
+
description: ""
|
|
1166
|
+
},
|
|
1143
1167
|
{
|
|
1144
1168
|
name: "ErrSpawnNotInteractive",
|
|
1145
1169
|
package: "api",
|
|
@@ -1517,10 +1541,6 @@ class SubprocessClient {
|
|
|
1517
1541
|
this.#assertOpen();
|
|
1518
1542
|
return this.#enqueue("expire", params);
|
|
1519
1543
|
}
|
|
1520
|
-
async delete(params) {
|
|
1521
|
-
this.#assertOpen();
|
|
1522
|
-
return this.#enqueue("delete", params);
|
|
1523
|
-
}
|
|
1524
1544
|
async makeTemplate(params) {
|
|
1525
1545
|
this.#assertOpen();
|
|
1526
1546
|
return this.#enqueue("make-template", params);
|
|
@@ -1635,12 +1655,15 @@ export {
|
|
|
1635
1655
|
errorFromEnvelope,
|
|
1636
1656
|
MIN_BINARY_VERSION,
|
|
1637
1657
|
ErrUnknownErrorName,
|
|
1658
|
+
ErrTmuxUnresponsive,
|
|
1638
1659
|
ErrTmuxSessionNameTooLong,
|
|
1639
1660
|
ErrTmuxSessionNameInvalid,
|
|
1640
1661
|
ErrTmuxSessionNameEmpty,
|
|
1641
1662
|
ErrTmuxSessionCreate,
|
|
1663
|
+
ErrTmuxSessionConflict,
|
|
1642
1664
|
ErrTmuxSendKeys,
|
|
1643
1665
|
ErrTmuxNotAvailable,
|
|
1666
|
+
ErrTmuxKillFailed,
|
|
1644
1667
|
ErrTmuxCaptureFailed,
|
|
1645
1668
|
ErrTemplateNotFound,
|
|
1646
1669
|
ErrTemplateNameUnsafe,
|
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
|
*
|
|
@@ -46,8 +46,8 @@ export interface GlobalArgvOptions {
|
|
|
46
46
|
* [cliPath, ...globalFlags, verbName, ...verbFlags]
|
|
47
47
|
*
|
|
48
48
|
* Global flags are inserted BEFORE the verb token because the CLI's
|
|
49
|
-
* `
|
|
50
|
-
* (see
|
|
49
|
+
* `ParseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
|
|
50
|
+
* (see internal/clisetup/globalflags.go). b.32k.
|
|
51
51
|
*
|
|
52
52
|
* @param cliPath The absolute path to the CLI binary (argv[0]).
|
|
53
53
|
* @param verb The kebab-case verb name (must be a VerbName).
|
|
@@ -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,9 +18,15 @@ 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
|
-
* Tilde expansion is handled TS-side by `src/internal/tilde.ts
|
|
22
|
-
*
|
|
23
|
-
*
|
|
21
|
+
* Tilde expansion is handled TS-side by `src/internal/tilde.ts`: in
|
|
22
|
+
* `storePath`, `home` and `tmuxCommand`, a bare `~` or a leading `~/` is
|
|
23
|
+
* expanded against `HOME` (or `os.homedir()` when `HOME` is unset or empty)
|
|
24
|
+
* before the value is forwarded to the CLI subprocess. Other values, relative
|
|
25
|
+
* paths included, are forwarded unchanged and the CLI resolves them.
|
|
26
|
+
*
|
|
27
|
+
* An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
|
|
28
|
+
* `--store-path ""`); the CLI rejects it on every verb call, which then
|
|
29
|
+
* rejects with `ErrInvalidFlags`. It never falls back to the default. b.pu2.
|
|
24
30
|
*/
|
|
25
31
|
export interface ClientOptions {
|
|
26
32
|
/**
|
|
@@ -99,7 +105,12 @@ export interface ListRow {
|
|
|
99
105
|
claude_instance_id: string;
|
|
100
106
|
/** Parent Spawn id (omitted when launched from a plain shell). */
|
|
101
107
|
parent_id?: string;
|
|
102
|
-
/**
|
|
108
|
+
/**
|
|
109
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
110
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
111
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
112
|
+
* prompt. A resumed pending row keeps its session id and history.
|
|
113
|
+
*/
|
|
103
114
|
state: string;
|
|
104
115
|
/** Canonicalized working directory. */
|
|
105
116
|
cwd: string;
|
|
@@ -115,9 +126,24 @@ export interface ListRow {
|
|
|
115
126
|
last_seen_at: string;
|
|
116
127
|
/** Set when state moves to ended (omitted while live). */
|
|
117
128
|
ended_at?: string | null;
|
|
118
|
-
/**
|
|
129
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
130
|
+
launch_started_at?: string | null;
|
|
131
|
+
/**
|
|
132
|
+
* RFC3339 timestamp of the first sweep that left this live row unverified;
|
|
133
|
+
* kept while later sweeps change `liveness_note`. Cleared together with
|
|
134
|
+
* `liveness_note` when a sweep finds the agent process alive; omitted/null
|
|
135
|
+
* while not unverified.
|
|
136
|
+
*/
|
|
119
137
|
liveness_unverified_since?: string | null;
|
|
120
|
-
/**
|
|
138
|
+
/**
|
|
139
|
+
* Reason token of the latest sweep that left this live row unverified (its
|
|
140
|
+
* agent process could not be checked and tmux did not settle it), for
|
|
141
|
+
* example `process_not_seen_session_present`,
|
|
142
|
+
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
143
|
+
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
144
|
+
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
145
|
+
* process alive; omitted/null while not unverified.
|
|
146
|
+
*/
|
|
121
147
|
liveness_note?: string | null;
|
|
122
148
|
}
|
|
123
149
|
/** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
|
|
@@ -142,15 +168,40 @@ export interface SpawnParams {
|
|
|
142
168
|
extra_env?: Record<string, string>;
|
|
143
169
|
/** Pass-through argv to `claude` after --settings. */
|
|
144
170
|
claude_args?: string[];
|
|
145
|
-
/**
|
|
171
|
+
/**
|
|
172
|
+
* Skip pre-writing the folder-trust entry for `cwd` (into
|
|
173
|
+
* `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets `CLAUDE_CONFIG_DIR`,
|
|
174
|
+
* otherwise `~/.claude.json`). The choice is recorded on the row for its life,
|
|
175
|
+
* and every `resume` of that life follows it. The result then reports
|
|
176
|
+
* `pre_trust: "skipped"`. Default false.
|
|
177
|
+
*/
|
|
146
178
|
no_pre_trust?: boolean;
|
|
147
179
|
/** Explicit tmux session name. Auto-derived when absent. */
|
|
148
180
|
tmux_session_name?: string;
|
|
181
|
+
/**
|
|
182
|
+
* Reuse an explicit `claude_instance_id` whose row is `ended` or `missing`;
|
|
183
|
+
* a live row, `pending` included, still collides. No effect without an
|
|
184
|
+
* explicit `claude_instance_id`; applies to this call only. Default false:
|
|
185
|
+
* any existing row with the id collides with `ErrInstanceIdCollision`.
|
|
186
|
+
*/
|
|
187
|
+
reuse_finished?: boolean;
|
|
149
188
|
}
|
|
150
|
-
/**
|
|
189
|
+
/**
|
|
190
|
+
* Mirrors pkg/api/spawn.go::SpawnResult. The row is `pending` from its insert until
|
|
191
|
+
* the agent reports in (Claude Code's SessionStart), then `waiting`.
|
|
192
|
+
*/
|
|
151
193
|
export interface SpawnResult {
|
|
152
194
|
/** The id the new Spawn is tracked under. */
|
|
153
195
|
claude_instance_id: string;
|
|
196
|
+
/**
|
|
197
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
|
|
198
|
+
* written. `"skipped"`: pre-trust was off for this launch because the caller passed
|
|
199
|
+
* `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
|
|
200
|
+
* entry was not written (the `.claude.json` file is missing, or could not be read,
|
|
201
|
+
* parsed or written); the agent may stop at Claude Code's folder-trust prompt.
|
|
202
|
+
* A pre-trust failure never fails the spawn.
|
|
203
|
+
*/
|
|
204
|
+
pre_trust: "ok" | "skipped" | "failed";
|
|
154
205
|
}
|
|
155
206
|
/** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
|
|
156
207
|
export interface StatusParams {
|
|
@@ -159,8 +210,16 @@ export interface StatusParams {
|
|
|
159
210
|
}
|
|
160
211
|
/** Mirrors pkg/api/status.go::StatusResult */
|
|
161
212
|
export interface StatusResult {
|
|
162
|
-
/**
|
|
213
|
+
/**
|
|
214
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
215
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
216
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
217
|
+
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
218
|
+
* from a fresh one by its non-empty `claude_session_id`, shown by `get`.
|
|
219
|
+
*/
|
|
163
220
|
state: string;
|
|
221
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
222
|
+
launch_started_at?: string | null;
|
|
164
223
|
}
|
|
165
224
|
/** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
|
|
166
225
|
export interface GetParams {
|
|
@@ -171,9 +230,18 @@ export interface GetParams {
|
|
|
171
230
|
export interface GetResult {
|
|
172
231
|
claude_instance_id: string;
|
|
173
232
|
parent_id: string;
|
|
233
|
+
/**
|
|
234
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
235
|
+
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
236
|
+
* reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
|
|
237
|
+
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
238
|
+
* `claude_session_id` tells it from a fresh one.
|
|
239
|
+
*/
|
|
174
240
|
state: string;
|
|
175
241
|
cwd: string;
|
|
176
242
|
tmux_session_name: string;
|
|
243
|
+
/** The tmux socket the row's launch uses; omitted for a row from before this release. */
|
|
244
|
+
tmux_socket?: string | null;
|
|
177
245
|
claude_args: string[];
|
|
178
246
|
relay_mode: string;
|
|
179
247
|
jsonl_path: string;
|
|
@@ -185,9 +253,24 @@ export interface GetResult {
|
|
|
185
253
|
last_seen_at: string;
|
|
186
254
|
/** Set when state moves to ended; omitted while live. */
|
|
187
255
|
ended_at?: string | null;
|
|
188
|
-
/**
|
|
256
|
+
/** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
|
|
257
|
+
launch_started_at?: string | null;
|
|
258
|
+
/**
|
|
259
|
+
* RFC3339 timestamp of the first sweep that left this live row unverified;
|
|
260
|
+
* kept while later sweeps change `liveness_note`. Cleared together with
|
|
261
|
+
* `liveness_note` when a sweep finds the agent process alive; omitted/null
|
|
262
|
+
* while not unverified.
|
|
263
|
+
*/
|
|
189
264
|
liveness_unverified_since?: string | null;
|
|
190
|
-
/**
|
|
265
|
+
/**
|
|
266
|
+
* Reason token of the latest sweep that left this live row unverified (its
|
|
267
|
+
* agent process could not be checked and tmux did not settle it), for
|
|
268
|
+
* example `process_not_seen_session_present`,
|
|
269
|
+
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
270
|
+
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
271
|
+
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
272
|
+
* process alive; omitted/null while not unverified.
|
|
273
|
+
*/
|
|
191
274
|
liveness_note?: string | null;
|
|
192
275
|
/** Open permission request; present only when state=check_permission with an undecided row. */
|
|
193
276
|
permission_request?: PermissionRequestInfo | null;
|
|
@@ -196,11 +279,17 @@ export interface GetResult {
|
|
|
196
279
|
export interface SendKeysParams {
|
|
197
280
|
/** Id of the Spawn whose pane will receive the text. */
|
|
198
281
|
claude_instance_id: string;
|
|
199
|
-
/**
|
|
282
|
+
/**
|
|
283
|
+
* Text to deliver to the pane. CR bytes stripped; LF preserved; Enter
|
|
284
|
+
* appended. Empty text sends Enter only: it submits what is already typed,
|
|
285
|
+
* such as a text a failed sendKeys left unsubmitted.
|
|
286
|
+
*/
|
|
200
287
|
text: string;
|
|
201
288
|
/**
|
|
202
|
-
* When true, also
|
|
203
|
-
*
|
|
289
|
+
* When true, also allows a pending row: a launch (spawn, reuse or resume)
|
|
290
|
+
* whose agent has not reported in yet. Keys are delivered only to a
|
|
291
|
+
* session started by the row's current launch. ended and missing rows are
|
|
292
|
+
* still rejected.
|
|
204
293
|
*/
|
|
205
294
|
allow_pending?: boolean;
|
|
206
295
|
}
|
|
@@ -227,13 +316,15 @@ export interface ReadPaneResult {
|
|
|
227
316
|
/** Captured pane text. */
|
|
228
317
|
pane: string;
|
|
229
318
|
}
|
|
230
|
-
/** Mirrors pkg/api.KillParams
|
|
319
|
+
/** Mirrors pkg/api.KillParams. */
|
|
231
320
|
export interface KillParams {
|
|
232
321
|
/** Id of the Spawn to kill. */
|
|
233
322
|
claude_instance_id: string;
|
|
234
323
|
}
|
|
235
|
-
/** Mirrors pkg/api/kill.go::KillResult (
|
|
324
|
+
/** Mirrors pkg/api/kill.go::KillResult (json tags). */
|
|
236
325
|
export interface KillResult {
|
|
326
|
+
/** True exactly when a pane kill or a session kill was sent. */
|
|
327
|
+
kill_sent: boolean;
|
|
237
328
|
}
|
|
238
329
|
/** Mirrors pkg/api.DecideParams (json tags). */
|
|
239
330
|
export interface DecideParams {
|
|
@@ -275,31 +366,66 @@ export interface GetPermissionResult {
|
|
|
275
366
|
}
|
|
276
367
|
/** Mirrors pkg/api.ResumeParams (json tags). */
|
|
277
368
|
export interface ResumeParams {
|
|
278
|
-
/** Id of the
|
|
369
|
+
/** Id of the finished (ended or missing) row to resume. */
|
|
279
370
|
claude_instance_id: string;
|
|
280
371
|
}
|
|
281
|
-
/**
|
|
372
|
+
/**
|
|
373
|
+
* Mirrors pkg/api/resume.go::ResumeResult. Resume moved the row to `pending`, keeping
|
|
374
|
+
* its session id and history, until the agent reports in (Claude Code's SessionStart),
|
|
375
|
+
* then `waiting`.
|
|
376
|
+
*/
|
|
282
377
|
export interface ResumeResult {
|
|
283
|
-
/** Same id that was passed in (
|
|
378
|
+
/** Same id that was passed in (resume preserves it). */
|
|
284
379
|
claude_instance_id: string;
|
|
380
|
+
/**
|
|
381
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
|
|
382
|
+
* written. `"skipped"`: pre-trust was off for this launch because the row records that
|
|
383
|
+
* the spawn that began its life turned it off (`no_pre_trust`); nothing was attempted.
|
|
384
|
+
* `"failed"`: pre-trust was attempted and the entry was not written (the `.claude.json`
|
|
385
|
+
* file is missing, or could not be read, parsed or written); the agent may stop at
|
|
386
|
+
* Claude Code's folder-trust prompt. A pre-trust failure never fails the resume.
|
|
387
|
+
*/
|
|
388
|
+
pre_trust: "ok" | "skipped" | "failed";
|
|
285
389
|
}
|
|
286
|
-
/**
|
|
390
|
+
/** Params for the `find-missing` verb, which takes no CLI flags. */
|
|
287
391
|
export interface FindMissingParams {
|
|
288
|
-
/**
|
|
392
|
+
/**
|
|
393
|
+
* Accepted but not sent: the `find-missing` CLI verb takes no flags, so
|
|
394
|
+
* this value has no effect. The call is bounded by the Client's
|
|
395
|
+
* `callTimeoutMs` like every other verb.
|
|
396
|
+
*/
|
|
289
397
|
timeout_ms?: number;
|
|
290
398
|
}
|
|
291
399
|
/** Mirrors pkg/api/find_missing.go::FindMissingResult */
|
|
292
400
|
export interface FindMissingResult {
|
|
293
|
-
/**
|
|
401
|
+
/**
|
|
402
|
+
* Number of rows this sweep marked `missing` (the length of `ids`). Zero is
|
|
403
|
+
* a normal result when nothing needed marking.
|
|
404
|
+
*/
|
|
294
405
|
count: number;
|
|
295
|
-
/** Sorted ids of rows transitioned to missing. */
|
|
296
|
-
ids: string[];
|
|
297
406
|
/**
|
|
298
|
-
*
|
|
299
|
-
*
|
|
407
|
+
* Sorted ids of rows this sweep marked `missing`, on process or tmux
|
|
408
|
+
* evidence: rows whose agent process (the SessionStart one or the recorded
|
|
409
|
+
* pane's) is dead, and rows whose process could not be checked and tmux
|
|
410
|
+
* found no session or pane of their current launch; a pending row only past
|
|
411
|
+
* the pending grace period. A row whose guarded write found it changed or
|
|
412
|
+
* gone, or failed, is in neither list. `missing` is the sweep's judgement
|
|
413
|
+
* on the evidence available to it, not proof that the agent has exited.
|
|
414
|
+
* Never null; [] when none.
|
|
300
415
|
*/
|
|
416
|
+
ids: string[];
|
|
417
|
+
/** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
|
|
301
418
|
unverified: number;
|
|
302
|
-
/**
|
|
419
|
+
/**
|
|
420
|
+
* Sorted ids of live rows this sweep left unverified with a liveness note,
|
|
421
|
+
* whether it wrote the note or found it already current: rows whose agent
|
|
422
|
+
* process could not be checked and which tmux did not mark, for example
|
|
423
|
+
* because their own session is present, tmux could not tell or was
|
|
424
|
+
* unavailable, or tmux was not called. Never a pending row inside the
|
|
425
|
+
* pending grace period. A row whose guarded write found it changed or gone,
|
|
426
|
+
* or failed, and a row whose note was cleared, is in neither list. Never
|
|
427
|
+
* null; [] when none.
|
|
428
|
+
*/
|
|
303
429
|
unverified_ids: string[];
|
|
304
430
|
}
|
|
305
431
|
/** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
|
|
@@ -312,20 +438,36 @@ export interface ExpireParams {
|
|
|
312
438
|
}
|
|
313
439
|
/** Mirrors pkg/api/expire.go::ExpireResult */
|
|
314
440
|
export interface ExpireResult {
|
|
315
|
-
/**
|
|
441
|
+
/**
|
|
442
|
+
* Number of rows deleted (the length of `ids`): rows deleted after tmux
|
|
443
|
+
* showed no session of the agent (Gone) and its recorded process was not
|
|
444
|
+
* seen running. Zero is a legitimate result when no row was deleted.
|
|
445
|
+
*/
|
|
316
446
|
count: number;
|
|
317
|
-
/**
|
|
447
|
+
/**
|
|
448
|
+
* Sorted ids of the rows deleted after tmux showed no session of the agent
|
|
449
|
+
* (Gone) and its recorded process was not seen running, each only while
|
|
450
|
+
* the row was unchanged since expire examined it. Never null; `[]` when
|
|
451
|
+
* none.
|
|
452
|
+
*/
|
|
318
453
|
ids: string[];
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
454
|
+
/**
|
|
455
|
+
* Number of selected rows kept rather than deleted (the length of
|
|
456
|
+
* `kept_ids`), for example because the agent's process or a session of the
|
|
457
|
+
* agent (its own, or a leftover of an earlier launch) may still run, tmux
|
|
458
|
+
* could not be checked or answered from a different server, the run's tmux
|
|
459
|
+
* time budget (`sweep_budget_seconds`) was spent, or the row changed after
|
|
460
|
+
* it was examined.
|
|
461
|
+
*/
|
|
462
|
+
kept: number;
|
|
463
|
+
/**
|
|
464
|
+
* Sorted ids of the selected rows kept rather than deleted, each reported
|
|
465
|
+
* with its reason in the trail (`ad.expire.kept`). tmux problems and a
|
|
466
|
+
* failed delete of one row never fail the run: the row is kept. A failed
|
|
467
|
+
* read of the selected rows fails the run. A row another caller removed
|
|
468
|
+
* first is in neither list. Never null; `[]` when none.
|
|
469
|
+
*/
|
|
470
|
+
kept_ids: string[];
|
|
329
471
|
}
|
|
330
472
|
/** Mirrors pkg/api.MakeTemplateParams (json tags). */
|
|
331
473
|
export interface MakeTemplateParams {
|