@warlock.js/core 4.4.0 → 4.6.0

package/esm/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/speech/index.mjs

@@ -0,0 +1,3 @@
+import { speech } from "./speech.mjs";
+
+export {  };

package/esm/ai/src/speech/speech.mjs

@@ -0,0 +1,122 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { ProviderError } from "../errors/provider-error.mjs";
+import { computeCost } from "../utils/compute-cost.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
+
+//#region ../@warlock.js/ai/src/speech/speech.ts
+/**
+* Synthesize speech from text — the text-to-speech verb of the
+* output-modality track (Theme I), sibling to `ai.image()`. Wraps a
+* {@link SpeechModelContract} (from `openai.speech(...)`) in the
+* framework's uniform result contract:
+*
+* - **Never throws.** Provider failures surface as a typed `AIError` on
+*   `result.error`; `result.data` is then `undefined`.
+* - **Cost-truth.** `result.usage.cost` is filled per-character
+*   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
+*   `Usage.cost` rollup as text.
+* - **Observable.** The completed {@link SpeechReport} routes to any
+*   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error } = await ai.speech({
+*   model: openai.speech({ name: "tts-1", voice: "alloy" }),
+*   text: "Your order has shipped.",
+*   format: "mp3",
+* });
+* if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
+*/
+async function speech(params) {
+	const { model, text } = params;
+	const runId = generateRunId("speech");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let characters = 0;
+	try {
+		const response = await model.generate(text, {
+			voice: params.voice,
+			format: params.format,
+			speed: params.speed,
+			instructions: params.instructions,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		characters = response.characters;
+		if (usage.cost === void 0) {
+			const cost = computeSpeechCost(usage, characters, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = { audio: response.audio };
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "speech",
+		type: "speech",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		characters,
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "speech",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price a TTS run: `perMillionCharacters × characters` (per-character
+* metering, attributed to `cost.input`) wins when configured, otherwise
+* the standard token math. Returns `undefined` when no usable pricing
+* is present.
+*/
+function computeSpeechCost(usage, characters, pricing) {
+	if (!pricing) return;
+	if (pricing.perMillionCharacters !== void 0) return {
+		input: characters * pricing.perMillionCharacters / 1e6,
+		output: 0
+	};
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+export { speech };
+//# sourceMappingURL=speech.mjs.map

package/esm/ai/src/speech/speech.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/speech/speech.ts"],"sourcesContent":["import type {\n  GeneratedAudio,\n  SpeechModelContract,\n  SpeechModelPricing,\n} from \"../contracts/speech-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { computeCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\n\n/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */\nexport type SpeechParams = {\n  /** The TTS model to synthesize with. */\n  model: SpeechModelContract;\n  /** The text to speak. */\n  text: string;\n  /** Voice id/name; overrides the model's default voice. */\n  voice?: string;\n  /** Output container (`\"mp3\"` / `\"opus\"` / `\"aac\"` / `\"flac\"` / `\"wav\"` / `\"pcm\"`). */\n  format?: string;\n  /** Playback speed multiplier. */\n  speed?: number;\n  /** Extra tone/delivery steering (model-dependent). */\n  instructions?: string;\n  /** Cancellation handle. */\n  signal?: AbortSignal;\n  /** Observability routing — same `observe` seam as agents. */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"speech\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link speech} run. */\nexport type SpeechData = {\n  /** The synthesized audio, normalized to the discriminated shape. */\n  audio: GeneratedAudio;\n};\n\n/** The report node a {@link speech} run produces (`type: \"speech\"`). */\nexport type SpeechReport = BaseReport & {\n  type: \"speech\";\n  /** Identity of the TTS model this run used. */\n  model: { name: string; provider: string };\n  /** Number of input characters synthesized (0 on failure). */\n  characters: number;\n};\n\n/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */\nexport type SpeechResult = ExecuteResult<SpeechData> & {\n  type: \"speech\";\n  report: SpeechReport;\n};\n\n/**\n * Synthesize speech from text — the text-to-speech verb of the\n * output-modality track (Theme I), sibling to `ai.image()`. Wraps a\n * {@link SpeechModelContract} (from `openai.speech(...)`) in the\n * framework's uniform result contract:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** `result.usage.cost` is filled per-character\n *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same\n *   `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link SpeechReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error } = await ai.speech({\n *   model: openai.speech({ name: \"tts-1\", voice: \"alloy\" }),\n *   text: \"Your order has shipped.\",\n *   format: \"mp3\",\n * });\n * if (!error) await fs.writeFile(\"ship.mp3\", Buffer.from(data.audio.base64, \"base64\"));\n */\nexport async function speech(params: SpeechParams): Promise<SpeechResult> {\n  const { model, text } = params;\n\n  const runId = generateRunId(\"speech\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: SpeechData | undefined;\n  let error: AIError | undefined;\n  let status: SpeechReport[\"status\"] = \"completed\";\n  let characters = 0;\n\n  try {\n    const response = await model.generate(text, {\n      voice: params.voice,\n      format: params.format,\n      speed: params.speed,\n      instructions: params.instructions,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    characters = response.characters;\n\n    if (usage.cost === undefined) {\n      const cost = computeSpeechCost(usage, characters, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { audio: response.audio };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: SpeechReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"speech\",\n    type: \"speech\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    characters,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"speech\", data, error, usage, report };\n}\n\n/**\n * Price a TTS run: `perMillionCharacters × characters` (per-character\n * metering, attributed to `cost.input`) wins when configured, otherwise\n * the standard token math. Returns `undefined` when no usable pricing\n * is present.\n */\nfunction computeSpeechCost(\n  usage: Usage,\n  characters: number,\n  pricing: SpeechModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perMillionCharacters !== undefined) {\n    return { input: (characters * pricing.perMillionCharacters) / 1_000_000, output: 0 };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,eAAsB,OAAO,QAA6C;CACxE,MAAM,EAAE,OAAO,SAAS;CAExB,MAAM,QAAQ,cAAc,QAAQ;CACpC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAiC;CACrC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,MAAM;GAC1C,OAAO,OAAO;GACd,QAAQ,OAAO;GACf,OAAO,OAAO;GACd,cAAc,OAAO;GACrB,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,aAAa,SAAS;EAEtB,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,kBAAkB,OAAO,YAAY,MAAM,OAAO;GAC/D,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,OAAO,SAAS,MAAM;CACjC,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAuB;EAC3B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAU;EAAM;EAAO;EAAO;CAAO;AACtD;;;;;;;AAQA,SAAS,kBACP,OACA,YACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,yBAAyB,QACnC,OAAO;EAAE,OAAQ,aAAa,QAAQ,uBAAwB;EAAW,QAAQ;CAAE;CAGrF,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/esm/ai/src/supervisor/as-tool.mjs

@@ -0,0 +1,74 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+import { compositeAsTool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/as-tool.ts
+/**
+* Wrap a `SupervisorContract` as a `ToolContract` so an outer agent
+* can invoke it from its tool-call loop. Mirrors
+* `workflow.asTool()` / `agent.asTool()` — same composition pattern,
+* same error-normalization behavior.
+*
+* Behavior:
+* - The tool's `name` mirrors the supervisor's `name` unless the
+*   caller overrides via `options.name`. Supervisors without a
+*   meaningful name throw `SupervisorFailedError` — an outer agent
+*   can't route to an anonymous tool.
+* - Tool `input` is the supplied schema; the validated value is
+*   coerced to a string (via `String()` for non-string values, or
+*   `JSON.stringify()` for objects) before being forwarded to
+*   `supervisor.execute(input)`. Consumers whose inputs need
+*   richer shaping should pre-format the string themselves.
+* - On `result.error`, the supervisor error is thrown so the tool
+*   wrapper catches it and produces a `ToolExecutionError` with
+*   `cause` set to the original typed supervisor error — the outer
+*   agent sees one uniform error class regardless of which
+*   primitive failed.
+*
+* @example
+* const support = ai.supervisor({ ... });
+* const supportTool = support.asTool({
+*   name: "handle_support_ticket",
+*   description: "Process a customer support ticket end-to-end.",
+*   inputSchema: z.object({ ticket: z.string() }),
+* });
+* const concierge = ai.agent({ model, tools: [supportTool] });
+*/
+function asTool(supervisorInstance, options) {
+	if (!supervisorInstance.name || typeof supervisorInstance.name !== "string") throw new SupervisorFailedError("supervisor.asTool(): supervisor must have a `name` to be wrapped as a tool");
+	return compositeAsTool({
+		name: options.name ?? supervisorInstance.name,
+		description: options.description ?? `Invoke supervisor "${supervisorInstance.name}" as a tool.`,
+		input: options.inputSchema,
+		execute: async (input, ctx) => {
+			const coerced = coerceInput(input);
+			const result = await supervisorInstance.execute(coerced, ctx?.signal ? { signal: ctx.signal } : void 0);
+			if (result.error) throw result.error;
+			return {
+				data: result.data,
+				usage: result.usage,
+				report: result.report
+			};
+		}
+	});
+}
+/**
+* Coerce a tool-input value into the `string` shape supervisor
+* `execute()` expects. Strings pass through; everything else gets
+* JSON-stringified so supervisors invoked via tool wrappers receive a
+* predictable textual input regardless of how the outer agent shaped
+* its call.
+*/
+function coerceInput(value) {
+	if (typeof value === "string") return value;
+	if (value === void 0 || value === null) return "";
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+//#endregion
+export { asTool };
+//# sourceMappingURL=as-tool.mjs.map

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

@@ -0,0 +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 * @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, ctx) => {\n      const coerced = coerceInput(input);\n      // Relay the outer agent's cancellation signal so cancelling the\n      // parent aborts this nested supervisor run — its mid-iteration\n      // aborts then propagate into every in-flight child (C2).\n      const result = await supervisorInstance.execute(\n        coerced,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\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,OAAO,QAAQ;GAC7B,MAAM,UAAU,YAAY,KAAK;GAIjC,MAAM,SAAS,MAAM,mBAAmB,QACtC,SACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,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/ai/src/supervisor/cancellation.mjs

@@ -0,0 +1,22 @@
+import { SupervisorCancelledError } from "../errors/supervisor-cancelled-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/cancellation.ts
+/**
+* Build a `SupervisorCancelledError` from an `AbortSignal`. Extracts a
+* human-readable reason from `signal.reason` whether it was a string,
+* an `Error`, or some other value. Used at between-iteration boundaries
+* and on any mid-iteration cancellation path.
+*/
+function createCancelledError(signal) {
+	const reason = signal?.reason;
+	const reasonText = typeof reason === "string" ? reason : reason instanceof Error ? reason.message : reason === void 0 ? "" : String(reason);
+	return new SupervisorCancelledError(`supervisor cancelled${reasonText ? `: ${reasonText}` : ""}`, {
+		cancelledAt: (/* @__PURE__ */ new Date()).toISOString(),
+		reason: reasonText
+	});
+}
+
+//#endregion
+export { createCancelledError };
+//# sourceMappingURL=cancellation.mjs.map

package/esm/ai/src/supervisor/cancellation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/supervisor/cancellation.ts"],"sourcesContent":["import { SupervisorCancelledError } from \"../errors\";\n\n/**\n * Build a `SupervisorCancelledError` from an `AbortSignal`. Extracts a\n * human-readable reason from `signal.reason` whether it was a string,\n * an `Error`, or some other value. Used at between-iteration boundaries\n * and on any mid-iteration cancellation path.\n */\nexport function createCancelledError(\n  signal: AbortSignal | undefined,\n): SupervisorCancelledError {\n  const reason = signal?.reason;\n  const reasonText =\n    typeof reason === \"string\"\n      ? reason\n      : reason instanceof Error\n        ? reason.message\n        : reason === undefined\n          ? \"\"\n          : String(reason);\n\n  return new SupervisorCancelledError(\n    `supervisor cancelled${reasonText ? `: ${reasonText}` : \"\"}`,\n    { cancelledAt: new Date().toISOString(), reason: reasonText },\n  );\n}\n"],"mappings":";;;;;;;;;;AAQA,SAAgB,qBACd,QAC0B;CAC1B,MAAM,SAAS,QAAQ;CACvB,MAAM,aACJ,OAAO,WAAW,WACd,SACA,kBAAkB,QAChB,OAAO,UACP,WAAW,SACT,KACA,OAAO,MAAM;CAEvB,OAAO,IAAI,yBACT,uBAAuB,aAAa,KAAK,eAAe,MACxD;EAAE,8BAAa,IAAI,KAAK,EAAC,CAAC,YAAY;EAAG,QAAQ;CAAW,CAC9D;AACF"}