agent-director 0.18.0 → 0.18.2
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 +32 -9
- package/dist/errors.d.ts +9 -0
- package/dist/index.d.ts +3 -3
- package/dist/index.js +45 -0
- package/dist/internal/argv.d.ts +5 -1
- package/dist/internal/subprocessClient.d.ts +3 -1
- package/dist/internal/verbs.d.ts +2 -2
- package/dist/types.d.ts +17 -0
- package/package.json +1 -1
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 `
|
|
31
|
-
|
|
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`
|
|
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`.
|
|
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`)
|
|
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,
|
package/dist/internal/argv.d.ts
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* [cliPath, ...globalFlags, verbName, ...verbFlags]
|
|
8
8
|
*
|
|
9
9
|
* Rules:
|
|
10
|
-
* - Long-flag form
|
|
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
|
package/dist/internal/verbs.d.ts
CHANGED
|
@@ -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
|
|
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
|