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/internal/argv.d.ts
CHANGED
|
@@ -7,16 +7,24 @@
|
|
|
7
7
|
* [cliPath, ...globalFlags, verbName, ...verbFlags]
|
|
8
8
|
*
|
|
9
9
|
* Rules:
|
|
10
|
-
* - Long-flag form only (e.g. --cwd, --
|
|
10
|
+
* - Long-flag form only (e.g. --cwd, --instance-id).
|
|
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.
|
|
14
14
|
* - Optional fields are omitted when undefined / falsy.
|
|
15
15
|
* - Boolean flags (--no-pre-trust, --reuse-finished, --ansi, --overwrite)
|
|
16
16
|
* are only appended when the field is explicitly true.
|
|
17
|
-
* - Global flags (b.32k: --store-path, --home, --tmux-command
|
|
18
|
-
* BEFORE the verb token so the CLI's
|
|
19
|
-
* internal/clisetup/globalflags.go strips them
|
|
17
|
+
* - Global flags (b.32k: --store-path, --home, --tmux-command; b.78b:
|
|
18
|
+
* --create-if-missing) appear BEFORE the verb token so the CLI's
|
|
19
|
+
* global-flag parser in internal/clisetup/globalflags.go strips them
|
|
20
|
+
* prior to verb dispatch.
|
|
21
|
+
* - A params object carrying an old key (OLD_PARAM_KEYS) is refused with
|
|
22
|
+
* ErrInvalidFlags naming the new key, thrown from buildArgv before any
|
|
23
|
+
* argv is built, so no subprocess runs (SR-4.3).
|
|
24
|
+
* - spawn's and make-template's extra_env keys that are not valid env-var
|
|
25
|
+
* names are refused with ErrReservedEnvKey, the name the CLI gives every
|
|
26
|
+
* refused extra_env key, thrown from buildArgv, so no subprocess runs
|
|
27
|
+
* (b.vpb, b.66q; see extraEnvFlags).
|
|
20
28
|
*
|
|
21
29
|
* Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
|
|
22
30
|
*
|
|
@@ -24,11 +32,11 @@
|
|
|
24
32
|
*/
|
|
25
33
|
import type { VerbName } from "./verbs.js";
|
|
26
34
|
/**
|
|
27
|
-
* GlobalArgvOptions — values for the
|
|
28
|
-
*
|
|
29
|
-
*
|
|
35
|
+
* GlobalArgvOptions — values for the global CLI flags (b.32k, b.78b). Each
|
|
36
|
+
* field is optional; when undefined the corresponding flag is omitted from
|
|
37
|
+
* argv and the CLI's own default-resolution kicks in.
|
|
30
38
|
*
|
|
31
|
-
*
|
|
39
|
+
* Path values are forwarded verbatim; the CLI expands `~` in them (b.38a).
|
|
32
40
|
*/
|
|
33
41
|
export interface GlobalArgvOptions {
|
|
34
42
|
/** Path forwarded to the CLI as `--store-path`. */
|
|
@@ -37,6 +45,12 @@ export interface GlobalArgvOptions {
|
|
|
37
45
|
home?: string;
|
|
38
46
|
/** Path forwarded to the CLI as `--tmux-command`. */
|
|
39
47
|
tmuxCommand?: string;
|
|
48
|
+
/**
|
|
49
|
+
* `false` is forwarded to the CLI as `--create-if-missing false`. `true`
|
|
50
|
+
* adds no flag: creating a missing store is already the CLI's default, and
|
|
51
|
+
* a binary older than the flag would reject every call that carries it.
|
|
52
|
+
*/
|
|
53
|
+
createIfMissing?: boolean;
|
|
40
54
|
}
|
|
41
55
|
/**
|
|
42
56
|
* buildArgv converts a CLI binary path, verb name, and typed parameters into
|
|
@@ -52,9 +66,9 @@ export interface GlobalArgvOptions {
|
|
|
52
66
|
* @param verb The kebab-case verb name (must be a VerbName).
|
|
53
67
|
* @param params The typed params object for the verb.
|
|
54
68
|
* @param globalOpts Optional global-flag values (--store-path / --home /
|
|
55
|
-
* --tmux-command). When undefined or
|
|
56
|
-
* no global flags appear in argv and
|
|
57
|
-
* own default-resolution.
|
|
69
|
+
* --tmux-command / --create-if-missing). When undefined or
|
|
70
|
+
* all-fields-omitted, no global flags appear in argv and
|
|
71
|
+
* the CLI applies its own default-resolution.
|
|
58
72
|
* @returns The full argv array starting with cliPath.
|
|
59
73
|
*/
|
|
60
74
|
export declare function buildArgv(cliPath: string, verb: VerbName, params: unknown, globalOpts?: GlobalArgvOptions): string[];
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
* discovery.ts — system-install discovery pipeline (b.ue3 / SR-1).
|
|
3
3
|
*
|
|
4
4
|
* Implements the two-step lookup defined in SR-1.1:
|
|
5
|
-
* 1. Standard install path: $HOME/.agent-director/bin/agent-director
|
|
5
|
+
* 1. Standard install path: $HOME/.config/agent-director/bin/agent-director
|
|
6
|
+
* ($HOME only; XDG_CONFIG_HOME is never read).
|
|
6
7
|
* Skipped (no candidate manufactured) when HOME is unset/empty/non-absolute.
|
|
7
8
|
* 2. PATH lookup for "agent-director", first match.
|
|
8
9
|
*
|
|
@@ -13,7 +14,7 @@
|
|
|
13
14
|
* Internal — not re-exported from src/index.ts.
|
|
14
15
|
*/
|
|
15
16
|
import { dirname } from "node:path";
|
|
16
|
-
declare const STANDARD_INSTALL_PATH_RELATIVE = ".agent-director/bin/agent-director";
|
|
17
|
+
declare const STANDARD_INSTALL_PATH_RELATIVE = ".config/agent-director/bin/agent-director";
|
|
17
18
|
/** Result of a successful candidate validation. */
|
|
18
19
|
export interface DiscoveredCandidate {
|
|
19
20
|
/** Canonicalized absolute path to the binary (symlinks resolved). */
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* errorMap.ts — catalog-driven static error map for the subprocess Client.
|
|
3
3
|
*
|
|
4
4
|
* Builds a `Map<string, ErrConstructor>` at module load time by iterating
|
|
5
|
-
* `pkg/api/errnames/catalog.json` (
|
|
5
|
+
* `pkg/api/errnames/catalog.json` (61 entries). The map
|
|
6
6
|
* keys are the canonical `err_name` strings (e.g. "ErrSpawnNotFound");
|
|
7
7
|
* values are the typed constructors already exported from `src/errors.ts`.
|
|
8
8
|
*
|
|
@@ -10,10 +10,9 @@
|
|
|
10
10
|
* - Looks up `envelope.err_name` in the static map.
|
|
11
11
|
* - Throws the typed subclass when found (carrying verb + envelope fields).
|
|
12
12
|
* - Throws `ErrUnknownErrorName` when the err_name is not in the map
|
|
13
|
-
* (SRD SR-4.3)
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* ErrUnknownVerb, ErrJSONMarshal and ErrTrailWrite (tracked in b.cm7).
|
|
13
|
+
* (SRD SR-4.3). The catalog lists every name the binary of this client's
|
|
14
|
+
* version emits (b.cm7), so that means a binary of another version,
|
|
15
|
+
* most often a newer one, emitted a name this client does not know.
|
|
17
16
|
* Callers read `unknownName` for the real err_name.
|
|
18
17
|
*
|
|
19
18
|
* Implements SRD SR-4.1 (static module-load-time map), SR-4.2 (throw by
|
|
@@ -23,7 +22,7 @@
|
|
|
23
22
|
* Internal — NOT re-exported from src/index.ts.
|
|
24
23
|
*/
|
|
25
24
|
import * as errors from "../errors.js";
|
|
26
|
-
type ErrConstructor = new (verb: string, err_name: string, err_description: string) => errors.AgentDirectorError;
|
|
25
|
+
type ErrConstructor = new (verb: string, err_name: string, err_description: string, err_details?: Readonly<Record<string, unknown>> | null) => errors.AgentDirectorError;
|
|
27
26
|
/**
|
|
28
27
|
* errorMap maps every err_name string from catalog.json to its typed
|
|
29
28
|
* AgentDirectorError constructor. Built once at module load.
|
|
@@ -33,10 +32,14 @@ type ErrConstructor = new (verb: string, err_name: string, err_description: stri
|
|
|
33
32
|
* throwFromEnvelope helper handles the miss via ErrUnknownErrorName.
|
|
34
33
|
*/
|
|
35
34
|
export declare const errorMap: ReadonlyMap<string, ErrConstructor>;
|
|
36
|
-
/**
|
|
35
|
+
/**
|
|
36
|
+
* Shape of a JSON envelope that carries a typed error. `err_details` is
|
|
37
|
+
* optional (b.146 rule 15): an object of facts, absent on most errors.
|
|
38
|
+
*/
|
|
37
39
|
interface ErrorEnvelope {
|
|
38
40
|
err_name: string;
|
|
39
41
|
err_description: string;
|
|
42
|
+
err_details?: unknown;
|
|
40
43
|
}
|
|
41
44
|
/**
|
|
42
45
|
* isErrorEnvelope returns true when the parsed envelope contains an err_name
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
* and the timeout was not the cause, ErrConsumerSignal is thrown.
|
|
25
25
|
*/
|
|
26
26
|
import type { ClientOptions } from "../types.js";
|
|
27
|
-
import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } 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, 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.
|
|
@@ -95,13 +95,17 @@ export declare class SubprocessClient {
|
|
|
95
95
|
* @internal Tests only.
|
|
96
96
|
*/
|
|
97
97
|
_assertOpenForTests(): void;
|
|
98
|
-
/** spawn — launch a tracked
|
|
98
|
+
/** spawn — launch a tracked agent in tmux; dropped_args reports removed resume tokens on a switch that starts fresh. */
|
|
99
99
|
spawn(params: SpawnParams): Promise<SpawnResult>;
|
|
100
100
|
/** status — get the current state of a Spawn. */
|
|
101
101
|
status(params: StatusParams): Promise<StatusResult>;
|
|
102
102
|
/** get — fetch the full Spawn record. */
|
|
103
103
|
get(params: GetParams): Promise<GetResult>;
|
|
104
|
-
/**
|
|
104
|
+
/**
|
|
105
|
+
* sendKeys — send keystrokes to a Spawn's tmux pane: text (Enter appended unless no_enter) or
|
|
106
|
+
* one key; with request_token, a pane answer to a fallen-back permission request (one key, no
|
|
107
|
+
* Enter).
|
|
108
|
+
*/
|
|
105
109
|
sendKeys(params: SendKeysParams): Promise<SendKeysResult>;
|
|
106
110
|
/** readPane — read the current contents of a Spawn's tmux pane. */
|
|
107
111
|
readPane(params: ReadPaneParams): Promise<ReadPaneResult>;
|
|
@@ -111,9 +115,22 @@ export declare class SubprocessClient {
|
|
|
111
115
|
decide(params: DecideParams): Promise<DecideResult>;
|
|
112
116
|
/** getPermission — fetch a permission_requests row by request_token. */
|
|
113
117
|
getPermission(params: GetPermissionParams): Promise<GetPermissionResult>;
|
|
114
|
-
/**
|
|
118
|
+
/**
|
|
119
|
+
* recordPaneAnswer — record that a fallen-back permission request was answered outside
|
|
120
|
+
* agent-director (types nothing). Rejects with ErrClaimTooSoon (retry at errDetails.not_before)
|
|
121
|
+
* until its relay hook has been gone 2 s, and with ErrPaneChanged when the pane no longer has
|
|
122
|
+
* expect_pane_sha256.
|
|
123
|
+
*/
|
|
124
|
+
recordPaneAnswer(params: RecordPaneAnswerParams): Promise<RecordPaneAnswerResult>;
|
|
125
|
+
/** resume — relaunch the latest session of a finished row interactively,
|
|
126
|
+
* filtering stored session selectors, Claude print mode and orphaned cloud
|
|
127
|
+
* controls while preserving other arguments and option-owned values. Claude
|
|
128
|
+
* inputs missing a recognized required value get literal filtering only;
|
|
129
|
+
* parsed-role preservation applies when all required values are present. Claude
|
|
130
|
+
* prompts move behind surviving options and --, and altered short clusters are
|
|
131
|
+
* re-encoded, only when needed to preserve their original parsed meaning. */
|
|
115
132
|
resume(params: ResumeParams): Promise<ResumeResult>;
|
|
116
|
-
/** findMissing — sweep live Spawns, marking each `missing` or leaving it unverified on process and tmux evidence; see FindMissingResult. */
|
|
133
|
+
/** findMissing — sweep live Spawns, marking each `missing` (a Codex row with its end report: `ended`) or leaving it unverified on process and tmux evidence; see FindMissingResult. */
|
|
117
134
|
findMissing(params: FindMissingParams): Promise<FindMissingResult>;
|
|
118
135
|
/**
|
|
119
136
|
* expire — remove finished rows older than the retention window whose
|
|
@@ -124,7 +141,21 @@ export declare class SubprocessClient {
|
|
|
124
141
|
makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
|
|
125
142
|
/** list — query Spawns with optional filter params. */
|
|
126
143
|
list(params: ListParams): Promise<ListResult>;
|
|
127
|
-
/**
|
|
144
|
+
/**
|
|
145
|
+
* listSubagents — whether an agent tracks subagents, and every subagent record of the row's
|
|
146
|
+
* current life, across every launch of it. Rejects with ErrSpawnNotFound when no row has the id.
|
|
147
|
+
*/
|
|
148
|
+
listSubagents(params: ListSubagentsParams): Promise<ListSubagentsResult>;
|
|
149
|
+
/**
|
|
150
|
+
* pause — politely shut down a waiting Spawn. Held like a plain sendKeys without
|
|
151
|
+
* expect_pane_sha256: rejects, typing nothing, with ErrSendKeysWhileRelayed, ErrRelayFallenBack
|
|
152
|
+
* or ErrDialogMaybeOpen whenever that sendKeys would. It takes no pane hash, and the hold
|
|
153
|
+
* (ErrDialogMaybeOpen) lasts until the agent's hooks prove each request gone, whatever is
|
|
154
|
+
* done at the pane. Past it: readPane, answer any dialog, then sendKeys `/exit` with the judged
|
|
155
|
+
* pane's expect_pane_sha256; or kill. On a Codex row whose agent process is gone and which
|
|
156
|
+
* holds an end report, pause moves the row to `ended` (before typing anything, or while it
|
|
157
|
+
* waits) and succeeds.
|
|
158
|
+
*/
|
|
128
159
|
pause(params: PauseParams): Promise<PauseResult>;
|
|
129
160
|
/** version — return the npm package version (b.6o1) plus the CLI's commit SHA. */
|
|
130
161
|
version(params: VersionParams): Promise<VersionResult>;
|
package/dist/internal/verbs.d.ts
CHANGED
|
@@ -6,14 +6,14 @@
|
|
|
6
6
|
* pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
|
|
7
7
|
* and excludes the three non-callable verbs (help, serve, hook).
|
|
8
8
|
*
|
|
9
|
-
* Currently
|
|
10
|
-
* kill, decide, get-permission, resume, find-missing,
|
|
11
|
-
* make-template, list, pause, version.
|
|
9
|
+
* Currently 17 callable verbs: spawn, status, get, send-keys, read-pane,
|
|
10
|
+
* kill, decide, get-permission, record-pane-answer, resume, find-missing,
|
|
11
|
+
* expire, make-template, list, list-subagents, pause, version.
|
|
12
12
|
*
|
|
13
13
|
* NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
|
|
14
14
|
* intentionally excluded here. The .go source wins.
|
|
15
15
|
*/
|
|
16
16
|
/** All callable verbs in their canonical kebab form (matches manifest). */
|
|
17
|
-
export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "make-template", "list", "pause", "version"];
|
|
17
|
+
export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "record-pane-answer", "resume", "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];
|