@warlock.js/ai 4.2.11 → 4.4.0

package/esm/planner/signature.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/signature.ts"],"sourcesContent":["import type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\n\n/**\n * Delimiter between capability names in a planner signature. A NUL\n * control character can never appear in a real capability name, so it\n * keeps name boundaries unambiguous — a single capability literally\n * named `\"a,b\"` can never collide with the two capabilities\n * `[\"a\", \"b\"]` (a comma delimiter would render both as `caps:a,b`).\n */\nconst CAPABILITY_DELIMITER = String.fromCharCode(0);\n\n/**\n * Compute a stable structural fingerprint for a planner definition —\n * the planner name plus its ordered capability names. Stamped on every\n * report node the planner produces so trace consumers can tell runs of\n * structurally-different planners apart even when they share a name.\n *\n * Deliberately coarse: it captures WHICH capabilities the planner can\n * dispatch (and in what registration order), not their descriptions or\n * the underlying executables' internals — those don't change the set of\n * plans the planner can produce.\n */\nexport function computeSignature(name: string, capabilities: PlannerCapability[]): string {\n  const capabilityNames = capabilities\n    .map((capability) => capability.name)\n    .join(CAPABILITY_DELIMITER);\n\n  return `planner:${name}|caps:${capabilityNames}`;\n}\n"],"mappings":";;;;;;;;AASA,MAAM,uBAAuB,OAAO,aAAa,CAAC;;;;;;;;;;;;AAalD,SAAgB,iBAAiB,MAAc,cAA2C;CAKxF,OAAO,WAAW,KAAK,QAJC,aACrB,KAAK,eAAe,WAAW,IAAI,CAAC,CACpC,KAAK,oBAEqC;AAC/C"}

package/esm/snapshot/index.d.mts

@@ -0,0 +1,3 @@
+import { memory } from "./memory.mjs";
+import { PgSnapshotStoreOptions, pg } from "./pg.mjs";
+import { RedisSnapshotStoreOptions, redis } from "./redis.mjs";

package/esm/snapshot/memory.d.mts

@@ -0,0 +1,26 @@
+import { SupervisorSnapshot } from "../contracts/supervisor/supervisor-snapshot.type.mjs";
+import { SnapshotStore } from "../contracts/orchestrator/snapshot-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/snapshot/memory.d.ts
+/**
+ * Create an in-memory {@link SnapshotStore}. Zero-config — no client,
+ * no connection. Suitable for dev, tests, and single-process apps that
+ * don't need to resume an interrupted `iterate: true` turn across
+ * restarts.
+ *
+ * @example
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const orchestrator = ai.orchestrator({
+ *   name: "support",
+ *   intents: { ... },
+ *   iterate: true,
+ *   snapshotStore: ai.snapshot.memory(),
+ * });
+ */
+declare function memory<TSnapshot extends {
+  runId: string;
+} = SupervisorSnapshot>(): SnapshotStore<TSnapshot>;
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.d.mts.map

package/esm/snapshot/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/memory.ts"],"mappings":";;;;;;AAwFA;;;;;;;;;;;;;;iBAAgB,MAAA;EACM,KAAA;AAAA,IAAkB,kBAAA,KACnC,aAAA,CAAc,SAAA"}

package/esm/snapshot/memory.mjs

@@ -0,0 +1,81 @@
+//#region ../@warlock.js/ai/src/snapshot/memory.ts
+/**
+* In-memory {@link SnapshotStore} — supervisor run snapshots held in a
+* process-local `Map`, keyed by `runId`, never persisted to disk.
+*
+* Owns: the `runId` → {@link SupervisorSnapshot} mapping for
+* `iterate: true` mid-turn resume. Does NOT own: durability,
+* cross-process sharing, or TTL eviction — it is the zero-config
+* default for dev, tests, and single-process apps. Reach for
+* `ai.snapshot.pg()` / `ai.snapshot.redis()` (Phase 2) when a crashed
+* process must resume an in-flight turn.
+*
+* Front it with the {@link memory} factory — callers never `new` it.
+*/
+var MemorySnapshotStore = class {
+	constructor() {
+		this.snapshots = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Return the snapshot for a `runId`, or `undefined` when no in-flight
+	* run is recorded.
+	*/
+	async load(runId) {
+		return this.snapshots.get(runId);
+	}
+	/**
+	* Persist a snapshot, keyed by its own `runId`. Overwrites any prior
+	* snapshot for the same run — a run has exactly one live snapshot.
+	*/
+	async save(snapshot) {
+		this.snapshots.set(snapshot.runId, snapshot);
+	}
+	/**
+	* Drop the snapshot for a `runId`.
+	*/
+	async delete(runId) {
+		this.snapshots.delete(runId);
+	}
+	/**
+	* List the known run ids, optionally filtered by a prefix.
+	*/
+	async list(prefix) {
+		const runIds = [];
+		for (const runId of this.snapshots.keys()) {
+			if (prefix !== void 0 && !runId.startsWith(prefix)) continue;
+			runIds.push(runId);
+		}
+		return runIds;
+	}
+	/**
+	* The memory store has no backing table — there is nothing to
+	* migrate. Returns an empty string so callers can treat `schema()`
+	* uniformly across drivers.
+	*/
+	schema() {
+		return "";
+	}
+};
+/**
+* Create an in-memory {@link SnapshotStore}. Zero-config — no client,
+* no connection. Suitable for dev, tests, and single-process apps that
+* don't need to resume an interrupted `iterate: true` turn across
+* restarts.
+*
+* @example
+* import { ai } from "@warlock.js/ai";
+*
+* const orchestrator = ai.orchestrator({
+*   name: "support",
+*   intents: { ... },
+*   iterate: true,
+*   snapshotStore: ai.snapshot.memory(),
+* });
+*/
+function memory() {
+	return new MemorySnapshotStore();
+}
+
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.mjs.map

package/esm/snapshot/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/memory.ts"],"sourcesContent":["import type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { SupervisorSnapshot } from \"../contracts/supervisor/supervisor-snapshot.type\";\n\n/**\n * In-memory {@link SnapshotStore} — supervisor run snapshots held in a\n * process-local `Map`, keyed by `runId`, never persisted to disk.\n *\n * Owns: the `runId` → {@link SupervisorSnapshot} mapping for\n * `iterate: true` mid-turn resume. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps. Reach for\n * `ai.snapshot.pg()` / `ai.snapshot.redis()` (Phase 2) when a crashed\n * process must resume an in-flight turn.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemorySnapshotStore<TSnapshot extends { runId: string }>\n  implements SnapshotStore<TSnapshot>\n{\n  /** Snapshots keyed by `runId`. */\n  private readonly snapshots = new Map<string, TSnapshot>();\n\n  /**\n   * Return the snapshot for a `runId`, or `undefined` when no in-flight\n   * run is recorded.\n   */\n  public async load(runId: string): Promise<TSnapshot | undefined> {\n    return this.snapshots.get(runId);\n  }\n\n  /**\n   * Persist a snapshot, keyed by its own `runId`. Overwrites any prior\n   * snapshot for the same run — a run has exactly one live snapshot.\n   */\n  public async save(snapshot: TSnapshot): Promise<void> {\n    this.snapshots.set(snapshot.runId, snapshot);\n  }\n\n  /**\n   * Drop the snapshot for a `runId`.\n   */\n  public async delete(runId: string): Promise<void> {\n    this.snapshots.delete(runId);\n  }\n\n  /**\n   * List the known run ids, optionally filtered by a prefix.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const runIds: string[] = [];\n\n    for (const runId of this.snapshots.keys()) {\n      if (prefix !== undefined && !runId.startsWith(prefix)) {\n        continue;\n      }\n\n      runIds.push(runId);\n    }\n\n    return runIds;\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link SnapshotStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need to resume an interrupted `iterate: true` turn across\n * restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   iterate: true,\n *   snapshotStore: ai.snapshot.memory(),\n * });\n */\nexport function memory<\n  TSnapshot extends { runId: string } = SupervisorSnapshot,\n>(): SnapshotStore<TSnapshot> {\n  return new MemorySnapshotStore<TSnapshot>();\n}\n"],"mappings":";;;;;;;;;;;;;;AAgBA,IAAM,sBAAN,MAEA;;mCAE+B,IAAI,IAAuB;;;;;;CAMxD,MAAa,KAAK,OAA+C;EAC/D,OAAO,KAAK,UAAU,IAAI,KAAK;CACjC;;;;;CAMA,MAAa,KAAK,UAAoC;EACpD,KAAK,UAAU,IAAI,SAAS,OAAO,QAAQ;CAC7C;;;;CAKA,MAAa,OAAO,OAA8B;EAChD,KAAK,UAAU,OAAO,KAAK;CAC7B;;;;CAKA,MAAa,KAAK,QAAoC;EACpD,MAAM,SAAmB,CAAC;EAE1B,KAAK,MAAM,SAAS,KAAK,UAAU,KAAK,GAAG;GACzC,IAAI,WAAW,UAAa,CAAC,MAAM,WAAW,MAAM,GAClD;GAGF,OAAO,KAAK,KAAK;EACnB;EAEA,OAAO;CACT;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,SAEc;CAC5B,OAAO,IAAI,oBAA+B;AAC5C"}

package/esm/snapshot/pg.d.mts

@@ -0,0 +1,41 @@
+import { PgClientLike, SnapshotStore } from "../contracts/orchestrator/snapshot-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/snapshot/pg.d.ts
+/**
+ * Options for {@link pg}. The `client` is an already-built `pg.Pool` /
+ * `pg.Client` (anything satisfying {@link PgClientLike}); the store never
+ * opens or closes it — connection lifecycle stays with the caller.
+ */
+type PgSnapshotStoreOptions = {
+  /** Pre-built pg client. The store only ever calls `query`. */client: PgClientLike; /** Table name. Defaults to `warlock_supervisor_snapshots`. */
+  table?: string;
+};
+/**
+ * Create a Postgres-backed {@link SnapshotStore}. Pass a live
+ * `pg.Pool`/`pg.Client` — the store never opens or closes it. Schema is
+ * not auto-migrated: run {@link SnapshotStore.schema} through your own
+ * migration tool first.
+ *
+ * @example
+ * import { Pool } from "pg";
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ *
+ * const orchestrator = ai.orchestrator({
+ *   name: "support",
+ *   intents: { ... },
+ *   iterate: true,
+ *   snapshotStore: ai.snapshot.pg({
+ *     client: pool,
+ *     table: "warlock_supervisor_snapshots",
+ *   }),
+ * });
+ *
+ * // Run once, via your own migration tooling:
+ * // await pool.query(orchestrator's store.schema());
+ */
+declare function pg(options: PgSnapshotStoreOptions): SnapshotStore;
+//#endregion
+export { PgSnapshotStoreOptions, pg };
+//# sourceMappingURL=pg.d.mts.map

package/esm/snapshot/pg.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/pg.ts"],"mappings":";;;;;AA2BA;;;KAAY,sBAAA;EAEV,8DAAA,MAAA,EAAQ,YAAY,EAEpB;EAAA,KAAA;AAAA;AAmLF;;;;;;;;AAAkE;;;;;;;;;;;;;;;;;AAAlE,iBAAgB,EAAA,CAAG,OAAA,EAAS,sBAAA,GAAyB,aAAa"}

package/esm/snapshot/pg.mjs

@@ -0,0 +1,146 @@
+//#region ../@warlock.js/ai/src/snapshot/pg.ts
+/**
+* Default backing table for the pg snapshot store. Matches the name used
+* in the orchestrator.md §8 reference wiring
+* (`ai.snapshot.pg({ client, table: "warlock_supervisor_snapshots" })`).
+*/
+const DEFAULT_TABLE = "warlock_supervisor_snapshots";
+/**
+* Allowed characters in a Postgres identifier (table name). The
+* conservative ASCII subset; anything else is rejected because the table
+* name is interpolated directly into DDL/DML, and an arbitrary string
+* there would be a SQL-injection footgun. Mirrors `@warlock.js/cache`'s
+* `PgCacheDriver`.
+*/
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Validate and resolve the table name. Throws on an unsafe identifier so
+* the failure surfaces at construction time, not on the first query.
+*/
+function resolveTable(table) {
+	const resolved = table ?? DEFAULT_TABLE;
+	if (!SAFE_IDENTIFIER.test(resolved)) throw new Error(`Pg snapshot store: invalid table name '${resolved}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+	return resolved;
+}
+/**
+* Coerce a `payload` column value back into a {@link SupervisorSnapshot}.
+* node-postgres parses `JSONB` into a JS value already, but some pool
+* wrappers hand back the raw string — be defensive across both.
+*/
+function parsePayload(payload) {
+	if (typeof payload === "string") return JSON.parse(payload);
+	return payload;
+}
+/**
+* Postgres {@link SnapshotStore} — supervisor run snapshots persisted to a
+* single row per `runId` in a dev-provisioned table (orchestrator.md §8).
+*
+* Owns: durable round-tripping of the {@link SupervisorSnapshot} envelope
+* keyed by `runId`, so a crashed mid-turn `iterate: true` iteration can
+* resume after a restart. Does NOT own: the connection (the caller passes
+* a live `pg.Pool`/`pg.Client` and keeps owning its lifecycle) or schema
+* migration ({@link PgSnapshotStore.schema} returns DDL the dev runs
+* themselves — the framework never auto-migrates, §8.5).
+*
+* Unlike the append-only checkpoint store, a run has exactly one live
+* snapshot, so `save()` upserts on the `run_id` primary key.
+*
+* Front it with the {@link pg} factory — callers never `new` it.
+*/
+var PgSnapshotStore = class {
+	constructor(options) {
+		if (!options || !options.client || typeof options.client.query !== "function") throw new Error("Pg snapshot store requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
+		this.client = options.client;
+		this.table = resolveTable(options.table);
+	}
+	/**
+	* Load the snapshot for a `runId`, or `undefined` when no in-flight run
+	* is recorded.
+	*/
+	async load(runId) {
+		const { rows } = await this.client.query(`SELECT payload FROM ${this.table} WHERE run_id = $1`, [runId]);
+		if (rows.length === 0) return;
+		return parsePayload(rows[0].payload);
+	}
+	/**
+	* Persist a snapshot, keyed by its own `runId`. Upserts — a run has
+	* exactly one live snapshot, so a second save for the same `runId`
+	* overwrites the payload rather than appending.
+	*/
+	async save(snapshot) {
+		await this.client.query(`INSERT INTO ${this.table} (run_id, payload, saved_at)
+       VALUES ($1, $2::jsonb, now())
+       ON CONFLICT (run_id) DO UPDATE
+         SET payload = EXCLUDED.payload,
+             saved_at = EXCLUDED.saved_at`, [snapshot.runId, JSON.stringify(snapshot)]);
+	}
+	/**
+	* Drop the snapshot for a `runId`.
+	*/
+	async delete(runId) {
+		await this.client.query(`DELETE FROM ${this.table} WHERE run_id = $1`, [runId]);
+	}
+	/**
+	* List the known run ids, optionally filtered by a prefix. The `_` and
+	* `%` LIKE wildcards in the prefix are escaped so an opaque runId that
+	* happens to contain them is matched literally.
+	*/
+	async list(prefix) {
+		if (prefix === void 0) {
+			const { rows } = await this.client.query(`SELECT run_id FROM ${this.table}`);
+			return rows.map((row) => row.run_id);
+		}
+		const escaped = prefix.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+		const { rows } = await this.client.query(`SELECT run_id FROM ${this.table} WHERE run_id LIKE $1 ESCAPE '\\'`, [`${escaped}%`]);
+		return rows.map((row) => row.run_id);
+	}
+	/**
+	* Return the DDL for this store's backing table. Run once via the
+	* caller's migration tooling — the store never auto-migrates (§8.5).
+	*
+	* @example
+	* await pool.query(store.schema());
+	*/
+	schema() {
+		return [
+			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
+			`  run_id    TEXT PRIMARY KEY,`,
+			`  payload   JSONB NOT NULL,`,
+			`  saved_at  TIMESTAMPTZ NOT NULL DEFAULT now()`,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at ON ${this.table} (saved_at);`
+		].join("\n");
+	}
+};
+/**
+* Create a Postgres-backed {@link SnapshotStore}. Pass a live
+* `pg.Pool`/`pg.Client` — the store never opens or closes it. Schema is
+* not auto-migrated: run {@link SnapshotStore.schema} through your own
+* migration tool first.
+*
+* @example
+* import { Pool } from "pg";
+* import { ai } from "@warlock.js/ai";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+*
+* const orchestrator = ai.orchestrator({
+*   name: "support",
+*   intents: { ... },
+*   iterate: true,
+*   snapshotStore: ai.snapshot.pg({
+*     client: pool,
+*     table: "warlock_supervisor_snapshots",
+*   }),
+* });
+*
+* // Run once, via your own migration tooling:
+* // await pool.query(orchestrator's store.schema());
+*/
+function pg(options) {
+	return new PgSnapshotStore(options);
+}
+
+//#endregion
+export { pg };
+//# sourceMappingURL=pg.mjs.map

package/esm/snapshot/pg.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/pg.ts"],"sourcesContent":["import type {\n  PgClientLike,\n  SnapshotStore,\n} from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { SupervisorSnapshot } from \"../contracts/supervisor/supervisor-snapshot.type\";\n\n/**\n * Default backing table for the pg snapshot store. Matches the name used\n * in the orchestrator.md §8 reference wiring\n * (`ai.snapshot.pg({ client, table: \"warlock_supervisor_snapshots\" })`).\n */\nconst DEFAULT_TABLE = \"warlock_supervisor_snapshots\";\n\n/**\n * Allowed characters in a Postgres identifier (table name). The\n * conservative ASCII subset; anything else is rejected because the table\n * name is interpolated directly into DDL/DML, and an arbitrary string\n * there would be a SQL-injection footgun. Mirrors `@warlock.js/cache`'s\n * `PgCacheDriver`.\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Options for {@link pg}. The `client` is an already-built `pg.Pool` /\n * `pg.Client` (anything satisfying {@link PgClientLike}); the store never\n * opens or closes it — connection lifecycle stays with the caller.\n */\nexport type PgSnapshotStoreOptions = {\n  /** Pre-built pg client. The store only ever calls `query`. */\n  client: PgClientLike;\n  /** Table name. Defaults to `warlock_supervisor_snapshots`. */\n  table?: string;\n};\n\n/**\n * Validate and resolve the table name. Throws on an unsafe identifier so\n * the failure surfaces at construction time, not on the first query.\n */\nfunction resolveTable(table: string | undefined): string {\n  const resolved = table ?? DEFAULT_TABLE;\n\n  if (!SAFE_IDENTIFIER.test(resolved)) {\n    throw new Error(\n      `Pg snapshot store: invalid table name '${resolved}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n    );\n  }\n\n  return resolved;\n}\n\n/**\n * Coerce a `payload` column value back into a {@link SupervisorSnapshot}.\n * node-postgres parses `JSONB` into a JS value already, but some pool\n * wrappers hand back the raw string — be defensive across both.\n */\nfunction parsePayload(payload: unknown): SupervisorSnapshot {\n  if (typeof payload === \"string\") {\n    return JSON.parse(payload) as SupervisorSnapshot;\n  }\n\n  return payload as SupervisorSnapshot;\n}\n\n/**\n * Postgres {@link SnapshotStore} — supervisor run snapshots persisted to a\n * single row per `runId` in a dev-provisioned table (orchestrator.md §8).\n *\n * Owns: durable round-tripping of the {@link SupervisorSnapshot} envelope\n * keyed by `runId`, so a crashed mid-turn `iterate: true` iteration can\n * resume after a restart. Does NOT own: the connection (the caller passes\n * a live `pg.Pool`/`pg.Client` and keeps owning its lifecycle) or schema\n * migration ({@link PgSnapshotStore.schema} returns DDL the dev runs\n * themselves — the framework never auto-migrates, §8.5).\n *\n * Unlike the append-only checkpoint store, a run has exactly one live\n * snapshot, so `save()` upserts on the `run_id` primary key.\n *\n * Front it with the {@link pg} factory — callers never `new` it.\n */\nclass PgSnapshotStore implements SnapshotStore {\n  /** The user-supplied pg client. The store only ever calls `query`. */\n  private readonly client: PgClientLike;\n\n  /** Validated, resolved table name. Safe to interpolate into SQL. */\n  private readonly table: string;\n\n  public constructor(options: PgSnapshotStoreOptions) {\n    if (!options || !options.client || typeof options.client.query !== \"function\") {\n      throw new Error(\n        \"Pg snapshot store requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n      );\n    }\n\n    this.client = options.client;\n    this.table = resolveTable(options.table);\n  }\n\n  /**\n   * Load the snapshot for a `runId`, or `undefined` when no in-flight run\n   * is recorded.\n   */\n  public async load(runId: string): Promise<SupervisorSnapshot | undefined> {\n    const { rows } = await this.client.query(\n      `SELECT payload FROM ${this.table} WHERE run_id = $1`,\n      [runId],\n    );\n\n    if (rows.length === 0) {\n      return undefined;\n    }\n\n    return parsePayload((rows[0] as { payload: unknown }).payload);\n  }\n\n  /**\n   * Persist a snapshot, keyed by its own `runId`. Upserts — a run has\n   * exactly one live snapshot, so a second save for the same `runId`\n   * overwrites the payload rather than appending.\n   */\n  public async save(snapshot: SupervisorSnapshot): Promise<void> {\n    await this.client.query(\n      `INSERT INTO ${this.table} (run_id, payload, saved_at)\n       VALUES ($1, $2::jsonb, now())\n       ON CONFLICT (run_id) DO UPDATE\n         SET payload = EXCLUDED.payload,\n             saved_at = EXCLUDED.saved_at`,\n      [snapshot.runId, JSON.stringify(snapshot)],\n    );\n  }\n\n  /**\n   * Drop the snapshot for a `runId`.\n   */\n  public async delete(runId: string): Promise<void> {\n    await this.client.query(`DELETE FROM ${this.table} WHERE run_id = $1`, [\n      runId,\n    ]);\n  }\n\n  /**\n   * List the known run ids, optionally filtered by a prefix. The `_` and\n   * `%` LIKE wildcards in the prefix are escaped so an opaque runId that\n   * happens to contain them is matched literally.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    if (prefix === undefined) {\n      const { rows } = await this.client.query(\n        `SELECT run_id FROM ${this.table}`,\n      );\n\n      return rows.map((row) => (row as { run_id: string }).run_id);\n    }\n\n    const escaped = prefix\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    const { rows } = await this.client.query(\n      `SELECT run_id FROM ${this.table} WHERE run_id LIKE $1 ESCAPE '\\\\'`,\n      [`${escaped}%`],\n    );\n\n    return rows.map((row) => (row as { run_id: string }).run_id);\n  }\n\n  /**\n   * Return the DDL for this store's backing table. Run once via the\n   * caller's migration tooling — the store never auto-migrates (§8.5).\n   *\n   * @example\n   * await pool.query(store.schema());\n   */\n  public schema(): string {\n    return [\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  run_id    TEXT PRIMARY KEY,`,\n      `  payload   JSONB NOT NULL,`,\n      `  saved_at  TIMESTAMPTZ NOT NULL DEFAULT now()`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at ON ${this.table} (saved_at);`,\n    ].join(\"\\n\");\n  }\n}\n\n/**\n * Create a Postgres-backed {@link SnapshotStore}. Pass a live\n * `pg.Pool`/`pg.Client` — the store never opens or closes it. Schema is\n * not auto-migrated: run {@link SnapshotStore.schema} through your own\n * migration tool first.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   iterate: true,\n *   snapshotStore: ai.snapshot.pg({\n *     client: pool,\n *     table: \"warlock_supervisor_snapshots\",\n *   }),\n * });\n *\n * // Run once, via your own migration tooling:\n * // await pool.query(orchestrator's store.schema());\n */\nexport function pg(options: PgSnapshotStoreOptions): SnapshotStore {\n  return new PgSnapshotStore(options);\n}\n"],"mappings":";;;;;;AAWA,MAAM,gBAAgB;;;;;;;;AAStB,MAAM,kBAAkB;;;;;AAkBxB,SAAS,aAAa,OAAmC;CACvD,MAAM,WAAW,SAAS;CAE1B,IAAI,CAAC,gBAAgB,KAAK,QAAQ,GAChC,MAAM,IAAI,MACR,0CAA0C,SAAS,oCACrD;CAGF,OAAO;AACT;;;;;;AAOA,SAAS,aAAa,SAAsC;CAC1D,IAAI,OAAO,YAAY,UACrB,OAAO,KAAK,MAAM,OAAO;CAG3B,OAAO;AACT;;;;;;;;;;;;;;;;;AAkBA,IAAM,kBAAN,MAA+C;CAO7C,AAAO,YAAY,SAAiC;EAClD,IAAI,CAAC,WAAW,CAAC,QAAQ,UAAU,OAAO,QAAQ,OAAO,UAAU,YACjE,MAAM,IAAI,MACR,kHACF;EAGF,KAAK,SAAS,QAAQ;EACtB,KAAK,QAAQ,aAAa,QAAQ,KAAK;CACzC;;;;;CAMA,MAAa,KAAK,OAAwD;EACxE,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,MACjC,uBAAuB,KAAK,MAAM,qBAClC,CAAC,KAAK,CACR;EAEA,IAAI,KAAK,WAAW,GAClB;EAGF,OAAO,aAAc,KAAK,EAAE,CAA0B,OAAO;CAC/D;;;;;;CAOA,MAAa,KAAK,UAA6C;EAC7D,MAAM,KAAK,OAAO,MAChB,eAAe,KAAK,MAAM;;;;4CAK1B,CAAC,SAAS,OAAO,KAAK,UAAU,QAAQ,CAAC,CAC3C;CACF;;;;CAKA,MAAa,OAAO,OAA8B;EAChD,MAAM,KAAK,OAAO,MAAM,eAAe,KAAK,MAAM,qBAAqB,CACrE,KACF,CAAC;CACH;;;;;;CAOA,MAAa,KAAK,QAAoC;EACpD,IAAI,WAAW,QAAW;GACxB,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,MACjC,sBAAsB,KAAK,OAC7B;GAEA,OAAO,KAAK,KAAK,QAAS,IAA2B,MAAM;EAC7D;EAEA,MAAM,UAAU,OACb,QAAQ,OAAO,MAAM,CAAC,CACtB,QAAQ,MAAM,KAAK,CAAC,CACpB,QAAQ,MAAM,KAAK;EAEtB,MAAM,EAAE,SAAS,MAAM,KAAK,OAAO,MACjC,sBAAsB,KAAK,MAAM,oCACjC,CAAC,GAAG,QAAQ,EAAE,CAChB;EAEA,OAAO,KAAK,KAAK,QAAS,IAA2B,MAAM;CAC7D;;;;;;;;CASA,AAAO,SAAiB;EACtB,OAAO;GACL,8BAA8B,KAAK,MAAM;GACzC;GACA;GACA;GACA;GACA,kCAAkC,KAAK,MAAM,eAAe,KAAK,MAAM;EACzE,CAAC,CAAC,KAAK,IAAI;CACb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,GAAG,SAAgD;CACjE,OAAO,IAAI,gBAAgB,OAAO;AACpC"}

package/esm/snapshot/redis.d.mts

@@ -0,0 +1,42 @@
+import { RedisClientLike, SnapshotStore } from "../contracts/orchestrator/snapshot-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/snapshot/redis.d.ts
+/**
+ * Options for {@link redis}. The `client` is an already-connected redis
+ * client (anything satisfying {@link RedisClientLike}); the store never
+ * connects or quits it — connection lifecycle stays with the caller.
+ */
+type RedisSnapshotStoreOptions = {
+  /** Pre-connected redis client. The store only calls `get`/`set`/`del`. */client: RedisClientLike;
+  /**
+   * Key prefix prepended to each `runId`. Defaults to
+   * `warlock:supervisor:snapshot:`.
+   */
+  prefix?: string;
+};
+/**
+ * Create a Redis-backed {@link SnapshotStore}. Pass a connected redis
+ * client — the store never connects or quits it.
+ *
+ * Note: this store does not implement the optional `list()` — the
+ * structural client surface has no `SCAN`/`KEYS`. Use a checkpoint store
+ * for the production boot-drain loop where enumeration is needed.
+ *
+ * @example
+ * import { createClient } from "redis";
+ * import { ai } from "@warlock.js/ai";
+ *
+ * const client = createClient({ url: process.env.REDIS_URL });
+ * await client.connect();
+ *
+ * const orchestrator = ai.orchestrator({
+ *   name: "support",
+ *   intents: { ... },
+ *   iterate: true,
+ *   snapshotStore: ai.snapshot.redis({ client }),
+ * });
+ */
+declare function redis(options: RedisSnapshotStoreOptions): SnapshotStore;
+//#endregion
+export { RedisSnapshotStoreOptions, redis };
+//# sourceMappingURL=redis.d.mts.map

package/esm/snapshot/redis.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/redis.ts"],"mappings":";;;;;AAkBA;;;KAAY,yBAAA;EAEV,0EAAA,MAAA,EAAQ,eAAe;EAKvB;;AAAM;AAqHR;EArHE,MAAA;AAAA;;;;;;AAqHsE;;;;;;;;;;;;;;;;;iBAAxD,KAAA,CAAM,OAAA,EAAS,yBAAA,GAA4B,aAAa"}

package/esm/snapshot/redis.mjs

@@ -0,0 +1,101 @@
+//#region ../@warlock.js/ai/src/snapshot/redis.ts
+/**
+* Default key prefix the redis store prepends to each `runId`. Namespaces
+* the snapshot keys so they coexist with other data in the same Redis
+* database without collision.
+*/
+const DEFAULT_PREFIX = "warlock:supervisor:snapshot:";
+/**
+* Redis {@link SnapshotStore} — supervisor run snapshots persisted as one
+* JSON string value per `runId`, under a namespaced key (orchestrator.md
+* §8).
+*
+* Owns: durable round-tripping of the {@link SupervisorSnapshot} envelope
+* keyed by `runId`, so a crashed mid-turn `iterate: true` iteration can
+* resume after a restart. Does NOT own: the connection (the caller passes
+* a live client and keeps owning its lifecycle) or enumeration — the
+* structural {@link RedisClientLike} surface exposes only `get`/`set`/
+* `del`, with no `SCAN`/`KEYS`, so `list()` is intentionally not
+* implemented (the contract allows stores that can't enumerate to omit
+* it). Pair it with a {@link import("../contracts/orchestrator/checkpoint-store.contract").CheckpointStore}
+* for the boot-drain loop, which is where enumeration is actually needed.
+*
+* `save()` overwrites the key — a run has exactly one live snapshot.
+* Redis needs no schema, so {@link RedisSnapshotStore.schema} returns an
+* empty string for uniformity with the other drivers.
+*
+* Front it with the {@link redis} factory — callers never `new` it.
+*/
+var RedisSnapshotStore = class {
+	constructor(options) {
+		if (!options || !options.client || typeof options.client.get !== "function" || typeof options.client.set !== "function" || typeof options.client.del !== "function") throw new Error("Redis snapshot store requires a 'client' option implementing { get, set, del } — pass a connected redis client.");
+		this.client = options.client;
+		this.prefix = options.prefix ?? DEFAULT_PREFIX;
+	}
+	/**
+	* Build the namespaced Redis key for a `runId`.
+	*/
+	key(runId) {
+		return `${this.prefix}${runId}`;
+	}
+	/**
+	* Load the snapshot for a `runId`, or `undefined` when the key is
+	* missing. Redis returns `null` for an absent key — converted to
+	* `undefined` at the boundary.
+	*/
+	async load(runId) {
+		const value = await this.client.get(this.key(runId));
+		if (value === null) return;
+		return JSON.parse(value);
+	}
+	/**
+	* Persist a snapshot, keyed by its own `runId`. Overwrites any prior
+	* snapshot for the same run — a run has exactly one live snapshot.
+	*/
+	async save(snapshot) {
+		await this.client.set(this.key(snapshot.runId), JSON.stringify(snapshot));
+	}
+	/**
+	* Drop the snapshot for a `runId`.
+	*/
+	async delete(runId) {
+		await this.client.del(this.key(runId));
+	}
+	/**
+	* Redis needs no backing table — there is nothing to migrate. Returns
+	* an empty string so callers can treat `schema()` uniformly across
+	* drivers.
+	*/
+	schema() {
+		return "";
+	}
+};
+/**
+* Create a Redis-backed {@link SnapshotStore}. Pass a connected redis
+* client — the store never connects or quits it.
+*
+* Note: this store does not implement the optional `list()` — the
+* structural client surface has no `SCAN`/`KEYS`. Use a checkpoint store
+* for the production boot-drain loop where enumeration is needed.
+*
+* @example
+* import { createClient } from "redis";
+* import { ai } from "@warlock.js/ai";
+*
+* const client = createClient({ url: process.env.REDIS_URL });
+* await client.connect();
+*
+* const orchestrator = ai.orchestrator({
+*   name: "support",
+*   intents: { ... },
+*   iterate: true,
+*   snapshotStore: ai.snapshot.redis({ client }),
+* });
+*/
+function redis(options) {
+	return new RedisSnapshotStore(options);
+}
+
+//#endregion
+export { redis };
+//# sourceMappingURL=redis.mjs.map

package/esm/snapshot/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/snapshot/redis.ts"],"sourcesContent":["import type {\n  RedisClientLike,\n  SnapshotStore,\n} from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { SupervisorSnapshot } from \"../contracts/supervisor/supervisor-snapshot.type\";\n\n/**\n * Default key prefix the redis store prepends to each `runId`. Namespaces\n * the snapshot keys so they coexist with other data in the same Redis\n * database without collision.\n */\nconst DEFAULT_PREFIX = \"warlock:supervisor:snapshot:\";\n\n/**\n * Options for {@link redis}. The `client` is an already-connected redis\n * client (anything satisfying {@link RedisClientLike}); the store never\n * connects or quits it — connection lifecycle stays with the caller.\n */\nexport type RedisSnapshotStoreOptions = {\n  /** Pre-connected redis client. The store only calls `get`/`set`/`del`. */\n  client: RedisClientLike;\n  /**\n   * Key prefix prepended to each `runId`. Defaults to\n   * `warlock:supervisor:snapshot:`.\n   */\n  prefix?: string;\n};\n\n/**\n * Redis {@link SnapshotStore} — supervisor run snapshots persisted as one\n * JSON string value per `runId`, under a namespaced key (orchestrator.md\n * §8).\n *\n * Owns: durable round-tripping of the {@link SupervisorSnapshot} envelope\n * keyed by `runId`, so a crashed mid-turn `iterate: true` iteration can\n * resume after a restart. Does NOT own: the connection (the caller passes\n * a live client and keeps owning its lifecycle) or enumeration — the\n * structural {@link RedisClientLike} surface exposes only `get`/`set`/\n * `del`, with no `SCAN`/`KEYS`, so `list()` is intentionally not\n * implemented (the contract allows stores that can't enumerate to omit\n * it). Pair it with a {@link import(\"../contracts/orchestrator/checkpoint-store.contract\").CheckpointStore}\n * for the boot-drain loop, which is where enumeration is actually needed.\n *\n * `save()` overwrites the key — a run has exactly one live snapshot.\n * Redis needs no schema, so {@link RedisSnapshotStore.schema} returns an\n * empty string for uniformity with the other drivers.\n *\n * Front it with the {@link redis} factory — callers never `new` it.\n */\nclass RedisSnapshotStore implements SnapshotStore {\n  /** The user-supplied redis client. Only `get`/`set`/`del` are called. */\n  private readonly client: RedisClientLike;\n\n  /** Key prefix prepended to each `runId`. */\n  private readonly prefix: string;\n\n  public constructor(options: RedisSnapshotStoreOptions) {\n    if (\n      !options ||\n      !options.client ||\n      typeof options.client.get !== \"function\" ||\n      typeof options.client.set !== \"function\" ||\n      typeof options.client.del !== \"function\"\n    ) {\n      throw new Error(\n        \"Redis snapshot store requires a 'client' option implementing { get, set, del } — pass a connected redis client.\",\n      );\n    }\n\n    this.client = options.client;\n    this.prefix = options.prefix ?? DEFAULT_PREFIX;\n  }\n\n  /**\n   * Build the namespaced Redis key for a `runId`.\n   */\n  private key(runId: string): string {\n    return `${this.prefix}${runId}`;\n  }\n\n  /**\n   * Load the snapshot for a `runId`, or `undefined` when the key is\n   * missing. Redis returns `null` for an absent key — converted to\n   * `undefined` at the boundary.\n   */\n  public async load(runId: string): Promise<SupervisorSnapshot | undefined> {\n    const value = await this.client.get(this.key(runId));\n\n    if (value === null) {\n      return undefined;\n    }\n\n    return JSON.parse(value) as SupervisorSnapshot;\n  }\n\n  /**\n   * Persist a snapshot, keyed by its own `runId`. Overwrites any prior\n   * snapshot for the same run — a run has exactly one live snapshot.\n   */\n  public async save(snapshot: SupervisorSnapshot): Promise<void> {\n    await this.client.set(this.key(snapshot.runId), JSON.stringify(snapshot));\n  }\n\n  /**\n   * Drop the snapshot for a `runId`.\n   */\n  public async delete(runId: string): Promise<void> {\n    await this.client.del(this.key(runId));\n  }\n\n  /**\n   * Redis needs no backing table — there is nothing to migrate. Returns\n   * an empty string so callers can treat `schema()` uniformly across\n   * drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create a Redis-backed {@link SnapshotStore}. Pass a connected redis\n * client — the store never connects or quits it.\n *\n * Note: this store does not implement the optional `list()` — the\n * structural client surface has no `SCAN`/`KEYS`. Use a checkpoint store\n * for the production boot-drain loop where enumeration is needed.\n *\n * @example\n * import { createClient } from \"redis\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const client = createClient({ url: process.env.REDIS_URL });\n * await client.connect();\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   iterate: true,\n *   snapshotStore: ai.snapshot.redis({ client }),\n * });\n */\nexport function redis(options: RedisSnapshotStoreOptions): SnapshotStore {\n  return new RedisSnapshotStore(options);\n}\n"],"mappings":";;;;;;AAWA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;AAsCvB,IAAM,qBAAN,MAAkD;CAOhD,AAAO,YAAY,SAAoC;EACrD,IACE,CAAC,WACD,CAAC,QAAQ,UACT,OAAO,QAAQ,OAAO,QAAQ,cAC9B,OAAO,QAAQ,OAAO,QAAQ,cAC9B,OAAO,QAAQ,OAAO,QAAQ,YAE9B,MAAM,IAAI,MACR,iHACF;EAGF,KAAK,SAAS,QAAQ;EACtB,KAAK,SAAS,QAAQ,UAAU;CAClC;;;;CAKA,AAAQ,IAAI,OAAuB;EACjC,OAAO,GAAG,KAAK,SAAS;CAC1B;;;;;;CAOA,MAAa,KAAK,OAAwD;EACxE,MAAM,QAAQ,MAAM,KAAK,OAAO,IAAI,KAAK,IAAI,KAAK,CAAC;EAEnD,IAAI,UAAU,MACZ;EAGF,OAAO,KAAK,MAAM,KAAK;CACzB;;;;;CAMA,MAAa,KAAK,UAA6C;EAC7D,MAAM,KAAK,OAAO,IAAI,KAAK,IAAI,SAAS,KAAK,GAAG,KAAK,UAAU,QAAQ,CAAC;CAC1E;;;;CAKA,MAAa,OAAO,OAA8B;EAChD,MAAM,KAAK,OAAO,IAAI,KAAK,IAAI,KAAK,CAAC;CACvC;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,MAAM,SAAmD;CACvE,OAAO,IAAI,mBAAmB,OAAO;AACvC"}

package/esm/supervisor/as-tool.d.mts

@@ -24,12 +24,6 @@ import { SupervisorAsToolOptions, SupervisorContract } from "../contracts/superv
  *   agent sees one uniform error class regardless of which
  *   primitive failed.
  *
- * **Usage caveat** (mirrors workflow-as-tool): nested usage is not
- * rolled into the outer agent's `result.usage` today — the
- * supervisor's tokens stay on the supervisor result. Sum manually
- * if you need a combined cost number until nested-usage
- * standardization lands.
- *
  * @example
  * const support = ai.supervisor({ ... });
  * const supportTool = support.asTool({

package/esm/supervisor/as-tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"as-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/as-tool.ts"],"mappings":";;;;;;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;AAGmC;;;;;;;;;;;iBAHnB,MAAA,sBACd,kBAAA,EAAoB,kBAAA,CAAmB,OAAA,GACvC,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAChC,YAAA,CAAa,UAAA,EAAY,OAAA"}
+{"version":3,"file":"as-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/as-tool.ts"],"mappings":";;;;;;AAsCA;;;;;;;;;;;;;;;;;;;;;;;;AAGmC;;;;;iBAHnB,MAAA,sBACd,kBAAA,EAAoB,kBAAA,CAAmB,OAAA,GACvC,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAChC,YAAA,CAAa,UAAA,EAAY,OAAA"}

package/esm/supervisor/as-tool.mjs

@@ -25,12 +25,6 @@ import { compositeAsTool } from "../tool/tool.mjs";
 *   agent sees one uniform error class regardless of which
 *   primitive failed.
 *
-* **Usage caveat** (mirrors workflow-as-tool): nested usage is not
-* rolled into the outer agent's `result.usage` today — the
-* supervisor's tokens stay on the supervisor result. Sum manually
-* if you need a combined cost number until nested-usage
-* standardization lands.
-*
 * @example
 * const support = ai.supervisor({ ... });
 * const supportTool = support.asTool({

package/esm/supervisor/as-tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/as-tool.ts"],"sourcesContent":["import type {\n  SupervisorAsToolOptions,\n  SupervisorContract,\n} from \"../contracts/supervisor/supervisor.contract\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\n\n/**\n * Wrap a `SupervisorContract` as a `ToolContract` so an outer agent\n * can invoke it from its tool-call loop. Mirrors\n * `workflow.asTool()` / `agent.asTool()` — same composition pattern,\n * same error-normalization behavior.\n *\n * Behavior:\n * - The tool's `name` mirrors the supervisor's `name` unless the\n *   caller overrides via `options.name`. Supervisors without a\n *   meaningful name throw `SupervisorFailedError` — an outer agent\n *   can't route to an anonymous tool.\n * - Tool `input` is the supplied schema; the validated value is\n *   coerced to a string (via `String()` for non-string values, or\n *   `JSON.stringify()` for objects) before being forwarded to\n *   `supervisor.execute(input)`. Consumers whose inputs need\n *   richer shaping should pre-format the string themselves.\n * - On `result.error`, the supervisor error is thrown so the tool\n *   wrapper catches it and produces a `ToolExecutionError` with\n *   `cause` set to the original typed supervisor error — the outer\n *   agent sees one uniform error class regardless of which\n *   primitive failed.\n *\n * **Usage caveat** (mirrors workflow-as-tool): nested usage is not\n * rolled into the outer agent's `result.usage` today — the\n * supervisor's tokens stay on the supervisor result. Sum manually\n * if you need a combined cost number until nested-usage\n * standardization lands.\n *\n * @example\n * const support = ai.supervisor({ ... });\n * const supportTool = support.asTool({\n *   name: \"handle_support_ticket\",\n *   description: \"Process a customer support ticket end-to-end.\",\n *   inputSchema: z.object({ ticket: z.string() }),\n * });\n * const concierge = ai.agent({ model, tools: [supportTool] });\n */\nexport function asTool<TOutput, TToolInput>(\n  supervisorInstance: SupervisorContract<TOutput>,\n  options: SupervisorAsToolOptions<TToolInput>,\n): ToolContract<TToolInput, TOutput> {\n  if (!supervisorInstance.name || typeof supervisorInstance.name !== \"string\") {\n    throw new SupervisorFailedError(\n      \"supervisor.asTool(): supervisor must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: options.name ?? supervisorInstance.name,\n    description: options.description ?? `Invoke supervisor \"${supervisorInstance.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input) => {\n      const coerced = coerceInput(input);\n      const result = await supervisorInstance.execute(coerced);\n\n      if (result.error) {\n        // Surface the typed supervisor error — the outer ToolContract\n        // wraps it as a ToolExecutionError with `cause` preserved.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Coerce a tool-input value into the `string` shape supervisor\n * `execute()` expects. Strings pass through; everything else gets\n * JSON-stringified so supervisors invoked via tool wrappers receive a\n * predictable textual input regardless of how the outer agent shaped\n * its call.\n */\nfunction coerceInput(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n\n  if (value === undefined || value === null) {\n    return \"\";\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,OACd,oBACA,SACmC;CACnC,IAAI,CAAC,mBAAmB,QAAQ,OAAO,mBAAmB,SAAS,UACjE,MAAM,IAAI,sBACR,4EACF;CAGF,OAAO,gBAAqC;EAC1C,MAAM,QAAQ,QAAQ,mBAAmB;EACzC,aAAa,QAAQ,eAAe,sBAAsB,mBAAmB,KAAK;EAClF,OAAO,QAAQ;EACf,SAAS,OAAO,UAAU;GACxB,MAAM,UAAU,YAAY,KAAK;GACjC,MAAM,SAAS,MAAM,mBAAmB,QAAQ,OAAO;GAEvD,IAAI,OAAO,OAGT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;AASA,SAAS,YAAY,OAAwB;CAC3C,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO;CAGT,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF"}
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/as-tool.ts"],"sourcesContent":["import type {\n  SupervisorAsToolOptions,\n  SupervisorContract,\n} from \"../contracts/supervisor/supervisor.contract\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\n\n/**\n * Wrap a `SupervisorContract` as a `ToolContract` so an outer agent\n * can invoke it from its tool-call loop. Mirrors\n * `workflow.asTool()` / `agent.asTool()` — same composition pattern,\n * same error-normalization behavior.\n *\n * Behavior:\n * - The tool's `name` mirrors the supervisor's `name` unless the\n *   caller overrides via `options.name`. Supervisors without a\n *   meaningful name throw `SupervisorFailedError` — an outer agent\n *   can't route to an anonymous tool.\n * - Tool `input` is the supplied schema; the validated value is\n *   coerced to a string (via `String()` for non-string values, or\n *   `JSON.stringify()` for objects) before being forwarded to\n *   `supervisor.execute(input)`. Consumers whose inputs need\n *   richer shaping should pre-format the string themselves.\n * - On `result.error`, the supervisor error is thrown so the tool\n *   wrapper catches it and produces a `ToolExecutionError` with\n *   `cause` set to the original typed supervisor error — the outer\n *   agent sees one uniform error class regardless of which\n *   primitive failed.\n *\n * @example\n * const support = ai.supervisor({ ... });\n * const supportTool = support.asTool({\n *   name: \"handle_support_ticket\",\n *   description: \"Process a customer support ticket end-to-end.\",\n *   inputSchema: z.object({ ticket: z.string() }),\n * });\n * const concierge = ai.agent({ model, tools: [supportTool] });\n */\nexport function asTool<TOutput, TToolInput>(\n  supervisorInstance: SupervisorContract<TOutput>,\n  options: SupervisorAsToolOptions<TToolInput>,\n): ToolContract<TToolInput, TOutput> {\n  if (!supervisorInstance.name || typeof supervisorInstance.name !== \"string\") {\n    throw new SupervisorFailedError(\n      \"supervisor.asTool(): supervisor must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: options.name ?? supervisorInstance.name,\n    description: options.description ?? `Invoke supervisor \"${supervisorInstance.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input) => {\n      const coerced = coerceInput(input);\n      const result = await supervisorInstance.execute(coerced);\n\n      if (result.error) {\n        // Surface the typed supervisor error — the outer ToolContract\n        // wraps it as a ToolExecutionError with `cause` preserved.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Coerce a tool-input value into the `string` shape supervisor\n * `execute()` expects. Strings pass through; everything else gets\n * JSON-stringified so supervisors invoked via tool wrappers receive a\n * predictable textual input regardless of how the outer agent shaped\n * its call.\n */\nfunction coerceInput(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n\n  if (value === undefined || value === null) {\n    return \"\";\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,OACd,oBACA,SACmC;CACnC,IAAI,CAAC,mBAAmB,QAAQ,OAAO,mBAAmB,SAAS,UACjE,MAAM,IAAI,sBACR,4EACF;CAGF,OAAO,gBAAqC;EAC1C,MAAM,QAAQ,QAAQ,mBAAmB;EACzC,aAAa,QAAQ,eAAe,sBAAsB,mBAAmB,KAAK;EAClF,OAAO,QAAQ;EACf,SAAS,OAAO,UAAU;GACxB,MAAM,UAAU,YAAY,KAAK;GACjC,MAAM,SAAS,MAAM,mBAAmB,QAAQ,OAAO;GAEvD,IAAI,OAAO,OAGT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;AASA,SAAS,YAAY,OAAwB;CAC3C,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO;CAGT,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF"}

package/esm/supervisor/execution.d.mts

@@ -1,10 +1,10 @@
-import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
-import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
-import { SupervisorExecuteOptions } from "../contracts/supervisor/supervisor-execute-options.type.mjs";
 import { SupervisorResult } from "../contracts/result/supervisor-result.type.mjs";
+import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
 import { SupervisorSnapshot } from "../contracts/supervisor/supervisor-snapshot.type.mjs";
-import { SupervisorEmitter } from "./emitter.mjs";
+import { SupervisorExecuteOptions } from "../contracts/supervisor/supervisor-execute-options.type.mjs";
+import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
 import { ResolvedIntentEntry } from "./entries.mjs";
+import { SupervisorEmitter } from "./emitter.mjs";
 import { SupervisorStreamController } from "./supervisor-stream.mjs";
 
 //#region ../@warlock.js/ai/src/supervisor/execution.d.ts
@@ -59,6 +59,21 @@ declare class SupervisorExecution<TOutput> {
   private readonly maxIterations;
   private readonly logger;
   private readonly logModule;
+  /**
+   * Supervisor-level middleware stack — `config.middleware` (default
+   * empty). Each entry's optional `supervisor` hook map fires once
+   * around the whole run via `runPipeline(..., "supervisor", ...)` in
+   * {@link run}; entries without that hook map are skipped by the
+   * pipeline.
+   */
+  private readonly middleware;
+  /**
+   * Per-run shared-state bag threaded through every `supervisor`-level
+   * hook (`before` / `after` / `onError`) of this one run. Fresh `Map`
+   * per `SupervisorExecution` so two concurrent runs of the same
+   * supervisor get isolated bags — mirrors the agent pipeline.
+   */
+  private readonly middlewareState;
   private readonly snapshots;
   private readonly childReports;
   private readonly usage;
@@ -182,12 +197,32 @@ declare class SupervisorExecution<TOutput> {
    */
   private applyAgentsWindow;
   /**
-   * Entry point. Drives the iteration loop, finalizes the result, and
-   * emits terminal events. Returns the uniform
-   * `{ data, report, usage, error }` shape and closes the stream if
-   * one was attached. Never throws.
+   * Entry point. Wraps the core run (`runCore`) in the
+   * `supervisor`-level middleware pipeline, then emits the terminal
+   * `supervisor.cancelled` / `supervisor.error` / `supervisor.completed`
+   * events and closes the stream (if any) with the post-pipeline result
+   * — so a middleware that short-circuits or transforms the final
+   * result still produces a well-formed public outcome. Returns the
+   * uniform `{ data, report, usage, error }` shape. Never throws.
    */
   run(): Promise<SupervisorResult<TOutput>>;
+  /**
+   * Build the `supervisor`-level middleware context — the stable
+   * identity of this run plus the per-run shared-state bag every hook
+   * sees. Constructed once per run, before the pipeline `before` hooks
+   * fire. Mirrors the agent's `buildExecuteContext`, one level up.
+   */
+  private buildSupervisorContext;
+  /**
+   * Inner body wrapped by the `supervisor`-level pipeline. Emits the
+   * `supervisor.starting` event, drives the iteration loop, absorbs
+   * every iteration-loop failure into `this.error` (so the run never
+   * throws from here), and returns the assembled `SupervisorResult`.
+   * `supervisor`-level `after` hooks receive this result, with `error`
+   * populated when the loop failed; `before` hooks can short-circuit
+   * before this ever runs.
+   */
+  private runCore;
   /**
    * Drive the iteration loop until a terminal condition fires:
    * `END` / `satisfied:true` / `maxIterations` / signal abort /