agent-director 0.11.1 → 0.12.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 +317 -144
- package/dist/errors.d.ts +108 -9
- package/dist/index.d.ts +4 -3
- package/dist/index.js +317 -40
- package/dist/internal/argv.d.ts +25 -11
- package/dist/internal/discovery.d.ts +3 -2
- package/dist/internal/errorMap.d.ts +10 -7
- package/dist/internal/subprocessClient.d.ts +37 -6
- package/dist/internal/verbs.d.ts +4 -4
- package/dist/types.d.ts +671 -141
- package/dist/version-floor.json +1 -1
- package/package.json +1 -1
package/dist/types.d.ts
CHANGED
|
@@ -10,13 +10,13 @@ export interface Logger {
|
|
|
10
10
|
error?: (message: string, ...args: unknown[]) => void;
|
|
11
11
|
}
|
|
12
12
|
/**
|
|
13
|
-
* Options accepted by the `Client` constructor
|
|
13
|
+
* Options accepted by the `Client` constructor.
|
|
14
14
|
*
|
|
15
|
-
* All fields are optional. When omitted, the
|
|
15
|
+
* All fields are optional. When omitted, the installed CLI binary's own
|
|
16
16
|
* three-tier default resolution applies (config.toml value, then the CLI's
|
|
17
|
-
* hardcoded fallback such as `~/.agent-director/state.db`). The TS Client
|
|
17
|
+
* hardcoded fallback such as `~/.config/agent-director/state.db`). The TS Client
|
|
18
18
|
* does NOT provide a fallback; it forwards user input verbatim to keep the
|
|
19
|
-
* CLI as the single source of truth for default resolution.
|
|
19
|
+
* CLI as the single source of truth for default resolution.
|
|
20
20
|
*
|
|
21
21
|
* `storePath`, `home` and `tmuxCommand` are forwarded verbatim; the TS Client
|
|
22
22
|
* does no tilde expansion of its own. The CLI subprocess, which inherits this
|
|
@@ -27,11 +27,11 @@ export interface Logger {
|
|
|
27
27
|
* passwd home: with `HOME` unset or empty, a `~` or `~/` `home` rejects every
|
|
28
28
|
* call with `ErrInvalidFlags`, and with no `home` either, every call that
|
|
29
29
|
* opens the store is refused. Other values, relative paths included, are
|
|
30
|
-
* forwarded unchanged and the CLI resolves them.
|
|
30
|
+
* forwarded unchanged and the CLI resolves them.
|
|
31
31
|
*
|
|
32
32
|
* An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
|
|
33
33
|
* `--store-path ""`); the CLI rejects it on every verb call, which then
|
|
34
|
-
* rejects with `ErrInvalidFlags`. It never falls back to the default.
|
|
34
|
+
* rejects with `ErrInvalidFlags`. It never falls back to the default.
|
|
35
35
|
*/
|
|
36
36
|
export interface ClientOptions {
|
|
37
37
|
/**
|
|
@@ -39,11 +39,11 @@ export interface ClientOptions {
|
|
|
39
39
|
* CLI subprocess, which expands a leading `~/`.
|
|
40
40
|
*
|
|
41
41
|
* When omitted, the CLI's three-tier default resolution applies:
|
|
42
|
-
* 1. CLI flag (this field, when set) → 2.
|
|
43
|
-
* ~/.agent-director/config.toml → 3. hardcoded fallback
|
|
44
|
-
* ~/.agent-director/state.db.
|
|
42
|
+
* 1. CLI flag (this field, when set) → 2. [store] db_path in
|
|
43
|
+
* ~/.config/agent-director/config.toml → 3. hardcoded fallback
|
|
44
|
+
* ~/.config/agent-director/state.db.
|
|
45
45
|
*
|
|
46
|
-
* The TS Client
|
|
46
|
+
* The TS Client forwards the option unchanged.
|
|
47
47
|
*/
|
|
48
48
|
storePath?: string;
|
|
49
49
|
/**
|
|
@@ -61,13 +61,25 @@ export interface ClientOptions {
|
|
|
61
61
|
* environment (which is the correct default — set HOME at the
|
|
62
62
|
* test-process level via withTempHome or similar). Set this only when you
|
|
63
63
|
* need the CLI to resolve `~/...` paths against a specific directory that
|
|
64
|
-
* differs from the calling process's HOME.
|
|
64
|
+
* differs from the calling process's HOME.
|
|
65
65
|
*/
|
|
66
66
|
home?: string;
|
|
67
67
|
/**
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
68
|
+
* Whether a call that opens the store creates it when it does not exist.
|
|
69
|
+
*
|
|
70
|
+
* - Omitted: the CLI's default, which creates a missing store.
|
|
71
|
+
* - `true`: a missing store is created (parent directories, file and
|
|
72
|
+
* schema) by the first call that opens it. No flag is forwarded, since
|
|
73
|
+
* this is the CLI's default.
|
|
74
|
+
* - `false`: forwarded as `--create-if-missing false`. A call that opens a
|
|
75
|
+
* missing store rejects with `ErrStoreOpen` (its cause: the store is not
|
|
76
|
+
* initialized) and creates none of it. Calls that open no store, such as
|
|
77
|
+
* `version`, are unaffected.
|
|
78
|
+
*
|
|
79
|
+
* `true` and `false` mirror `pkg/api.Options.CreateIfMissing`; unlike that
|
|
80
|
+
* field, omitting this one keeps the CLI's default, which creates the store.
|
|
81
|
+
* `false` needs a CLI binary that knows `--create-if-missing`: an older
|
|
82
|
+
* binary rejects every call made with it.
|
|
71
83
|
*/
|
|
72
84
|
createIfMissing?: boolean;
|
|
73
85
|
/** Optional logger for client-side warnings (e.g., non-fatal close errors). */
|
|
@@ -80,45 +92,154 @@ export interface ClientOptions {
|
|
|
80
92
|
* in-flight call's promise rejects with ErrCallTimeout.
|
|
81
93
|
*
|
|
82
94
|
* Zero or negative values are rejected at Client construction time.
|
|
83
|
-
*
|
|
95
|
+
*
|
|
96
|
+
* Each store statement a call runs can wait up to the store's busy
|
|
97
|
+
* timeout (`[store] busy_timeout_ms`, 10 s by default) while another
|
|
98
|
+
* process holds the store locked. A call whose waits add up to this
|
|
99
|
+
* timeout, one wait at this length or more or several shorter ones, is
|
|
100
|
+
* cut off with ErrCallTimeout before SQLite gives up. Nothing adjusts this
|
|
101
|
+
* timeout to that key: raise it to match when raising the key.
|
|
84
102
|
*/
|
|
85
103
|
callTimeoutMs?: number;
|
|
86
104
|
}
|
|
87
|
-
/**
|
|
105
|
+
/** One entry in the `help` verb result. */
|
|
88
106
|
export interface VerbSummary {
|
|
89
107
|
/** Canonical CLI/MCP verb name (e.g. "spawn", "send-keys"). */
|
|
90
108
|
name: string;
|
|
91
109
|
/** One-line verb description from the manifest. */
|
|
92
110
|
description: string;
|
|
93
111
|
}
|
|
94
|
-
/**
|
|
95
|
-
|
|
112
|
+
/**
|
|
113
|
+
* A permission request's delivery state:
|
|
114
|
+
* - `"delivered"`: the request's relay hook acknowledged a verdict.
|
|
115
|
+
* - `"not_confirmed"`: no ack yet and the relay hook may still run; it ends by `confirm_by`.
|
|
116
|
+
* - `"fallen_back"`: no ack, and the relay hook is gone (or cannot be checked and `confirm_by`
|
|
117
|
+
* has passed): no answer from the relay reached the agent. While `pane_answer` is `"none"` or
|
|
118
|
+
* `"intent"` the request is open and only an answer at the pane, or `recordPaneAnswer`, closes
|
|
119
|
+
* it; with `"sent"`, `"outside"` or `"tool_ran"` it is closed.
|
|
120
|
+
*/
|
|
121
|
+
export type Delivery = "delivered" | "not_confirmed" | "fallen_back";
|
|
122
|
+
/**
|
|
123
|
+
* How a permission request was answered at the pane:
|
|
124
|
+
* - `"none"`: no pane answer recorded through agent-director (something outside it, such as a
|
|
125
|
+
* person at tmux, may still have answered it).
|
|
126
|
+
* - `"intent"`: a pane answer through `sendKeys` was started; whether its key was typed is unknown.
|
|
127
|
+
* - `"sent"`: a pane answer's key was sent (`decision_reason` `"pane"`).
|
|
128
|
+
* - `"outside"`: a caller recorded it answered outside agent-director (`recordPaneAnswer`,
|
|
129
|
+
* `decision_reason` `"pane_outside"`).
|
|
130
|
+
* - `"tool_ran"`: the agent's hooks reported its tool ran (`decision` `"allow"`, `decision_reason`
|
|
131
|
+
* `"tool_ran"`).
|
|
132
|
+
* `"sent"`, `"outside"` and `"tool_ran"` close the request; its `delivery` stays `"fallen_back"`.
|
|
133
|
+
*/
|
|
134
|
+
export type PaneAnswer = "none" | "intent" | "sent" | "outside" | "tool_ran";
|
|
135
|
+
/**
|
|
136
|
+
* A permission request's delivery facts, with whether the agent's hooks proved its dialog gone, on every
|
|
137
|
+
* `get` / `list` permission request and `get`'s `unproven_requests`, on `getPermission` and on
|
|
138
|
+
* `decide`'s result. Derived on every read. A recorded `decision` is not the outcome:
|
|
139
|
+
* `delivery` is.
|
|
140
|
+
*/
|
|
141
|
+
export interface RequestDelivery {
|
|
142
|
+
/** Delivery state; see {@link Delivery}. */
|
|
143
|
+
delivery: Delivery;
|
|
144
|
+
/**
|
|
145
|
+
* RFC3339 time by which `not_confirmed` ends: the relay hook's kill instant plus 2 s. For a
|
|
146
|
+
* request with no recorded settle instant: `requested_at` plus the relay window plus 2 s.
|
|
147
|
+
*/
|
|
148
|
+
confirm_by: string;
|
|
149
|
+
/**
|
|
150
|
+
* Whether the relay hook process runs: true, false, or null when it cannot be checked
|
|
151
|
+
* (another or unreadable pid namespace, unreadable /proc, or no recorded hook identity).
|
|
152
|
+
*/
|
|
153
|
+
hook_alive: boolean | null;
|
|
154
|
+
/** When a reader first found the request fallen back; null until then. */
|
|
155
|
+
hook_gone_at: string | null;
|
|
156
|
+
/** The verdict a decide refused as fallen back tried to record; null when none. Never acted on. */
|
|
157
|
+
attempted_decision: "allow" | "deny" | null;
|
|
158
|
+
/** When that refused decide ran; null when none. */
|
|
159
|
+
attempted_at: string | null;
|
|
160
|
+
/** The request's tool_use_id from the agent's hook input; null when none was given. */
|
|
161
|
+
tool_use_id: string | null;
|
|
162
|
+
/** How the request was answered at the pane; see {@link PaneAnswer}. */
|
|
163
|
+
pane_answer: PaneAnswer;
|
|
164
|
+
/**
|
|
165
|
+
* The verdict a pane answer claims: allow, deny, or unknown (an outside record that did not see
|
|
166
|
+
* the answer); null when none was recorded. The caller's claim, stored and never checked.
|
|
167
|
+
*/
|
|
168
|
+
pane_as: "allow" | "deny" | "unknown" | null;
|
|
169
|
+
/**
|
|
170
|
+
* When the agent's hooks proved the request's permission dialog gone; null until
|
|
171
|
+
* then. agent-director's own records (`delivered`, a pane answer, `recordPaneAnswer`) are not
|
|
172
|
+
* proof. While it is null, a plain `sendKeys` to the live Spawn without `expect_pane_sha256`,
|
|
173
|
+
* and a `pause`, reject with `ErrDialogMaybeOpen`.
|
|
174
|
+
*/
|
|
175
|
+
proven_gone_at: string | null;
|
|
176
|
+
/** How it was proven gone; see {@link ProvenGoneHow}. Null until proven. */
|
|
177
|
+
proven_gone_how: ProvenGoneHow | null;
|
|
178
|
+
/**
|
|
179
|
+
* For a request not proven gone that no longer awaits an answer in agent-director's records:
|
|
180
|
+
* when its record stopped awaiting one (its relay hook's ack, its pane answer's or
|
|
181
|
+
* `recordPaneAnswer`'s write, or the close of its Spawn's requests; a request with no recorded settle instant: its recorded verdict). Null while it still awaits an answer, and once proven
|
|
182
|
+
* gone. A request that stays unproven a while after it is a reason to read the pane.
|
|
183
|
+
*/
|
|
184
|
+
unproven_since: string | null;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* How the agent's hooks proved a permission request's dialog gone:
|
|
188
|
+
* - `"tool_ran"`: a Claude PostToolUse or PostToolUseFailure carried its `tool_use_id` (never on a
|
|
189
|
+
* Codex row).
|
|
190
|
+
* - `"turn_end"`: the turn of the agent that asked ended after it was written; the main agent's
|
|
191
|
+
* Stop or idle-prompt Notification, or a Codex main agent's Interrupt (Esc), proves a request
|
|
192
|
+
* with no agent_id (including a main-agent request).
|
|
193
|
+
* - `"agent_gone"`: its Spawn was marked missing, ended or resumed.
|
|
194
|
+
*/
|
|
195
|
+
export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
|
|
196
|
+
/**
|
|
197
|
+
* One permission request with its delivery facts:
|
|
198
|
+
* an open one (still awaiting an answer) in the `permission_requests` of a `get` or `list` row in
|
|
199
|
+
* state check_permission; one not proven gone, open or read closed, in `get`'s
|
|
200
|
+
* `unproven_requests`; and the request an `errDetails` names (the base of
|
|
201
|
+
* `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
|
|
202
|
+
*/
|
|
203
|
+
export interface PermissionRequestInfo extends RequestDelivery {
|
|
96
204
|
/** Autoincrement primary key of the permission_requests row. */
|
|
97
205
|
request_id: number;
|
|
98
206
|
/** UUIDv4 token minted by runRelay for this request. Pass to the decide verb to target a specific row. */
|
|
99
207
|
request_token: string;
|
|
100
|
-
/**
|
|
208
|
+
/** Agent tool that triggered the permission request (e.g. "Bash"). */
|
|
101
209
|
tool_name: string;
|
|
102
210
|
/** Raw JSON string of the tool input as stored in the DB. NOT a nested object. */
|
|
103
211
|
tool_input: string;
|
|
104
212
|
/** RFC3339 timestamp when the permission request row was created. */
|
|
105
213
|
requested_at: string;
|
|
214
|
+
/** The recorded verdict, not the outcome (read `delivery`); null while none is recorded. */
|
|
215
|
+
decision: "allow" | "deny" | null;
|
|
216
|
+
/** The recorded verdict's decision_reason; null when none is recorded. */
|
|
217
|
+
decision_reason: string | null;
|
|
106
218
|
}
|
|
107
|
-
/**
|
|
219
|
+
/** One Spawn row returned by the list verb. */
|
|
108
220
|
export interface ListRow {
|
|
109
221
|
/** Stable Spawn id. */
|
|
110
|
-
|
|
222
|
+
instance_id: string;
|
|
111
223
|
/** Parent Spawn id (omitted when launched from a plain shell). */
|
|
112
224
|
parent_id?: string;
|
|
113
225
|
/**
|
|
114
226
|
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
115
227
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
116
|
-
* reported in yet (
|
|
228
|
+
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
117
229
|
* prompt. A resumed pending row keeps its session id and history.
|
|
230
|
+
*
|
|
231
|
+
* With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
|
|
232
|
+
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
233
|
+
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
234
|
+
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
235
|
+
* Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
|
|
236
|
+
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
118
237
|
*/
|
|
119
238
|
state: string;
|
|
120
239
|
/** Canonicalized working directory. */
|
|
121
240
|
cwd: string;
|
|
241
|
+
/** The agent the row runs: `"claude"` (Claude Code) or `"codex"` (Codex). Set at spawn; resume follows it. */
|
|
242
|
+
agent: string;
|
|
122
243
|
/** tmux session name. */
|
|
123
244
|
tmux_session_name: string;
|
|
124
245
|
/** "on" or "off". */
|
|
@@ -131,13 +252,20 @@ export interface ListRow {
|
|
|
131
252
|
last_seen_at: string;
|
|
132
253
|
/** Set when state moves to ended (omitted while live). */
|
|
133
254
|
ended_at?: string | null;
|
|
134
|
-
/**
|
|
255
|
+
/**
|
|
256
|
+
* Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
|
|
257
|
+
* pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
|
|
258
|
+
* set, a row whose agent has reported in can read pending without it for up to settle_ms.
|
|
259
|
+
*/
|
|
135
260
|
launch_started_at?: string | null;
|
|
136
261
|
/**
|
|
137
|
-
* RFC3339 timestamp of the first sweep that
|
|
138
|
-
* kept while later sweeps change
|
|
139
|
-
* `liveness_note`
|
|
140
|
-
*
|
|
262
|
+
* RFC3339 timestamp of the first sweep that noted this live row (left it
|
|
263
|
+
* unverified, or noted it `unreported`); kept while later sweeps change
|
|
264
|
+
* `liveness_note`, `unreported` included. Cleared together with
|
|
265
|
+
* `liveness_note` when a sweep finds the agent process alive, except on a
|
|
266
|
+
* pending row it notes `unreported` and a pending row noted
|
|
267
|
+
* `provenance_conflict`, which keeps it; omitted/null while the row has no
|
|
268
|
+
* note.
|
|
141
269
|
*/
|
|
142
270
|
liveness_unverified_since?: string | null;
|
|
143
271
|
/**
|
|
@@ -147,18 +275,45 @@ export interface ListRow {
|
|
|
147
275
|
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
148
276
|
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
149
277
|
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
150
|
-
* process alive
|
|
278
|
+
* process alive, except on a pending row it notes `unreported` and a
|
|
279
|
+
* pending row noted `provenance_conflict`, which keeps it; omitted/null
|
|
280
|
+
* while the row has no note. Or `unreported`, on a pending row past the
|
|
281
|
+
* pending grace period: its agent is alive, but no hook has reported since
|
|
282
|
+
* its launch, so it may sit at an agent startup screen or idle at its
|
|
283
|
+
* prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
|
|
284
|
+
* with `allow_pending`; only a caller that looked should type. A later
|
|
285
|
+
* sweep that finds the agent alive keeps the note; the agent's next hook
|
|
286
|
+
* clears it. `unreported` never replaces `provenance_conflict`.
|
|
151
287
|
*/
|
|
152
288
|
liveness_note?: string | null;
|
|
289
|
+
/**
|
|
290
|
+
* The row's open permission requests (those still awaiting an answer), each with its
|
|
291
|
+
* delivery facts; populated only when the row's live state is check_permission, `[]`
|
|
292
|
+
* otherwise. A row can read waiting, working or ask_user while a request is still open:
|
|
293
|
+
* follow a tracked request with `getPermission`. Requests are never delayed by
|
|
294
|
+
* `[state] settle_ms`, so with it set a row can also read any state (even ended or missing)
|
|
295
|
+
* with open requests listed, or check_permission with `[]`, for up to settle_ms.
|
|
296
|
+
*/
|
|
297
|
+
permission_requests: PermissionRequestInfo[];
|
|
153
298
|
}
|
|
154
|
-
/**
|
|
299
|
+
/** Parameters for launching a tracked agent. */
|
|
155
300
|
export interface SpawnParams {
|
|
156
|
-
/** Absolute (or ~/-prefixed) path the Spawn's
|
|
301
|
+
/** Absolute (or ~/-prefixed) path the Spawn's agent starts in. Required. */
|
|
157
302
|
cwd: string;
|
|
158
|
-
/** Named template under ~/.agent-director/templates/. */
|
|
303
|
+
/** Named template under ~/.config/agent-director/templates/. */
|
|
159
304
|
template?: string;
|
|
305
|
+
/**
|
|
306
|
+
* The agent to launch: `"claude"` (Claude Code) or `"codex"` (Codex); case-sensitive,
|
|
307
|
+
* empty or absent means not given. Spawn resolves it per call, else from `template`'s
|
|
308
|
+
* `agent`; with neither, the spawn is refused with `ErrAgentMissing`. Any other value is
|
|
309
|
+
* refused with `ErrAgentInvalid`. A template's `agent_args` belong to the template's agent
|
|
310
|
+
* and are refused with `ErrAgentArgsMismatch` when the spawn's agent differs, unless this call
|
|
311
|
+
* passes its own non-empty `agent_args`. The
|
|
312
|
+
* row records it for life; `get` and `list` show it.
|
|
313
|
+
*/
|
|
314
|
+
agent?: string;
|
|
160
315
|
/** Explicit instance id (UUID4 minted when absent). */
|
|
161
|
-
|
|
316
|
+
instance_id?: string;
|
|
162
317
|
/** KEY=VALUE label pairs. */
|
|
163
318
|
label?: string[];
|
|
164
319
|
/** permissions.allow entries. */
|
|
@@ -169,88 +324,152 @@ export interface SpawnParams {
|
|
|
169
324
|
ask?: string[];
|
|
170
325
|
/** "on" | "off" | "" (use config default). */
|
|
171
326
|
relay_mode?: string;
|
|
172
|
-
/**
|
|
327
|
+
/**
|
|
328
|
+
* KEY→VALUE env-var overrides injected on the tmux session. `AGENT_DIRECTOR_*`
|
|
329
|
+
* keys and `HOME` (any value) are refused with `ErrReservedEnvKey`, a template's
|
|
330
|
+
* included: an extra_env `HOME` would move the agent's hook to another
|
|
331
|
+
* agent-director store. Set an absolute `CLAUDE_CONFIG_DIR` (Claude Code) or
|
|
332
|
+
* `CODEX_HOME` (Codex) to give the agent its own config folder. A key that is not a valid env-var name (empty, or
|
|
333
|
+
* containing `=` or a NUL character, which tmux would read as a different
|
|
334
|
+
* variable) is refused with `ErrReservedEnvKey` too, a template's included,
|
|
335
|
+
* and never rewritten; the description says what is wrong with it, and
|
|
336
|
+
* nothing is launched.
|
|
337
|
+
*/
|
|
173
338
|
extra_env?: Record<string, string>;
|
|
174
|
-
/** Pass-through argv to `claude` after --settings. */
|
|
175
|
-
claude_args?: string[];
|
|
176
339
|
/**
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
340
|
+
* Pass-through argv to the agent's program. Claude always refuses `--settings`,
|
|
341
|
+
* `--output-format` and print (`-p`/`--print`, parsed clusters included). Session
|
|
342
|
+
* selectors and owned values are refused except on a finished-agent switch:
|
|
343
|
+
* removed tokens appear in `dropped_args`; the agent starts fresh and resumes nothing.
|
|
344
|
+
* Exact denied long tokens owned as option values always refuse. For codex, a Codex subcommand in
|
|
345
|
+
* command position, `--remote`, `--remote-auth-token-env`, `-c`/`--config` keys at, above or
|
|
346
|
+
* under `hooks`, `tui.disable_paste_burst` or `features.hooks`, and `--disable hooks` are
|
|
347
|
+
* refused (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
|
|
348
|
+
* default_mode_request_user_input` and the question-tool keys are refused too. agent-director
|
|
349
|
+
* adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
|
|
350
|
+
* `--enable write_stdin_approval` when the arguments already carry one before any `--`;
|
|
351
|
+
* Codex rejects a flag the arguments themselves repeat.
|
|
352
|
+
*/
|
|
353
|
+
agent_args?: string[];
|
|
354
|
+
/**
|
|
355
|
+
* Skip the folder pre-trust for `cwd`. For a claude agent, that is pre-writing the
|
|
356
|
+
* folder-trust entry (into `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets
|
|
357
|
+
* `CLAUDE_CONFIG_DIR`, otherwise `~/.claude.json`). For a codex agent, it is putting the
|
|
358
|
+
* folder trust and the hook-trust bypass on the launch's command line (no file is
|
|
359
|
+
* written). The choice is recorded on the row until the next spawn or reuse,
|
|
360
|
+
* and every `resume` follows it. The result then reports
|
|
181
361
|
* `pre_trust: "skipped"`. Default false.
|
|
182
362
|
*/
|
|
183
363
|
no_pre_trust?: boolean;
|
|
184
364
|
/** Explicit tmux session name. Auto-derived when absent. */
|
|
185
365
|
tmux_session_name?: string;
|
|
186
366
|
/**
|
|
187
|
-
* Reuse an explicit `
|
|
367
|
+
* Reuse an explicit `instance_id` whose row is `ended` or `missing`;
|
|
188
368
|
* a live row, `pending` included, still collides. No effect without an
|
|
189
|
-
* explicit `
|
|
190
|
-
*
|
|
369
|
+
* explicit `instance_id`; applies to this call only. The spawn names its
|
|
370
|
+
* agent (`agent`, or the template's) and the reused row takes it; to reuse
|
|
371
|
+
* a row for the agent it ran, pass the row's agent, which `get` shows.
|
|
372
|
+
* Same-agent reuse starts a fresh conversation and retains history and subagent records.
|
|
373
|
+
* An agent switch or switch back starts a new life, hiding earlier lives.
|
|
374
|
+
* Resume continues only the latest session; older sessions are for inspection only.
|
|
375
|
+
* Default false: any existing row with the id collides with
|
|
376
|
+
* `ErrInstanceIdCollision`.
|
|
191
377
|
*/
|
|
192
378
|
reuse_finished?: boolean;
|
|
193
379
|
}
|
|
194
380
|
/**
|
|
195
|
-
*
|
|
196
|
-
* the agent reports in (
|
|
381
|
+
* The launch result. The row is `pending` from its insert until
|
|
382
|
+
* the agent reports in (its SessionStart hook), then `waiting`.
|
|
197
383
|
*/
|
|
198
384
|
export interface SpawnResult {
|
|
199
385
|
/** The id the new Spawn is tracked under. */
|
|
200
|
-
|
|
386
|
+
instance_id: string;
|
|
201
387
|
/**
|
|
202
|
-
* What the launch's folder-trust pre-trust did. `"ok"`: the folder
|
|
203
|
-
*
|
|
388
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
|
|
389
|
+
* (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
|
|
390
|
+
* trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the caller passed
|
|
204
391
|
* `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
|
|
206
|
-
* parsed or written
|
|
207
|
-
*
|
|
392
|
+
* entry was not written (a claude agent: the `.claude.json` file is missing, or could not
|
|
393
|
+
* be read, parsed or written, or `extra_env` sets `CLAUDE_CONFIG_DIR` to a path that is
|
|
394
|
+
* not absolute; a codex agent: `extra_env` sets `CODEX_HOME` to a path that is not
|
|
395
|
+
* absolute, and the launch carries neither the folder trust nor the hook-trust bypass);
|
|
396
|
+
* the agent may stop at its folder-trust prompt. A pre-trust failure never fails the
|
|
397
|
+
* spawn.
|
|
208
398
|
*/
|
|
209
399
|
pre_trust: "ok" | "skipped" | "failed";
|
|
400
|
+
/** Original resume tokens removed on a finished-agent switch, in argv order; omitted when empty. */
|
|
401
|
+
dropped_args?: string[];
|
|
210
402
|
}
|
|
211
|
-
/**
|
|
403
|
+
/** The id whose state is requested. */
|
|
212
404
|
export interface StatusParams {
|
|
213
405
|
/** Id of the Spawn to inspect. */
|
|
214
|
-
|
|
406
|
+
instance_id: string;
|
|
215
407
|
}
|
|
216
|
-
/**
|
|
408
|
+
/** The row's reported lifecycle state. */
|
|
217
409
|
export interface StatusResult {
|
|
218
410
|
/**
|
|
219
411
|
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
220
412
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
221
|
-
* reported in yet (
|
|
413
|
+
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
222
414
|
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
223
|
-
* from a fresh one by its non-empty `
|
|
415
|
+
* from a fresh one by its non-empty `session_id`, shown by `get`.
|
|
416
|
+
*
|
|
417
|
+
* With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
|
|
418
|
+
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
419
|
+
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
420
|
+
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
421
|
+
* Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
|
|
422
|
+
* can be newer: a refusal can name a state status does not show yet.
|
|
224
423
|
*/
|
|
225
424
|
state: string;
|
|
226
|
-
/**
|
|
425
|
+
/**
|
|
426
|
+
* Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
|
|
427
|
+
* pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
|
|
428
|
+
* set, a row whose agent has reported in can read pending without it for up to settle_ms.
|
|
429
|
+
*/
|
|
227
430
|
launch_started_at?: string | null;
|
|
228
431
|
}
|
|
229
|
-
/**
|
|
432
|
+
/** The id whose row is requested. */
|
|
230
433
|
export interface GetParams {
|
|
231
434
|
/** Id of the Spawn to fetch. */
|
|
232
|
-
|
|
435
|
+
instance_id: string;
|
|
233
436
|
}
|
|
234
|
-
/**
|
|
437
|
+
/** One tracked agent row, with its current session and request facts. */
|
|
235
438
|
export interface GetResult {
|
|
236
|
-
|
|
439
|
+
instance_id: string;
|
|
237
440
|
parent_id: string;
|
|
238
441
|
/**
|
|
239
442
|
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
240
443
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
241
|
-
* reported in yet (
|
|
444
|
+
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
242
445
|
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
243
|
-
* `
|
|
446
|
+
* `session_id` tells it from a fresh one.
|
|
447
|
+
*
|
|
448
|
+
* With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
|
|
449
|
+
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
450
|
+
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
451
|
+
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
452
|
+
* Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
|
|
453
|
+
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
244
454
|
*/
|
|
245
455
|
state: string;
|
|
246
456
|
cwd: string;
|
|
457
|
+
/** The agent the row runs: `"claude"` (Claude Code) or `"codex"` (Codex). Set at spawn; resume follows it. */
|
|
458
|
+
agent: string;
|
|
247
459
|
tmux_session_name: string;
|
|
248
|
-
/** The tmux socket the row's launch uses; omitted
|
|
460
|
+
/** The tmux socket the row's launch uses; omitted when the row has no recorded socket. */
|
|
249
461
|
tmux_socket?: string | null;
|
|
250
|
-
|
|
462
|
+
agent_args: string[];
|
|
251
463
|
relay_mode: string;
|
|
464
|
+
/**
|
|
465
|
+
* Current session's transcript path, persisted by its hooks; legacy rows may be empty.
|
|
466
|
+
* Resume tries it, then for Claude recomputes the current session's path from `cwd`
|
|
467
|
+
* and `session_id`, under a usable absolute `CLAUDE_CONFIG_DIR` from `extra_env`
|
|
468
|
+
* (otherwise `~/.claude`). Codex uses only its recorded path. Older sessions remain
|
|
469
|
+
* listed for inspection only and are never resume candidates.
|
|
470
|
+
*/
|
|
252
471
|
jsonl_path: string;
|
|
253
|
-
|
|
472
|
+
session_id: string;
|
|
254
473
|
labels: Record<string, string>;
|
|
255
474
|
/** Row insert time (RFC3339). */
|
|
256
475
|
started_at: string;
|
|
@@ -258,13 +477,20 @@ export interface GetResult {
|
|
|
258
477
|
last_seen_at: string;
|
|
259
478
|
/** Set when state moves to ended; omitted while live. */
|
|
260
479
|
ended_at?: string | null;
|
|
261
|
-
/**
|
|
480
|
+
/**
|
|
481
|
+
* Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
|
|
482
|
+
* pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
|
|
483
|
+
* set, a row whose agent has reported in can read pending without it for up to settle_ms.
|
|
484
|
+
*/
|
|
262
485
|
launch_started_at?: string | null;
|
|
263
486
|
/**
|
|
264
|
-
* RFC3339 timestamp of the first sweep that
|
|
265
|
-
* kept while later sweeps change
|
|
266
|
-
* `liveness_note`
|
|
267
|
-
*
|
|
487
|
+
* RFC3339 timestamp of the first sweep that noted this live row (left it
|
|
488
|
+
* unverified, or noted it `unreported`); kept while later sweeps change
|
|
489
|
+
* `liveness_note`, `unreported` included. Cleared together with
|
|
490
|
+
* `liveness_note` when a sweep finds the agent process alive, except on a
|
|
491
|
+
* pending row it notes `unreported` and a pending row noted
|
|
492
|
+
* `provenance_conflict`, which keeps it; omitted/null while the row has no
|
|
493
|
+
* note.
|
|
268
494
|
*/
|
|
269
495
|
liveness_unverified_since?: string | null;
|
|
270
496
|
/**
|
|
@@ -274,22 +500,55 @@ export interface GetResult {
|
|
|
274
500
|
* `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
|
|
275
501
|
* or `provenance_conflict`; overwritten when the reason changes. Cleared
|
|
276
502
|
* together with `liveness_unverified_since` when a sweep finds the agent
|
|
277
|
-
* process alive
|
|
503
|
+
* process alive, except on a pending row it notes `unreported` and a
|
|
504
|
+
* pending row noted `provenance_conflict`, which keeps it; omitted/null
|
|
505
|
+
* while the row has no note. Or `unreported`, on a pending row past the
|
|
506
|
+
* pending grace period: its agent is alive, but no hook has reported since
|
|
507
|
+
* its launch, so it may sit at an agent startup screen or idle at its
|
|
508
|
+
* prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
|
|
509
|
+
* with `allow_pending`; only a caller that looked should type. A later
|
|
510
|
+
* sweep that finds the agent alive keeps the note; the agent's next hook
|
|
511
|
+
* clears it. `unreported` never replaces `provenance_conflict`.
|
|
278
512
|
*/
|
|
279
513
|
liveness_note?: string | null;
|
|
280
|
-
/**
|
|
281
|
-
|
|
514
|
+
/**
|
|
515
|
+
* The row's open permission requests (those still awaiting an answer: not acked by their relay
|
|
516
|
+
* hook and not answered at the pane, decided or not), each with its delivery facts; populated
|
|
517
|
+
* only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
|
|
518
|
+
* working or ask_user while a request is still open: follow a tracked request with
|
|
519
|
+
* `getPermission`.
|
|
520
|
+
* Requests are never delayed by `[state] settle_ms`, so with it set a row can also read any
|
|
521
|
+
* state (even ended or missing) with open requests listed, or check_permission with `[]`, for
|
|
522
|
+
* up to settle_ms.
|
|
523
|
+
*/
|
|
524
|
+
permission_requests: PermissionRequestInfo[];
|
|
525
|
+
/**
|
|
526
|
+
* Every permission request of the row that the agent's hooks have not proven gone (`proven_gone_at`
|
|
527
|
+
* null), oldest first, in any live state but ended and missing (`[]` on those). Unlike
|
|
528
|
+
* `permission_requests` it also lists requests agent-director's records read closed
|
|
529
|
+
* (delivered, answered at the pane, or recorded answered outside it), each with
|
|
530
|
+
* `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
|
|
531
|
+
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
|
|
532
|
+
* row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
|
|
533
|
+
* with `state` for up to settle_ms.
|
|
534
|
+
*/
|
|
535
|
+
unproven_requests: PermissionRequestInfo[];
|
|
282
536
|
}
|
|
283
|
-
/**
|
|
537
|
+
/**
|
|
538
|
+
* Parameters for sending keys. A call is plain, or a pane answer when
|
|
539
|
+
* `request_token` is set: a pane answer needs `as`, `key` and
|
|
540
|
+
* `expect_pane_sha256`, takes no `text`, and sends exactly one key with no Enter.
|
|
541
|
+
*/
|
|
284
542
|
export interface SendKeysParams {
|
|
285
|
-
/** Id of the Spawn whose pane will receive the
|
|
286
|
-
|
|
543
|
+
/** Id of the Spawn whose pane will receive the keys. */
|
|
544
|
+
instance_id: string;
|
|
287
545
|
/**
|
|
288
|
-
* Text to deliver to the pane. CR bytes stripped; LF preserved; Enter
|
|
289
|
-
* appended
|
|
290
|
-
* such as a text a failed sendKeys left unsubmitted.
|
|
546
|
+
* Text to deliver to the pane on a plain call. CR bytes stripped; LF preserved; Enter
|
|
547
|
+
* appended unless `no_enter`. Empty or omitted text sends Enter only: it submits what is
|
|
548
|
+
* already typed, such as a text a failed sendKeys left unsubmitted. Exclusive with `key`;
|
|
549
|
+
* must be empty on a pane answer.
|
|
291
550
|
*/
|
|
292
|
-
text
|
|
551
|
+
text?: string;
|
|
293
552
|
/**
|
|
294
553
|
* When true, also allows a pending row: a launch (spawn, reuse or resume)
|
|
295
554
|
* whose agent has not reported in yet. Keys are delivered only to a
|
|
@@ -297,15 +556,40 @@ export interface SendKeysParams {
|
|
|
297
556
|
* still rejected.
|
|
298
557
|
*/
|
|
299
558
|
allow_pending?: boolean;
|
|
559
|
+
/** Type `text` with no Enter after it (plain calls; a pane answer never presses Enter). */
|
|
560
|
+
no_enter?: boolean;
|
|
561
|
+
/**
|
|
562
|
+
* One key to send instead of text, never followed by Enter: a named key (`"Escape"`,
|
|
563
|
+
* `"Enter"`, `"Up"`, `"Down"`, `"Tab"`) or one character. Required on a pane answer.
|
|
564
|
+
*/
|
|
565
|
+
key?: string;
|
|
566
|
+
/**
|
|
567
|
+
* The `pane_sha256` of the readPane the keys were chosen from: the pane is captured again
|
|
568
|
+
* with the same `n_lines` (ANSI stripped) and compared byte for byte, `ErrPaneChanged` when it
|
|
569
|
+
* differs (the error does not carry the new hash). Required on a pane answer. On a plain call
|
|
570
|
+
* a matching hash also passes the hold of a request not proven gone (`ErrDialogMaybeOpen`);
|
|
571
|
+
* every other refusal still applies. Never pass it from an automatic flow: it means a person
|
|
572
|
+
* or LLM judged this exact screen.
|
|
573
|
+
*/
|
|
574
|
+
expect_pane_sha256?: string;
|
|
575
|
+
/** The `n_lines` of the readPane `expect_pane_sha256` came from. Defaults to 25. */
|
|
576
|
+
n_lines?: number;
|
|
577
|
+
/**
|
|
578
|
+
* Makes the call a pane answer to this fallen-back permission request of the Spawn: one key
|
|
579
|
+
* (`key`), no Enter, recorded as `pane_answer` `"sent"` with `decision` = `as`.
|
|
580
|
+
*/
|
|
581
|
+
request_token?: string;
|
|
582
|
+
/** A pane answer's claimed verdict, recorded as its decision; never checked against the key. */
|
|
583
|
+
as?: "allow" | "deny";
|
|
300
584
|
}
|
|
301
|
-
/**
|
|
585
|
+
/** Successful sendKeys calls return an empty object. */
|
|
302
586
|
export interface SendKeysResult {
|
|
303
587
|
}
|
|
304
|
-
/**
|
|
588
|
+
/** Parameters for capturing the agent's pane. */
|
|
305
589
|
export interface ReadPaneParams {
|
|
306
590
|
/** Id of the Spawn whose pane will be captured. */
|
|
307
|
-
|
|
308
|
-
/** Trailing lines to return. Defaults to 25 when 0/omitted. */
|
|
591
|
+
instance_id: string;
|
|
592
|
+
/** Trailing lines to return. Defaults to 25 when 0/omitted. A negative value is refused (ErrInvalidFlags). */
|
|
309
593
|
n_lines?: number;
|
|
310
594
|
/** When true return raw bytes (ANSI preserved); when false strip ANSI (default). */
|
|
311
595
|
ansi?: boolean;
|
|
@@ -316,79 +600,229 @@ export interface ReadPaneParams {
|
|
|
316
600
|
*/
|
|
317
601
|
allow_pending?: boolean;
|
|
318
602
|
}
|
|
319
|
-
/**
|
|
603
|
+
/** Captured pane text and its checksum. */
|
|
320
604
|
export interface ReadPaneResult {
|
|
321
605
|
/** Captured pane text. */
|
|
322
606
|
pane: string;
|
|
607
|
+
/**
|
|
608
|
+
* SHA-256, lowercase hex, of exactly the bytes of `pane`. Pass it as sendKeys' or
|
|
609
|
+
* recordPaneAnswer's `expect_pane_sha256`, with the same `n_lines`, when acting on what this
|
|
610
|
+
* pane shows; those compare it with the pane as readPane gives it by default (ANSI stripped).
|
|
611
|
+
*/
|
|
612
|
+
pane_sha256: string;
|
|
323
613
|
}
|
|
324
|
-
/**
|
|
614
|
+
/** Parameters for stopping the tracked agent. */
|
|
325
615
|
export interface KillParams {
|
|
326
616
|
/** Id of the Spawn to kill. */
|
|
327
|
-
|
|
617
|
+
instance_id: string;
|
|
328
618
|
}
|
|
329
|
-
/**
|
|
619
|
+
/** Whether the call sent a kill. */
|
|
330
620
|
export interface KillResult {
|
|
331
621
|
/** True exactly when a pane kill or a session kill was sent. */
|
|
332
622
|
kill_sent: boolean;
|
|
333
623
|
}
|
|
334
|
-
/**
|
|
624
|
+
/** Parameters for deciding one permission request. */
|
|
335
625
|
export interface DecideParams {
|
|
336
626
|
/** Id of the Spawn whose open permission request is being decided. */
|
|
337
|
-
|
|
338
|
-
/** UUIDv4 token identifying the specific permission request to decide. Required
|
|
627
|
+
instance_id: string;
|
|
628
|
+
/** UUIDv4 token identifying the specific permission request to decide. Required (`ErrMissingRequestToken` when absent); optional here for backward-compatible call shape. */
|
|
339
629
|
request_token?: string;
|
|
340
630
|
/** Orchestrator verdict. */
|
|
341
631
|
decision: "allow" | "deny";
|
|
342
|
-
/**
|
|
632
|
+
/** Accepted but ignored; a deny records decision_reason operator regardless of this value. */
|
|
343
633
|
reason?: string;
|
|
634
|
+
/**
|
|
635
|
+
* Optional bound on the whole call, in milliseconds from its start (no default). Required
|
|
636
|
+
* waits before recording, for the store or a request with no recorded settle instant, must
|
|
637
|
+
* fit within it; otherwise `ErrStoreBusy`, nothing recorded, so a retry is safe. With no time
|
|
638
|
+
* left, recording proceeds only if the store is free at once. Once
|
|
639
|
+
* the verdict is recorded the call never rejects with `ErrStoreBusy`: the wait for the relay
|
|
640
|
+
* hook's ack ends at the bound with `not_confirmed`. Pass at most your deadline minus 1 s.
|
|
641
|
+
* Negative: `ErrInvalidFlags`.
|
|
642
|
+
*/
|
|
643
|
+
max_wait_ms?: number;
|
|
344
644
|
}
|
|
345
|
-
/**
|
|
346
|
-
|
|
645
|
+
/**
|
|
646
|
+
* The request's delivery facts once the verdict is
|
|
647
|
+
* recorded, read after decide's wait of at most 1 s for the relay hook's ack. `delivery` is
|
|
648
|
+
* `"delivered"` or `"not_confirmed"` (poll `getPermission`, at the latest at `confirm_by`); a
|
|
649
|
+
* request whose relay hook fell back rejects with `ErrRelayFallenBack` instead.
|
|
650
|
+
*/
|
|
651
|
+
export interface DecideResult extends RequestDelivery {
|
|
652
|
+
delivery: "delivered" | "not_confirmed";
|
|
347
653
|
}
|
|
348
|
-
/**
|
|
654
|
+
/** Parameters for reading one permission request. */
|
|
349
655
|
export interface GetPermissionParams {
|
|
350
656
|
/** UUIDv4 token identifying the permission_requests row to fetch. Required; empty string rejected by the backend. */
|
|
351
657
|
request_token: string;
|
|
352
658
|
}
|
|
353
|
-
/**
|
|
354
|
-
|
|
659
|
+
/**
|
|
660
|
+
* One permission request with its delivery facts.
|
|
661
|
+
* A decided request can remain open until acknowledged. A recorded `decision` is not
|
|
662
|
+
* the outcome: `delivery` is.
|
|
663
|
+
*/
|
|
664
|
+
export interface GetPermissionResult extends RequestDelivery {
|
|
355
665
|
/** UUIDv4 token the row is keyed under (echoed back). */
|
|
356
666
|
request_token: string;
|
|
357
667
|
/** Autoincrement primary key of the permission_requests row. */
|
|
358
668
|
request_id: number;
|
|
359
|
-
/**
|
|
669
|
+
/** Agent tool that triggered the permission request (e.g. "Bash", "Write"). */
|
|
360
670
|
tool_name: string;
|
|
361
671
|
/** Raw JSON string of the tool's input as stored in the DB. NOT a nested object — callers parse it themselves. */
|
|
362
672
|
tool_input: string;
|
|
363
673
|
/** RFC3339 timestamp when the permission request row was created. */
|
|
364
674
|
requested_at: string;
|
|
365
|
-
/**
|
|
675
|
+
/**
|
|
676
|
+
* "allow" or "deny" once decided; null while undecided, and
|
|
677
|
+
* for a recordPaneAnswer claiming unknown.
|
|
678
|
+
*/
|
|
366
679
|
decision?: "allow" | "deny" | null;
|
|
367
|
-
/**
|
|
368
|
-
|
|
369
|
-
|
|
680
|
+
/**
|
|
681
|
+
* Canonical decision-reason string: "operator" | "timeout" | "find_missing" | "ended" for deny
|
|
682
|
+
* rows ("find_missing" / "ended": still undecided when find-missing marked its spawn missing, or
|
|
683
|
+
* when its spawn ended or was resumed, and closed); "pane" | "pane_outside" | "tool_ran" for a
|
|
684
|
+
* request closed at the pane; null while undecided and for allow rows decided by decide.
|
|
685
|
+
*/
|
|
686
|
+
decision_reason?: "operator" | "timeout" | "find_missing" | "ended" | "pane" | "pane_outside" | "tool_ran" | null;
|
|
687
|
+
/** RFC3339 timestamp when the verdict was written; null while undecided. */
|
|
370
688
|
decided_at?: string | null;
|
|
371
689
|
}
|
|
372
|
-
/**
|
|
690
|
+
/**
|
|
691
|
+
* Record that a fallen-back permission
|
|
692
|
+
* request was answered outside agent-director. It types nothing.
|
|
693
|
+
*/
|
|
694
|
+
export interface RecordPaneAnswerParams {
|
|
695
|
+
/** Token of the permission request answered outside agent-director. */
|
|
696
|
+
request_token: string;
|
|
697
|
+
/**
|
|
698
|
+
* How it was answered, as the caller claims: "allow", "deny", or "unknown" when the answer was
|
|
699
|
+
* not seen (pass "unknown" unless it was). Stored, never checked.
|
|
700
|
+
*/
|
|
701
|
+
as: "allow" | "deny" | "unknown";
|
|
702
|
+
/** The `pane_sha256` of the readPane that showed it answered; compared byte for byte. */
|
|
703
|
+
expect_pane_sha256: string;
|
|
704
|
+
/** The `n_lines` of that readPane. Defaults to 25. */
|
|
705
|
+
n_lines?: number;
|
|
706
|
+
}
|
|
707
|
+
/** The request as recordPaneAnswer recorded it. */
|
|
708
|
+
export interface RecordPaneAnswerResult {
|
|
709
|
+
/** The request's token (echoed back). */
|
|
710
|
+
request_token: string;
|
|
711
|
+
/** Always "outside". */
|
|
712
|
+
pane_answer: "outside";
|
|
713
|
+
/** The claim recorded. */
|
|
714
|
+
pane_as: "allow" | "deny" | "unknown";
|
|
715
|
+
/** The claim when "allow" or "deny"; null for "unknown". */
|
|
716
|
+
decision: "allow" | "deny" | null;
|
|
717
|
+
/** Always "pane_outside". */
|
|
718
|
+
decision_reason: "pane_outside";
|
|
719
|
+
}
|
|
720
|
+
/**
|
|
721
|
+
* One other open request of the Spawn in
|
|
722
|
+
* {@link RelayFallenBackDetails}.
|
|
723
|
+
*/
|
|
724
|
+
export interface OpenRequestFacts {
|
|
725
|
+
request_token: string;
|
|
726
|
+
tool_name: string;
|
|
727
|
+
requested_at: string;
|
|
728
|
+
delivery: Delivery;
|
|
729
|
+
hook_alive: boolean | null;
|
|
730
|
+
pane_answer: PaneAnswer;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* ErrRelayFallenBack's errDetails (from decide, a plain
|
|
734
|
+
* sendKeys and pause): the request that fell back (its fields and delivery facts), the Spawn's
|
|
735
|
+
* state and its other open requests (null when they could not be read).
|
|
736
|
+
*/
|
|
737
|
+
export interface RelayFallenBackDetails extends PermissionRequestInfo {
|
|
738
|
+
state: string;
|
|
739
|
+
open_requests: OpenRequestFacts[] | null;
|
|
740
|
+
}
|
|
741
|
+
/**
|
|
742
|
+
* ErrDialogMaybeOpen's errDetails (from a plain
|
|
743
|
+
* sendKeys without `expect_pane_sha256`, and from pause): the oldest request of the Spawn that
|
|
744
|
+
* the agent's hooks have not proven gone (its fields and delivery facts: how agent-director's records
|
|
745
|
+
* say it closed, `delivery` and `pane_answer`, and since when, `unproven_since`), the Spawn's
|
|
746
|
+
* state, and the Spawn's other requests not proven gone, oldest first.
|
|
747
|
+
*/
|
|
748
|
+
export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
|
|
749
|
+
state: string;
|
|
750
|
+
unproven_requests: PermissionRequestInfo[];
|
|
751
|
+
}
|
|
752
|
+
/**
|
|
753
|
+
* ErrPaneAnswerInProgress's errDetails: another
|
|
754
|
+
* pane answer on the request is still being sent.
|
|
755
|
+
*/
|
|
756
|
+
export interface PaneAnswerInProgressDetails {
|
|
757
|
+
request_token: string;
|
|
758
|
+
pane_as: string;
|
|
759
|
+
pane_intent_at: string;
|
|
760
|
+
/** true when its sender process runs; null when it cannot be checked. */
|
|
761
|
+
sender_alive: boolean | null;
|
|
762
|
+
/** When the sender cannot be checked, the time the intent stops counting; else null. */
|
|
763
|
+
not_before: string | null;
|
|
764
|
+
}
|
|
765
|
+
/**
|
|
766
|
+
* ErrClaimTooSoon's errDetails: retry recordPaneAnswer
|
|
767
|
+
* at `not_before` (null only while the request's relay hook is seen running).
|
|
768
|
+
*/
|
|
769
|
+
export interface ClaimTooSoonDetails {
|
|
770
|
+
request_token: string;
|
|
771
|
+
hook_alive: boolean | null;
|
|
772
|
+
hook_gone_at: string | null;
|
|
773
|
+
not_before: string | null;
|
|
774
|
+
}
|
|
775
|
+
/**
|
|
776
|
+
* The errDetails of an ErrInternal from a pane answer
|
|
777
|
+
* (`sendKeys` with `request_token`) whose key was sent but whose record of it failed: the key
|
|
778
|
+
* reached the pane, so read it before anything else is sent.
|
|
779
|
+
*/
|
|
780
|
+
export interface PaneKeySentDetails {
|
|
781
|
+
key_sent: true;
|
|
782
|
+
request_token: string;
|
|
783
|
+
}
|
|
784
|
+
/**
|
|
785
|
+
* ErrPaneChanged's errDetails. It never carries the pane's
|
|
786
|
+
* new hash: read the pane again before any retry.
|
|
787
|
+
*/
|
|
788
|
+
export interface PaneChangedDetails {
|
|
789
|
+
n_lines: number;
|
|
790
|
+
request_token?: string;
|
|
791
|
+
}
|
|
792
|
+
/** Parameters for relaunching the latest session. */
|
|
373
793
|
export interface ResumeParams {
|
|
374
|
-
/** Id of the finished (ended or missing) row
|
|
375
|
-
|
|
794
|
+
/** Id of the finished (ended or missing) row whose latest session is resumed. */
|
|
795
|
+
instance_id: string;
|
|
376
796
|
}
|
|
377
797
|
/**
|
|
378
|
-
*
|
|
379
|
-
*
|
|
798
|
+
* Resume relaunches only the latest session
|
|
799
|
+
* of the row's recorded agent. Older sessions remain listed for inspection only.
|
|
800
|
+
* Stored session selectors and Claude print mode are removed from replay;
|
|
801
|
+
* cloud controls also lose their values when selector removal leaves no parsed
|
|
802
|
+
* environment/pool context. Other arguments and option-owned values survive.
|
|
803
|
+
* Claude inputs missing a recognized required value get literal filtering only;
|
|
804
|
+
* parsed-role preservation applies when all required values are present.
|
|
805
|
+
* Claude prompts move behind surviving options and --, and altered short clusters
|
|
806
|
+
* are re-encoded, only when needed to preserve their original parsed meaning;
|
|
807
|
+
* otherwise their order and spelling survive. Stored agent_args are unchanged.
|
|
808
|
+
* Resume moved the row to `pending`, keeping
|
|
809
|
+
* its session id and history, until the agent reports in (its SessionStart hook),
|
|
380
810
|
* then `waiting`.
|
|
381
811
|
*/
|
|
382
812
|
export interface ResumeResult {
|
|
383
813
|
/** Same id that was passed in (resume preserves it). */
|
|
384
|
-
|
|
814
|
+
instance_id: string;
|
|
385
815
|
/**
|
|
386
|
-
* What the launch's folder-trust pre-trust did. `"ok"`: the folder
|
|
387
|
-
*
|
|
388
|
-
*
|
|
389
|
-
*
|
|
390
|
-
*
|
|
391
|
-
*
|
|
816
|
+
* What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
|
|
817
|
+
* (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
|
|
818
|
+
* trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the row records that
|
|
819
|
+
* the row's latest spawn turned it off (`no_pre_trust`); nothing was attempted.
|
|
820
|
+
* `"failed"`: pre-trust was attempted and the entry was not written (a claude agent: the
|
|
821
|
+
* `.claude.json` file is missing, or could not be read, parsed or written, or the row's
|
|
822
|
+
* `extra_env` sets `CLAUDE_CONFIG_DIR` to a path that is not absolute; a codex agent: the
|
|
823
|
+
* row's `extra_env` sets `CODEX_HOME` to a path that is not absolute, and the launch
|
|
824
|
+
* carries neither the folder trust nor the hook-trust bypass); the agent may stop at its
|
|
825
|
+
* folder-trust prompt. A pre-trust failure never fails the resume.
|
|
392
826
|
*/
|
|
393
827
|
pre_trust: "ok" | "skipped" | "failed";
|
|
394
828
|
}
|
|
@@ -401,11 +835,12 @@ export interface FindMissingParams {
|
|
|
401
835
|
*/
|
|
402
836
|
timeout_ms?: number;
|
|
403
837
|
}
|
|
404
|
-
/**
|
|
838
|
+
/** Rows marked missing, ended or left unverified by the sweep. */
|
|
405
839
|
export interface FindMissingResult {
|
|
406
840
|
/**
|
|
407
|
-
* Number of rows this sweep marked `missing` (the length of `ids`)
|
|
408
|
-
* a normal result when
|
|
841
|
+
* Number of rows this sweep marked `missing` (the length of `ids`); a Codex
|
|
842
|
+
* row it moved to `ended` is not counted. Zero is a normal result when
|
|
843
|
+
* nothing needed marking.
|
|
409
844
|
*/
|
|
410
845
|
count: number;
|
|
411
846
|
/**
|
|
@@ -413,10 +848,13 @@ export interface FindMissingResult {
|
|
|
413
848
|
* evidence: rows whose agent process (the SessionStart one or the recorded
|
|
414
849
|
* pane's) is dead, and rows whose process could not be checked and tmux
|
|
415
850
|
* found no session or pane of their current launch; a pending row only past
|
|
416
|
-
* the pending grace period
|
|
417
|
-
*
|
|
418
|
-
*
|
|
419
|
-
*
|
|
851
|
+
* the pending grace period, and never while the spawn, reuse or resume that
|
|
852
|
+
* began its launch still runs. A row whose guarded write found it changed or
|
|
853
|
+
* gone, or failed, is in neither list, and so is a Codex row the sweep moved
|
|
854
|
+
* to `ended` (its agent process gone and an end report held) and a pending
|
|
855
|
+
* row the sweep notes `unreported` (its agent alive) or finds already noted
|
|
856
|
+
* so. `missing` is the sweep's judgement on the evidence available to it, not
|
|
857
|
+
* proof that the agent has exited. Never null; [] when none.
|
|
420
858
|
*/
|
|
421
859
|
ids: string[];
|
|
422
860
|
/** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
|
|
@@ -427,13 +865,15 @@ export interface FindMissingResult {
|
|
|
427
865
|
* process could not be checked and which tmux did not mark, for example
|
|
428
866
|
* because their own session is present, tmux could not tell or was
|
|
429
867
|
* unavailable, or tmux was not called. Never a pending row inside the
|
|
430
|
-
* pending grace period. A row whose guarded write
|
|
431
|
-
* or failed,
|
|
432
|
-
*
|
|
868
|
+
* pending grace period or while its launch runs. A row whose guarded write
|
|
869
|
+
* found it changed or gone, or failed, a row whose note was cleared, and a
|
|
870
|
+
* pending row noted `unreported` (its agent alive, no hook reported since
|
|
871
|
+
* its launch; find it by `liveness_note` in `get` or `list`) are in neither
|
|
872
|
+
* list. Never null; [] when none.
|
|
433
873
|
*/
|
|
434
874
|
unverified_ids: string[];
|
|
435
875
|
}
|
|
436
|
-
/**
|
|
876
|
+
/** The minimum finished-row age for cleanup. */
|
|
437
877
|
export interface ExpireParams {
|
|
438
878
|
/**
|
|
439
879
|
* Duration override (e.g. "7d", "2h", "0d"). When omitted, the config
|
|
@@ -441,7 +881,7 @@ export interface ExpireParams {
|
|
|
441
881
|
*/
|
|
442
882
|
older_than?: string;
|
|
443
883
|
}
|
|
444
|
-
/**
|
|
884
|
+
/** Rows deleted or kept by the cleanup. */
|
|
445
885
|
export interface ExpireResult {
|
|
446
886
|
/**
|
|
447
887
|
* Number of rows deleted (the length of `ids`): rows deleted after tmux
|
|
@@ -474,17 +914,33 @@ export interface ExpireResult {
|
|
|
474
914
|
*/
|
|
475
915
|
kept_ids: string[];
|
|
476
916
|
}
|
|
477
|
-
/**
|
|
917
|
+
/** Parameters for writing a named template. */
|
|
478
918
|
export interface MakeTemplateParams {
|
|
479
919
|
/** Template filename (without extension). Must be filename-safe. Required. */
|
|
480
920
|
name: string;
|
|
481
921
|
/** Default working directory to bake in. */
|
|
482
922
|
cwd?: string;
|
|
923
|
+
/**
|
|
924
|
+
* The agent the template belongs to: `"claude"` (Claude Code) or `"codex"` (Codex);
|
|
925
|
+
* case-sensitive, empty or absent means not given. Required when the template bakes in
|
|
926
|
+
* `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex template cannot bake in
|
|
927
|
+
* `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). Any other value is refused
|
|
928
|
+
* with `ErrTemplateMalformed` (`ErrAgentInvalid` is spawn's per-call refusal). A spawn
|
|
929
|
+
* that names no agent takes it from the template.
|
|
930
|
+
*/
|
|
931
|
+
agent?: string;
|
|
483
932
|
/** Default relay mode: "on" | "off" | "" (inherit). */
|
|
484
933
|
relay_mode?: string;
|
|
485
|
-
/** Default
|
|
486
|
-
|
|
487
|
-
/**
|
|
934
|
+
/** Default agent argv. Per-call `agent_args` replaces wholesale. */
|
|
935
|
+
agent_args?: string[];
|
|
936
|
+
/**
|
|
937
|
+
* Env-var overrides to bake in. A key spawn would refuse is refused here with
|
|
938
|
+
* `ErrReservedEnvKey` and nothing is written: `AGENT_DIRECTOR_*` keys, `HOME`
|
|
939
|
+
* (any value), and a key that is not a valid env-var name (empty, or
|
|
940
|
+
* containing `=` or a NUL character); the description says which. Set an absolute
|
|
941
|
+
* `CLAUDE_CONFIG_DIR` (Claude Code) or `CODEX_HOME` (Codex) to give the agent its
|
|
942
|
+
* own config folder.
|
|
943
|
+
*/
|
|
488
944
|
extra_env?: Record<string, string>;
|
|
489
945
|
/** Label k=v entries to bake in. */
|
|
490
946
|
label?: string[];
|
|
@@ -501,14 +957,17 @@ export interface MakeTemplateParams {
|
|
|
501
957
|
*/
|
|
502
958
|
overwrite?: boolean;
|
|
503
959
|
}
|
|
504
|
-
/**
|
|
960
|
+
/** The template's saved path. */
|
|
505
961
|
export interface MakeTemplateResult {
|
|
506
962
|
/** Absolute path of the written template TOML file. */
|
|
507
963
|
path: string;
|
|
508
964
|
}
|
|
509
|
-
/**
|
|
965
|
+
/** Filters for listing tracked agent rows. */
|
|
510
966
|
export interface ListParams {
|
|
511
|
-
/**
|
|
967
|
+
/**
|
|
968
|
+
* Filter by state (multiple values OR together). With `[state] settle_ms` set it matches the
|
|
969
|
+
* settled state each row's `state` shows, before `limit` applies.
|
|
970
|
+
*/
|
|
512
971
|
state?: string[];
|
|
513
972
|
/** Filter by label k=v pairs (multiple entries AND together). */
|
|
514
973
|
label?: string[];
|
|
@@ -518,29 +977,100 @@ export interface ListParams {
|
|
|
518
977
|
cwd?: string;
|
|
519
978
|
/** Filter by tmux session name exact match. */
|
|
520
979
|
tmux_session_name?: string;
|
|
521
|
-
/** Cap result count. 0/omitted means no cap. */
|
|
980
|
+
/** Cap result count. 0/omitted means no cap. A negative value is refused (ErrInvalidFlags). */
|
|
522
981
|
limit?: number;
|
|
523
982
|
}
|
|
524
|
-
/**
|
|
983
|
+
/** Matching tracked agent rows. */
|
|
525
984
|
export interface ListResult {
|
|
526
985
|
/** Matching Spawn rows. Empty array when none match. */
|
|
527
986
|
spawns: ListRow[];
|
|
528
987
|
}
|
|
529
|
-
/**
|
|
988
|
+
/** The id whose subagent records are requested. */
|
|
989
|
+
export interface ListSubagentsParams {
|
|
990
|
+
/** Id of the Spawn whose subagents to list. */
|
|
991
|
+
instance_id: string;
|
|
992
|
+
}
|
|
993
|
+
/**
|
|
994
|
+
* One subagent record. Every key is always present; a field with
|
|
995
|
+
* no known value is `null`. Each time is an RFC3339 UTC string with millisecond precision
|
|
996
|
+
* (trailing zeros dropped, no fraction on a whole second), exactly as the CLI prints it.
|
|
997
|
+
*/
|
|
998
|
+
export interface SubagentRecord {
|
|
999
|
+
/** The subagent's id, unique among the records shown for its row. */
|
|
1000
|
+
subagent_id: string;
|
|
1001
|
+
/** The id of the row (agent) the subagent belongs to. */
|
|
1002
|
+
instance_id: string;
|
|
1003
|
+
/** The session of the event that created the record; never changed after. */
|
|
1004
|
+
session_id: string | null;
|
|
1005
|
+
/** The subagent's type. */
|
|
1006
|
+
subagent_type: string | null;
|
|
1007
|
+
/** The short description the launching call gave the subagent; never the prompt text. */
|
|
1008
|
+
description: string | null;
|
|
1009
|
+
/** The model the subagent runs. */
|
|
1010
|
+
model: string | null;
|
|
1011
|
+
/**
|
|
1012
|
+
* What launched the subagent: `"agent"` (the row's own agent, so `parent_id` is the row's
|
|
1013
|
+
* instance_id) or `"subagent"` (another subagent, so `parent_id` is that subagent's id).
|
|
1014
|
+
*/
|
|
1015
|
+
parent_type: "agent" | "subagent" | null;
|
|
1016
|
+
/** The instance_id or the parent subagent's id, as `parent_type` says. */
|
|
1017
|
+
parent_id: string | null;
|
|
1018
|
+
/** The id of the tool call that launched the subagent. */
|
|
1019
|
+
tool_use_id: string | null;
|
|
1020
|
+
/** `"background"` or `"foreground"`. */
|
|
1021
|
+
run_mode: "background" | "foreground" | null;
|
|
1022
|
+
/** When the subagent first started. */
|
|
1023
|
+
first_started_at: string | null;
|
|
1024
|
+
/** When the subagent's latest run started. */
|
|
1025
|
+
started_at: string | null;
|
|
1026
|
+
/** When the subagent last stopped; null if it never has (kept when it runs again). */
|
|
1027
|
+
stopped_at: string | null;
|
|
1028
|
+
/** When the subagent was judged lost; null unless it was. */
|
|
1029
|
+
lost_at: string | null;
|
|
1030
|
+
/**
|
|
1031
|
+
* `"running"` (started, neither stopped nor judged lost), `"stopped"` (its agent reported it
|
|
1032
|
+
* finished) or `"lost"` (judged gone without a stop report).
|
|
1033
|
+
*/
|
|
1034
|
+
state: string;
|
|
1035
|
+
/**
|
|
1036
|
+
* Why the subagent is no longer running; null exactly while `state` is `"running"`:
|
|
1037
|
+
* `"stop_event"` (its agent reported it finished), `"absent_from_snapshot"` (a snapshot of the
|
|
1038
|
+
* agent's running background tasks did not list it) or `"agent_gone"` (its agent ended, went
|
|
1039
|
+
* missing or began a new launch).
|
|
1040
|
+
*/
|
|
1041
|
+
close_reason: "stop_event" | "absent_from_snapshot" | "agent_gone" | null;
|
|
1042
|
+
}
|
|
1043
|
+
/** The current life's subagent records and tracking status. */
|
|
1044
|
+
export interface ListSubagentsResult {
|
|
1045
|
+
/**
|
|
1046
|
+
* Whether the row's launch registered subagent tracking: false for a row launched before
|
|
1047
|
+
* subagent tracking existed, which has no records, and false for a row whose launch
|
|
1048
|
+
* registers no subagent events; true for any other row.
|
|
1049
|
+
*/
|
|
1050
|
+
tracked: boolean;
|
|
1051
|
+
/**
|
|
1052
|
+
* Every subagent record of the row's current life, across every launch of it, ordered by
|
|
1053
|
+
* `first_started_at` ascending (a null one last), then `subagent_id`. Empty array when it has none.
|
|
1054
|
+
*/
|
|
1055
|
+
subagents: SubagentRecord[];
|
|
1056
|
+
}
|
|
1057
|
+
/** Parameters for asking a waiting agent to exit. */
|
|
530
1058
|
export interface PauseParams {
|
|
531
1059
|
/** Id of the Spawn to pause gracefully. */
|
|
532
|
-
|
|
1060
|
+
instance_id: string;
|
|
533
1061
|
}
|
|
534
|
-
/**
|
|
1062
|
+
/** Successful pause calls return an empty object. */
|
|
535
1063
|
export interface PauseResult {
|
|
536
1064
|
}
|
|
537
|
-
/**
|
|
1065
|
+
/** The version call takes no parameters. */
|
|
538
1066
|
export interface VersionParams {
|
|
539
1067
|
}
|
|
540
|
-
/**
|
|
1068
|
+
/** The installed npm package's version. */
|
|
541
1069
|
export interface VersionResult {
|
|
542
|
-
/** npm package version (e.g. "0.5.0"). Sourced from the installed agent-director package's package.json — not the CLI binary.
|
|
1070
|
+
/** npm package version (e.g. "0.5.0"). Sourced from the installed agent-director package's package.json — not the CLI binary. */
|
|
543
1071
|
version: string;
|
|
544
1072
|
/** CLI binary's full git SHA. "unknown" for unstamped builds. */
|
|
545
1073
|
commit: string;
|
|
1074
|
+
/** Directory the CLI binary keeps agent-director's files in: "~/.config/agent-director", unexpanded, for every HOME. */
|
|
1075
|
+
config_dir: string;
|
|
546
1076
|
}
|