agent-director 0.11.0 → 0.11.1

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
@@ -65,7 +65,7 @@ try {
65
65
  }
66
66
  ```
67
67
 
68
- All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. Tilde expansion (`~` → home directory) is handled automatically before paths are forwarded to the CLI subprocess. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
68
+ All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
69
69
 
70
70
  `ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
71
71
 
@@ -73,6 +73,14 @@ All constructor options are optional. Omitted fields fall back to the CLI binary
73
73
  - `home` → `--home`
74
74
  - `tmuxCommand` → `--tmux-command`
75
75
 
76
+ The CLI, not the client, expands a `~` in them, against `HOME` and nothing
77
+ else (never the passwd entry's home). It applies `home` first, so with `home`
78
+ set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
79
+ `HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
80
+ `ErrInvalidFlags`, and with no `home` either, every call that opens the store
81
+ is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
82
+ expand its config path `~/.agent-director/config.toml`.
83
+
76
84
  Set them only when the consumer needs to override the CLI's default for that field.
77
85
 
78
86
  ## Verb examples
@@ -293,7 +301,7 @@ The public typed-error surface falls into four groups. Every class named below i
293
301
 
294
302
  ### Realistic catch-site shortlist
295
303
 
296
- Most services only need to route on the "agent-director is sick" set. Alert on these six and let everything else propagate:
304
+ Most services only need to route on the "agent-director is sick" set. Alert on these eight:
297
305
 
298
306
  - `ErrSystemInstallNotFound`
299
307
  - `ErrSystemInstallTooOld`
@@ -301,6 +309,10 @@ Most services only need to route on the "agent-director is sick" set. Alert on t
301
309
  - `ErrCallerCwdUnreachable`
302
310
  - `ErrSystemInstallDisappeared`
303
311
  - `ErrCallTimeout`
312
+ - `ErrStoreOpen`
313
+ - `ErrConfigMalformed`
314
+
315
+ Also alert on an `ErrUnknownErrorName` whose `unknownName` is `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: the store needs an operator (see the per-call infrastructure table below). Let everything else propagate.
304
316
 
305
317
  Everything else is either **programmer error** (bad arguments — fix the call site, do not retry) or a **normal operational signal** (an expected verb outcome you branch on, like "no such spawn" or "already decided"). `ErrConsumerSignal` sits in between: it is a runtime infrastructure failure, but a routine one during shutdown, so treat it as an operational signal rather than a page.
306
318
 
@@ -333,11 +345,11 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
333
345
  |---|---|---|
334
346
  | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational — include in your "AD is sick" alert set. |
335
347
  | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
336
- | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client version does not recognize (client older than the binary). Carries `unknownName`, `envelope`. | Programmer/version error — upgrade the client. |
348
+ | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for: either the binary is newer than the client, or the name is one the binary emits but the shared catalog leaves out (for example `ErrInternal`, `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`). Carries `unknownName` (the real `err_name`) and `envelope`. | Read `unknownName`. `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: operational — the store needs an operator and no verb ran, so alert, as for `ErrStoreOpen`. A name the binary has and this client lacks because the binary is newer: version error — upgrade the client. |
337
349
 
338
350
  ### 4. Catalog-derived (CLI-side validation)
339
351
 
340
- These 42 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input or a verb's own state preconditions — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
352
+ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input, a verb's own state preconditions, or a config or store the CLI cannot open — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
341
353
 
342
354
  **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
343
355
 
@@ -373,8 +385,8 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
373
385
  | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
374
386
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
375
387
  | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
376
- | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Also returned when the row changed after `resume` examined it; nothing is written. |
377
- | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
388
+ | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. If that launch was abandoned or failed, `find-missing` marks the row `missing` once the pending grace period has passed; then a row with a `claude_session_id` (typically a resume's launch) can be resumed, and one without (typically a spawn's or reuse's launch), if `get` still shows no `claude_session_id`, is spawned again with `reuse_finished: true`, as the error says. An agent that reports in late records a `claude_session_id`, and its row, once `missing`, can be resumed instead. Also returned when the row changed after `resume` examined it; nothing is written. |
389
+ | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
378
390
  | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
379
391
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
380
392
  | `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
@@ -385,7 +397,7 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
385
397
  |---|---|---|
386
398
  | `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
387
399
  | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled; the new row stays `pending`. After tmux answers "duplicate session", `spawn` returns it only when the session holding the requested name was gone by the re-lookup; the new row is then ended (the error says if it was not), and the error names the instance id (a minted one included) and the retry: spawn that `claude_instance_id` again with `reuse_finished: true` once the name is free (if the row was not ended, once `get` shows it `ended` or `missing`), since a plain `spawn` of the id collides with its row. From `resume`, the session could not be created or labelled, or after "duplicate session" no session held the name when it was looked up again; the row is restored to `ended` or `missing` (the error says if it was not). A name found held is never this error. |
388
- | `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
400
+ | `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored; if it was not, the error says so and names the next step in place of "retry later": do not retry until `get` shows the row `ended` or `missing`, or, for a removed row, later a `spawn` of the id starts afresh. From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
389
401
  | `ErrTmuxSessionConflict` | CONFLICT (permanent until a human looks) | A tmux session conflict that needs a human. From `spawn` with an explicit `claude_instance_id` that has no row: a session of this store still labelled with that id is left over from an earlier life, or labels conflict; nothing is written. From a plain `spawn` whose requested tmux session name is already held (tmux answered "duplicate session"): the holder is a session left over from an earlier life of this id, another row's session, a session of another agent-director store, or one with no valid instance id, or labels conflict; the new row is ended (the error says if it was not) and the error names the blocking session. Another row's or another store's session is another agent and is never ended; the holding session is never read or typed into. From `resume` of a finished row, before anything is written and with no session touched: a session holds the row's session name (another row's session, a session of another agent-director store, or one with no valid instance id), a session is left over from an earlier life of this id, the row's own old session (or its agent process still running with no session) is past the stopping window and the starting-session bound, or labels conflict; the error names the blocking session. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). None of these means the agent is dead. From `kill` on a live row: the session found is not this launch's session (it carries the label of an earlier launch with this row's own id), or labels conflict; no kill was sent. From `readPane`, `sendKeys` and `pause`: the agent's pane was not found, a session an earlier launch left behind is there (for `readPane`, more than one; for `sendKeys`, on a live row), or labels conflict; nothing was read or sent. See "Operator actions" in the agent-director README. |
390
402
  | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry `kill` later; never `delete` the row. |
391
403
  | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
@@ -397,7 +409,8 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
397
409
 
398
410
  | Error | When it fires |
399
411
  |---|---|
400
- | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. |
412
+ | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. Time-bounded: refused until 1 s after every one of the spawn's permission requests' relay windows has elapsed; from then this guard lets `send-keys` through. |
413
+ | `ErrRelayFallenBack` | `decide` was called on an open request whose relay window has run out (from 1 s before it ends); no verdict was recorded. Answer at the pane with `send-keys` once its relay guard releases, 1 s after every request's window (for this request, at most 2 s after the refusal); until then `send-keys` may throw `ErrSendKeysWhileRelayed`. |
401
414
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
402
415
  | `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
403
416
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
@@ -421,6 +434,13 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
421
434
  |---|---|
422
435
  | `ErrInvalidFlags` | CLI flag parsing rejected the invocation, or `spawn` was given an explicit `claude_instance_id` containing an ASCII control character (0x00–0x1f or 0x7f). |
423
436
 
437
+ **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational; both are in the "AD is sick" alert set):
438
+
439
+ | Error | When it fires |
440
+ |---|---|
441
+ | `ErrConfigMalformed` | The CLI refused its config file, `~/.agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. Do not retry or act on any agent; alert an operator once, and never read it as an agent being dead. |
442
+ | `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. It says nothing about any agent. |
443
+
424
444
  ## Architecture
425
445
 
426
446
  See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle, the subprocess call recipe, Per-platform packaging, Error mapping, TS smoke-test harness, and TS envelope-diff regression.
package/dist/errors.d.ts CHANGED
@@ -69,8 +69,10 @@ export declare class ErrCallTimeout extends AgentDirectorError {
69
69
  /**
70
70
  * ErrUnknownErrorName — thrown when a subprocess JSON envelope contains an
71
71
  * `err_name` field that is not present in the static catalog-derived error map.
72
- * This indicates the Go-side catalog has a new entry that the TS catalog has
73
- * not yet been regenerated to include.
72
+ * Either the binary is newer than this client, or the name is one the binary
73
+ * emits but the shared catalog leaves out (for example ErrInternal or
74
+ * ErrSchemaMismatch; cross-ref: b.cm7). Read `unknownName` for the
75
+ * real err_name.
74
76
  *
75
77
  * Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
76
78
  * - `unknownName` — the unrecognised err_name string from the envelope.
@@ -315,6 +317,12 @@ export declare class ErrMissingRequestToken extends AgentDirectorError {
315
317
  /** Mirrors ErrInvalidFlags (package: api) */
316
318
  export declare class ErrInvalidFlags extends AgentDirectorError {
317
319
  }
320
+ /** Mirrors ErrConfigMalformed (package: clisetup) */
321
+ export declare class ErrConfigMalformed extends AgentDirectorError {
322
+ }
323
+ /** Mirrors ErrStoreOpen (package: clisetup) */
324
+ export declare class ErrStoreOpen extends AgentDirectorError {
325
+ }
318
326
  /**
319
327
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
320
328
  * subprocess error envelope fields.
package/dist/index.d.ts CHANGED
@@ -7,7 +7,7 @@ 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, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, } 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 } from "./types.js";
package/dist/index.js CHANGED
@@ -46,6 +46,7 @@ __export(exports_errors, {
46
46
  ErrSystemInstallTooOld: () => ErrSystemInstallTooOld,
47
47
  ErrSystemInstallNotFound: () => ErrSystemInstallNotFound,
48
48
  ErrSystemInstallDisappeared: () => ErrSystemInstallDisappeared,
49
+ ErrStoreOpen: () => ErrStoreOpen,
49
50
  ErrSpawnNotResumable: () => ErrSpawnNotResumable,
50
51
  ErrSpawnNotPausable: () => ErrSpawnNotPausable,
51
52
  ErrSpawnNotInteractive: () => ErrSpawnNotInteractive,
@@ -73,6 +74,7 @@ __export(exports_errors, {
73
74
  ErrCwdNotADirectory: () => ErrCwdNotADirectory,
74
75
  ErrCwdMissing: () => ErrCwdMissing,
75
76
  ErrConsumerSignal: () => ErrConsumerSignal,
77
+ ErrConfigMalformed: () => ErrConfigMalformed,
76
78
  ErrClientClosed: () => ErrClientClosed,
77
79
  ErrCallerCwdUnreachable: () => ErrCallerCwdUnreachable,
78
80
  ErrCallTimeout: () => ErrCallTimeout,
@@ -368,6 +370,12 @@ class ErrMissingRequestToken extends AgentDirectorError {
368
370
 
369
371
  class ErrInvalidFlags extends AgentDirectorError {
370
372
  }
373
+
374
+ class ErrConfigMalformed extends AgentDirectorError {
375
+ }
376
+
377
+ class ErrStoreOpen extends AgentDirectorError {
378
+ }
371
379
  var ERROR_TABLE = {
372
380
  ErrCwdMissing,
373
381
  ErrCwdNotAPath,
@@ -410,7 +418,9 @@ var ERROR_TABLE = {
410
418
  ErrTemplateNotFound,
411
419
  ErrTemplateMalformed,
412
420
  ErrTemplateExists,
413
- ErrProbeUnsupported
421
+ ErrProbeUnsupported,
422
+ ErrConfigMalformed,
423
+ ErrStoreOpen
414
424
  };
415
425
  function errorFromEnvelope(verb, err_name, err_description) {
416
426
  const Ctor = ERROR_TABLE[err_name];
@@ -822,19 +832,6 @@ function checkBunVersion() {
822
832
  import { readFile } from "fs/promises";
823
833
  import { statSync as statSync2 } from "fs";
824
834
 
825
- // src/internal/tilde.ts
826
- import * as os from "os";
827
- function expandTilde(p) {
828
- if (p === "")
829
- return "";
830
- if (p !== "~" && !p.startsWith("~/"))
831
- return p;
832
- const home = process.env["HOME"] || os.homedir();
833
- if (p === "~")
834
- return home;
835
- return home + p.slice(1);
836
- }
837
-
838
835
  // src/internal/argv.ts
839
836
  function buildArgv(cliPath, verb, params, globalOpts) {
840
837
  const globalFlags = buildGlobalFlags(globalOpts);
@@ -1278,6 +1275,16 @@ var catalog_default = [
1278
1275
  name: "ErrAmbiguousRequest",
1279
1276
  package: "store",
1280
1277
  description: ""
1278
+ },
1279
+ {
1280
+ name: "ErrConfigMalformed",
1281
+ package: "clisetup",
1282
+ description: ""
1283
+ },
1284
+ {
1285
+ name: "ErrStoreOpen",
1286
+ package: "clisetup",
1287
+ description: ""
1281
1288
  }
1282
1289
  ];
1283
1290
 
@@ -1341,11 +1348,11 @@ class SubprocessClient {
1341
1348
  this.#binaryVersion = init.binaryVersion;
1342
1349
  const g = {};
1343
1350
  if (opts.storePath !== undefined)
1344
- g.storePath = expandTilde(opts.storePath);
1351
+ g.storePath = opts.storePath;
1345
1352
  if (opts.tmuxCommand !== undefined)
1346
- g.tmuxCommand = expandTilde(opts.tmuxCommand);
1353
+ g.tmuxCommand = opts.tmuxCommand;
1347
1354
  if (opts.home !== undefined)
1348
- g.home = expandTilde(opts.home);
1355
+ g.home = opts.home;
1349
1356
  this.#globalOpts = g;
1350
1357
  this.#open = true;
1351
1358
  this.#tail = Promise.resolve();
@@ -1673,6 +1680,7 @@ export {
1673
1680
  ErrSystemInstallTooOld,
1674
1681
  ErrSystemInstallNotFound,
1675
1682
  ErrSystemInstallDisappeared,
1683
+ ErrStoreOpen,
1676
1684
  ErrSpawnNotResumable,
1677
1685
  ErrSpawnNotPausable,
1678
1686
  ErrSpawnNotInteractive,
@@ -1700,6 +1708,7 @@ export {
1700
1708
  ErrCwdNotADirectory,
1701
1709
  ErrCwdMissing,
1702
1710
  ErrConsumerSignal,
1711
+ ErrConfigMalformed,
1703
1712
  ErrClientClosed,
1704
1713
  ErrCallerCwdUnreachable,
1705
1714
  ErrCallTimeout,
@@ -28,15 +28,14 @@ import type { VerbName } from "./verbs.js";
28
28
  * bug b.32k. Each field is optional; when undefined the corresponding flag
29
29
  * is omitted from argv and the CLI's own default-resolution kicks in.
30
30
  *
31
- * Tilde-expansion is the caller's responsibility (typically done at Client
32
- * construction time via src/internal/tilde.ts).
31
+ * Values are forwarded verbatim; the CLI expands `~` in them (b.38a).
33
32
  */
34
33
  export interface GlobalArgvOptions {
35
- /** Tilde-expanded path forwarded to the CLI as `--store-path`. */
34
+ /** Path forwarded to the CLI as `--store-path`. */
36
35
  storePath?: string;
37
- /** Tilde-expanded path forwarded to the CLI as `--home`. */
36
+ /** Path forwarded to the CLI as `--home`. */
38
37
  home?: string;
39
- /** Tilde-expanded path forwarded to the CLI as `--tmux-command`. */
38
+ /** Path forwarded to the CLI as `--tmux-command`. */
40
39
  tmuxCommand?: string;
41
40
  }
42
41
  /**
@@ -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` (37 entries as of 2026-05-31). The map
5
+ * `pkg/api/errnames/catalog.json` (44 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,8 +10,11 @@
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 — defensive against Go-side catalog additions that race
14
- * the TS-side regen).
13
+ * (SRD SR-4.3): either a Go-side catalog addition that races the TS-side
14
+ * regen, or a name the binary emits but the catalog leaves out —
15
+ * currently ErrInternal, ErrSchemaMismatch, ErrSchemaMigrationRequired,
16
+ * ErrUnknownVerb, ErrJSONMarshal and ErrTrailWrite (tracked in b.cm7).
17
+ * Callers read `unknownName` for the real err_name.
15
18
  *
16
19
  * Implements SRD SR-4.1 (static module-load-time map), SR-4.2 (throw by
17
20
  * constructor with envelope fields), SR-4.3 (ErrUnknownErrorName for
package/dist/types.d.ts CHANGED
@@ -18,11 +18,16 @@ export interface Logger {
18
18
  * does NOT provide a fallback; it forwards user input verbatim to keep the
19
19
  * CLI as the single source of truth for default resolution. See bug b.32k.
20
20
  *
21
- * Tilde expansion is handled TS-side by `src/internal/tilde.ts`: in
22
- * `storePath`, `home` and `tmuxCommand`, a bare `~` or a leading `~/` is
23
- * expanded against `HOME` (or `os.homedir()` when `HOME` is unset or empty)
24
- * before the value is forwarded to the CLI subprocess. Other values, relative
25
- * paths included, are forwarded unchanged and the CLI resolves them.
21
+ * `storePath`, `home` and `tmuxCommand` are forwarded verbatim; the TS Client
22
+ * does no tilde expansion of its own. The CLI subprocess, which inherits this
23
+ * process's environment, expands `~`: a bare `~` or a leading `~/` in `home`
24
+ * against the inherited `HOME`, then a leading `~/` in `storePath` and
25
+ * `tmuxCommand` (and a bare `~` in `tmuxCommand`) against the resulting
26
+ * `HOME`, which is `home` when set. The CLI never resolves `~` against the
27
+ * passwd home: with `HOME` unset or empty, a `~` or `~/` `home` rejects every
28
+ * call with `ErrInvalidFlags`, and with no `home` either, every call that
29
+ * opens the store is refused. Other values, relative paths included, are
30
+ * forwarded unchanged and the CLI resolves them. b.38a.
26
31
  *
27
32
  * An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
28
33
  * `--store-path ""`); the CLI rejects it on every verb call, which then
@@ -30,8 +35,8 @@ export interface Logger {
30
35
  */
31
36
  export interface ClientOptions {
32
37
  /**
33
- * Path to the SQLite store file. Tilde-expanded before being forwarded as
34
- * `--store-path` to the CLI subprocess.
38
+ * Path to the SQLite store file. Forwarded verbatim as `--store-path` to the
39
+ * CLI subprocess, which expands a leading `~/`.
35
40
  *
36
41
  * When omitted, the CLI's three-tier default resolution applies:
37
42
  * 1. CLI flag (this field, when set) → 2. cfg.Store.DbPath in
@@ -42,15 +47,15 @@ export interface ClientOptions {
42
47
  */
43
48
  storePath?: string;
44
49
  /**
45
- * Override the tmux binary. Tilde-expanded before being forwarded as
46
- * `--tmux-command` to the CLI subprocess. When omitted, the CLI looks up
47
- * `tmux` on PATH.
50
+ * Override the tmux binary. Forwarded verbatim as `--tmux-command` to the
51
+ * CLI subprocess, which expands a bare `~` or a leading `~/`. When omitted,
52
+ * the CLI looks up `tmux` on PATH.
48
53
  */
49
54
  tmuxCommand?: string;
50
55
  /**
51
56
  * Override HOME for the duration of every subprocess call this Client
52
- * issues. Tilde-expanded before being forwarded as `--home` to the CLI
53
- * subprocess.
57
+ * issues. Forwarded verbatim as `--home` to the CLI subprocess, which
58
+ * expands a bare `~` or a leading `~/` against the inherited `HOME`.
54
59
  *
55
60
  * When omitted, the CLI subprocess inherits HOME from the calling process
56
61
  * environment (which is the correct default — set HOME at the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.11.0",
3
+ "version": "0.11.1",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],
@@ -1,16 +0,0 @@
1
- /**
2
- * expandTilde resolves a leading `~` or `~/` to the user's home directory.
3
- *
4
- * Resolution order:
5
- * 1. `process.env.HOME` if set and non-empty.
6
- * 2. `os.homedir()` from node:os as fallback.
7
- *
8
- * Behaviour by input:
9
- * - `""` → `""` (empty string unchanged)
10
- * - `"~"` → `"/home/user"` (bare tilde → home directory)
11
- * - `"~/foo"` → `"/home/user/foo"` (tilde-prefix → home + rest)
12
- * - `"/abs/path"` → `"/abs/path"` (absolute path unchanged)
13
- * - `"relative/path"` → `"relative/path"` (relative path unchanged)
14
- * - `"foo~bar"` → `"foo~bar"` (tilde not at start → unchanged)
15
- */
16
- export declare function expandTilde(p: string): string;