@rarebit-one/harness-kernel 0.15.0 → 0.19.0

package/dist/tools/metadata.d.ts

@@ -11,7 +11,7 @@ import type { Tool } from "./registry.js";
  *
  * The metadata here is only ever *descriptive*. The kernel records that a tool
  * says `requiresConfirmation`; it never implements a confirmation flow, because
- * what confirmation means — a modal, a Slack approval, a second agent — is the
+ * what confirmation means — a modal, a chat approval, a second agent — is the
  * application's decision. Same for undo and retention. Policy lives in the app
  * layer; the vocabulary lives here so every layer agrees on the words.
  */
@@ -33,8 +33,9 @@ export type ResultRetention = "ephemeral" | "standard" | "persistent";
  *   - `terminal` — run it, append its result, then END the loop with the call
  *                  as the structured answer. A final-answer tool. The other
  *                  calls of the same assistant turn still run (in order), so
- *                  the transcript stays whole; the first terminal call that
- *                  succeeds is the answer.
+ *                  the transcript stays whole; the first terminal call, in the
+ *                  model's order, that succeeds is the answer, even when calls
+ *                  ran in parallel and a later one finished first.
  *   - `external` — the loop does not run it: the call is parked on
  *                  `LoopResult.pending`, the run ends `suspended`, and the
  *                  caller resumes the conversation with the call's result (or
@@ -93,6 +94,15 @@ export interface ToolMetadata {
      * kernel only records the claim; deciding to replay is the application's.
      */
     replay?: "safe" | "unsafe";
+    /**
+     * The tool may run at the same time as other calls of the same step: it has
+     * no effect another call could observe or race (a read, a lookup). Absent
+     * means it makes no such claim, and it runs alone. The loop never reads this
+     * itself; a run that opts into parallel calls passes a predicate
+     * (`toolConcurrency.concurrencySafe`), and `isConcurrencySafe` honours this
+     * field.
+     */
+    concurrencySafe?: boolean;
     resultRetention?: ResultRetention;
     clientResultVisibility?: ClientResultVisibility;
 }
@@ -130,6 +140,11 @@ export declare function toolsRequiringConfirmation(tools: Tool[]): Tool[];
  * after an interruption. An undeclared tool is excluded: absent means unsafe.
  */
 export declare function replaySafeTools(tools: Tool[]): Tool[];
+/**
+ * Whether a tool declared `concurrencySafe: true`. The predicate to pass as
+ * `toolConcurrency.concurrencySafe` when the tools' own claims are the policy.
+ */
+export declare function isConcurrencySafe(tool: Tool): boolean;
 /** Look up the tool that undoes `name`, when one is declared and reversible. */
 export declare function undoToolFor(tools: Tool[], name: string): Tool | undefined;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/tools/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAA;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;AAE9D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,YAAY,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAA;IACzC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;CAChD;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAmBhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,IAAI,EAAE,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAErD;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAErD;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEnD;AAED,mEAAmE;AACnE,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAErD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAIzE"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAA;AAErE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;AAE9D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,YAAY,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAA;IACzC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;CAChD;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAmBhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,IAAI,EAAE,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAErD;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAErD;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEnD;AAED,mEAAmE;AACnE,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAErD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAErD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAIzE"}

package/dist/tools/metadata.js

@@ -54,6 +54,13 @@ export function toolsRequiringConfirmation(tools) {
 export function replaySafeTools(tools) {
     return tools.filter((tool) => tool.meta?.replay === "safe");
 }
+/**
+ * Whether a tool declared `concurrencySafe: true`. The predicate to pass as
+ * `toolConcurrency.concurrencySafe` when the tools' own claims are the policy.
+ */
+export function isConcurrencySafe(tool) {
+    return tool.meta?.concurrencySafe === true;
+}
 /** Look up the tool that undoes `name`, when one is declared and reversible. */
 export function undoToolFor(tools, name) {
     const tool = tools.find((t) => t.spec.name === name);

package/dist/tools/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AA6HA,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,YAA2B,EAAE;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACtB,IAAI,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,0EAA0E;IAC1E,6EAA6E;IAC7E,4CAA4C;IAC5C,IAAI,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACrF,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;IACrF,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,YAA2B,EAAE;IACtE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,SAAS,CAAA;AACzC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,CAAA;AAClE,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC,CAAA;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAU;IAC1C,OAAO,IAAI,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;AAC5C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IACpD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAA;IACxE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AACnE,CAAC"}

package/dist/tools/registry.d.ts

@@ -1,4 +1,4 @@
-import { type McpConnection } from "../connectors/mcpClient.js";
+import { type ConnectMcpOptions, type McpConnection } from "../connectors/mcpClient.js";
 import type { ConnectorConfig } from "../types.js";
 import type { ToolSpec } from "../providers/types.js";
 import type { ToolMetadata } from "./metadata.js";
@@ -79,12 +79,14 @@ export declare const namespacedToolName: ConnectorToolName;
  * `<connector>__<tool>` by default so two connectors cannot collide; pass
  * `toolName` to name them differently (a single-connector application may
  * want the server's own names, so its prompts and its tool names match).
- * Returns a `close` to tear down the connections when the run ends.
+ * Returns a `close` to tear down the connections when the run ends. `onSecret`
+ * is handed to `connect` and hears every connector credential, including each
+ * rotated one an `auth.headers` function returns mid-run.
  */
-export declare function connectorTools(connectors: ConnectorConfig[], connect?: (config: ConnectorConfig) => Promise<McpConnection>, opts?: {
+export declare function connectorTools(connectors: ConnectorConfig[], connect?: (config: ConnectorConfig, opts?: ConnectMcpOptions) => Promise<McpConnection>, opts?: {
     signal?: AbortSignal;
     toolName?: ConnectorToolName;
-}): Promise<{
+} & ConnectMcpOptions): Promise<{
     tools: Tool[];
     close: () => Promise<void>;
 }>;

package/dist/tools/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAA;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3E;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC3F;AAED,sFAAsF;AACtF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,IAAI,EAAE,CAiGR;AAED,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;AAEnF,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,iBAAgE,CAAA;AAEjG;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,aAAa,CAAc,EACzE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAO,GAChE,OAAO,CAAC;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAoExD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAA;AACnG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAA;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3E;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC3F;AAED,sFAAsF;AACtF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,IAAI,EAAE,CAiGR;AAED,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;AAEnF,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,iBAAgE,CAAA;AAEjG;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,CACP,MAAM,EAAE,eAAe,EACvB,IAAI,CAAC,EAAE,iBAAiB,KACrB,OAAO,CAAC,aAAa,CAAc,EACxC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAE,GAAG,iBAAsB,GACpF,OAAO,CAAC;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAoExD"}

package/dist/tools/registry.js

@@ -154,10 +154,12 @@ export const namespacedToolName = (connector, tool) => `${connector}__${tool}`;
  * `<connector>__<tool>` by default so two connectors cannot collide; pass
  * `toolName` to name them differently (a single-connector application may
  * want the server's own names, so its prompts and its tool names match).
- * Returns a `close` to tear down the connections when the run ends.
+ * Returns a `close` to tear down the connections when the run ends. `onSecret`
+ * is handed to `connect` and hears every connector credential, including each
+ * rotated one an `auth.headers` function returns mid-run.
  */
 export async function connectorTools(connectors, connect = connectMcp, opts = {}) {
-    const { signal } = opts;
+    const { signal, onSecret } = opts;
     const nameFor = opts.toolName ?? namespacedToolName;
     const connections = [];
     // Each setup await stops waiting the moment `signal` aborts, so a stalled
@@ -182,7 +184,7 @@ export async function connectorTools(connectors, connect = connectMcp, opts = {}
         for (const config of connectors) {
             if (config.kind !== "mcp")
                 continue;
-            const connecting = connect(config);
+            const connecting = onSecret ? connect(config, { onSecret }) : connect(config);
             let conn;
             try {
                 conn = await step(connecting);

package/dist/tools/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAA;AAClF,OAAO,EAAE,UAAU,EAA8C,MAAM,4BAA4B,CAAA;AA6DnG,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAU,EACV,KAA8B,EAC9B,GAAiB;IAEjB,IAAI,IAAI,CAAC,iBAAiB;QAAE,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IACrE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAA;AACpD,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AACpE,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAY,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAElF,2EAA2E;AAC3E,SAAS,aAAa,CAAC,CAAU;IAC/B,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACjD,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;QACxE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IACjD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,IAAiB;IACnD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,IAAI,CAAA;QAClB,KAAK,SAAS;YACZ,OAAO,aAAa,CAAA;QACtB,KAAK,WAAW;YACd,OAAO,cAAc,IAAI,kCAAkC,CAAA;QAC7D,KAAK,WAAW;YACd,OAAO,CACL,cAAc,IAAI,OAAO,IAAI,CAAC,KAAK,oBAAoB,IAAI,CAAC,QAAQ,yBAAyB;gBAC7F,iEAAiE,CAClE,CAAA;QACH,KAAK,QAAQ;YACX,OAAO,cAAc,IAAI,wBAAwB,IAAI,CAAC,KAAK,8CAA8C,CAAA;IAC7G,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAkB,EAClB,GAAsB,EACtB,OAAkB,EAClB,UAAqB;IAErB,MAAM,GAAG,GAAW;QAClB;YACE,IAAI,EAAE;gBACJ,IAAI,EAAE,UAAU;gBAChB,WAAW,EACT,iGAAiG;oBACjG,qGAAqG;oBACrG,oGAAoG;oBACpG,mFAAmF;gBACrF,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;wBAClD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBAC1B;oBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;iBACtB;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACjC,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;gBACvE,wEAAwE;gBACxE,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,CAAA;gBAC1B,0EAA0E;gBAC1E,4EAA4E;gBAC5E,6EAA6E;gBAC7E,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,CAAC;oBACb,CAAC,CAAC,MAAM,OAAO,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;oBACvE,CAAC,CAAC,MAAM,OAAO,CAAC;wBACZ,GAAG,EAAE,UAAU;wBACf,OAAO,EAAE,SAAS;wBAClB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;wBACrB,GAAG;wBACH,KAAK;wBACL,MAAM;qBACP,CAAC,CAAA;gBACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;YAC/B,CAAC;SACF;QACD;YACE,IAAI,EAAE;gBACJ,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,+CAA+C;gBAC5D,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;oBACxC,QAAQ,EAAE,CAAC,MAAM,CAAC;iBACnB;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CACvB,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,eAAe,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;SACpF;QACD;YACE,IAAI,EAAE;gBACJ,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,wDAAwD;gBACrE,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;iBACxC;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;SAC1F;QACD;YACE,IAAI,EAAE;gBACJ,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,6DAA6D;gBAC1E,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACvB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBACzB;oBACD,QAAQ,EAAE,CAAC,KAAK,CAAC;iBAClB;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC;oBAC1B,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;oBACnB,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK;oBAClC,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;oBACrC,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;oBAC7D,UAAU,EAAE,iFAAiF;oBAC7F,MAAM,EAAE,GAAG,EAAE,MAAM;iBACpB,CAAC,CAAA;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;YAC/D,CAAC;SACF;KACF,CAAA;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;AACzE,CAAC;AAKD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAsB,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,EAAE,CAAA;AAEjG;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAA6B,EAC7B,UAG8B,UAAU,EACxC,OAAmF,EAAE;IAErF,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAA;IACnD,MAAM,WAAW,GAAoB,EAAE,CAAA;IACvC,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E;IAC3E,MAAM,IAAI,GAAG,CAAI,IAAgB,EAAc,EAAE;QAC/C,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QACxB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAe,CAAC,CAAA;YAC1D,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,OAAO,EAAE,CAAA;YACpC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;YACzD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;QACxF,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IACD,MAAM,KAAK,GAAW,EAAE,CAAA;IACxB,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,MAAM,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAC7D,CAAC,CAAA;IAED,IAAI,CAAC;QACH,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK;gBAAE,SAAQ;YAEnC,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YAC7E,IAAI,IAAmB,CAAA;YACvB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,CAAA;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;gBAC5D,MAAM,GAAG,CAAA;YACX,CAAC;YACD,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAEtB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAE3C,CAAA;YAED,wEAAwE;YACxE,0DAA0D;YAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAA;YAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,SAAQ;gBACrD,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE;wBACJ,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;wBACrC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG,MAAM,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,EAAE;wBACnE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;qBACpD;oBACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;wBAC5B,+DAA+D;wBAC/D,iEAAiE;wBACjE,MAAM,MAAM,GAAG,GAAG;4BAChB,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;4BAC/D,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;wBACzC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;oBAC/B,CAAC;iBACF,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wDAAwD;QACxD,MAAM,KAAK,EAAE,CAAA;QACb,MAAM,GAAG,CAAA;IACX,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACzB,CAAC"}

package/dist/tools/terminal.d.ts

@@ -15,12 +15,14 @@ export interface TerminalToolOptions {
  *
  * This is how a conversational application gets a typed reply out of the loop
  * instead of parsing prose. The model is told the schema through the tool
- * definition, so the shape is enforced where models enforce shapes best. The
- * kernel does not validate the arguments against the schema (it ships no
- * JSON-Schema validator); a caller that needs validation runs it on
- * `terminal.input`, or supplies its own `Tool` with `meta.dispatch: "terminal"`
- * whose executor throws on a bad answer, which sends the error back to the
- * model and lets it try again.
+ * definition, so the shape is enforced where models enforce shapes best. By
+ * default the kernel does not check the arguments against the schema; a run
+ * with `validateToolInput: true` does, and refuses a call that does not fit
+ * before it can end the run, telling the model what to fix. A rule the schema
+ * cannot express (one field required only when another has a given value) is
+ * the caller's: supply your own `Tool` with `meta.dispatch: "terminal"` whose
+ * executor throws on a bad answer, which sends the error back to the model and
+ * lets it try again.
  *
  * The executor here is a no-op that acknowledges the call: a tool result still
  * has to be appended so the transcript carries no dangling tool call and can be

package/dist/tools/terminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/tools/terminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAU/D"}
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/tools/terminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAU/D"}

package/dist/tools/terminal.js

@@ -4,12 +4,14 @@
  *
  * This is how a conversational application gets a typed reply out of the loop
  * instead of parsing prose. The model is told the schema through the tool
- * definition, so the shape is enforced where models enforce shapes best. The
- * kernel does not validate the arguments against the schema (it ships no
- * JSON-Schema validator); a caller that needs validation runs it on
- * `terminal.input`, or supplies its own `Tool` with `meta.dispatch: "terminal"`
- * whose executor throws on a bad answer, which sends the error back to the
- * model and lets it try again.
+ * definition, so the shape is enforced where models enforce shapes best. By
+ * default the kernel does not check the arguments against the schema; a run
+ * with `validateToolInput: true` does, and refuses a call that does not fit
+ * before it can end the run, telling the model what to fix. A rule the schema
+ * cannot express (one field required only when another has a given value) is
+ * the caller's: supply your own `Tool` with `meta.dispatch: "terminal"` whose
+ * executor throws on a bad answer, which sends the error back to the model and
+ * lets it try again.
  *
  * The executor here is a no-op that acknowledges the call: a tool result still
  * has to be appended so the transcript carries no dangling tool call and can be

package/dist/tools/terminal.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/tools/terminal.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,OAAO;QACL,IAAI,EAAE;YACJ,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;QACD,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE;QAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;KAC3C,CAAA;AACH,CAAC"}
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/tools/terminal.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,OAAO;QACL,IAAI,EAAE;YACJ,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;QACD,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE;QAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;KAC3C,CAAA;AACH,CAAC"}

package/dist/tools/validate.d.ts

@@ -0,0 +1,49 @@
+import type { Tool } from "./registry.js";
+/**
+ * One way a tool call's arguments fail the tool's declared `inputSchema`.
+ * `path` is a JSON Pointer into the arguments (`/items/0/name`), or `""` for
+ * the arguments object itself.
+ */
+export interface ToolInputProblem {
+    path: string;
+    message: string;
+}
+/**
+ * Check a tool call's arguments against a JSON Schema, returning every problem
+ * found (empty when the arguments fit).
+ *
+ * This is the subset of JSON Schema that tool schemas actually use: `type`
+ * (including `integer`, `null` and type arrays), `properties`, `required`,
+ * `additionalProperties`, `enum`, `const`, `items` / `prefixItems`, the
+ * length, size and range bounds, `pattern`, `allOf` / `anyOf` / `oneOf`,
+ * local `$ref`s (`#/$defs/...`, `#/definitions/...`) and OpenAPI's
+ * `nullable`. A `$ref`'s sibling keywords apply as in 2019-09 and later, and
+ * are ignored when the root `$schema` names draft 03 to 07, where a `$ref`
+ * replaced its whole schema object; `const` is ignored before draft 6 and
+ * `prefixItems` before 2020-12, the drafts that introduced them. Any other keyword (`format`, `not`,
+ * `if`/`then`/`else`, `multipleOf`, `uniqueItems`, the `dependent*` family, a
+ * remote or malformed `$ref`, a local `$ref` inside an embedded resource with
+ * its own `$id`, a `type` name outside the seven JSON types) is ignored, and
+ * `oneOf` is read as `anyOf`. A schema whose check would take more than a
+ * fixed amount of work is not judged at all: no problems are returned.
+ *
+ * Ignoring is the point: the validator may let a bad call through, but it
+ * never refuses a call the schema accepts. A refusal costs the model a turn,
+ * so a false one is worse than a missed one, and a schema written by someone
+ * else (an MCP server's) can use any keyword it likes without the run
+ * starting to refuse calls its server would have taken.
+ *
+ * `pattern` is compiled and run synchronously on the model's input, like any
+ * regular expression. A schema author's pattern with catastrophic
+ * backtracking (`^(a+)+$`) can stall the event loop, and the run's deadline
+ * cannot interrupt it; turn validation on only for tools whose schemas you
+ * would run that way.
+ */
+export declare function validateToolInput(schema: unknown, input: unknown): ToolInputProblem[];
+/**
+ * The tool result a call gets when its arguments fail the tool's schema, or
+ * `undefined` when they fit. The loop answers the call with this instead of
+ * running it, and the model corrects the call within its own budgets.
+ */
+export declare function invalidInputRefusal(tool: Tool, input: Record<string, unknown>): string | undefined;
+//# sourceMappingURL=validate.d.ts.map

package/dist/tools/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/tools/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAUrF;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,GAAG,SAAS,CAmBpB"}

package/dist/tools/validate.js

@@ -0,0 +1,346 @@
+/**
+ * Check a tool call's arguments against a JSON Schema, returning every problem
+ * found (empty when the arguments fit).
+ *
+ * This is the subset of JSON Schema that tool schemas actually use: `type`
+ * (including `integer`, `null` and type arrays), `properties`, `required`,
+ * `additionalProperties`, `enum`, `const`, `items` / `prefixItems`, the
+ * length, size and range bounds, `pattern`, `allOf` / `anyOf` / `oneOf`,
+ * local `$ref`s (`#/$defs/...`, `#/definitions/...`) and OpenAPI's
+ * `nullable`. A `$ref`'s sibling keywords apply as in 2019-09 and later, and
+ * are ignored when the root `$schema` names draft 03 to 07, where a `$ref`
+ * replaced its whole schema object; `const` is ignored before draft 6 and
+ * `prefixItems` before 2020-12, the drafts that introduced them. Any other keyword (`format`, `not`,
+ * `if`/`then`/`else`, `multipleOf`, `uniqueItems`, the `dependent*` family, a
+ * remote or malformed `$ref`, a local `$ref` inside an embedded resource with
+ * its own `$id`, a `type` name outside the seven JSON types) is ignored, and
+ * `oneOf` is read as `anyOf`. A schema whose check would take more than a
+ * fixed amount of work is not judged at all: no problems are returned.
+ *
+ * Ignoring is the point: the validator may let a bad call through, but it
+ * never refuses a call the schema accepts. A refusal costs the model a turn,
+ * so a false one is worse than a missed one, and a schema written by someone
+ * else (an MCP server's) can use any keyword it likes without the run
+ * starting to refuse calls its server would have taken.
+ *
+ * `pattern` is compiled and run synchronously on the model's input, like any
+ * regular expression. A schema author's pattern with catastrophic
+ * backtracking (`^(a+)+$`) can stall the event loop, and the run's deadline
+ * cannot interrupt it; turn validation on only for tools whose schemas you
+ * would run that way.
+ */
+export function validateToolInput(schema, input) {
+    const problems = [];
+    try {
+        check(schema, input, "", { root: schema, scoped: false, work: { left: MAX_WORK } }, 0, problems);
+    }
+    catch (err) {
+        // A schema too costly to judge is one the validator cannot judge.
+        if (err instanceof WorkExhausted)
+            return [];
+        throw err;
+    }
+    return problems;
+}
+/** How many problems the model is told about; the rest are counted. */
+const MAX_REPORTED = 10;
+/**
+ * The tool result a call gets when its arguments fail the tool's schema, or
+ * `undefined` when they fit. The loop answers the call with this instead of
+ * running it, and the model corrects the call within its own budgets.
+ */
+export function invalidInputRefusal(tool, input) {
+    let problems;
+    try {
+        problems = validateToolInput(tool.spec.inputSchema, input);
+    }
+    catch {
+        // A schema the validator trips over is one it cannot judge: the call runs,
+        // as it would with validation off, rather than the run failing.
+        return undefined;
+    }
+    if (problems.length === 0)
+        return undefined;
+    const shown = problems
+        .slice(0, MAX_REPORTED)
+        .map((p) => `${p.path || "(arguments)"}: ${p.message}`);
+    const more = problems.length - shown.length;
+    return (`invalid arguments for ${tool.spec.name}; the call was not run. ` +
+        `Call it again with arguments that match its input schema: ${shown.join("; ")}` +
+        (more > 0 ? `; and ${more} more` : ""));
+}
+/** Deep enough for any real tool schema; a `$ref` cycle stops here instead of looping. */
+const MAX_DEPTH = 32;
+/**
+ * How many schema/value checks one validation may make. Shared definitions
+ * referenced from several composition branches can multiply the work
+ * exponentially without any cycle, and validation runs synchronously before
+ * the call, where no deadline can interrupt it; past this the validator gives
+ * up and the call runs unjudged.
+ */
+const MAX_WORK = 25_000;
+class WorkExhausted extends Error {
+}
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** The JSON type of a parsed value, as JSON Schema names it. */
+function jsonType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+}
+const JSON_TYPES = new Set(["null", "boolean", "object", "array", "number", "integer", "string"]);
+/**
+ * The draft the root schema declares in `$schema`: 3 to 7 for draft-03 to
+ * draft-07, 2019 for 2019-09, 2020 for 2020-12, or `undefined` when it names
+ * none (then every keyword the validator knows applies).
+ */
+function declaredDraft(root) {
+    const declared = isObject(root) ? root.$schema : undefined;
+    if (typeof declared !== "string")
+        return undefined;
+    const old = /draft-0([3-7])\b/.exec(declared);
+    if (old)
+        return Number(old[1]);
+    if (declared.includes("2019-09"))
+        return 2019;
+    if (declared.includes("2020-12"))
+        return 2020;
+    return undefined;
+}
+/** Whether the root schema declares a draft (03 to 07) in which `$ref` siblings are ignored. */
+function refReplacesSiblings(root) {
+    const draft = declaredDraft(root);
+    return draft !== undefined && draft <= 7;
+}
+/** Whether a keyword introduced in `since` exists in the draft the root schema declares. */
+function inDraft(root, since) {
+    const draft = declaredDraft(root);
+    return draft === undefined || draft >= since;
+}
+function typeMatches(expected, actual) {
+    return expected === actual || (expected === "number" && actual === "integer");
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isObject(a) && isObject(b)) {
+        const keys = Object.keys(a);
+        return (keys.length === Object.keys(b).length &&
+            keys.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k])));
+    }
+    return false;
+}
+/** A pattern the validator can compile, or `undefined` for one it cannot (then the keyword is ignored). */
+function compile(pattern) {
+    if (typeof pattern !== "string")
+        return undefined;
+    try {
+        return new RegExp(pattern, "u");
+    }
+    catch {
+        try {
+            return new RegExp(pattern);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Resolve a local `#/...` JSON Pointer against the root schema. */
+function resolveRef(root, ref) {
+    if (!ref.startsWith("#"))
+        return undefined;
+    // The fragment is percent-decoded as a whole before it is read as a JSON
+    // Pointer (RFC 6901 §6), so an encoded `/` (`%2F`) separates tokens.
+    let fragment;
+    try {
+        fragment = decodeURIComponent(ref.slice(1));
+    }
+    catch {
+        // A malformed escape (`%` not followed by two hex digits) names nothing.
+        return undefined;
+    }
+    if (fragment === "")
+        return root;
+    if (!fragment.startsWith("/"))
+        return undefined;
+    let node = root;
+    for (const raw of fragment.slice(1).split("/")) {
+        const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (!isObject(node) && !Array.isArray(node))
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+const pointer = (path, key) => `${path}/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const num = (v) => (typeof v === "number" ? v : undefined);
+const quoted = (values) => {
+    const shown = values.slice(0, MAX_REPORTED).map((v) => JSON.stringify(v));
+    return values.length > shown.length ? `${shown.join(", ")}, …` : shown.join(", ");
+};
+function check(schema, value, path, outer, depth, problems) {
+    if (--outer.work.left < 0)
+        throw new WorkExhausted();
+    if (schema === false) {
+        problems.push({ path, message: "is not allowed" });
+        return;
+    }
+    if (!isObject(schema) || depth > MAX_DEPTH)
+        return;
+    const s = schema;
+    const env = !outer.scoped &&
+        schema !== outer.root &&
+        (typeof s.$id === "string" || typeof s.id === "string")
+        ? { ...outer, scoped: true }
+        : outer;
+    const at = (message) => problems.push({ path, message });
+    // OpenAPI's `nullable` admits null whatever else the schema says, composition
+    // included (generators emit `{ allOf: [{ $ref }], nullable: true }`).
+    if (s.nullable === true && value === null)
+        return;
+    if (typeof s.$ref === "string") {
+        // Inside an embedded resource a local `$ref` means that resource, which
+        // this validator does not track, so it is ignored rather than misread.
+        const target = env.scoped ? undefined : resolveRef(env.root, s.$ref);
+        if (target !== undefined)
+            check(target, value, path, env, depth + 1, problems);
+        // Before 2019-09 a `$ref` replaced its whole schema object: the keywords
+        // beside it are ignored, so they are ignored here too.
+        if (refReplacesSiblings(env.root))
+            return;
+    }
+    if (Array.isArray(s.allOf)) {
+        for (const branch of s.allOf)
+            check(branch, value, path, env, depth + 1, problems);
+    }
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = s[key];
+        if (!Array.isArray(branches) || branches.length === 0)
+            continue;
+        const fits = branches.some((branch) => {
+            const inner = [];
+            check(branch, value, path, env, depth + 1, inner);
+            return inner.length === 0;
+        });
+        if (!fits)
+            at(`matches none of the ${branches.length} allowed shapes`);
+    }
+    const actual = jsonType(value);
+    const types = typeof s.type === "string" ? [s.type] : Array.isArray(s.type) ? s.type : undefined;
+    // A type name outside the seven JSON types (draft 3's `any`, a typo) is a
+    // keyword the validator does not know, so the whole `type` check is skipped.
+    const knownTypes = types !== undefined &&
+        types.length > 0 &&
+        types.every((t) => typeof t === "string" && JSON_TYPES.has(t));
+    if (types && knownTypes && !types.some((t) => typeMatches(t, actual))) {
+        // "integer" is the schema's word for a kind of number, not a type a model writes.
+        at(`expected ${types.join(" or ")}, got ${actual === "integer" ? "number" : actual}`);
+        // The keywords below would only restate a wrong type as several problems.
+        return;
+    }
+    if (Array.isArray(s.enum) && !s.enum.some((v) => deepEqual(v, value))) {
+        at(`must be one of ${quoted(s.enum)}`);
+    }
+    // `const` arrived in draft 6; an older schema's `const` is an unknown keyword.
+    if (Object.hasOwn(s, "const") && inDraft(env.root, 6) && !deepEqual(s.const, value)) {
+        at(`must be ${JSON.stringify(s.const)}`);
+    }
+    if (typeof value === "string") {
+        const length = [...value].length;
+        const min = num(s.minLength);
+        const max = num(s.maxLength);
+        if (min !== undefined && length < min)
+            at(`must be at least ${min} characters`);
+        if (max !== undefined && length > max)
+            at(`must be at most ${max} characters`);
+        const pattern = compile(s.pattern);
+        if (pattern && !pattern.test(value))
+            at(`must match the pattern ${String(s.pattern)}`);
+    }
+    if (typeof value === "number") {
+        const min = num(s.minimum);
+        const max = num(s.maximum);
+        // Draft 4 spelled the exclusive bounds as booleans beside minimum/maximum.
+        const exMin = num(s.exclusiveMinimum) ?? (s.exclusiveMinimum === true ? min : undefined);
+        const exMax = num(s.exclusiveMaximum) ?? (s.exclusiveMaximum === true ? max : undefined);
+        if (min !== undefined && s.exclusiveMinimum !== true && value < min)
+            at(`must be >= ${min}`);
+        if (max !== undefined && s.exclusiveMaximum !== true && value > max)
+            at(`must be <= ${max}`);
+        if (exMin !== undefined && value <= exMin)
+            at(`must be > ${exMin}`);
+        if (exMax !== undefined && value >= exMax)
+            at(`must be < ${exMax}`);
+    }
+    if (Array.isArray(value)) {
+        const min = num(s.minItems);
+        const max = num(s.maxItems);
+        if (min !== undefined && value.length < min)
+            at(`must have at least ${min} items`);
+        if (max !== undefined && value.length > max)
+            at(`must have at most ${max} items`);
+        // Positional schemas: `prefixItems` (2020-12) or an `items` array (draft 7).
+        // `prefixItems` arrived in 2020-12; under an older declared draft it is unknown.
+        const positional = Array.isArray(s.prefixItems) && inDraft(env.root, 2020)
+            ? s.prefixItems
+            : Array.isArray(s.items)
+                ? s.items
+                : [];
+        positional.forEach((item, i) => {
+            if (i < value.length)
+                check(item, value[i], pointer(path, i), env, depth + 1, problems);
+        });
+        if (!Array.isArray(s.items) && s.items !== undefined) {
+            for (let i = positional.length; i < value.length; i += 1) {
+                check(s.items, value[i], pointer(path, i), env, depth + 1, problems);
+            }
+        }
+    }
+    if (isObject(value)) {
+        const properties = isObject(s.properties) ? s.properties : {};
+        if (Array.isArray(s.required)) {
+            for (const key of s.required) {
+                if (typeof key === "string" && !Object.hasOwn(value, key)) {
+                    problems.push({ path: pointer(path, key), message: "is required" });
+                }
+            }
+        }
+        const min = num(s.minProperties);
+        const max = num(s.maxProperties);
+        const count = Object.keys(value).length;
+        if (min !== undefined && count < min)
+            at(`must have at least ${min} properties`);
+        if (max !== undefined && count > max)
+            at(`must have at most ${max} properties`);
+        // A key matched by `patternProperties` is not "additional". If any of its
+        // patterns cannot be compiled, nothing can be called additional with
+        // confidence, so that check is skipped rather than guessed.
+        const patternKeys = isObject(s.patternProperties) ? Object.keys(s.patternProperties) : [];
+        const patterns = patternKeys.map(compile);
+        const additionalKnown = patterns.every((p) => p !== undefined);
+        for (const [key, item] of Object.entries(value)) {
+            const where = pointer(path, key);
+            if (Object.hasOwn(properties, key)) {
+                check(properties[key], item, where, env, depth + 1, problems);
+                continue;
+            }
+            if (!additionalKnown || patterns.some((p) => p?.test(key)))
+                continue;
+            if (s.additionalProperties === false) {
+                problems.push({ path: where, message: "is not an allowed property" });
+            }
+            else if (isObject(s.additionalProperties)) {
+                check(s.additionalProperties, item, where, env, depth + 1, problems);
+            }
+        }
+    }
+}
+//# sourceMappingURL=validate.js.map