@warlock.js/core 4.4.0 → 4.5.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/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"}

package/esm/ai/src/supervisor/decide.mjs

@@ -0,0 +1,272 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import { SupervisorRoutingError } from "../errors/supervisor-routing-error.mjs";
+import "../errors/index.mjs";
+import { END } from "../contracts/end.type.mjs";
+import { buildRouterContextMessage } from "./router-prompt.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/decide.ts
+/**
+* Unified dispatch decision entry — calls either the `route` callback
+* or the `router` agent based on the supervisor's configured mode and
+* normalizes the result into a `DispatchDecision`. Runtime validates
+* every routing value against the configured agent keys; unknown keys
+* surface as `SupervisorRoutingError`.
+*/
+async function decide(params) {
+	if (params.useInitialAgent && params.config.initialAgent) {
+		const intent = params.config.initialAgent;
+		validateKey(intent, params.entries);
+		return {
+			kind: "dispatch",
+			intents: [intent],
+			source: "initialAgent",
+			raw: intent,
+			durationMs: 0
+		};
+	}
+	if (params.config.route) return decideViaCallback(params);
+	if (params.config.router) return decideViaRouter(params);
+	throw new SupervisorFailedError(`ai.supervisor("${params.config.name}"): neither \`route\` nor \`router\` is configured — factory validation should have prevented this`, { context: { authoring: true } });
+}
+async function decideViaCallback(params) {
+	const started = performance.now();
+	const ctx = {
+		iteration: params.iteration,
+		input: params.input,
+		state: params.state,
+		iterations: params.iterations,
+		feedback: typeof params.evaluateFeedback?.feedback === "string" ? params.evaluateFeedback.feedback : void 0,
+		evaluateFeedback: params.evaluateFeedback,
+		context: params.context,
+		history: params.history,
+		goal: params.goal,
+		classifier: params.classifier
+	};
+	let raw;
+	try {
+		raw = await params.config.route(ctx);
+	} catch (thrown) {
+		throw wrapRouteError(params.config.name, thrown);
+	}
+	const durationMs = performance.now() - started;
+	return normalize(raw, params.entries, "route", durationMs);
+}
+async function decideViaRouter(params) {
+	const { agent, placeholders, inputOverride, historySlicer } = resolveRouterEntry(params.config.router);
+	const started = performance.now();
+	const routeCtx = {
+		iteration: params.iteration,
+		input: params.input,
+		state: params.state,
+		iterations: params.iterations,
+		feedback: typeof params.evaluateFeedback?.feedback === "string" ? params.evaluateFeedback.feedback : void 0,
+		evaluateFeedback: params.evaluateFeedback,
+		context: params.context,
+		history: params.history,
+		goal: params.goal
+	};
+	const userMessage = inputOverride?.(routeCtx) ?? buildRouterContextMessage({
+		entries: params.entries,
+		iteration: params.iteration,
+		maxIterations: params.maxIterations,
+		iterations: params.iterations,
+		input: params.input,
+		state: params.state,
+		feedback: routeCtx.feedback,
+		supervisorPrompt: resolveSupervisorPromptText(params.config),
+		goal: params.goal
+	});
+	const resolvedPlaceholders = placeholders?.(routeCtx);
+	const routerHistory = resolveRouterHistory(historySlicer, routeCtx, params.history, params.config.historyWindow?.router);
+	const routerResult = await agent.execute(userMessage, {
+		signal: params.signal,
+		output: ROUTER_OUTPUT_SCHEMA,
+		...resolvedPlaceholders ? { placeholders: resolvedPlaceholders } : {},
+		...routerHistory.length > 0 ? { history: routerHistory } : {}
+	});
+	const durationMs = performance.now() - started;
+	if (routerResult.error) throw routerResult.error instanceof AIError ? routerResult.error : new SupervisorFailedError(`router agent failed`, { cause: routerResult.error });
+	const data = routerResult.data;
+	if (!data || typeof data !== "object") throw new SupervisorRoutingError(`router agent returned no structured \`next\` — did its output schema include { next, reasoning? }?`, {
+		returned: data,
+		availableKeys: [...params.entries.keys()]
+	});
+	const rawNext = data.next;
+	const reasoning = data.reasoning;
+	if (rawNext === void 0) throw new SupervisorRoutingError(`router agent output missing \`next\` field`, {
+		returned: data,
+		availableKeys: [...params.entries.keys()]
+	});
+	return {
+		...normalize(rawNext, params.entries, "router", durationMs),
+		reasoning: typeof reasoning === "string" ? reasoning : void 0,
+		usage: routerResult.usage,
+		routerReport: routerResult.report
+	};
+}
+/**
+* Normalize the `router` config field — accepts either a bare
+* `AgentContract` (shorthand) or a full `RouterEntry` — into a
+* uniform `{ agent, placeholders?, inputOverride? }` triple. Centralized
+* so the dispatch path doesn't branch on shape.
+*/
+function resolveRouterEntry(router) {
+	if (typeof router.execute === "function") return { agent: router };
+	const entry = router;
+	return {
+		agent: entry.agent,
+		placeholders: entry.placeholders,
+		inputOverride: entry.input,
+		historySlicer: entry.history
+	};
+}
+/**
+* Resolve the supervisor's own `systemPrompt` (string or contract)
+* into plain text. Returns `undefined` when the supervisor didn't
+* configure one. The resolved text is surfaced in the per-turn
+* router user message so the router sees team/domain context without
+* disturbing the router agent's own factory-level system prompt —
+* functionally equivalent to prepending, without requiring an API
+* expansion on `AgentContract` to read the router's system prompt.
+*/
+function resolveSupervisorPromptText(config) {
+	if (!config.systemPrompt) return;
+	return typeof config.systemPrompt === "string" ? config.systemPrompt : config.systemPrompt.resolve();
+}
+/**
+* Convert the raw routing value (callback return OR router agent
+* `next` field) into a canonical `DispatchDecision`, validating every
+* named intent against the supervisor's `intents` map.
+*/
+function normalize(raw, entries, source, durationMs) {
+	if (isEnd(raw)) return {
+		kind: "end",
+		source,
+		raw,
+		durationMs
+	};
+	if (typeof raw === "string") {
+		validateKey(raw, entries);
+		return {
+			kind: "dispatch",
+			intents: [raw],
+			source,
+			raw,
+			durationMs
+		};
+	}
+	if (Array.isArray(raw)) {
+		if (raw.length === 0) throw new SupervisorRoutingError(`router returned an empty array — must be a non-empty list of agent intents`, {
+			returned: raw,
+			availableKeys: [...entries.keys()]
+		});
+		for (const intent of raw) {
+			if (typeof intent !== "string") throw new SupervisorRoutingError(`router returned a non-string inside its fan-out array`, {
+				returned: raw,
+				availableKeys: [...entries.keys()]
+			});
+			validateKey(intent, entries);
+		}
+		return {
+			kind: "dispatch",
+			intents: raw,
+			source,
+			raw,
+			durationMs
+		};
+	}
+	throw new SupervisorRoutingError(`router returned an unsupported value — expected a string, string[], or END`, {
+		returned: raw,
+		availableKeys: [...entries.keys()]
+	});
+}
+function validateKey(intent, entries) {
+	if (!entries.has(intent)) throw new SupervisorRoutingError(`router returned unknown agent key "${intent}"`, {
+		returned: intent,
+		availableKeys: [...entries.keys()]
+	});
+}
+function isEnd(value) {
+	return value === END;
+}
+/**
+* Resolve the history slice forwarded to the router agent. Mirrors
+* `SupervisorExecution.resolveHistoryFor("router", ...)` — duplicated
+* here so the standalone `decide()` function stays callable without
+* threading the execution instance through. Precedence is identical:
+* entry slicer > `historyWindow.router` > full history.
+*/
+function resolveRouterHistory(slicer, routeCtx, full, window) {
+	if (slicer) {
+		const sliced = slicer(routeCtx);
+		return sliced ? [...sliced] : [];
+	}
+	if (window === void 0 || window < 0) return [...full];
+	if (window === 0) return [];
+	return full.slice(-window);
+}
+/**
+* JSON Schema form of the canonical router output shape. Surfaced via
+* the Standard JSON Schema V1 extension path (`["~standard"].jsonSchema.input`)
+* so `extractJsonSchema()` can pull it for native structured-output
+* enforcement on capable providers (OpenAI strict json_schema mode,
+* Anthropic tool-use shape, etc.). Without this, the model is told to
+* emit JSON only via soft system-prompt instruction — fragile, and
+* skipped entirely when the model advertises `structuredOutput: true`.
+*
+* `next` is intentionally `string` (not a union with arrays) because
+* OpenAI strict mode rejects polymorphic root types — fan-out via
+* `string[]` is still validated at the framework layer; the model
+* just emits a single intent name (or the END sentinel) and the
+* supervisor's own normalizer handles the rest.
+*/
+const ROUTER_OUTPUT_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		next: {
+			type: "string",
+			description: "Name of the agent to dispatch next, or the END sentinel to terminate the run."
+		},
+		reasoning: {
+			type: "string",
+			description: "One-sentence justification for the routing choice."
+		}
+	},
+	required: ["next", "reasoning"],
+	additionalProperties: false
+};
+/**
+* Canonical Standard Schema the supervisor injects when calling the
+* router agent. Pragmatic — accepts any `next` shape the router can
+* plausibly emit (`string`, `string[]`, or the `END` literal) plus an
+* optional `reasoning` field. Rejects anything else so a broken
+* router output surfaces cleanly via the agent's own validation path.
+*
+* Exposes `["~standard"].jsonSchema.input()` (Standard JSON Schema V1)
+* so capable providers enforce the shape natively rather than relying
+* on prompt-side coaching.
+*/
+const ROUTER_OUTPUT_SCHEMA = { "~standard": {
+	version: 1,
+	vendor: "warlock-supervisor",
+	jsonSchema: { input: () => ROUTER_OUTPUT_JSON_SCHEMA },
+	validate(value) {
+		if (!value || typeof value !== "object") return { issues: [{ message: "router output must be an object" }] };
+		const record = value;
+		const rawNext = record.next;
+		if (!(typeof rawNext === "string" || Array.isArray(rawNext) && rawNext.every((element) => typeof element === "string"))) return { issues: [{ message: "router output `next` must be a string, string[], or the END sentinel" }] };
+		return { value: {
+			next: rawNext,
+			reasoning: typeof record.reasoning === "string" ? record.reasoning : void 0
+		} };
+	}
+} };
+function wrapRouteError(supervisorName, thrown) {
+	if (thrown instanceof AIError) return thrown;
+	return new SupervisorFailedError(`\`route\` callback threw in supervisor "${supervisorName}": ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
+}
+
+//#endregion
+export { decide };
+//# sourceMappingURL=decide.mjs.map