agent-director 0.18.1 → 0.18.3

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 CHANGED
@@ -25,10 +25,11 @@ its version must meet the client floor.
25
25
  ## Supported platforms
26
26
 
27
27
  - `linux/x64` (Linux on x86_64)
28
+ - `linux/arm64` (Linux on arm64/aarch64)
28
29
  - `darwin/arm64` (Apple Silicon Mac, macOS 13 or later)
29
30
 
30
- Package installation may also succeed on `linux/arm64` and `darwin/x64`;
31
- those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
31
+ Package installation may also succeed on `darwin/x64`, where no CLI installs.
32
+ See [Requirements](../../docs/install.md#requirements).
32
33
 
33
34
  ## Quick start
34
35
 
@@ -146,7 +147,7 @@ handling are in the [caller contract](../../docs/caller-contract.md#cursor-opera
146
147
 
147
148
  Get the current lifecycle state of a Spawn.
148
149
 
149
- `status`, `get`, `list` and `sweep` (also `findMissing`) share
150
+ `status`, `get`, `getMany`, `list` and `sweep` (also `findMissing`) share
150
151
  [bounded recovery](../../docs/caller-contract.md#bounded-recovery-on-state-reads).
151
152
  Single-row reads check only that row; read success does not confirm every write.
152
153
 
@@ -191,11 +192,31 @@ state last changed; `StatusResult` does not. The
191
192
  [caller contract](../../docs/caller-contract.md#state-change-time) defines it
192
193
  and how it differs from `last_seen_at`, the settled `state` and `since`.
193
194
 
194
- `status`, `get` and `list` use `[state] settle_ms` in the CLI's
195
+ `status`, `get`, `getMany` and `list` use `[state] settle_ms` in the CLI's
195
196
  `~/.config/agent-director/config.toml` for [independent state and family
196
197
  settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
197
198
  Spawn judge its live state, which can be newer than its reported state.
198
199
 
200
+ ### getMany
201
+
202
+ ```ts
203
+ const result = await client.getMany({ instance_ids: ["agent-a", "agent-b"] });
204
+ for (const row of result.spawns) {
205
+ console.log(row.instance_id, row.state);
206
+ }
207
+ console.log(result.not_found);
208
+ ```
209
+
210
+ Returns `GetManyResult`; each `spawns` element is `get`'s `GetResult`, with
211
+ the fields and guarantees described here. Ordering, the Id Cap and read
212
+ failures are defined in the
213
+ [caller contract](../../docs/caller-contract.md#reading-many-agents).
214
+
215
+ Before running anything, the client refuses with `ErrInvalidFlags` an ID
216
+ equal to `--store-path`, `--home`, `--tmux-command` or `--create-if-missing`,
217
+ starting with one of them followed by `=`, or containing a NUL byte. The
218
+ error names its 1-based position.
219
+
199
220
  ### list
200
221
 
201
222
  Query Spawns with optional filters.
@@ -584,7 +605,7 @@ comparing two real versions should use a standard semver library;
584
605
  agent-director does not export a comparator.
585
606
 
586
607
  The floor is a construction check, not feature negotiation: an older CLI
587
- that meets it can lack `sweep` (an unknown-verb error) and return
608
+ that meets it can lack `sweep` or `getMany` (`ErrUnknownVerb`) and return
588
609
  `status`/`get`/`list`/`findMissing` results without `process_liveness`,
589
610
  `confirmations` or `checks`, which the client does not synthesize. Those
590
611
  need the CLI release matching this package ([install guide](../../docs/install.md)).
@@ -628,12 +649,13 @@ try {
628
649
  ```
629
650
 
630
651
  Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
631
- the error envelope's optional `err_details` object, or `null`. Seven errors
652
+ the error envelope's optional `err_details` object, or `null`. Eight errors
632
653
  carry one, typed as exported interfaces: `ErrRelayFallenBack`
633
654
  (`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
634
655
  (`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
635
656
  `ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
636
- (`DialogMaybeOpenDetails`), `ErrPauseTimeout` (`PauseTimeoutDetails`) and
657
+ (`DialogMaybeOpenDetails`), `ErrPauseTimeout` (`PauseTimeoutDetails`),
658
+ `ErrTooManyIds` (`TooManyIdsDetails`) and
637
659
  `ErrSubmissionUnconfirmed`
638
660
  (`SubmissionUnconfirmedDetails`, for failed fallback hook observation).
639
661
  Native, Claude readiness, Claude paced typing, Codex paste and Cursor gateway
@@ -760,7 +782,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
760
782
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
761
783
  | `ErrNoOpenPermissionRequest` | No eligible permission request matches the `(instance_id, request_token)` pair, including a closed, proven-gone or obsolete request. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or shared recovery or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when shared recovery marked it `missing`) before the request relay acknowledged its recorded verdict, the missing mark's own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (for a request with a settle instant, `"delivered"` requires durable relay acknowledgement; requests recorded by an older binary retain the [legacy delivery rules](../../docs/permissions.md#requests-recorded-by-an-older-binary), including derived delivery after expiry even when closed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
762
784
  | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the recorded decision and acknowledgement prevent a second API answer. Acknowledgement does not establish agent receipt or dialog closure; see [Permission relay](../../docs/caller-contract.md#permission-relay). It also includes a request shared recovery denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay acknowledged, or one already closed at the pane, throws it too. |
763
- | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). `status`, `get`, `list`, `sweep` and `findMissing` throw it when a bounded store read does not finish in time; see [Bounded recovery on state reads](../../docs/caller-contract.md#bounded-recovery-on-state-reads). |
785
+ | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). `status`, `get`, `getMany`, `list`, `sweep` and `findMissing` throw it when a bounded store read does not finish in time; see [Bounded recovery on state reads](../../docs/caller-contract.md#bounded-recovery-on-state-reads). |
764
786
  | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
765
787
  | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
766
788
 
@@ -777,7 +799,8 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
777
799
 
778
800
  | Error | When it fires |
779
801
  |---|---|
780
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
802
+ | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; `getMany` received no IDs, an empty or repeated ID, or an ID the client [cannot pass to the CLI](#getmany); a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
803
+ | `ErrTooManyIds` | `getMany` received more IDs than the configured Id Cap; `errDetails` is `TooManyIdsDetails` with `id_cap`. See [Reading many agents](../../docs/caller-contract.md#reading-many-agents) for handling. |
781
804
 
782
805
  **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
783
806
 
package/dist/errors.d.ts CHANGED
@@ -230,6 +230,9 @@ export declare class ErrAgentCapabilityUnsupported extends AgentDirectorError {
230
230
  /** The pane-only launch has no explicit model. */
231
231
  export declare class ErrModelMissing extends AgentDirectorError {
232
232
  }
233
+ /** A required host credential is unset or empty in agent-director's environment. */
234
+ export declare class ErrHostCredentialMissing extends AgentDirectorError {
235
+ }
233
236
  /** Mirrors ErrAgentMissing (package: spawn) */
234
237
  export declare class ErrAgentMissing extends AgentDirectorError {
235
238
  }
@@ -413,6 +416,12 @@ export declare class ErrMissingRequestToken extends AgentDirectorError {
413
416
  /** Mirrors ErrInvalidFlags (package: api) */
414
417
  export declare class ErrInvalidFlags extends AgentDirectorError {
415
418
  }
419
+ /**
420
+ * Mirrors ErrTooManyIds (package: api). `errDetails` is a `TooManyIdsDetails`
421
+ * whose `id_cap` is the Id Cap in force; split the ids into calls of at most that many.
422
+ */
423
+ export declare class ErrTooManyIds extends AgentDirectorError {
424
+ }
416
425
  /** Mirrors ErrConfigMalformed (package: clisetup) */
417
426
  export declare class ErrConfigMalformed extends AgentDirectorError {
418
427
  }
package/dist/index.d.ts CHANGED
@@ -7,9 +7,9 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
8
  export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
9
9
  ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
10
- ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrExperimentalAgentDisabled, ErrAgentCapabilityUnsupported, ErrModelMissing, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrExperimentalAgentDisabled, ErrAgentCapabilityUnsupported, ErrModelMissing, ErrHostCredentialMissing, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrTooManyIds, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
11
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
12
12
  export type { ClientOptions, Logger } from "./types.js";
13
13
  export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, IdleScreenAvailability, ProcessLiveness, Confirmation, Confirmations, ConfirmationStatus, ConfirmationSource, ConfirmationReason, } from "./types.js";
14
- export type { PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
- export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, SweepCheck, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
14
+ export type { TooManyIdsDetails, PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
+ export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, GetManyParams, GetManyResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, SweepCheck, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
package/dist/index.js CHANGED
@@ -30,6 +30,7 @@ __export(exports_errors, {
30
30
  ErrUnknownVerb: () => ErrUnknownVerb,
31
31
  ErrUnknownErrorName: () => ErrUnknownErrorName,
32
32
  ErrTrailWrite: () => ErrTrailWrite,
33
+ ErrTooManyIds: () => ErrTooManyIds,
33
34
  ErrTmuxUnresponsive: () => ErrTmuxUnresponsive,
34
35
  ErrTmuxSessionNameTooLong: () => ErrTmuxSessionNameTooLong,
35
36
  ErrTmuxSessionNameInvalid: () => ErrTmuxSessionNameInvalid,
@@ -83,6 +84,7 @@ __export(exports_errors, {
83
84
  ErrInvalidDecision: () => ErrInvalidDecision,
84
85
  ErrInternal: () => ErrInternal,
85
86
  ErrInstanceIdCollision: () => ErrInstanceIdCollision,
87
+ ErrHostCredentialMissing: () => ErrHostCredentialMissing,
86
88
  ErrExperimentalAgentDisabled: () => ErrExperimentalAgentDisabled,
87
89
  ErrDialogMaybeOpen: () => ErrDialogMaybeOpen,
88
90
  ErrCwdNotFound: () => ErrCwdNotFound,
@@ -298,6 +300,9 @@ class ErrAgentCapabilityUnsupported extends AgentDirectorError {
298
300
  class ErrModelMissing extends AgentDirectorError {
299
301
  }
300
302
 
303
+ class ErrHostCredentialMissing extends AgentDirectorError {
304
+ }
305
+
301
306
  class ErrAgentMissing extends AgentDirectorError {
302
307
  }
303
308
 
@@ -436,6 +441,9 @@ class ErrMissingRequestToken extends AgentDirectorError {
436
441
  class ErrInvalidFlags extends AgentDirectorError {
437
442
  }
438
443
 
444
+ class ErrTooManyIds extends AgentDirectorError {
445
+ }
446
+
439
447
  class ErrConfigMalformed extends AgentDirectorError {
440
448
  }
441
449
 
@@ -473,6 +481,7 @@ var ERROR_TABLE = {
473
481
  ErrExperimentalAgentDisabled,
474
482
  ErrAgentCapabilityUnsupported,
475
483
  ErrModelMissing,
484
+ ErrHostCredentialMissing,
476
485
  ErrAgentMissing,
477
486
  ErrAgentInvalid,
478
487
  ErrAgentArgsMismatch,
@@ -513,6 +522,7 @@ var ERROR_TABLE = {
513
522
  ErrInvalidDecision,
514
523
  ErrMissingRequestToken,
515
524
  ErrInvalidFlags,
525
+ ErrTooManyIds,
516
526
  ErrTemplateNameUnsafe,
517
527
  ErrTemplateNotFound,
518
528
  ErrTemplateMalformed,
@@ -940,6 +950,12 @@ import { readFile } from "fs/promises";
940
950
  import { statSync as statSync2 } from "fs";
941
951
 
942
952
  // src/internal/argv.ts
953
+ var GLOBAL_FLAGS = [
954
+ "--store-path",
955
+ "--home",
956
+ "--tmux-command",
957
+ "--create-if-missing"
958
+ ];
943
959
  function buildArgv(cliPath, verb, params, globalOpts) {
944
960
  refuseOldKeys(verb, params);
945
961
  const globalFlags = buildGlobalFlags(globalOpts);
@@ -983,6 +999,8 @@ function buildVerbFlags(verb, params) {
983
999
  return buildStatus(params);
984
1000
  case "get":
985
1001
  return buildGet(params);
1002
+ case "get-many":
1003
+ return buildGetMany(params);
986
1004
  case "send-keys":
987
1005
  return buildSendKeys(params);
988
1006
  case "read-pane":
@@ -1016,6 +1034,17 @@ function buildVerbFlags(verb, params) {
1016
1034
  }
1017
1035
  }
1018
1036
  }
1037
+ function buildGetMany(p) {
1038
+ for (const [i, id] of p.instance_ids.entries()) {
1039
+ if (GLOBAL_FLAGS.some((flag) => id === flag || id.startsWith(`${flag}=`))) {
1040
+ throw new ErrInvalidFlags("get-many", "ErrInvalidFlags", `get-many: id at position ${i + 1} would be consumed as a CLI global flag`);
1041
+ }
1042
+ if (id.includes("\x00")) {
1043
+ throw new ErrInvalidFlags("get-many", "ErrInvalidFlags", `get-many: id at position ${i + 1} contains a NUL byte, which a CLI argument cannot carry`);
1044
+ }
1045
+ }
1046
+ return ["get-many", ...p.instance_ids];
1047
+ }
1019
1048
  function buildVersion() {
1020
1049
  return ["version"];
1021
1050
  }
@@ -1300,6 +1329,11 @@ var catalog_default = [
1300
1329
  package: "spawn",
1301
1330
  description: ""
1302
1331
  },
1332
+ {
1333
+ name: "ErrHostCredentialMissing",
1334
+ package: "spawn",
1335
+ description: "A required host credential is unset or empty in agent-director's own environment; the launch refuses before mutation."
1336
+ },
1303
1337
  {
1304
1338
  name: "ErrAgentMissing",
1305
1339
  package: "spawn",
@@ -1500,6 +1534,11 @@ var catalog_default = [
1500
1534
  package: "api",
1501
1535
  description: ""
1502
1536
  },
1537
+ {
1538
+ name: "ErrTooManyIds",
1539
+ package: "api",
1540
+ description: ""
1541
+ },
1503
1542
  {
1504
1543
  name: "ErrMissingRequestToken",
1505
1544
  package: "api",
@@ -1814,6 +1853,10 @@ class SubprocessClient {
1814
1853
  this.#assertOpen();
1815
1854
  return this.#enqueue("get", params);
1816
1855
  }
1856
+ async getMany(params) {
1857
+ this.#assertOpen();
1858
+ return this.#enqueue("get-many", params);
1859
+ }
1817
1860
  async sendKeys(params) {
1818
1861
  this.#assertOpen();
1819
1862
  return this.#enqueue("send-keys", params);
@@ -1974,6 +2017,7 @@ export {
1974
2017
  ErrUnknownVerb,
1975
2018
  ErrUnknownErrorName,
1976
2019
  ErrTrailWrite,
2020
+ ErrTooManyIds,
1977
2021
  ErrTmuxUnresponsive,
1978
2022
  ErrTmuxSessionNameTooLong,
1979
2023
  ErrTmuxSessionNameInvalid,
@@ -2027,6 +2071,7 @@ export {
2027
2071
  ErrInvalidDecision,
2028
2072
  ErrInternal,
2029
2073
  ErrInstanceIdCollision,
2074
+ ErrHostCredentialMissing,
2030
2075
  ErrExperimentalAgentDisabled,
2031
2076
  ErrDialogMaybeOpen,
2032
2077
  ErrCwdNotFound,
@@ -7,7 +7,7 @@
7
7
  * [cliPath, ...globalFlags, verbName, ...verbFlags]
8
8
  *
9
9
  * Rules:
10
- * - Long-flag form only (e.g. --cwd, --instance-id).
10
+ * - Long-flag form (e.g. --cwd, --instance-id); get-many takes ids as words.
11
11
  * - No shell interpolation, no sh -c.
12
12
  * - Mapping between camelCase method name and kebab CLI verb follows the
13
13
  * same mapping in src/internal/verbs.ts.
@@ -25,12 +25,16 @@
25
25
  * names are refused with ErrReservedEnvKey, the name the CLI gives every
26
26
  * refused extra_env key, thrown from buildArgv, so no subprocess runs
27
27
  * (b.vpb, b.66q; see extraEnvFlags).
28
+ * - get-many refuses ids the CLI cannot carry: global-flag names (including
29
+ * equals spellings) and NUL bytes, before any subprocess runs.
28
30
  *
29
31
  * Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
30
32
  *
31
33
  * Internal — NOT re-exported from src/index.ts.
32
34
  */
33
35
  import type { VerbName } from "./verbs.js";
36
+ /** The CLI global flags ParseGlobalFlags takes anywhere in argv. Internal only. */
37
+ export declare const GLOBAL_FLAGS: readonly ["--store-path", "--home", "--tmux-command", "--create-if-missing"];
34
38
  /**
35
39
  * GlobalArgvOptions — values for the global CLI flags (b.32k, b.78b). Each
36
40
  * field is optional; when undefined the corresponding flag is omitted from
@@ -24,7 +24,7 @@
24
24
  * and the timeout was not the cause, ErrConsumerSignal is thrown.
25
25
  */
26
26
  import type { ClientOptions } from "../types.js";
27
- import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
27
+ import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, GetManyParams, GetManyResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
28
28
  /**
29
29
  * Internal construction parameters. Carries pre-resolved binaryPath +
30
30
  * binaryVersion so the runtime constructor doesn't run discovery itself.
@@ -101,6 +101,8 @@ export declare class SubprocessClient {
101
101
  status(params: StatusParams): Promise<StatusResult>;
102
102
  /** get — fetch the full Spawn record. */
103
103
  get(params: GetParams): Promise<GetResult>;
104
+ /** getMany — fetch get's full rows in order, listing ids without a record separately. */
105
+ getMany(params: GetManyParams): Promise<GetManyResult>;
104
106
  /**
105
107
  * sendKeys — send keystrokes to a Spawn's tmux pane: text (Enter appended unless no_enter) or
106
108
  * one key; with request_token, a pane answer to a fallen-back permission request (one key, no
@@ -6,7 +6,7 @@
6
6
  * pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
7
7
  * and excludes the three non-callable verbs (help, serve, hook).
8
8
  *
9
- * Currently 18 callable verbs: spawn, status, get, send-keys, read-pane,
9
+ * Currently 19 callable verbs: spawn, status, get, get-many, send-keys, read-pane,
10
10
  * kill, decide, get-permission, record-pane-answer, resume, sweep, find-missing,
11
11
  * expire, make-template, list, list-subagents, pause, version.
12
12
  *
@@ -14,6 +14,6 @@
14
14
  * intentionally excluded here. The .go source wins.
15
15
  */
16
16
  /** All callable verbs in their canonical kebab form (matches manifest). */
17
- export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "record-pane-answer", "resume", "sweep", "find-missing", "expire", "make-template", "list", "list-subagents", "pause", "version"];
17
+ export declare const VERBS: readonly ["spawn", "status", "get", "get-many", "send-keys", "read-pane", "kill", "decide", "get-permission", "record-pane-answer", "resume", "sweep", "find-missing", "expire", "make-template", "list", "list-subagents", "pause", "version"];
18
18
  /** Union type of every callable verb name. */
19
19
  export type VerbName = (typeof VERBS)[number];
package/dist/types.d.ts CHANGED
@@ -774,6 +774,18 @@ export interface GetResult {
774
774
  */
775
775
  unproven_requests: PermissionRequestInfo[];
776
776
  }
777
+ /** The ids whose full rows are requested, in order. */
778
+ export interface GetManyParams {
779
+ /** One up to the configured Id Cap (20 by default), none empty or repeated. */
780
+ instance_ids: string[];
781
+ }
782
+ /** Full get rows and ids without a record, each in input order. */
783
+ export interface GetManyResult {
784
+ /** Exactly get's result for each found id. Always an array, never null. */
785
+ spawns: GetResult[];
786
+ /** Ids without a record. Always an array, never null. */
787
+ not_found: string[];
788
+ }
777
789
  /**
778
790
  * Parameters for sending keys. A call is plain, or a pane answer when
779
791
  * `request_token` is set: a pane answer needs `as`, `key` and
@@ -967,6 +979,11 @@ export interface RecordPaneAnswerResult {
967
979
  /** Always "pane_outside". */
968
980
  decision_reason: "pane_outside";
969
981
  }
982
+ /** ErrTooManyIds's errDetails: the Id Cap in force for the refusing call. */
983
+ export interface TooManyIdsDetails {
984
+ /** Maximum number of ids accepted in one call. */
985
+ id_cap: number;
986
+ }
970
987
  /**
971
988
  * ErrPauseTimeout's errDetails after exit keys were sent but ended was not
972
989
  * observed. Pass the outcome to a caller that can inspect the session and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.18.1",
3
+ "version": "0.18.3",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],