@theokit/agents 16.6.0 → 16.7.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.
Files changed (56) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +84 -3
  3. package/dist/{agent-compiler-C-4X_vKz.d.ts → agent-compiler-aubY9WIa.d.ts} +13 -1
  4. package/dist/{agent-handle-rEWdERuv.d.ts → agent-handle-C343-xUh.d.ts} +16 -1
  5. package/dist/{agent-orchestrator-4xtsYrzm.d.ts → agent-orchestrator-DQtfrPaq.d.ts} +1 -1
  6. package/dist/{agent-runner-CE8MzVTu.d.ts → agent-runner-BuuqK_Dp.d.ts} +2 -2
  7. package/dist/{bridge-entry-BT2ou71q.d.ts → bridge-entry-nkeH6pAk.d.ts} +49 -6
  8. package/dist/bridge.d.ts +5 -5
  9. package/dist/bridge.js +7 -5
  10. package/dist/{chunk-KXE52FP2.js → chunk-4DOKIDGC.js} +59 -1
  11. package/dist/chunk-4DOKIDGC.js.map +1 -0
  12. package/dist/{chunk-NIQJ4GZX.js → chunk-JJ6Y6EBP.js} +4 -1
  13. package/dist/chunk-JJ6Y6EBP.js.map +1 -0
  14. package/dist/{chunk-ZLKZOSWR.js → chunk-RXD6S6RV.js} +2 -2
  15. package/dist/{chunk-K4MY4CV7.js → chunk-UARNAQ6O.js} +3 -3
  16. package/dist/{chunk-AZ2FOUSN.js → chunk-W533YIGA.js} +32 -5
  17. package/dist/chunk-W533YIGA.js.map +1 -0
  18. package/dist/{chunk-CZIJFINK.js → chunk-XGW7IZP6.js} +67 -3
  19. package/dist/chunk-XGW7IZP6.js.map +1 -0
  20. package/dist/client-react.d.ts +1 -1
  21. package/dist/client-react.js +1 -1
  22. package/dist/client.d.ts +14 -4
  23. package/dist/client.js +49 -2
  24. package/dist/client.js.map +1 -1
  25. package/dist/commands.d.ts +64 -12
  26. package/dist/commands.js +104 -12
  27. package/dist/commands.js.map +1 -1
  28. package/dist/config.d.ts +105 -1
  29. package/dist/config.js +454 -60
  30. package/dist/config.js.map +1 -1
  31. package/dist/{delegation-scoring-4dQIXi-w.d.ts → delegation-scoring-DPckVefy.d.ts} +1 -1
  32. package/dist/evals.d.ts +2 -2
  33. package/dist/evals.js +2 -2
  34. package/dist/handoff.d.ts +3 -3
  35. package/dist/handoff.js +3 -3
  36. package/dist/hooks.d.ts +24 -1
  37. package/dist/hooks.js +78 -3
  38. package/dist/hooks.js.map +1 -1
  39. package/dist/index.d.ts +21 -11
  40. package/dist/index.js +15 -5
  41. package/dist/index.js.map +1 -1
  42. package/dist/{sdk-adapter-BE0Cmj7f.d.ts → sdk-adapter-B0i8J7N0.d.ts} +1 -1
  43. package/dist/session.d.ts +17 -1
  44. package/dist/session.js +15 -0
  45. package/dist/session.js.map +1 -1
  46. package/dist/testing.d.ts +1 -1
  47. package/dist/testing.js +1 -1
  48. package/dist/tools.d.ts +3 -3
  49. package/dist/tools.js +4 -4
  50. package/package.json +1 -1
  51. package/dist/chunk-AZ2FOUSN.js.map +0 -1
  52. package/dist/chunk-CZIJFINK.js.map +0 -1
  53. package/dist/chunk-KXE52FP2.js.map +0 -1
  54. package/dist/chunk-NIQJ4GZX.js.map +0 -1
  55. /package/dist/{chunk-ZLKZOSWR.js.map → chunk-RXD6S6RV.js.map} +0 -0
  56. /package/dist/{chunk-K4MY4CV7.js.map → chunk-UARNAQ6O.js.map} +0 -0
@@ -1,3 +1,5 @@
1
+ import { TheokitAgentError } from '@theokit/sdk/errors';
2
+
1
3
  /**
2
4
  * M83 — the command routing MECHANISM, and only that.
3
5
  *
@@ -7,9 +9,10 @@
7
9
  * `@theokit/ui` / `@theokit/tui`. What has no counterpart anywhere is this: a registry, longest-prefix
8
10
  * routing, and the interpreter shape.
9
11
  *
10
- * What is deliberately NOT here (Top-risk 1 of the milestone): help rendering, aliases, completions.
11
- * Each of those is a mini CLI framework growing inside the agents package, and each needs its own ADR
12
- * with demand behind it. The ~50 command NAMES stay in the product; only the routing crosses.
12
+ * What is deliberately NOT here (Top-risk 1 of the milestone): help rendering and completions.
13
+ * Each is a mini CLI framework growing inside the agents package, and each needs its own ADR with
14
+ * demand behind it. Aliases and hidden names have that ADR (0036). The ~50 command NAMES stay in the
15
+ * product; only the routing crosses.
13
16
  *
14
17
  * ## Longest prefix, not first match
15
18
  *
@@ -21,24 +24,33 @@
21
24
  /** How a command treats the text after its name. */
22
25
  type CommandArgument = 'none' | 'optional' | 'required';
23
26
  /** One routable command. The NAME is the contract: it is what the user types and what logs record. */
24
- interface CommandDefinition {
27
+ interface CommandDefinition<Ctx = void> {
25
28
  readonly name: string;
26
29
  readonly description: string;
27
30
  /** Omitted ⇒ `'optional'`, the shape that refuses nothing. */
28
31
  readonly arg: CommandArgument;
32
+ /** Other names routed to this definition; never shown in the palette. */
33
+ readonly aliases?: readonly string[];
34
+ /** Routed, but not shown in the palette. */
35
+ readonly hidden?: boolean;
36
+ /** Called by a registry's `dispatch` with the argument and the caller's context. */
37
+ readonly run?: (arg: string, ctx: Ctx) => void | Promise<void>;
29
38
  }
30
39
  /** Declare a command. A function rather than an object literal so the default is stated once. */
31
- declare function defineCommand(input: {
40
+ declare function defineCommand<Ctx = void>(input: {
32
41
  name: string;
33
42
  description: string;
34
43
  arg?: CommandArgument;
35
- }): CommandDefinition;
44
+ aliases?: readonly string[];
45
+ hidden?: boolean;
46
+ run?: (arg: string, ctx: Ctx) => void | Promise<void>;
47
+ }): CommandDefinition<Ctx>;
36
48
  /** Why an input could not be routed. */
37
49
  type RouteFailure = 'unknown-command' | 'missing-argument' | 'unexpected-argument' | 'ambiguous-command';
38
50
  /** What the input turned out to be. */
39
- type RoutedInput = {
51
+ type RoutedInput<Ctx = void> = {
40
52
  readonly kind: 'command';
41
- readonly command: CommandDefinition;
53
+ readonly command: CommandDefinition<Ctx>;
42
54
  readonly arg: string;
43
55
  } | {
44
56
  readonly kind: 'message';
@@ -56,7 +68,28 @@ type RoutedInput = {
56
68
  * unrecognised one is an ERROR rather than prose — sending `/moddel gpt-5` to the model as text
57
69
  * hides a typo behind a plausible answer.
58
70
  */
59
- declare function routeCommand(input: string, commands: readonly CommandDefinition[]): RoutedInput;
71
+ declare function routeCommand<Ctx = void>(input: string, commands: readonly CommandDefinition<Ctx>[]): RoutedInput<Ctx>;
72
+
73
+ /** Thrown at creation when two definitions or aliases claim the same name. */
74
+ declare class CommandRegistryError extends TheokitAgentError {
75
+ readonly name = "CommandRegistryError";
76
+ readonly claimed: string;
77
+ readonly owners: readonly [string, string];
78
+ constructor(claimed: string, first: string, second: string);
79
+ }
80
+ /** One list of commands for the palette, the router and the handlers. */
81
+ interface CommandRegistry<Ctx> {
82
+ /** Visible, canonical names only, in definition order. */
83
+ palette(): readonly {
84
+ name: string;
85
+ description: string;
86
+ }[];
87
+ /** `command` is the canonical definition even when an alias was typed. */
88
+ route(input: string): RoutedInput<Ctx>;
89
+ /** Routes, then calls `run` when the input is a command that has one. */
90
+ dispatch(input: string, ctx: Ctx): Promise<RoutedInput<Ctx>>;
91
+ }
92
+ declare function createCommandRegistry<Ctx>(definitions: readonly CommandDefinition<Ctx>[]): CommandRegistry<Ctx>;
60
93
 
61
94
  /**
62
95
  * M83 — orderly shutdown, with a watchdog.
@@ -102,10 +135,29 @@ interface ShutdownDeps {
102
135
  readonly onWarn?: (message: string) => void;
103
136
  /** Watchdog budget in ms. */
104
137
  readonly watchdogMs?: number;
138
+ /** Exit through `exitAfterDrain` (let the event loop drain) instead of calling `exit` at once. */
139
+ readonly drain?: boolean;
105
140
  }
141
+ interface ExitAfterDrainDeps {
142
+ /** Forces the exit. Default `process.exit`. */
143
+ readonly exit?: (code: number) => void;
144
+ /** Records the exit code. Default sets `process.exitCode`. */
145
+ readonly setExitCode?: (code: number) => void;
146
+ /** How long the loop may take to drain before the exit is forced. Default `DEFAULT_WATCHDOG_MS`. */
147
+ readonly capMs?: number;
148
+ }
149
+ /**
150
+ * Set the exit code and let the event loop drain; force the exit only if it has not ended within
151
+ * `capMs`. A bare `process.exit` right after a stdout write can cut piped output. The timer is
152
+ * unref'd so it never keeps a finished process alive.
153
+ */
154
+ declare function exitAfterDrain(code: number, deps?: ExitAfterDrainDeps): void;
106
155
  interface Shutdown {
107
- /** Register a cleanup. Runs in registration order. */
108
- register(task: CleanupTask): void;
156
+ /**
157
+ * Register a cleanup. Runs in registration order. Returns a disposer: calling it before `run()`
158
+ * removes the task, after `run()` it is a no-op.
159
+ */
160
+ register(task: CleanupTask): () => void;
109
161
  /** Run every cleanup, then exit. Idempotent: a second Ctrl-C does not start a second teardown. */
110
162
  run(): Promise<ShutdownOutcome>;
111
163
  }
@@ -117,4 +169,4 @@ interface Shutdown {
117
169
  */
118
170
  declare function createShutdown(deps?: ShutdownDeps): Shutdown;
119
171
 
120
- export { type CleanupTask, type CommandArgument, type CommandDefinition, DEFAULT_WATCHDOG_MS, type RouteFailure, type RoutedInput, SHUTDOWN_EXIT_CODES, type Shutdown, type ShutdownDeps, type ShutdownOutcome, createShutdown, defineCommand, routeCommand };
172
+ export { type CleanupTask, type CommandArgument, type CommandDefinition, type CommandRegistry, CommandRegistryError, DEFAULT_WATCHDOG_MS, type ExitAfterDrainDeps, type RouteFailure, type RoutedInput, SHUTDOWN_EXIT_CODES, type Shutdown, type ShutdownDeps, type ShutdownOutcome, createCommandRegistry, createShutdown, defineCommand, exitAfterDrain, routeCommand };
package/dist/commands.js CHANGED
@@ -4,10 +4,10 @@ import {
4
4
 
5
5
  // src/commands/command-router.ts
6
6
  function defineCommand(input) {
7
+ const { arg, ...rest } = input;
7
8
  return {
8
- name: input.name,
9
- description: input.description,
10
- arg: input.arg ?? "optional"
9
+ ...rest,
10
+ arg: arg ?? "optional"
11
11
  };
12
12
  }
13
13
  __name(defineCommand, "defineCommand");
@@ -18,32 +18,40 @@ function routeCommand(input, commands) {
18
18
  text: input
19
19
  };
20
20
  const body = input.slice(PREFIX.length);
21
+ const entries = commands.flatMap((command2) => [
22
+ command2.name,
23
+ ...command2.aliases ?? []
24
+ ].map((typed) => ({
25
+ typed,
26
+ command: command2
27
+ })));
21
28
  const byLength = [
22
- ...commands
23
- ].sort((a, b) => b.name.length - a.name.length);
24
- const matches = byLength.filter((command) => matchesName(body, command.name));
29
+ ...entries
30
+ ].sort((a, b) => b.typed.length - a.typed.length);
31
+ const matches = byLength.filter((entry) => matchesName(body, entry.typed));
25
32
  if (matches.length === 0) return {
26
33
  kind: "error",
27
34
  reason: "unknown-command",
28
35
  input
29
36
  };
30
37
  const best = matches[0];
31
- if (matches.length > 1 && matches[1].name.length === best.name.length) {
38
+ if (matches.length > 1 && matches[1].typed.length === best.typed.length) {
32
39
  return {
33
40
  kind: "error",
34
41
  reason: "ambiguous-command",
35
42
  input
36
43
  };
37
44
  }
38
- const arg = body.slice(best.name.length).trim();
39
- if (arg !== "" && best.arg === "none") {
45
+ const arg = body.slice(best.typed.length).trim();
46
+ const command = best.command;
47
+ if (arg !== "" && command.arg === "none") {
40
48
  return {
41
49
  kind: "error",
42
50
  reason: "unexpected-argument",
43
51
  input
44
52
  };
45
53
  }
46
- if (arg === "" && best.arg === "required") {
54
+ if (arg === "" && command.arg === "required") {
47
55
  return {
48
56
  kind: "error",
49
57
  reason: "missing-argument",
@@ -52,7 +60,7 @@ function routeCommand(input, commands) {
52
60
  }
53
61
  return {
54
62
  kind: "command",
55
- command: best,
63
+ command,
56
64
  arg
57
65
  };
58
66
  }
@@ -64,6 +72,61 @@ function matchesName(body, name) {
64
72
  }
65
73
  __name(matchesName, "matchesName");
66
74
 
75
+ // src/commands/command-registry.ts
76
+ import { TheokitAgentError } from "@theokit/sdk/errors";
77
+ var CommandRegistryError = class extends TheokitAgentError {
78
+ static {
79
+ __name(this, "CommandRegistryError");
80
+ }
81
+ name = "CommandRegistryError";
82
+ claimed;
83
+ owners;
84
+ constructor(claimed, first, second) {
85
+ super(`command name "${claimed}" is claimed by both "${first}" and "${second}"`, {
86
+ code: "COMMAND_NAME_COLLISION",
87
+ // the same definitions collide the same way on every attempt.
88
+ isRetryable: false
89
+ });
90
+ this.claimed = claimed;
91
+ this.owners = [
92
+ first,
93
+ second
94
+ ];
95
+ }
96
+ };
97
+ function createCommandRegistry(definitions) {
98
+ const owners = /* @__PURE__ */ new Map();
99
+ for (const definition of definitions) {
100
+ for (const name of [
101
+ definition.name,
102
+ ...definition.aliases ?? []
103
+ ]) {
104
+ const owner = owners.get(name);
105
+ if (owner !== void 0) throw new CommandRegistryError(name, owner, definition.name);
106
+ owners.set(name, definition.name);
107
+ }
108
+ }
109
+ const list = [
110
+ ...definitions
111
+ ];
112
+ const route = /* @__PURE__ */ __name((input) => routeCommand(input, list), "route");
113
+ return {
114
+ palette: /* @__PURE__ */ __name(() => list.filter((definition) => definition.hidden !== true).map(({ name, description }) => ({
115
+ name,
116
+ description
117
+ })), "palette"),
118
+ route,
119
+ async dispatch(input, ctx) {
120
+ const routed = route(input);
121
+ if (routed.kind === "command" && routed.command.run !== void 0) {
122
+ await routed.command.run(routed.arg, ctx);
123
+ }
124
+ return routed;
125
+ }
126
+ };
127
+ }
128
+ __name(createCommandRegistry, "createCommandRegistry");
129
+
67
130
  // src/commands/shutdown.ts
68
131
  var SHUTDOWN_EXIT_CODES = {
69
132
  clean: 130,
@@ -71,11 +134,32 @@ var SHUTDOWN_EXIT_CODES = {
71
134
  "watchdog-timeout": 2
72
135
  };
73
136
  var DEFAULT_WATCHDOG_MS = 3e3;
137
+ function exitAfterDrain(code, deps = {}) {
138
+ const setExitCode = deps.setExitCode ?? ((c) => {
139
+ process.exitCode = c;
140
+ });
141
+ const exit = deps.exit ?? ((c) => process.exit(c));
142
+ setExitCode(code);
143
+ const timer = setTimeout(() => {
144
+ exit(code);
145
+ }, deps.capMs ?? DEFAULT_WATCHDOG_MS);
146
+ timer.unref();
147
+ }
148
+ __name(exitAfterDrain, "exitAfterDrain");
74
149
  var IGNORE = /* @__PURE__ */ __name(() => void 0, "IGNORE");
75
150
  function createShutdown(deps = {}) {
76
151
  const tasks = [];
77
152
  const warn = deps.onWarn ?? IGNORE;
78
153
  const exit = deps.exit ?? IGNORE;
154
+ const finish = /* @__PURE__ */ __name((code) => {
155
+ if (deps.drain !== true) {
156
+ exit(code);
157
+ return;
158
+ }
159
+ exitAfterDrain(code, deps.exit === void 0 ? {} : {
160
+ exit: deps.exit
161
+ });
162
+ }, "finish");
79
163
  const watchdogMs = deps.watchdogMs ?? DEFAULT_WATCHDOG_MS;
80
164
  let running;
81
165
  const withWatchdog = /* @__PURE__ */ __name(async () => {
@@ -115,10 +199,15 @@ function createShutdown(deps = {}) {
115
199
  const shutdown = {
116
200
  register(task) {
117
201
  tasks.push(task);
202
+ return () => {
203
+ if (running !== void 0) return;
204
+ const i = tasks.indexOf(task);
205
+ if (i !== -1) tasks.splice(i, 1);
206
+ };
118
207
  },
119
208
  run() {
120
209
  running ??= withWatchdog().then((outcome) => {
121
- exit(SHUTDOWN_EXIT_CODES[outcome]);
210
+ finish(SHUTDOWN_EXIT_CODES[outcome]);
122
211
  return outcome;
123
212
  });
124
213
  return running;
@@ -136,10 +225,13 @@ function createShutdown(deps = {}) {
136
225
  }
137
226
  __name(createShutdown, "createShutdown");
138
227
  export {
228
+ CommandRegistryError,
139
229
  DEFAULT_WATCHDOG_MS,
140
230
  SHUTDOWN_EXIT_CODES,
231
+ createCommandRegistry,
141
232
  createShutdown,
142
233
  defineCommand,
234
+ exitAfterDrain,
143
235
  routeCommand
144
236
  };
145
237
  //# sourceMappingURL=commands.js.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/commands/command-router.ts","../src/commands/shutdown.ts"],"mappings":";;;;;AAiCO,SAASA,cAAcC,OAI7B;AACC,SAAO;IAAEC,MAAMD,MAAMC;IAAMC,aAAaF,MAAME;IAAaC,KAAKH,MAAMG,OAAO;EAAW;AAC1F;AANgBJ;AAqBhB,IAAMK,SAAS;AAUR,SAASC,aAAaL,OAAeM,UAAsC;AAChF,MAAI,CAACN,MAAMO,WAAWH,MAAAA,EAAS,QAAO;IAAEI,MAAM;IAAWC,MAAMT;EAAM;AAErE,QAAMU,OAAOV,MAAMW,MAAMP,OAAOQ,MAAM;AAItC,QAAMC,WAAW;OAAIP;IAAUQ,KAAK,CAACC,GAAGC,MAAMA,EAAEf,KAAKW,SAASG,EAAEd,KAAKW,MAAM;AAC3E,QAAMK,UAAUJ,SAASK,OAAO,CAACC,YAAYC,YAAYV,MAAMS,QAAQlB,IAAI,CAAA;AAK3E,MAAIgB,QAAQL,WAAW,EAAG,QAAO;IAAEJ,MAAM;IAASa,QAAQ;IAAmBrB;EAAM;AACnF,QAAMsB,OAAOL,QAAQ,CAAA;AAKrB,MAAIA,QAAQL,SAAS,KAAKK,QAAQ,CAAA,EAAGhB,KAAKW,WAAWU,KAAKrB,KAAKW,QAAQ;AACrE,WAAO;MAAEJ,MAAM;MAASa,QAAQ;MAAqBrB;IAAM;EAC7D;AAEA,QAAMG,MAAMO,KAAKC,MAAMW,KAAKrB,KAAKW,MAAM,EAAEW,KAAI;AAC7C,MAAIpB,QAAQ,MAAMmB,KAAKnB,QAAQ,QAAQ;AAGrC,WAAO;MAAEK,MAAM;MAASa,QAAQ;MAAuBrB;IAAM;EAC/D;AACA,MAAIG,QAAQ,MAAMmB,KAAKnB,QAAQ,YAAY;AACzC,WAAO;MAAEK,MAAM;MAASa,QAAQ;MAAoBrB;IAAM;EAC5D;AACA,SAAO;IAAEQ,MAAM;IAAWW,SAASG;IAAMnB;EAAI;AAC/C;AAjCgBE;AAyChB,SAASe,YAAYV,MAAcT,MAAY;AAC7C,MAAI,CAACS,KAAKH,WAAWN,IAAAA,EAAO,QAAO;AACnC,QAAMuB,OAAOd,KAAKe,OAAOxB,KAAKW,MAAM;AACpC,SAAOY,SAAS,MAAMA,SAAS,OAAOA,SAAS;AACjD;AAJSJ;;;ACtEF,IAAMM,sBAAiE;EAC5EC,OAAO;EACP,kBAAkB;EAClB,oBAAoB;AACtB;AAGO,IAAMC,sBAAsB;AAoBnC,IAAMC,SAAS,6BAAYC,QAAZ;AAQR,SAASC,eAAeC,OAAqB,CAAC,GAAC;AACpD,QAAMC,QAAuB,CAAA;AAC7B,QAAMC,OAAOF,KAAKG,UAAUN;AAC5B,QAAMO,OAAOJ,KAAKI,QAAQP;AAC1B,QAAMQ,aAAaL,KAAKK,cAAcT;AACtC,MAAIU;AAEJ,QAAMC,eAAe,mCAAA;AACnB,QAAIC;AACJ,UAAMC,UAAU,IAAIC,IAAIT,MAAMU,IAAI,CAACC,MAAMA,EAAEC,IAAI,CAAA;AAC/C,UAAMC,WAAW,IAAIC,QAAyB,CAACC,YAAAA;AAC7CR,cAAQS,WAAW,MAAA;AAGjB,cAAMC,cAAc;aAAIT;UAASU,KAAK,IAAA,KAAS;AAC/CjB,aACE,iCAAiCkB,OAAOf,UAAAA,CAAAA,0BAAqCa,WAAAA,EAAa;AAE5FF,gBAAQ,kBAAA;MACV,GAAGX,UAAAA;IACL,CAAA;AAEA,UAAMgB,YAAY,YAAA;AAChB,UAAIC,UAA2B;AAC/B,iBAAWC,QAAQtB,OAAO;AACxB,YAAI;AACF,gBAAMsB,KAAKC,IAAG;QAChB,SAASC,OAAO;AACdH,oBAAU;AACVpB,eAAK,YAAYqB,KAAKV,IAAI,aAAcY,MAAgBC,OAAO,EAAE;QACnE;AACAjB,gBAAQkB,OAAOJ,KAAKV,IAAI;MAC1B;AACA,aAAOS;IACT,GAAA;AAEA,QAAI;AACF,aAAO,MAAMP,QAAQa,KAAK;QAACP;QAAUP;OAAS;IAChD,UAAA;AAGE,UAAIN,UAAUV,OAAW+B,cAAarB,KAAAA;IACxC;EACF,GApCqB;AAsCrB,QAAMsB,WAAqB;IACzBC,SAASR,MAAI;AACXtB,YAAM+B,KAAKT,IAAAA;IACb;IACAC,MAAAA;AAGElB,kBAAYC,aAAAA,EAAe0B,KAAK,CAACX,YAAAA;AAC/BlB,aAAKV,oBAAoB4B,OAAAA,CAAQ;AACjC,eAAOA;MACT,CAAA;AACA,aAAOhB;IACT;EACF;AAEA,MAAIN,KAAKkC,aAAapC,QAAW;AAC/B,eAAWqC,UAAU;MAAC;MAAU;OAAqB;AACnDnC,WAAKkC,SAASC,QAAQ,MAAM,KAAKL,SAASN,IAAG,CAAA;IAC/C;EACF;AACA,SAAOM;AACT;AAlEgB/B;","names":["defineCommand","input","name","description","arg","PREFIX","routeCommand","commands","startsWith","kind","text","body","slice","length","byLength","sort","a","b","matches","filter","command","matchesName","reason","best","trim","next","charAt","SHUTDOWN_EXIT_CODES","clean","DEFAULT_WATCHDOG_MS","IGNORE","undefined","createShutdown","deps","tasks","warn","onWarn","exit","watchdogMs","running","withWatchdog","timer","pending","Set","map","t","name","watchdog","Promise","resolve","setTimeout","outstanding","join","String","sequence","outcome","task","run","error","message","delete","race","clearTimeout","shutdown","register","push","then","onSignal","signal"]}
1
+ {"version":3,"sources":["../src/commands/command-router.ts","../src/commands/command-registry.ts","../src/commands/shutdown.ts"],"mappings":"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","names":["defineCommand","input","arg","rest","PREFIX","routeCommand","commands","startsWith","kind","text","body","slice","length","entries","flatMap","command","name","aliases","map","typed","byLength","sort","a","b","matches","filter","entry","matchesName","reason","best","trim","next","charAt","TheokitAgentError","CommandRegistryError","TheokitAgentError","name","claimed","owners","first","second","code","isRetryable","createCommandRegistry","definitions","Map","definition","aliases","owner","get","undefined","set","list","route","input","routeCommand","palette","filter","hidden","map","description","dispatch","ctx","routed","kind","command","run","arg","SHUTDOWN_EXIT_CODES","clean","DEFAULT_WATCHDOG_MS","exitAfterDrain","code","deps","setExitCode","c","process","exitCode","exit","timer","setTimeout","capMs","unref","IGNORE","undefined","createShutdown","tasks","warn","onWarn","finish","drain","watchdogMs","running","withWatchdog","pending","Set","map","t","name","watchdog","Promise","resolve","outstanding","join","String","sequence","outcome","task","run","error","message","delete","race","clearTimeout","shutdown","register","push","i","indexOf","splice","then","onSignal","signal"]}
package/dist/config.d.ts CHANGED
@@ -128,6 +128,48 @@ declare const LayeredConfig: {
128
128
  resolve<TSchema extends z.ZodType>(input: LayeredConfigInput<TSchema>): LayeredConfigResult<z.infer<TSchema>>;
129
129
  };
130
130
 
131
+ /** What every step receives: the environment to mutate, the working directory and the app's home. */
132
+ interface BootstrapContext {
133
+ readonly env: NodeJS.ProcessEnv;
134
+ readonly cwd: string;
135
+ readonly home: string;
136
+ }
137
+ interface BootstrapStep {
138
+ readonly name: string;
139
+ readonly run: (ctx: BootstrapContext) => void | Promise<void>;
140
+ }
141
+ interface AppBootstrap {
142
+ /**
143
+ * Run every step once, in order. A second call returns the first call's promise, including when
144
+ * that promise rejected: a bootstrap that failed is not retried by asking again.
145
+ */
146
+ run(ctx: BootstrapContext): Promise<{
147
+ ran: readonly string[];
148
+ }>;
149
+ readonly steps: readonly string[];
150
+ /** True after run() completed. Lets a module that resolves SDK paths assert it is not too early. */
151
+ readonly done: boolean;
152
+ }
153
+ /** A step threw. Names the step and keeps the original error as `cause`; later steps did not run. */
154
+ declare class BootstrapStepError extends TheokitAgentError {
155
+ readonly name = "BootstrapStepError";
156
+ readonly step: string;
157
+ constructor(step: string, cause: unknown);
158
+ }
159
+ /** Something that needs the bootstrap ran before it. Names the caller. */
160
+ declare class BootstrapNotRunError extends TheokitAgentError {
161
+ readonly name = "BootstrapNotRunError";
162
+ constructor(caller: string);
163
+ }
164
+ declare function defineAppBootstrap(steps: readonly BootstrapStep[]): AppBootstrap;
165
+ /** Throws {@link BootstrapNotRunError} naming `caller` unless `bootstrap.run()` has completed. */
166
+ declare function assertBootstrapped(bootstrap: AppBootstrap, caller: string): void;
167
+ /**
168
+ * Loads `<cwd>/.env` into `ctx.env` without overwriting set variables, then restores the SDK's
169
+ * sovereign keys (`SOVEREIGN_ENV_KEYS`) through `loadProjectEnv`. A missing file is not an error.
170
+ */
171
+ declare const projectEnvStep: BootstrapStep;
172
+
131
173
  /**
132
174
  * M73 — the per-directory trust store: a trust decision that survives the process.
133
175
  *
@@ -1063,6 +1105,22 @@ declare const SETTINGS_SCHEMA: z.ZodObject<{
1063
1105
  ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
1064
1106
  }, z.core.$loose>>;
1065
1107
  }, z.core.$loose>;
1108
+ /**
1109
+ * What this package does with each `.claude/settings.json` key its diagnostics name, and why.
1110
+ *
1111
+ * #736 — the issue's ask in its own words: "Decide each documented key: honoured, or explicitly
1112
+ * unsupported with the reason." Reporting a key as "not implemented here" says the code does not act
1113
+ * on it. It does not say whether that is a REFUSAL or an OMISSION, and an author reading it cannot
1114
+ * tell whether to stop writing the key or to wait for it — the accepted-and-ignored failure one step
1115
+ * removed, arriving through the diagnostic instead of through the loader.
1116
+ *
1117
+ * Each verdict is decided on what exists HERE, never on what the reference documents. Exported
1118
+ * because a decision nobody can read is not a decision.
1119
+ */
1120
+ declare const FOREIGN_KEY_DECISIONS: Readonly<Record<string, {
1121
+ readonly verdict: 'honoured' | 'refused';
1122
+ readonly because: string;
1123
+ }>>;
1066
1124
  type Settings = z.infer<typeof SETTINGS_SCHEMA>;
1067
1125
  interface LoadSettingsInput {
1068
1126
  /** Project root. Its `.claude/settings.json` and `.claude/settings.local.json` are read. */
@@ -1086,6 +1144,52 @@ interface LoadSettingsResult {
1086
1144
  */
1087
1145
  declare function loadSettings(input: LoadSettingsInput): LoadSettingsResult;
1088
1146
 
1147
+ /** The keys Claude Code's `settings.json` defines, for classifying a foreign file's keys. */
1148
+ declare const CLAUDE_SETTINGS_KEYS: ReadonlySet<string>;
1149
+ interface SettingsCandidate {
1150
+ readonly path: string;
1151
+ readonly foreignRoot: boolean;
1152
+ }
1153
+ interface SettingsCandidates {
1154
+ readonly user: readonly SettingsCandidate[];
1155
+ readonly project: readonly SettingsCandidate[];
1156
+ readonly projectLocal: readonly SettingsCandidate[];
1157
+ }
1158
+ /** Per scope, the ordered candidate paths: the own root before the foreign root. */
1159
+ declare function settingsCandidates(input: {
1160
+ readonly cwd: string;
1161
+ readonly home: string;
1162
+ readonly ownRoot: string;
1163
+ readonly foreignRoot?: string | false;
1164
+ }): SettingsCandidates;
1165
+ interface SettingsFileRead {
1166
+ readonly path: string;
1167
+ /** Own keys, renamed per `renames`. In an own-root file this also holds unknown keys. */
1168
+ readonly values: Record<string, unknown>;
1169
+ /** Known foreign keys not implemented here, plus `$schema` and `_`-prefixed keys. */
1170
+ readonly ignored: readonly string[];
1171
+ /** Keys neither own nor known to Claude Code; foreign file only. */
1172
+ readonly unrecognised: readonly string[];
1173
+ readonly permissionRules: readonly PermissionRule[];
1174
+ readonly unsupportedPermissions: readonly {
1175
+ readonly entry: string;
1176
+ readonly reason: string;
1177
+ }[];
1178
+ /** Raw `hooks`; pass to `parseClaudeHooks` for the foreign dialect. */
1179
+ readonly hooks?: unknown;
1180
+ }
1181
+ interface ReadSettingsFileOptions {
1182
+ readonly ownKeys: readonly string[];
1183
+ readonly renames?: Readonly<Record<string, string>>;
1184
+ readonly baseDir?: string;
1185
+ readonly specifierArg?: Readonly<Record<string, string>>;
1186
+ readonly onWarn?: (message: string) => void;
1187
+ }
1188
+ /** Read one candidate. `undefined` when the file is absent, or exists and cannot be parsed (warned). */
1189
+ declare function readSettingsFile(candidate: SettingsCandidate, options: ReadSettingsFileOptions): SettingsFileRead | undefined;
1190
+ /** The first candidate that yields a file; later candidates are not read. */
1191
+ declare function firstSettingsFile(candidates: readonly SettingsCandidate[], options: ReadSettingsFileOptions): SettingsFileRead | undefined;
1192
+
1089
1193
  /**
1090
1194
  * Split a markdown file into frontmatter lines and body.
1091
1195
  *
@@ -1175,4 +1279,4 @@ declare class ContextPressureThresholdError extends TheokitAgentError {
1175
1279
  */
1176
1280
  declare function contextPressure(usedTokens: number, effectiveWindow: number, thresholds?: ContextPressureThresholds): ContextPressure;
1177
1281
 
1178
- export { type AgentMemory, AgentMemoryError, type AgentMemoryScope, type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LAYERS_ARE_POSITIONED, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type LoadOutputStyleInput, type LoadSettingsInput, type LoadSettingsResult, MEMORY_BYTE_CAP, MEMORY_LINE_CAP, type OperatorDefinition, type OperatorOrigin, type OperatorPolicy, OperatorRootUnreadableError, type OperatorRootsOptions, type OperatorRootsResult, type OutputStyle, OutputStyleError, type ParsedFrontmatter, type PermissionTranslation, type PermissionsBlock, type PrecedenceReport, type ProvenancePerKey, type ResolveAgentMemoryInput, SETTINGS_LAYERS, type Settings, type SettingsLayer, type ShellResult, type SkippedDefinition, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, type UnsupportedPermissionEntry, type WithheldRoot, applySubagentMemory, blockAppliesTo, composeInstructions, contextPressure, currentOperatorPolicy, expandCommandTemplate, expandInstructionImports, frontmatterValue, layerPrecedence, loadCustomCommands, loadInstructionTree, loadOutputStyle, loadSettings, mcpServerAdmitted, permissionRulesFromSettings, resolveAgentMemory, resolveOperatorRoots, resolveOutputStyle, settingsLayerChain, splitFrontmatter, templateHints };
1282
+ export { type AgentMemory, AgentMemoryError, type AgentMemoryScope, type AppBootstrap, type BootstrapContext, BootstrapNotRunError, type BootstrapStep, BootstrapStepError, CLAUDE_SETTINGS_KEYS, type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, FOREIGN_KEY_DECISIONS, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LAYERS_ARE_POSITIONED, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type LoadOutputStyleInput, type LoadSettingsInput, type LoadSettingsResult, MEMORY_BYTE_CAP, MEMORY_LINE_CAP, type OperatorDefinition, type OperatorOrigin, type OperatorPolicy, OperatorRootUnreadableError, type OperatorRootsOptions, type OperatorRootsResult, type OutputStyle, OutputStyleError, type ParsedFrontmatter, type PermissionTranslation, type PermissionsBlock, type PrecedenceReport, type ProvenancePerKey, type ReadSettingsFileOptions, type ResolveAgentMemoryInput, SETTINGS_LAYERS, type Settings, type SettingsCandidate, type SettingsCandidates, type SettingsFileRead, type SettingsLayer, type ShellResult, type SkippedDefinition, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, type UnsupportedPermissionEntry, type WithheldRoot, applySubagentMemory, assertBootstrapped, blockAppliesTo, composeInstructions, contextPressure, currentOperatorPolicy, defineAppBootstrap, expandCommandTemplate, expandInstructionImports, firstSettingsFile, frontmatterValue, layerPrecedence, loadCustomCommands, loadInstructionTree, loadOutputStyle, loadSettings, mcpServerAdmitted, permissionRulesFromSettings, projectEnvStep, readSettingsFile, resolveAgentMemory, resolveOperatorRoots, resolveOutputStyle, settingsCandidates, settingsLayerChain, splitFrontmatter, templateHints };