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