@warlock.js/ai 4.2.10 → 4.3.0

package/esm/checkpoint/redis.mjs

@@ -0,0 +1,200 @@
+//#region ../@warlock.js/ai/src/checkpoint/redis.ts
+/**
+* Default key prefix — namespaces the store's keys inside a shared
+* Redis database.
+*/
+const DEFAULT_PREFIX = "warlock:orchestrator";
+/**
+* Redis-backed {@link CheckpointStore} (orchestrator.md §8.2).
+*
+* Owns: the per-session append-only document, a per-orchestrator
+* session-id index (so {@link RedisCheckpointStore.list} works without
+* `KEYS`/`SCAN`), the "latest turn wins" load, and the §4-Phase-6
+* retention prune. Does NOT own: durability guarantees beyond Redis's
+* own, the connection lifecycle (the dev passes a client), or the
+* `keepSnapshots` policy (that lives on the orchestrator config).
+*
+* Because {@link RedisClientLike} is intentionally minimal (`get` /
+* `set` / `del` only — §8.4), the store models a session as a single
+* JSON document rather than one Redis key per turn. This keeps every
+* operation a single round-trip and avoids depending on key scanning,
+* at the cost of read-modify-write on `save`. Callers must serialize
+* traffic per `sessionId` anyway (§17 "two turns racing"), so the
+* read-modify-write is safe under that contract.
+*
+* Front it with the {@link redis} factory — callers never `new` it.
+*/
+var RedisCheckpointStore = class {
+	constructor(options) {
+		if (!options || typeof options.client?.get !== "function" || typeof options.client?.set !== "function" || typeof options.client?.del !== "function") throw new TypeError("ai.checkpoint.redis requires a 'client' option implementing { get, set, del } — pass a connected redis client.");
+		this.client = options.client;
+		this.prefix = options.prefix ?? DEFAULT_PREFIX;
+		this.ttl = options.ttl;
+	}
+	/**
+	* Return the latest checkpoint (highest `turn_index`) for a session,
+	* or `undefined` when the session has no document. Rows are appended
+	* in turn order, so the last element is the latest.
+	*/
+	async load(orchestratorName, sessionId) {
+		const document = await this.readSession(orchestratorName, sessionId);
+		if (!document || document.rows.length === 0) return;
+		return document.rows[document.rows.length - 1];
+	}
+	/**
+	* Append a checkpoint row to its session document, creating the
+	* document and indexing the session id on first write. Append-only —
+	* an existing `turn_index` is never overwritten; a fresh row is
+	* pushed (§4 Phase 6, Q15).
+	*/
+	async save(record) {
+		const { orchestrator_name, session_id } = record;
+		const document = await this.readSession(orchestrator_name, session_id) ?? { rows: [] };
+		document.rows.push(record);
+		await this.writeSession(orchestrator_name, session_id, document);
+		await this.indexSession(orchestrator_name, session_id);
+	}
+	/**
+	* Drop a session document and de-index its session id.
+	*/
+	async delete(orchestratorName, sessionId) {
+		await this.client.del(this.sessionKey(orchestratorName, sessionId));
+		await this.deindexSession(orchestratorName, sessionId);
+	}
+	/**
+	* List the session ids known for an orchestrator, optionally filtered
+	* by a session-id prefix. Reads the self-maintained index document
+	* (§9.3 boot drain).
+	*/
+	async list(orchestratorName, prefix) {
+		const index = await this.readIndex(orchestratorName);
+		if (prefix === void 0) return [...index.sessionIds];
+		return index.sessionIds.filter((sessionId) => sessionId.startsWith(prefix));
+	}
+	/**
+	* Prune retained turns for a session down to the most recent
+	* `keepSnapshots` rows (orchestrator.md §4 Phase 6 / §15.2). Drops
+	* every row whose `turn_index` is below `(max_turn_index -
+	* keepSnapshots)`. The orchestrator calls this synchronously after a
+	* successful {@link save} when `keepSnapshots` is a finite number;
+	* `"all"` retention skips the call. Additive to the
+	* {@link CheckpointStore} contract — the policy stays on the
+	* orchestrator and the store only executes the bounded trim.
+	*/
+	async prune(orchestratorName, sessionId, keepSnapshots) {
+		if (!Number.isFinite(keepSnapshots) || keepSnapshots < 0) return;
+		const document = await this.readSession(orchestratorName, sessionId);
+		if (!document || document.rows.length === 0) return;
+		const threshold = document.rows[document.rows.length - 1].turn_index - keepSnapshots;
+		const kept = document.rows.filter((row) => row.turn_index >= threshold);
+		if (kept.length === document.rows.length) return;
+		await this.writeSession(orchestratorName, sessionId, { rows: kept });
+	}
+	/**
+	* The Redis store has no relational table — there is nothing to
+	* migrate. Returns an empty string so callers can treat `schema()`
+	* uniformly across drivers (mirrors the memory store).
+	*/
+	schema() {
+		return "";
+	}
+	/**
+	* Set the idle-key TTL (§8.2). Applied on every subsequent write; the
+	* store never opens a background timer.
+	*/
+	setOptions(options) {
+		this.ttl = options.ttl;
+	}
+	/**
+	* Read and parse a session document, or `undefined` when the key is
+	* absent.
+	*/
+	async readSession(orchestratorName, sessionId) {
+		const raw = await this.client.get(this.sessionKey(orchestratorName, sessionId));
+		if (raw === null) return;
+		return JSON.parse(raw);
+	}
+	/**
+	* Serialize and persist a session document, honoring the configured
+	* idle TTL when set.
+	*/
+	async writeSession(orchestratorName, sessionId, document) {
+		await this.write(this.sessionKey(orchestratorName, sessionId), JSON.stringify(document));
+	}
+	/**
+	* Read and parse the per-orchestrator index document, defaulting to an
+	* empty index when absent.
+	*/
+	async readIndex(orchestratorName) {
+		const raw = await this.client.get(this.indexKey(orchestratorName));
+		if (raw === null) return { sessionIds: [] };
+		return JSON.parse(raw);
+	}
+	/**
+	* Add a session id to the per-orchestrator index, no-op when already
+	* present.
+	*/
+	async indexSession(orchestratorName, sessionId) {
+		const index = await this.readIndex(orchestratorName);
+		if (index.sessionIds.includes(sessionId)) return;
+		index.sessionIds.push(sessionId);
+		await this.write(this.indexKey(orchestratorName), JSON.stringify(index));
+	}
+	/**
+	* Remove a session id from the per-orchestrator index, no-op when
+	* absent.
+	*/
+	async deindexSession(orchestratorName, sessionId) {
+		const index = await this.readIndex(orchestratorName);
+		const next = index.sessionIds.filter((id) => id !== sessionId);
+		if (next.length === index.sessionIds.length) return;
+		await this.write(this.indexKey(orchestratorName), JSON.stringify({ sessionIds: next }));
+	}
+	/**
+	* Write a key, attaching the `EX` expiry option when an idle TTL is
+	* configured. The TTL flows through {@link RedisClientLike.set}'s
+	* variadic args as node-redis's `{ EX }` option object.
+	*/
+	async write(key, value) {
+		if (this.ttl !== void 0 && this.ttl > 0) {
+			await this.client.set(key, value, { EX: this.ttl });
+			return;
+		}
+		await this.client.set(key, value);
+	}
+	/**
+	* Key for a session document — `<prefix>:session:<name>:<sessionId>`.
+	*/
+	sessionKey(orchestratorName, sessionId) {
+		return `${this.prefix}:session:${orchestratorName}:${sessionId}`;
+	}
+	/**
+	* Key for a per-orchestrator session-id index —
+	* `<prefix>:index:<name>`.
+	*/
+	indexKey(orchestratorName) {
+		return `${this.prefix}:index:${orchestratorName}`;
+	}
+};
+/**
+* Create a Redis-backed {@link CheckpointStore} (orchestrator.md §8.3).
+* The dev installs `redis` and passes a connected client —
+* `@warlock.js/ai` never imports `redis`. {@link CheckpointStore.schema}
+* returns an empty string; Redis needs no migration.
+*
+* @example
+* import { createClient } from "redis";
+* import { ai } from "@warlock.js/ai";
+*
+* const client = createClient();
+* await client.connect();
+*
+* const store = ai.checkpoint.redis({ client });
+*/
+function redis(options) {
+	return new RedisCheckpointStore(options);
+}
+
+//#endregion
+export { redis };
+//# sourceMappingURL=redis.mjs.map

package/esm/checkpoint/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/redis.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { RedisClientLike } from \"../contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Options for the Redis {@link CheckpointStore} (orchestrator.md §8.3).\n *\n * The dev owns the connection — `@warlock.js/ai` takes no peer dep on\n * `redis` and never opens or closes the client.\n */\nexport type RedisCheckpointOptions = {\n  /** An already-connected `redis` client — anything matching {@link RedisClientLike}. */\n  client: RedisClientLike;\n  /**\n   * Key prefix for every key this store writes. Lets one Redis database\n   * back multiple stores without collision. Defaults to\n   * `warlock:orchestrator`.\n   */\n  prefix?: string;\n  /** Idle-key TTL in seconds. When set, every written key expires after the TTL. */\n  ttl?: number;\n};\n\n/**\n * Default key prefix — namespaces the store's keys inside a shared\n * Redis database.\n */\nconst DEFAULT_PREFIX = \"warlock:orchestrator\";\n\n/**\n * Per-session document persisted under one Redis key: the append-only\n * list of {@link CheckpointRecord} rows in turn order, mirroring the\n * Postgres append-only PK shape (§8.6) inside a single JSON value so\n * the store needs only `get`/`set`/`del` from {@link RedisClientLike}.\n */\ntype SessionDocument = {\n  rows: CheckpointRecord[];\n};\n\n/**\n * Per-orchestrator index document: the set of live session ids. Kept as\n * a JSON array because {@link RedisClientLike} exposes no `keys` / `scan`\n * — enumeration for the §9.3 boot drain must be self-maintained.\n */\ntype IndexDocument = {\n  sessionIds: string[];\n};\n\n/**\n * Redis-backed {@link CheckpointStore} (orchestrator.md §8.2).\n *\n * Owns: the per-session append-only document, a per-orchestrator\n * session-id index (so {@link RedisCheckpointStore.list} works without\n * `KEYS`/`SCAN`), the \"latest turn wins\" load, and the §4-Phase-6\n * retention prune. Does NOT own: durability guarantees beyond Redis's\n * own, the connection lifecycle (the dev passes a client), or the\n * `keepSnapshots` policy (that lives on the orchestrator config).\n *\n * Because {@link RedisClientLike} is intentionally minimal (`get` /\n * `set` / `del` only — §8.4), the store models a session as a single\n * JSON document rather than one Redis key per turn. This keeps every\n * operation a single round-trip and avoids depending on key scanning,\n * at the cost of read-modify-write on `save`. Callers must serialize\n * traffic per `sessionId` anyway (§17 \"two turns racing\"), so the\n * read-modify-write is safe under that contract.\n *\n * Front it with the {@link redis} factory — callers never `new` it.\n */\nclass RedisCheckpointStore implements CheckpointStore {\n  /** The dev-supplied redis client. Never disconnected by the store. */\n  private readonly client: RedisClientLike;\n\n  /** Key prefix namespacing every key this store writes. */\n  private readonly prefix: string;\n\n  /** Idle-key TTL in seconds, or `undefined` for no expiry. */\n  private ttl?: number;\n\n  public constructor(options: RedisCheckpointOptions) {\n    if (\n      !options ||\n      typeof options.client?.get !== \"function\" ||\n      typeof options.client?.set !== \"function\" ||\n      typeof options.client?.del !== \"function\"\n    ) {\n      throw new TypeError(\n        \"ai.checkpoint.redis 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    this.ttl = options.ttl;\n  }\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no document. Rows are appended\n   * in turn order, so the last element is the latest.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const document = await this.readSession(orchestratorName, sessionId);\n\n    if (!document || document.rows.length === 0) {\n      return undefined;\n    }\n\n    return document.rows[document.rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session document, creating the\n   * document and indexing the session id on first write. Append-only —\n   * an existing `turn_index` is never overwritten; a fresh row is\n   * pushed (§4 Phase 6, Q15).\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const { orchestrator_name, session_id } = record;\n\n    const document =\n      (await this.readSession(orchestrator_name, session_id)) ?? { rows: [] };\n\n    document.rows.push(record);\n\n    await this.writeSession(orchestrator_name, session_id, document);\n    await this.indexSession(orchestrator_name, session_id);\n  }\n\n  /**\n   * Drop a session document and de-index its session id.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    await this.client.del(this.sessionKey(orchestratorName, sessionId));\n    await this.deindexSession(orchestratorName, sessionId);\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the self-maintained index document\n   * (§9.3 boot drain).\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const index = await this.readIndex(orchestratorName);\n\n    if (prefix === undefined) {\n      return [...index.sessionIds];\n    }\n\n    return index.sessionIds.filter((sessionId) =>\n      sessionId.startsWith(prefix),\n    );\n  }\n\n  /**\n   * Prune retained turns for a session down to the most recent\n   * `keepSnapshots` rows (orchestrator.md §4 Phase 6 / §15.2). Drops\n   * every row whose `turn_index` is below `(max_turn_index -\n   * keepSnapshots)`. The orchestrator calls this synchronously after a\n   * successful {@link save} when `keepSnapshots` is a finite number;\n   * `\"all\"` retention skips the call. Additive to the\n   * {@link CheckpointStore} contract — the policy stays on the\n   * orchestrator and the store only executes the bounded trim.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepSnapshots: number,\n  ): Promise<void> {\n    if (!Number.isFinite(keepSnapshots) || keepSnapshots < 0) {\n      return;\n    }\n\n    const document = await this.readSession(orchestratorName, sessionId);\n\n    if (!document || document.rows.length === 0) {\n      return;\n    }\n\n    const maxTurnIndex = document.rows[document.rows.length - 1].turn_index;\n    const threshold = maxTurnIndex - keepSnapshots;\n\n    const kept = document.rows.filter((row) => row.turn_index >= threshold);\n\n    if (kept.length === document.rows.length) {\n      return;\n    }\n\n    await this.writeSession(orchestratorName, sessionId, { rows: kept });\n  }\n\n  /**\n   * The Redis store has no relational table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers (mirrors the memory store).\n   */\n  public schema(): string {\n    return \"\";\n  }\n\n  /**\n   * Set the idle-key TTL (§8.2). Applied on every subsequent write; the\n   * store never opens a background timer.\n   */\n  public setOptions(options: { ttl?: number }): void {\n    this.ttl = options.ttl;\n  }\n\n  /**\n   * Read and parse a session document, or `undefined` when the key is\n   * absent.\n   */\n  private async readSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<SessionDocument | undefined> {\n    const raw = await this.client.get(\n      this.sessionKey(orchestratorName, sessionId),\n    );\n\n    if (raw === null) {\n      return undefined;\n    }\n\n    return JSON.parse(raw) as SessionDocument;\n  }\n\n  /**\n   * Serialize and persist a session document, honoring the configured\n   * idle TTL when set.\n   */\n  private async writeSession(\n    orchestratorName: string,\n    sessionId: string,\n    document: SessionDocument,\n  ): Promise<void> {\n    await this.write(\n      this.sessionKey(orchestratorName, sessionId),\n      JSON.stringify(document),\n    );\n  }\n\n  /**\n   * Read and parse the per-orchestrator index document, defaulting to an\n   * empty index when absent.\n   */\n  private async readIndex(orchestratorName: string): Promise<IndexDocument> {\n    const raw = await this.client.get(this.indexKey(orchestratorName));\n\n    if (raw === null) {\n      return { sessionIds: [] };\n    }\n\n    return JSON.parse(raw) as IndexDocument;\n  }\n\n  /**\n   * Add a session id to the per-orchestrator index, no-op when already\n   * present.\n   */\n  private async indexSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    const index = await this.readIndex(orchestratorName);\n\n    if (index.sessionIds.includes(sessionId)) {\n      return;\n    }\n\n    index.sessionIds.push(sessionId);\n\n    await this.write(this.indexKey(orchestratorName), JSON.stringify(index));\n  }\n\n  /**\n   * Remove a session id from the per-orchestrator index, no-op when\n   * absent.\n   */\n  private async deindexSession(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    const index = await this.readIndex(orchestratorName);\n    const next = index.sessionIds.filter((id) => id !== sessionId);\n\n    if (next.length === index.sessionIds.length) {\n      return;\n    }\n\n    await this.write(\n      this.indexKey(orchestratorName),\n      JSON.stringify({ sessionIds: next }),\n    );\n  }\n\n  /**\n   * Write a key, attaching the `EX` expiry option when an idle TTL is\n   * configured. The TTL flows through {@link RedisClientLike.set}'s\n   * variadic args as node-redis's `{ EX }` option object.\n   */\n  private async write(key: string, value: string): Promise<void> {\n    if (this.ttl !== undefined && this.ttl > 0) {\n      await this.client.set(key, value, { EX: this.ttl });\n\n      return;\n    }\n\n    await this.client.set(key, value);\n  }\n\n  /**\n   * Key for a session document — `<prefix>:session:<name>:<sessionId>`.\n   */\n  private sessionKey(orchestratorName: string, sessionId: string): string {\n    return `${this.prefix}:session:${orchestratorName}:${sessionId}`;\n  }\n\n  /**\n   * Key for a per-orchestrator session-id index —\n   * `<prefix>:index:<name>`.\n   */\n  private indexKey(orchestratorName: string): string {\n    return `${this.prefix}:index:${orchestratorName}`;\n  }\n}\n\n/**\n * Create a Redis-backed {@link CheckpointStore} (orchestrator.md §8.3).\n * The dev installs `redis` and passes a connected client —\n * `@warlock.js/ai` never imports `redis`. {@link CheckpointStore.schema}\n * returns an empty string; Redis needs no migration.\n *\n * @example\n * import { createClient } from \"redis\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const client = createClient();\n * await client.connect();\n *\n * const store = ai.checkpoint.redis({ client });\n */\nexport function redis(options: RedisCheckpointOptions): CheckpointStore {\n  return new RedisCheckpointStore(options);\n}\n"],"mappings":";;;;;AA6BA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;AAyCvB,IAAM,uBAAN,MAAsD;CAUpD,AAAO,YAAY,SAAiC;EAClD,IACE,CAAC,WACD,OAAO,QAAQ,QAAQ,QAAQ,cAC/B,OAAO,QAAQ,QAAQ,QAAQ,cAC/B,OAAO,QAAQ,QAAQ,QAAQ,YAE/B,MAAM,IAAI,UACR,gHACF;EAGF,KAAK,SAAS,QAAQ;EACtB,KAAK,SAAS,QAAQ,UAAU;EAChC,KAAK,MAAM,QAAQ;CACrB;;;;;;CAOA,MAAa,KACX,kBACA,WACuC;EACvC,MAAM,WAAW,MAAM,KAAK,YAAY,kBAAkB,SAAS;EAEnE,IAAI,CAAC,YAAY,SAAS,KAAK,WAAW,GACxC;EAGF,OAAO,SAAS,KAAK,SAAS,KAAK,SAAS;CAC9C;;;;;;;CAQA,MAAa,KAAK,QAAyC;EACzD,MAAM,EAAE,mBAAmB,eAAe;EAE1C,MAAM,WACH,MAAM,KAAK,YAAY,mBAAmB,UAAU,KAAM,EAAE,MAAM,CAAC,EAAE;EAExE,SAAS,KAAK,KAAK,MAAM;EAEzB,MAAM,KAAK,aAAa,mBAAmB,YAAY,QAAQ;EAC/D,MAAM,KAAK,aAAa,mBAAmB,UAAU;CACvD;;;;CAKA,MAAa,OACX,kBACA,WACe;EACf,MAAM,KAAK,OAAO,IAAI,KAAK,WAAW,kBAAkB,SAAS,CAAC;EAClE,MAAM,KAAK,eAAe,kBAAkB,SAAS;CACvD;;;;;;CAOA,MAAa,KACX,kBACA,QACmB;EACnB,MAAM,QAAQ,MAAM,KAAK,UAAU,gBAAgB;EAEnD,IAAI,WAAW,QACb,OAAO,CAAC,GAAG,MAAM,UAAU;EAG7B,OAAO,MAAM,WAAW,QAAQ,cAC9B,UAAU,WAAW,MAAM,CAC7B;CACF;;;;;;;;;;;CAYA,MAAa,MACX,kBACA,WACA,eACe;EACf,IAAI,CAAC,OAAO,SAAS,aAAa,KAAK,gBAAgB,GACrD;EAGF,MAAM,WAAW,MAAM,KAAK,YAAY,kBAAkB,SAAS;EAEnE,IAAI,CAAC,YAAY,SAAS,KAAK,WAAW,GACxC;EAIF,MAAM,YADe,SAAS,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,aAC5B;EAEjC,MAAM,OAAO,SAAS,KAAK,QAAQ,QAAQ,IAAI,cAAc,SAAS;EAEtE,IAAI,KAAK,WAAW,SAAS,KAAK,QAChC;EAGF,MAAM,KAAK,aAAa,kBAAkB,WAAW,EAAE,MAAM,KAAK,CAAC;CACrE;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;;;;;CAMA,AAAO,WAAW,SAAiC;EACjD,KAAK,MAAM,QAAQ;CACrB;;;;;CAMA,MAAc,YACZ,kBACA,WACsC;EACtC,MAAM,MAAM,MAAM,KAAK,OAAO,IAC5B,KAAK,WAAW,kBAAkB,SAAS,CAC7C;EAEA,IAAI,QAAQ,MACV;EAGF,OAAO,KAAK,MAAM,GAAG;CACvB;;;;;CAMA,MAAc,aACZ,kBACA,WACA,UACe;EACf,MAAM,KAAK,MACT,KAAK,WAAW,kBAAkB,SAAS,GAC3C,KAAK,UAAU,QAAQ,CACzB;CACF;;;;;CAMA,MAAc,UAAU,kBAAkD;EACxE,MAAM,MAAM,MAAM,KAAK,OAAO,IAAI,KAAK,SAAS,gBAAgB,CAAC;EAEjE,IAAI,QAAQ,MACV,OAAO,EAAE,YAAY,CAAC,EAAE;EAG1B,OAAO,KAAK,MAAM,GAAG;CACvB;;;;;CAMA,MAAc,aACZ,kBACA,WACe;EACf,MAAM,QAAQ,MAAM,KAAK,UAAU,gBAAgB;EAEnD,IAAI,MAAM,WAAW,SAAS,SAAS,GACrC;EAGF,MAAM,WAAW,KAAK,SAAS;EAE/B,MAAM,KAAK,MAAM,KAAK,SAAS,gBAAgB,GAAG,KAAK,UAAU,KAAK,CAAC;CACzE;;;;;CAMA,MAAc,eACZ,kBACA,WACe;EACf,MAAM,QAAQ,MAAM,KAAK,UAAU,gBAAgB;EACnD,MAAM,OAAO,MAAM,WAAW,QAAQ,OAAO,OAAO,SAAS;EAE7D,IAAI,KAAK,WAAW,MAAM,WAAW,QACnC;EAGF,MAAM,KAAK,MACT,KAAK,SAAS,gBAAgB,GAC9B,KAAK,UAAU,EAAE,YAAY,KAAK,CAAC,CACrC;CACF;;;;;;CAOA,MAAc,MAAM,KAAa,OAA8B;EAC7D,IAAI,KAAK,QAAQ,UAAa,KAAK,MAAM,GAAG;GAC1C,MAAM,KAAK,OAAO,IAAI,KAAK,OAAO,EAAE,IAAI,KAAK,IAAI,CAAC;GAElD;EACF;EAEA,MAAM,KAAK,OAAO,IAAI,KAAK,KAAK;CAClC;;;;CAKA,AAAQ,WAAW,kBAA0B,WAA2B;EACtE,OAAO,GAAG,KAAK,OAAO,WAAW,iBAAiB,GAAG;CACvD;;;;;CAMA,AAAQ,SAAS,kBAAkC;EACjD,OAAO,GAAG,KAAK,OAAO,SAAS;CACjC;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,MAAM,SAAkD;CACtE,OAAO,IAAI,qBAAqB,OAAO;AACzC"}

package/esm/config.d.mts

@@ -1,3 +1,5 @@
+import { SnapshotStore } from "./contracts/orchestrator/snapshot-store.contract.mjs";
+import { CheckpointStore } from "./contracts/orchestrator/checkpoint-store.contract.mjs";
 import { CacheDriver } from "@warlock.js/cache";
 
 //#region ../@warlock.js/ai/src/config.d.ts
@@ -24,15 +26,19 @@ import { CacheDriver } from "@warlock.js/cache";
  */
 type AIConfig = {
   /**
-   * Default store used by every consumer that supports persistence
-   * but didn't supply its own `store` / `snapshotStore`. Most
-   * realistic deployments back resume snapshots, semantic cache, and
-   * future memory primitives with the same driver — declaring it
-   * once here removes the repetition.
+   * Default `@warlock.js/cache` driver for cache-backed consumers that
+   * didn't supply their own `store` — currently the `semanticCache`
+   * middleware's vector store. Declaring it once here removes the
+   * repetition across middleware declarations.
    *
-   * Per-declaration overrides (`SupervisorConfig.snapshotStore`,
-   * `semanticCache({ store })`) win when supplied. Set this once at
-   * app boot, *after* you've constructed your driver.
+   * NOT the snapshot-persistence fallback anymore. Supervisor /
+   * workflow / orchestrator resume snapshots resolve through
+   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),
+   * never this driver.
+   *
+   * Per-declaration overrides (`semanticCache({ store })`) win when
+   * supplied. Set this once at app boot, *after* you've constructed
+   * your driver.
    *
    * @example
    * import { cache } from "@warlock.js/cache";
@@ -43,6 +49,32 @@ type AIConfig = {
    * });
    */
   defaultStore?: CacheDriver<any, any>;
+  /**
+   * Default {@link CheckpointStore} for every orchestrator that didn't
+   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds
+   * durable session state — `state`, `turn_index`, drift `signature`,
+   * compaction locks. Per-orchestrator `checkpointStore` wins when
+   * supplied. Set once at app boot.
+   *
+   * @example
+   * import { ai } from "@warlock.js/ai";
+   *
+   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });
+   */
+  defaultCheckpointStore?: CheckpointStore;
+  /**
+   * Default {@link SnapshotStore} for every orchestrator that didn't
+   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the
+   * internal supervisor run state used to resume an interrupted
+   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when
+   * supplied. Set once at app boot.
+   *
+   * @example
+   * import { ai } from "@warlock.js/ai";
+   *
+   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });
+   */
+  defaultSnapshotStore?: SnapshotStore;
 };
 /**
  * Set or extend process-wide AI configuration. Merges over existing
@@ -67,13 +99,28 @@ declare function setAIConfig(partial: Partial<AIConfig>): AIConfig;
  */
 declare function getAIConfig(): AIConfig;
 /**
- * Resolve the effective store for a consumer that didn't receive an
- * explicit one. Returns the global `defaultStore` if set, otherwise
- * `undefined`. Consumers decide whether `undefined` is fatal (semantic
- * cache: yes, throws) or a no-op (snapshot persistence: yes, just
- * skips).
+ * Resolve the effective `@warlock.js/cache` driver for a cache-backed
+ * consumer that didn't receive an explicit one. Returns the global
+ * `defaultStore` if set, otherwise `undefined`. The semantic-cache
+ * middleware treats `undefined` as fatal and throws. Snapshot
+ * persistence no longer consults this — it resolves through
+ * {@link resolveDefaultSnapshotStore}.
  */
 declare function resolveDefaultStore(): CacheDriver<any, any> | undefined;
+/**
+ * Resolve the global default {@link CheckpointStore} for an
+ * orchestrator that didn't receive an explicit `checkpointStore`.
+ * Returns `undefined` when none is configured — the orchestrator
+ * factory decides whether that's fatal.
+ */
+declare function resolveDefaultCheckpointStore(): CheckpointStore | undefined;
+/**
+ * Resolve the global default {@link SnapshotStore} for an orchestrator
+ * that didn't receive an explicit `snapshotStore`. Returns `undefined`
+ * when none is configured — the orchestrator factory decides whether
+ * that's fatal (it is, when `iterate: true`).
+ */
+declare function resolveDefaultSnapshotStore(): SnapshotStore | undefined;
 //#endregion
-export { AIConfig, getAIConfig, resolveDefaultStore, setAIConfig };
+export { AIConfig, getAIConfig, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
 //# sourceMappingURL=config.d.mts.map

package/esm/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"mappings":";;;;;AAuBA;;;;AAoB4B;AAoB5B;;;;;;;;;;;;;AAAiE;KAxCrD,QAAA;EAkDe;;;AAAY;AAWvC;;;;AAAkD;;;;;;;;;;;EAzChD,YAAA,GAAe,WAAW;AAAA;;;;;;;;;;;;;;;;iBAoBZ,WAAA,CAAY,OAAA,EAAS,OAAA,CAAQ,QAAA,IAAY,QAAA;;;;;;iBAUzC,WAAA,IAAe,QAAQ;;;;;;;;iBAWvB,mBAAA,IAAuB,WAAW"}
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"mappings":";;;;;;;AAyBA;;;;;;;;;;;;;;;AAoDsC;AAoBtC;;;KAxEY,QAAA;EAwEyB;;;;;;;;;AAA4B;AAUjE;;;;AAAuC;AAYvC;;;;AAAkD;AAUlD;;;EAhFE,YAAA,GAAe,WAAA;EAgF+C;AAUhE;;;;AAA4D;;;;;;;EA5E1D,sBAAA,GAAyB,eAAA;;;;;;;;;;;;;EAczB,oBAAA,GAAuB,aAAA;AAAA;;;;;;;;;;;;;;;;iBAoBT,WAAA,CAAY,OAAA,EAAS,OAAA,CAAQ,QAAA,IAAY,QAAA;;;;;;iBAUzC,WAAA,IAAe,QAAQ;;;;;;;;;iBAYvB,mBAAA,IAAuB,WAAW;;;;;;;iBAUlC,6BAAA,IAAiC,eAAe;;;;;;;iBAUhD,2BAAA,IAA+B,aAAa"}

package/esm/config.mjs

@@ -28,16 +28,35 @@ function getAIConfig() {
 	return { ...aiConfig };
 }
 /**
-* Resolve the effective store for a consumer that didn't receive an
-* explicit one. Returns the global `defaultStore` if set, otherwise
-* `undefined`. Consumers decide whether `undefined` is fatal (semantic
-* cache: yes, throws) or a no-op (snapshot persistence: yes, just
-* skips).
+* Resolve the effective `@warlock.js/cache` driver for a cache-backed
+* consumer that didn't receive an explicit one. Returns the global
+* `defaultStore` if set, otherwise `undefined`. The semantic-cache
+* middleware treats `undefined` as fatal and throws. Snapshot
+* persistence no longer consults this — it resolves through
+* {@link resolveDefaultSnapshotStore}.
 */
 function resolveDefaultStore() {
 	return aiConfig.defaultStore;
 }
+/**
+* Resolve the global default {@link CheckpointStore} for an
+* orchestrator that didn't receive an explicit `checkpointStore`.
+* Returns `undefined` when none is configured — the orchestrator
+* factory decides whether that's fatal.
+*/
+function resolveDefaultCheckpointStore() {
+	return aiConfig.defaultCheckpointStore;
+}
+/**
+* Resolve the global default {@link SnapshotStore} for an orchestrator
+* that didn't receive an explicit `snapshotStore`. Returns `undefined`
+* when none is configured — the orchestrator factory decides whether
+* that's fatal (it is, when `iterate: true`).
+*/
+function resolveDefaultSnapshotStore() {
+	return aiConfig.defaultSnapshotStore;
+}
 
 //#endregion
-export { getAIConfig, resolveDefaultStore, setAIConfig };
+export { getAIConfig, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
 //# sourceMappingURL=config.mjs.map

package/esm/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n */\nexport type AIConfig = {\n  /**\n   * Default store used by every consumer that supports persistence\n   * but didn't supply its own `store` / `snapshotStore`. Most\n   * realistic deployments back resume snapshots, semantic cache, and\n   * future memory primitives with the same driver — declaring it\n   * once here removes the repetition.\n   *\n   * Per-declaration overrides (`SupervisorConfig.snapshotStore`,\n   * `semanticCache({ store })`) win when supplied. Set this once at\n   * app boot, *after* you've constructed your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n};\n\nconst aiConfig: AIConfig = {};\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  return { ...aiConfig };\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective store for a consumer that didn't receive an\n * explicit one. Returns the global `defaultStore` if set, otherwise\n * `undefined`. Consumers decide whether `undefined` is fatal (semantic\n * cache: yes, throws) or a no-op (snapshot persistence: yes, just\n * skips).\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n"],"mappings":";AA8CA,MAAM,WAAqB,CAAC;;;;;;;;;;;;;;;;AAiB5B,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;AASA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n */\nexport type AIConfig = {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  return { ...aiConfig };\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAgFA,MAAM,WAAqB,CAAC;;;;;;;;;;;;;;;;AAiB5B,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;;AAUA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}

package/esm/contracts/agent/agent.contract.d.mts

@@ -1,6 +1,7 @@
 import { AgentResult } from "../result/agent-result.type.mjs";
 import { ExecutableContract } from "../executable.contract.mjs";
 import { StreamContract } from "../stream/stream.contract.mjs";
+import { EvalOptions, EvalReport } from "./eval.type.mjs";
 import { AgentEventMap } from "../events/event-map.type.mjs";
 import { AgentExecuteOptions } from "./agent-options.type.mjs";
 
@@ -86,6 +87,48 @@ interface AgentContract<TOutput = unknown> extends ExecutableContract<string, Ag
    * never registered or was already removed.
    */
   off<K extends keyof AgentEventMap>(event: K, handler: AgentEventHandler<K>): void;
+  /**
+   * Run a suite of evaluation cases against this agent and return an
+   * aggregate {@link EvalReport}. Each case runs through
+   * `execute(input)`; the result is scored by the resolved scorers —
+   * a per-case `scorers` override, else the suite `scorers`, else the
+   * suite `judge` (LLM-as-judge). A case passes only when every scorer
+   * passes and the agent did not error.
+   *
+   * Never throws on a case-level failure — failures surface on the
+   * report (`report.passed`, per-case `passed`) and via the
+   * `onFailure` callback. Throws at author time only when a case can
+   * resolve neither a scorer nor a judge.
+   *
+   * @example
+   * const report = await myAgent.eval({
+   *   cases: [
+   *     { name: "capital", input: "Capital of Egypt?", expected: "Cairo" },
+   *   ],
+   *   scorers: [ai.eval.exact()],
+   * });
+   *
+   * expect(report.passed).toBe(true);
+   *
+   * @example
+   * // LLM-as-judge
+   * const report = await myAgent.eval({
+   *   cases: [{ name: "tone", input: "Comfort an upset user." }],
+   *   judge: { agent: judgeAgent, rubric: "Score 1.0 only if empathetic." },
+   * });
+   *
+   * @typeParam TEval - Output type the eval cases/scorers are written
+   *   against. Defaults to the agent's own `TOutput`, so normal calls
+   *   stay fully typed. Exposed as a method-level generic (rather than
+   *   pinned to the interface's `TOutput`) so that the `eval` surface —
+   *   which references `TOutput` invariantly through the per-case
+   *   `output` schema — does not make `AgentContract<TOutput>` itself
+   *   invariant. That keeps a concretely-typed agent (e.g.
+   *   `AgentContract<RouterOutput>`) assignable to an
+   *   `AgentContract<unknown>` slot such as the supervisor's `router`,
+   *   `intents`, and `classifier`.
+   */
+  eval<TEval = TOutput>(options: EvalOptions<TEval>): Promise<EvalReport<TEval>>;
 }
 //#endregion
 export { AgentContract, AgentEventHandler };

package/esm/contracts/agent/agent.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;AAUA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EAAZ;;;;;;;;EAAA,SAUS,IAAA;EAmBP;;;;;EAAA,SAbO,WAAA;EAqBU;;;;;EAAA,SAfV,WAAA;EAwBT;;;;EAnBA,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EAkBnB;;;;AAAoB;EAX/B,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;EAO7B,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;AAAA"}
+{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;;AAWA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EAH8D;;;;;;;;EAAA,SAajE,IAAA;EAMA;;;;;EAAA,SAAA,WAAA;EAaP;;;;;EAAA,SAPO,WAAA;EAeU;;;;EAVnB,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EAS5B;;;;;EAFF,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EASlB;;;;EAFX,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EA4ChB;;;;;;;;AAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA5E,IAAA,SAAa,OAAA,EAAS,OAAA,EAAS,WAAA,CAAY,KAAA,IAAS,OAAA,CAAQ,UAAA,CAAW,KAAA;AAAA"}

package/esm/contracts/agent/eval.type.d.mts

@@ -0,0 +1,143 @@
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { AgentContract } from "./agent.contract.mjs";
+import { AgentExecuteOptions } from "./agent-options.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/agent/eval.type.d.ts
+/**
+ * Outcome the scorer assigns to a single case. `score` is a normalized
+ * `0..1` quality signal; `passed` is the boolean gate the suite asserts
+ * on. A scorer may set `passed` independently of `score` (e.g. a hard
+ * threshold) — when it returns only a `score`, the runner derives
+ * `passed` from `score >= passThreshold`.
+ */
+type EvalScore = {
+  /** Normalized quality signal in `[0, 1]`. */score: number;
+  /**
+   * Whether this case counts as a pass. When omitted the runner
+   * derives it from `score >= passThreshold`.
+   */
+  passed?: boolean; /** Optional human-readable explanation surfaced in the report. */
+  reason?: string;
+};
+/**
+ * Context handed to a {@link EvalScorer} for one case. Carries the
+ * case definition, the agent's actual result, and the parsed output /
+ * raw text shortcuts so a scorer never has to re-narrow the result
+ * union.
+ */
+type EvalScorerContext<TOutput = unknown> = {
+  /** The case currently being scored. */case: EvalCase<TOutput>; /** The full `AgentResult` produced by running the case input. */
+  result: AgentResult<TOutput>; /** Shortcut for `result.data` — the parsed structured output, if any. */
+  output?: TOutput; /** Shortcut for `result.text` — the raw final-trip text. */
+  text?: string;
+};
+/**
+ * Scorer for a single eval case. Returns an {@link EvalScore} (sync or
+ * async). Three built-in scorers ship via the `ai.eval` namespace:
+ * `exactScorer`, `predicateScorer`, and `judgeScorer` (LLM-as-judge).
+ * Custom scorers implement this signature directly.
+ */
+type EvalScorer<TOutput = unknown> = (context: EvalScorerContext<TOutput>) => EvalScore | Promise<EvalScore>;
+/**
+ * A single evaluation case. `input` is the prompt fed to the agent;
+ * `expected` is the optional reference answer exact / judge scorers
+ * compare against. `scorers` overrides the suite-level scorer list for
+ * this case only; `options` overrides the per-call execute options.
+ */
+type EvalCase<TOutput = unknown> = {
+  /** Stable identifier for the case — surfaced in the report. */name: string; /** Prompt fed to `agent.execute(input)`. */
+  input: string;
+  /**
+   * Reference answer the default scorers compare against. Free-form —
+   * a string for text comparison, a structured value for output
+   * comparison, or omitted when the scorer is purely predicate-based.
+   */
+  expected?: unknown; /** Per-case scorer override. Falls back to the suite `scorers`. */
+  scorers?: EvalScorer<TOutput>[]; /** Per-case execute-options override merged over the suite default. */
+  options?: AgentExecuteOptions<TOutput>;
+};
+/**
+ * LLM-as-judge configuration. When supplied to `agent.eval`, the
+ * judge agent scores every case that has no explicit `scorers`. The
+ * judge receives the case input, the expected reference (if any), and
+ * the actual output, and returns a `{ score, passed?, reason? }`
+ * verdict.
+ *
+ * `agent` must be name-bearing and configured with an output schema
+ * matching the judge verdict shape — the runner extracts `score` /
+ * `passed` / `reason` from `result.data`, falling back to parsing the
+ * raw text when no schema is set.
+ */
+type EvalJudge = {
+  /** The judge agent. Runs once per case scored by the judge. */agent: AgentContract<unknown>;
+  /**
+   * Optional rubric prepended to the judge prompt — the criteria the
+   * judge grades against ("score 1.0 only if the answer cites a
+   * source", etc.).
+   */
+  rubric?: string;
+  /**
+   * Score at or above which the judge verdict counts as a pass when
+   * the judge returns only a numeric score. Defaults to the suite
+   * `passThreshold`.
+   */
+  passThreshold?: number;
+};
+/**
+ * Options for `agent.eval`.
+ *
+ * `cases` is the suite; `scorers` is the default scorer list applied
+ * to every case lacking its own; `judge` enables LLM-as-judge scoring
+ * for cases with neither. At least one of `scorers` / `judge` must be
+ * resolvable per case or the runner throws at author time.
+ */
+type EvalOptions<TOutput = unknown> = {
+  /** The evaluation cases to run. */cases: EvalCase<TOutput>[]; /** Default scorers applied to every case without its own `scorers`. */
+  scorers?: EvalScorer<TOutput>[]; /** LLM-as-judge fallback for cases with no scorers. */
+  judge?: EvalJudge;
+  /**
+   * Score at or above which a case passes when a scorer returns only a
+   * numeric `score` (no explicit `passed`). Defaults to `0.5`.
+   */
+  passThreshold?: number;
+  /**
+   * Fired once per failing case, after it is scored. Receives the
+   * full case result so suites can log, snapshot, or accumulate
+   * failures. Errors thrown here are swallowed so a reporting bug
+   * cannot abort the run.
+   */
+  onFailure?: (caseResult: EvalCaseResult<TOutput>) => void | Promise<void>; /** Execute-options applied to every case (merged under per-case `options`). */
+  executeOptions?: AgentExecuteOptions<TOutput>;
+};
+/**
+ * Per-case outcome in an {@link EvalReport}. Bundles the case, the
+ * agent result, the resolved scores, and the case-level pass/fail
+ * verdict (the AND of every scorer's `passed`).
+ */
+type EvalCaseResult<TOutput = unknown> = {
+  /** The case that produced this result. */case: EvalCase<TOutput>; /** The full agent result for the case input. */
+  result: AgentResult<TOutput>; /** Every scorer's verdict, in scorer order. */
+  scores: EvalScore[]; /** Mean of `scores[].score` — the case's aggregate quality signal. */
+  score: number; /** `true` only when EVERY scorer passed and the agent did not error. */
+  passed: boolean; /** Wall-clock duration of the case run in milliseconds. */
+  duration: number;
+};
+/**
+ * Aggregate report returned by `agent.eval`. Summarizes pass rate and
+ * mean score across the suite and carries every per-case result for
+ * drill-down. Assertion-friendly: `expect(report.passed).toBe(true)`.
+ */
+type EvalReport<TOutput = unknown> = {
+  /** Name of the agent under evaluation. */agentName: string; /** Total number of cases run. */
+  total: number; /** Number of cases that passed. */
+  passedCount: number; /** Number of cases that failed. */
+  failedCount: number; /** `passedCount / total` in `[0, 1]`. */
+  passRate: number; /** Mean of every case's aggregate `score`. */
+  meanScore: number; /** `true` only when every case passed. */
+  passed: boolean; /** Per-case results in suite order. */
+  cases: EvalCaseResult<TOutput>[]; /** Total wall-clock duration of the whole suite in milliseconds. */
+  duration: number;
+};
+//#endregion
+export { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext };
+//# sourceMappingURL=eval.type.d.mts.map

package/esm/contracts/agent/eval.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/eval.type.ts"],"mappings":";;;;;;;AAWA;;;;;KAAY,SAAA;EASV,6CAPA,KAAA;EAOM;AASR;;;EAXE,MAAA,YAaM;EAXN,MAAA;AAAA;;;;;;;KASU,iBAAA;EAIV,uCAFA,IAAA,EAAM,QAAA,CAAS,OAAA,GAEK;EAApB,MAAA,EAAQ,WAAA,CAAY,OAAA,GAEX;EAAT,MAAA,GAAS,OAAA,EAEL;EAAJ,IAAA;AAAA;;;;;;;KASU,UAAA,uBACV,OAAA,EAAS,iBAAA,CAAkB,OAAA,MACxB,SAAA,GAAY,OAAA,CAAQ,SAAA;;;;;;;KAQb,QAAA;EARK,+DAUf,IAAA,UAVgC;EAYhC,KAAA;EAJU;;;;;EAUV,QAAA,YAIU;EAFV,OAAA,GAAU,UAAA,CAAW,OAAA,KAEQ;EAA7B,OAAA,GAAU,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;AAAO;AAevC;;KAAY,SAAA;EAEU,+DAApB,KAAA,EAAO,aAAa;EAAb;;;;AAYM;EANb,MAAA;EAiBqB;;;;;EAXrB,aAAA;AAAA;;;;;;;;;KAWU,WAAA;EAEH,mCAAP,KAAA,EAAO,QAAA,CAAS,OAAA,KAEhB;EAAA,OAAA,GAAU,UAAA,CAAW,OAAA,KAAA;EAErB,KAAA,GAAQ,SAAA;EAAA;;;;EAKR,aAAA;EAOa;;;;;;EAAb,SAAA,IAAa,UAAA,EAAY,cAAA,CAAe,OAAA,aAAoB,OAAA,QAUlD;EARV,cAAA,GAAiB,mBAAA,CAAoB,OAAA;AAAA;;;;;;KAQ3B,cAAA;EAMO,0CAJjB,IAAA,EAAM,QAAA,CAAS,OAAA,GAAf;EAEA,MAAA,EAAQ,WAAA,CAAY,OAAA,GAFL;EAIf,MAAA,EAAQ,SAAA,IAFA;EAIR,KAAA,UAFA;EAIA,MAAA,WAFA;EAIA,QAAA;AAAA;;AAAQ;AAQV;;;KAAY,UAAA;EAAW,0CAErB,SAAA,UAEA;EAAA,KAAA,UAIA;EAFA,WAAA,UAMA;EAJA,WAAA,UAQA;EANA,QAAA,UAMsB;EAJtB,SAAA,UAMQ;EAJR,MAAA;EAEA,KAAA,EAAO,cAAc,CAAC,OAAA;EAEtB,QAAA;AAAA"}

package/esm/contracts/agent/index.d.mts

@@ -1,2 +1,3 @@
+import { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext } from "./eval.type.mjs";
 import { AgentContract, AgentEventHandler } from "./agent.contract.mjs";
 import { AgentExecuteOptions } from "./agent-options.type.mjs";

package/esm/contracts/events/supervisor-events.type.d.mts

@@ -1,10 +1,10 @@
 import { AIError } from "../../errors/ai-error.mjs";
 import { Usage } from "../result/usage.type.mjs";
-import { Next } from "../supervisor/next.type.mjs";
-import { IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
+import { SupervisorResult } from "../result/supervisor-result.type.mjs";
 import { SupervisorInput } from "../supervisor/supervisor-input.type.mjs";
+import { Next } from "../supervisor/next.type.mjs";
 import { EvaluateResult } from "../supervisor/evaluate-context.type.mjs";
-import { SupervisorResult } from "../result/supervisor-result.type.mjs";
+import { IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
 //#region ../@warlock.js/ai/src/contracts/events/supervisor-events.type.d.ts
 /** Fires once at the start of every `supervisor.execute()` call. */
 type SupervisorStartingPayload = {