@warlock.js/ai 4.2.11 → 4.3.0

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

@@ -0,0 +1,42 @@
+import { ToolContract } from "../tool/tool.mjs";
+import { OrchestratorAsToolOptions, OrchestratorContract } from "../contracts/orchestrator/orchestrator.contract.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/as-tool.d.ts
+/**
+ * Wrap an {@link OrchestratorContract} as a {@link ToolContract} so an
+ * outer agent can invoke it from its tool-call loop (design §13).
+ * Mirrors `supervisor.asTool()` — same `compositeAsTool` composition and
+ * error normalization — and adds `sessionScope`.
+ *
+ * The boundary is OPAQUE (§13, §18.6): the parent's `signal` / `context`
+ * / events do NOT auto-forward. Anything the wrapped orchestrator needs
+ * per call must ride on the tool's `inputSchema` payload.
+ *
+ * Session continuity:
+ * - `"fresh"` (default) — each invocation gets a brand-new `sessionId`
+ *   (a generated id) and empty history; the session lives only for this
+ *   tool call. The whole validated payload is forwarded as the
+ *   orchestrator's `execute(input)` argument.
+ * - `"shared"` — the parent supplies `sessionId` (and optionally
+ *   `history`) inside the validated payload; the orchestrator
+ *   participates in that session. The remaining payload fields are
+ *   forwarded as `execute(input)`. A missing/blank `sessionId` throws
+ *   {@link SupervisorFailedError}.
+ *
+ * On `result.error`, the typed orchestrator error is thrown so the tool
+ * wrapper produces a `ToolExecutionError` with `cause` preserved — the
+ * outer agent sees one uniform error class.
+ *
+ * @example
+ * const support = ai.orchestrator({ name: "refund-support", intents });
+ * const supportTool = support.asTool({
+ *   name: "handle_refund",
+ *   description: "Handle a refund conversation end-to-end.",
+ *   inputSchema: v.object({ message: v.string() }),
+ * });
+ * const concierge = ai.agent({ model, tools: [supportTool] });
+ */
+declare function asTool<TOutput, TState, TToolInput>(orchestrator: OrchestratorContract<TOutput, TState>, options: OrchestratorAsToolOptions<TToolInput>): ToolContract<TToolInput, TOutput>;
+//#endregion
+export { asTool };
+//# sourceMappingURL=as-tool.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/as-tool.ts"],"mappings":";;;;;;AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGmC;;;;;iBAHnB,MAAA,8BACd,YAAA,EAAc,oBAAA,CAAqB,OAAA,EAAS,MAAA,GAC5C,OAAA,EAAS,yBAAA,CAA0B,UAAA,IAClC,YAAA,CAAa,UAAA,EAAY,OAAA"}

package/esm/orchestrator/as-tool.mjs

@@ -0,0 +1,98 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { compositeAsTool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/as-tool.ts
+/**
+* Wrap an {@link OrchestratorContract} as a {@link ToolContract} so an
+* outer agent can invoke it from its tool-call loop (design §13).
+* Mirrors `supervisor.asTool()` — same `compositeAsTool` composition and
+* error normalization — and adds `sessionScope`.
+*
+* The boundary is OPAQUE (§13, §18.6): the parent's `signal` / `context`
+* / events do NOT auto-forward. Anything the wrapped orchestrator needs
+* per call must ride on the tool's `inputSchema` payload.
+*
+* Session continuity:
+* - `"fresh"` (default) — each invocation gets a brand-new `sessionId`
+*   (a generated id) and empty history; the session lives only for this
+*   tool call. The whole validated payload is forwarded as the
+*   orchestrator's `execute(input)` argument.
+* - `"shared"` — the parent supplies `sessionId` (and optionally
+*   `history`) inside the validated payload; the orchestrator
+*   participates in that session. The remaining payload fields are
+*   forwarded as `execute(input)`. A missing/blank `sessionId` throws
+*   {@link SupervisorFailedError}.
+*
+* On `result.error`, the typed orchestrator error is thrown so the tool
+* wrapper produces a `ToolExecutionError` with `cause` preserved — the
+* outer agent sees one uniform error class.
+*
+* @example
+* const support = ai.orchestrator({ name: "refund-support", intents });
+* const supportTool = support.asTool({
+*   name: "handle_refund",
+*   description: "Handle a refund conversation end-to-end.",
+*   inputSchema: v.object({ message: v.string() }),
+* });
+* const concierge = ai.agent({ model, tools: [supportTool] });
+*/
+function asTool(orchestrator, options) {
+	if (!orchestrator.name || typeof orchestrator.name !== "string") throw new SupervisorFailedError("orchestrator.asTool(): orchestrator must have a `name` to be wrapped as a tool");
+	const sessionScope = options.sessionScope ?? "fresh";
+	return compositeAsTool({
+		name: options.name ?? orchestrator.name,
+		description: options.description ?? `Invoke orchestrator "${orchestrator.name}" as a tool.`,
+		input: options.inputSchema,
+		execute: async (input) => {
+			const { sessionId, history, executeInput } = resolveSession(sessionScope, input);
+			const result = await orchestrator.execute(executeInput, {
+				sessionId,
+				history
+			});
+			if (result.error) throw result.error;
+			return {
+				data: result.data,
+				usage: result.usage,
+				report: result.report
+			};
+		}
+	});
+}
+/**
+* Resolve the per-call `sessionId`, `history`, and the `execute(input)`
+* argument from the validated tool payload, according to `sessionScope`.
+*/
+function resolveSession(sessionScope, input) {
+	if (sessionScope === "fresh") return {
+		sessionId: generateRunId("session"),
+		history: [],
+		executeInput: coerceInput(input)
+	};
+	const payload = typeof input === "object" && input !== null ? input : {};
+	if (typeof payload.sessionId !== "string" || payload.sessionId.length === 0) throw new SupervisorFailedError("orchestrator.asTool(): sessionScope \"shared\" requires a `sessionId` string in the tool input payload");
+	const { sessionId, history, ...rest } = payload;
+	return {
+		sessionId,
+		history: Array.isArray(history) ? history : [],
+		executeInput: coerceInput(rest)
+	};
+}
+/**
+* Coerce a tool-input value into the `SupervisorInput` shape the
+* orchestrator's `execute()` accepts (`string | Record<string,
+* unknown>`). Strings and plain objects pass through; everything else
+* is JSON-stringified so the orchestrator receives a predictable input
+* regardless of how the outer agent shaped its call.
+*/
+function coerceInput(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "object" && value !== null) return value;
+	if (value === void 0 || value === null) return "";
+	return String(value);
+}
+
+//#endregion
+export { asTool };
+//# sourceMappingURL=as-tool.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/as-tool.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  OrchestratorAsToolOptions,\n  OrchestratorContract,\n} from \"../contracts/orchestrator/orchestrator.contract\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\nimport { generateRunId } from \"../utils/generate-run-id\";\n\n/**\n * Shape the orchestrator looks for inside the validated tool input when\n * `sessionScope: \"shared\"` — the parent must thread the session id (and\n * optionally the prior history) through the tool's `inputSchema`\n * payload, since the boundary is opaque (§13). Everything else on the\n * payload becomes the orchestrator's `execute(input)` argument.\n */\ntype SharedScopePayload = {\n  sessionId?: unknown;\n  history?: unknown;\n  [key: string]: unknown;\n};\n\n/**\n * Wrap an {@link OrchestratorContract} as a {@link ToolContract} so an\n * outer agent can invoke it from its tool-call loop (design §13).\n * Mirrors `supervisor.asTool()` — same `compositeAsTool` composition and\n * error normalization — and adds `sessionScope`.\n *\n * The boundary is OPAQUE (§13, §18.6): the parent's `signal` / `context`\n * / events do NOT auto-forward. Anything the wrapped orchestrator needs\n * per call must ride on the tool's `inputSchema` payload.\n *\n * Session continuity:\n * - `\"fresh\"` (default) — each invocation gets a brand-new `sessionId`\n *   (a generated id) and empty history; the session lives only for this\n *   tool call. The whole validated payload is forwarded as the\n *   orchestrator's `execute(input)` argument.\n * - `\"shared\"` — the parent supplies `sessionId` (and optionally\n *   `history`) inside the validated payload; the orchestrator\n *   participates in that session. The remaining payload fields are\n *   forwarded as `execute(input)`. A missing/blank `sessionId` throws\n *   {@link SupervisorFailedError}.\n *\n * On `result.error`, the typed orchestrator error is thrown so the tool\n * wrapper produces a `ToolExecutionError` with `cause` preserved — the\n * outer agent sees one uniform error class.\n *\n * @example\n * const support = ai.orchestrator({ name: \"refund-support\", intents });\n * const supportTool = support.asTool({\n *   name: \"handle_refund\",\n *   description: \"Handle a refund conversation end-to-end.\",\n *   inputSchema: v.object({ message: v.string() }),\n * });\n * const concierge = ai.agent({ model, tools: [supportTool] });\n */\nexport function asTool<TOutput, TState, TToolInput>(\n  orchestrator: OrchestratorContract<TOutput, TState>,\n  options: OrchestratorAsToolOptions<TToolInput>,\n): ToolContract<TToolInput, TOutput> {\n  if (!orchestrator.name || typeof orchestrator.name !== \"string\") {\n    throw new SupervisorFailedError(\n      \"orchestrator.asTool(): orchestrator must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  const sessionScope = options.sessionScope ?? \"fresh\";\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: options.name ?? orchestrator.name,\n    description:\n      options.description ??\n      `Invoke orchestrator \"${orchestrator.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input) => {\n      const { sessionId, history, executeInput } = resolveSession(\n        sessionScope,\n        input,\n      );\n\n      const result = await orchestrator.execute(executeInput, {\n        sessionId,\n        history,\n      });\n\n      if (result.error) {\n        // Surface the typed orchestrator 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 * Resolve the per-call `sessionId`, `history`, and the `execute(input)`\n * argument from the validated tool payload, according to `sessionScope`.\n */\nfunction resolveSession(\n  sessionScope: \"fresh\" | \"shared\",\n  input: unknown,\n): { sessionId: string; history: Message[]; executeInput: SupervisorInput } {\n  if (sessionScope === \"fresh\") {\n    return {\n      sessionId: generateRunId(\"session\"),\n      history: [],\n      executeInput: coerceInput(input),\n    };\n  }\n\n  const payload = (\n    typeof input === \"object\" && input !== null ? input : {}\n  ) as SharedScopePayload;\n\n  if (typeof payload.sessionId !== \"string\" || payload.sessionId.length === 0) {\n    throw new SupervisorFailedError(\n      'orchestrator.asTool(): sessionScope \"shared\" requires a `sessionId` string in the tool input payload',\n    );\n  }\n\n  const { sessionId, history, ...rest } = payload;\n\n  return {\n    sessionId,\n    history: Array.isArray(history) ? (history as Message[]) : [],\n    executeInput: coerceInput(rest),\n  };\n}\n\n/**\n * Coerce a tool-input value into the `SupervisorInput` shape the\n * orchestrator's `execute()` accepts (`string | Record<string,\n * unknown>`). Strings and plain objects pass through; everything else\n * is JSON-stringified so the orchestrator receives a predictable input\n * regardless of how the outer agent shaped its call.\n */\nfunction coerceInput(value: unknown): SupervisorInput {\n  if (typeof value === \"string\") {\n    return value;\n  }\n\n  if (typeof value === \"object\" && value !== null) {\n    return value as Record<string, unknown>;\n  }\n\n  if (value === undefined || value === null) {\n    return \"\";\n  }\n\n  return String(value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,OACd,cACA,SACmC;CACnC,IAAI,CAAC,aAAa,QAAQ,OAAO,aAAa,SAAS,UACrD,MAAM,IAAI,sBACR,gFACF;CAGF,MAAM,eAAe,QAAQ,gBAAgB;CAE7C,OAAO,gBAAqC;EAC1C,MAAM,QAAQ,QAAQ,aAAa;EACnC,aACE,QAAQ,eACR,wBAAwB,aAAa,KAAK;EAC5C,OAAO,QAAQ;EACf,SAAS,OAAO,UAAU;GACxB,MAAM,EAAE,WAAW,SAAS,iBAAiB,eAC3C,cACA,KACF;GAEA,MAAM,SAAS,MAAM,aAAa,QAAQ,cAAc;IACtD;IACA;GACF,CAAC;GAED,IAAI,OAAO,OAGT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;AAMA,SAAS,eACP,cACA,OAC0E;CAC1E,IAAI,iBAAiB,SACnB,OAAO;EACL,WAAW,cAAc,SAAS;EAClC,SAAS,CAAC;EACV,cAAc,YAAY,KAAK;CACjC;CAGF,MAAM,UACJ,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ,CAAC;CAGzD,IAAI,OAAO,QAAQ,cAAc,YAAY,QAAQ,UAAU,WAAW,GACxE,MAAM,IAAI,sBACR,wGACF;CAGF,MAAM,EAAE,WAAW,SAAS,GAAG,SAAS;CAExC,OAAO;EACL;EACA,SAAS,MAAM,QAAQ,OAAO,IAAK,UAAwB,CAAC;EAC5D,cAAc,YAAY,IAAI;CAChC;AACF;;;;;;;;AASA,SAAS,YAAY,OAAiC;CACpD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO;CAGT,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO;CAGT,OAAO,OAAO,KAAK;AACrB"}

package/esm/orchestrator/checkpoint.mjs

@@ -0,0 +1,75 @@
+//#region ../@warlock.js/ai/src/orchestrator/checkpoint.ts
+/** Framework default for snapshot retention per session (§4 Phase 6). */
+const DEFAULT_KEEP_SNAPSHOTS = 100;
+/**
+* Summarize a supervisor dispatch decision into the `last_route`
+* checkpoint column (§4 Phase 6). A bare string passes through; a
+* fan-out array passes through; the `END` sentinel and anything else
+* collapse to `null` (the turn routed nowhere worth recording).
+*/
+function summarizeRoute(next) {
+	if (typeof next === "string") return next === "__warlock:end__" ? null : next;
+	if (Array.isArray(next)) return next;
+	return null;
+}
+/**
+* Phase 6 — persist checkpoint (orchestrator.md §3 / §4 Phase 6).
+* Writes a fresh append-only row at `turn_index = N` carrying the
+* post-merge `state`, the current `signature` (read by the next call's
+* Phase 2), the informational `version`, the dispatch `last_route`, and
+* the carried-forward `summarized_through`. Lock columns are written
+* `null` here — they are populated only by an in-flight Phase 7
+* compaction.
+*
+* Emits `orchestrator.checkpoint.persisted` after the row lands, then
+* prunes to `keepSnapshots` (default 100; `"all"` opts out) — §4 Phase
+* 6 pruning (Q20). Pruning runs only when the store exposes the
+* optional `prune` hook (memory/pg/redis own their own pruning); when
+* absent the write still succeeds.
+*
+* Returns the persisted record so the engine can fold it into the
+* turn's report.
+*/
+async function persistCheckpoint(params) {
+	const { ctx, sessionId, turnIndex, state, lastRoute, summarizedThrough } = params;
+	const record = {
+		orchestrator_name: ctx.config.name,
+		session_id: sessionId,
+		turn_index: turnIndex,
+		state,
+		last_route: lastRoute,
+		signature: ctx.signature,
+		version: ctx.config.version ?? null,
+		summarized_through: summarizedThrough,
+		lock_acquired_at: null,
+		lock_expires_at: null,
+		saved_at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await ctx.checkpointStore.save(record);
+	ctx.emitter.emit("orchestrator.checkpoint.persisted", {
+		sessionId,
+		turnIndex
+	});
+	await prune(ctx, sessionId, turnIndex);
+	return record;
+}
+/**
+* Prune session rows older than `max_turn_index - keepSnapshots` (§4
+* Phase 6). Synchronous-after-save; opted out with
+* `keepSnapshots: "all"`. Delegated to an optional store-side `prune`
+* hook so each driver implements deletion in its own dialect — the
+* engine never reaches into store internals.
+*/
+async function prune(ctx, sessionId, latestTurnIndex) {
+	const keep = ctx.config.keepSnapshots ?? 100;
+	if (keep === "all") return;
+	const store = ctx.checkpointStore;
+	if (typeof store.prune !== "function") return;
+	const keepBeforeTurnIndex = latestTurnIndex - keep + 1;
+	if (keepBeforeTurnIndex <= 0) return;
+	await store.prune(ctx.config.name, sessionId, keepBeforeTurnIndex);
+}
+
+//#endregion
+export { persistCheckpoint, summarizeRoute };
+//# sourceMappingURL=checkpoint.mjs.map

package/esm/orchestrator/checkpoint.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/checkpoint.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { Next } from \"../contracts/supervisor/next.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/** Framework default for snapshot retention per session (§4 Phase 6). */\nexport const DEFAULT_KEEP_SNAPSHOTS = 100;\n\n/** Fields the engine supplies to build a fresh checkpoint row. */\nexport type PersistParams<TState> = {\n  ctx: OrchestratorEngineContext<unknown, TState>;\n  sessionId: string;\n  turnIndex: number;\n  state: unknown;\n  /** Dispatch decision summary — a single intent, fan-out list, or null. */\n  lastRoute: string | string[] | null;\n  /** Carried forward from the loaded checkpoint (compaction progress). */\n  summarizedThrough: number | null;\n};\n\n/**\n * Summarize a supervisor dispatch decision into the `last_route`\n * checkpoint column (§4 Phase 6). A bare string passes through; a\n * fan-out array passes through; the `END` sentinel and anything else\n * collapse to `null` (the turn routed nowhere worth recording).\n */\nexport function summarizeRoute(next: Next | undefined): string | string[] | null {\n  if (typeof next === \"string\") {\n    return next === \"__warlock:end__\" ? null : next;\n  }\n\n  if (Array.isArray(next)) {\n    return next;\n  }\n\n  return null;\n}\n\n/**\n * Phase 6 — persist checkpoint (orchestrator.md §3 / §4 Phase 6).\n * Writes a fresh append-only row at `turn_index = N` carrying the\n * post-merge `state`, the current `signature` (read by the next call's\n * Phase 2), the informational `version`, the dispatch `last_route`, and\n * the carried-forward `summarized_through`. Lock columns are written\n * `null` here — they are populated only by an in-flight Phase 7\n * compaction.\n *\n * Emits `orchestrator.checkpoint.persisted` after the row lands, then\n * prunes to `keepSnapshots` (default 100; `\"all\"` opts out) — §4 Phase\n * 6 pruning (Q20). Pruning runs only when the store exposes the\n * optional `prune` hook (memory/pg/redis own their own pruning); when\n * absent the write still succeeds.\n *\n * Returns the persisted record so the engine can fold it into the\n * turn's report.\n */\nexport async function persistCheckpoint<TState>(\n  params: PersistParams<TState>,\n): Promise<CheckpointRecord> {\n  const { ctx, sessionId, turnIndex, state, lastRoute, summarizedThrough } = params;\n\n  const record: CheckpointRecord = {\n    orchestrator_name: ctx.config.name,\n    session_id: sessionId,\n    turn_index: turnIndex,\n    state,\n    last_route: lastRoute,\n    signature: ctx.signature,\n    version: ctx.config.version ?? null,\n    summarized_through: summarizedThrough,\n    lock_acquired_at: null,\n    lock_expires_at: null,\n    saved_at: new Date().toISOString(),\n  };\n\n  await ctx.checkpointStore.save(record);\n\n  ctx.emitter.emit(\"orchestrator.checkpoint.persisted\", {\n    sessionId,\n    turnIndex,\n  });\n\n  await prune(ctx, sessionId, turnIndex);\n\n  return record;\n}\n\n/**\n * Prune session rows older than `max_turn_index - keepSnapshots` (§4\n * Phase 6). Synchronous-after-save; opted out with\n * `keepSnapshots: \"all\"`. Delegated to an optional store-side `prune`\n * hook so each driver implements deletion in its own dialect — the\n * engine never reaches into store internals.\n */\nasync function prune<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  latestTurnIndex: number,\n): Promise<void> {\n  const keep = ctx.config.keepSnapshots ?? DEFAULT_KEEP_SNAPSHOTS;\n\n  if (keep === \"all\") {\n    return;\n  }\n\n  const store = ctx.checkpointStore as {\n    prune?: (\n      orchestratorName: string,\n      sessionId: string,\n      keepBeforeTurnIndex: number,\n    ) => Promise<void>;\n  };\n\n  if (typeof store.prune !== \"function\") {\n    return;\n  }\n\n  const keepBeforeTurnIndex = latestTurnIndex - keep + 1;\n\n  if (keepBeforeTurnIndex <= 0) {\n    return;\n  }\n\n  await store.prune(ctx.config.name, sessionId, keepBeforeTurnIndex);\n}\n"],"mappings":";;AAKA,MAAa,yBAAyB;;;;;;;AAoBtC,SAAgB,eAAe,MAAkD;CAC/E,IAAI,OAAO,SAAS,UAClB,OAAO,SAAS,oBAAoB,OAAO;CAG7C,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO;CAGT,OAAO;AACT;;;;;;;;;;;;;;;;;;;AAoBA,eAAsB,kBACpB,QAC2B;CAC3B,MAAM,EAAE,KAAK,WAAW,WAAW,OAAO,WAAW,sBAAsB;CAE3E,MAAM,SAA2B;EAC/B,mBAAmB,IAAI,OAAO;EAC9B,YAAY;EACZ,YAAY;EACZ;EACA,YAAY;EACZ,WAAW,IAAI;EACf,SAAS,IAAI,OAAO,WAAW;EAC/B,oBAAoB;EACpB,kBAAkB;EAClB,iBAAiB;EACjB,2BAAU,IAAI,KAAK,EAAC,CAAC,YAAY;CACnC;CAEA,MAAM,IAAI,gBAAgB,KAAK,MAAM;CAErC,IAAI,QAAQ,KAAK,qCAAqC;EACpD;EACA;CACF,CAAC;CAED,MAAM,MAAM,KAAK,WAAW,SAAS;CAErC,OAAO;AACT;;;;;;;;AASA,eAAe,MACb,KACA,WACA,iBACe;CACf,MAAM,OAAO,IAAI,OAAO;CAExB,IAAI,SAAS,OACX;CAGF,MAAM,QAAQ,IAAI;CAQlB,IAAI,OAAO,MAAM,UAAU,YACzB;CAGF,MAAM,sBAAsB,kBAAkB,OAAO;CAErD,IAAI,uBAAuB,GACzB;CAGF,MAAM,MAAM,MAAM,IAAI,OAAO,MAAM,WAAW,mBAAmB;AACnE"}

package/esm/orchestrator/commands.d.mts

@@ -0,0 +1,38 @@
+import { OrchestratorCommands } from "../contracts/orchestrator/orchestrator-commands.type.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/commands.d.ts
+/**
+ * Per-command handler bag — one async runner per key of
+ * {@link OrchestratorCommands}. The orchestrator factory supplies the
+ * `compact` runner (which delegates to the shared compaction code path,
+ * §11) so this module owns command ROUTING only, never the compaction
+ * logic itself.
+ *
+ * Typed against the same discriminated map the public `command<K>`
+ * method uses, so a registered handler's `args` / result line up with
+ * the contract with no casting at the call site.
+ */
+type OrchestratorCommandHandlers = { [K in keyof OrchestratorCommands]: (args: OrchestratorCommands[K]["args"]) => Promise<OrchestratorCommands[K]["result"]> };
+/**
+ * Build the typed `command(name, args)` dispatcher backing
+ * {@link import("../contracts/orchestrator/orchestrator.contract").OrchestratorContract.command}
+ * (design §11). Looks the command up in the supplied handler bag and
+ * forwards `args`, preserving the discriminated `OrchestratorCommands`
+ * typing end to end.
+ *
+ * v1 ships exactly one built-in command, `compact`. v2 user commands
+ * attach via module augmentation of `OrchestratorCommands`; the
+ * dispatcher widens with the map automatically, and an unregistered
+ * command throws {@link SupervisorFailedError} rather than silently
+ * resolving `undefined`.
+ *
+ * @example
+ * const command = createCommandDispatcher({
+ *   compact: (args) => runCompaction(args),
+ * });
+ * const result = await command("compact", { sessionId, history });
+ */
+declare function createCommandDispatcher(handlers: OrchestratorCommandHandlers): <K extends keyof OrchestratorCommands>(name: K, args: OrchestratorCommands[K]["args"]) => Promise<OrchestratorCommands[K]["result"]>;
+//#endregion
+export { OrchestratorCommandHandlers, createCommandDispatcher };
+//# sourceMappingURL=commands.d.mts.map

package/esm/orchestrator/commands.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/commands.ts"],"mappings":";;;;;AAcA;;;;;;;;;KAAY,2BAAA,iBACE,oBAAA,IACV,IAAA,EAAM,oBAAA,CAAqB,CAAA,cACxB,OAAA,CAAQ,oBAAA,CAAqB,CAAA;;;;;;;;;AAAC;AAsBrC;;;;;;;;;;iBAAgB,uBAAA,CAAwB,QAAA,EAAU,2BAAA,oBACR,oBAAA,EACtC,IAAA,EAAM,CAAA,EACN,IAAA,EAAM,oBAAA,CAAqB,CAAA,cAC1B,OAAA,CAAQ,oBAAA,CAAqB,CAAA"}

package/esm/orchestrator/commands.mjs

@@ -0,0 +1,34 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/commands.ts
+/**
+* Build the typed `command(name, args)` dispatcher backing
+* {@link import("../contracts/orchestrator/orchestrator.contract").OrchestratorContract.command}
+* (design §11). Looks the command up in the supplied handler bag and
+* forwards `args`, preserving the discriminated `OrchestratorCommands`
+* typing end to end.
+*
+* v1 ships exactly one built-in command, `compact`. v2 user commands
+* attach via module augmentation of `OrchestratorCommands`; the
+* dispatcher widens with the map automatically, and an unregistered
+* command throws {@link SupervisorFailedError} rather than silently
+* resolving `undefined`.
+*
+* @example
+* const command = createCommandDispatcher({
+*   compact: (args) => runCompaction(args),
+* });
+* const result = await command("compact", { sessionId, history });
+*/
+function createCommandDispatcher(handlers) {
+	return function command(name, args) {
+		const handler = handlers[name];
+		if (typeof handler !== "function") throw new SupervisorFailedError(`orchestrator.command(): unknown command "${String(name)}"`);
+		return handler(args);
+	};
+}
+
+//#endregion
+export { createCommandDispatcher };
+//# sourceMappingURL=commands.mjs.map

package/esm/orchestrator/commands.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/commands.ts"],"sourcesContent":["import type { OrchestratorCommands } from \"../contracts/orchestrator/orchestrator-commands.type\";\nimport { SupervisorFailedError } from \"../errors\";\n\n/**\n * Per-command handler bag — one async runner per key of\n * {@link OrchestratorCommands}. The orchestrator factory supplies the\n * `compact` runner (which delegates to the shared compaction code path,\n * §11) so this module owns command ROUTING only, never the compaction\n * logic itself.\n *\n * Typed against the same discriminated map the public `command<K>`\n * method uses, so a registered handler's `args` / result line up with\n * the contract with no casting at the call site.\n */\nexport type OrchestratorCommandHandlers = {\n  [K in keyof OrchestratorCommands]: (\n    args: OrchestratorCommands[K][\"args\"],\n  ) => Promise<OrchestratorCommands[K][\"result\"]>;\n};\n\n/**\n * Build the typed `command(name, args)` dispatcher backing\n * {@link import(\"../contracts/orchestrator/orchestrator.contract\").OrchestratorContract.command}\n * (design §11). Looks the command up in the supplied handler bag and\n * forwards `args`, preserving the discriminated `OrchestratorCommands`\n * typing end to end.\n *\n * v1 ships exactly one built-in command, `compact`. v2 user commands\n * attach via module augmentation of `OrchestratorCommands`; the\n * dispatcher widens with the map automatically, and an unregistered\n * command throws {@link SupervisorFailedError} rather than silently\n * resolving `undefined`.\n *\n * @example\n * const command = createCommandDispatcher({\n *   compact: (args) => runCompaction(args),\n * });\n * const result = await command(\"compact\", { sessionId, history });\n */\nexport function createCommandDispatcher(handlers: OrchestratorCommandHandlers) {\n  return function command<K extends keyof OrchestratorCommands>(\n    name: K,\n    args: OrchestratorCommands[K][\"args\"],\n  ): Promise<OrchestratorCommands[K][\"result\"]> {\n    const handler = handlers[name];\n\n    if (typeof handler !== \"function\") {\n      throw new SupervisorFailedError(\n        `orchestrator.command(): unknown command \"${String(name)}\"`,\n      );\n    }\n\n    return handler(args);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,wBAAwB,UAAuC;CAC7E,OAAO,SAAS,QACd,MACA,MAC4C;EAC5C,MAAM,UAAU,SAAS;EAEzB,IAAI,OAAO,YAAY,YACrB,MAAM,IAAI,sBACR,4CAA4C,OAAO,IAAI,EAAE,EAC3D;EAGF,OAAO,QAAQ,IAAI;CACrB;AACF"}

package/esm/orchestrator/compaction.mjs

@@ -0,0 +1,206 @@
+import { DEFAULT_LOCK_MAX_WAIT } from "./lock.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/compaction.ts
+/**
+* Most-recent messages kept verbatim when `summarize.keep` is omitted.
+* Defaulting to 0 would compact the entire history into one memo (losing
+* the live tail every turn), so the object form keeps a small recent
+* window by default — matching the canonical doc examples (`keep: 8`).
+*/
+const DEFAULT_COMPACTION_KEEP = 8;
+/** Whether the configured `summarize` is the fully-pluggable callback form. */
+function isCallbackForm(summarize) {
+	return typeof summarize === "function";
+}
+/**
+* Decide whether Phase 7 compaction should fire this turn (orchestrator
+* .md §4 Phase 7 / §12.1). v1 trigger is count-based:
+* `summarize.afterTurns` fires once `turnIndex >= afterTurns`. The
+* callback form has no threshold and never auto-fires — it is driven
+* exclusively by `command("compact")` (the manual path). Returns false
+* when `summarize` is unset.
+*/
+function shouldCompact(ctx, turnIndex) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0 || isCallbackForm(summarize)) return false;
+	const afterTurns = summarize.afterTurns;
+	return afterTurns !== void 0 && turnIndex >= afterTurns;
+}
+/**
+* Run the configured summarizer against the session history and build
+* a {@link CompactionResult} (§12.2 step 2–3). Three resolution paths:
+*
+* - callback form — `summarize(history)` returns the result directly.
+* - config + `summarizer` model — summarize the slice (history minus
+*   the most-recent `keep`) into one synthetic memo turn.
+* - config without a `summarizer` — produce a trivial degenerate memo
+*   (no model available); the dev is expected to supply a summarizer
+*   for real compaction. The range still reflects the kept tail.
+*/
+async function produceCompaction(summarize, history) {
+	if (isCallbackForm(summarize)) return summarize(history);
+	const keep = summarize.keep ?? 8;
+	const replacesFromIndex = 0;
+	const replacesToIndex = Math.max(-1, history.length - keep - 1);
+	return {
+		summary: {
+			role: "system",
+			content: await summarizeSlice(summarize, history.slice(0, replacesToIndex + 1))
+		},
+		replacesFromIndex,
+		replacesToIndex
+	};
+}
+/**
+* Summarize a slice of history into text. Uses the configured
+* `summarizer` model when present (a single non-streaming completion);
+* otherwise returns a placeholder memo. The summarizer is intentionally
+* the cheap model — never the specialists (§12.4).
+*/
+async function summarizeSlice(summarize, slice) {
+	if (slice.length === 0) return "";
+	if (!summarize.summarizer) return `Summary of ${slice.length} prior message(s).`;
+	const transcript = slice.map((message) => `${message.role}: ${stringifyContent(message.content)}`).join("\n");
+	return (await summarize.summarizer.complete([{
+		role: "system",
+		content: "Summarize the following conversation slice into a concise memo that preserves the facts, decisions, and open threads a later turn would need. Reply with the memo only."
+	}, {
+		role: "user",
+		content: transcript
+	}])).content;
+}
+/** Coerce a message's content into a flat string for the summarizer prompt. */
+function stringifyContent(content) {
+	if (typeof content === "string") return content;
+	return JSON.stringify(content);
+}
+/**
+* Phase 7 — post-turn compaction (orchestrator.md §3 / §4 Phase 7 /
+* §12.2). Runs AFTER the turn settles; never blocks the caller's
+* resolution path beyond this phase.
+*
+* Acquires the cooperative session lock (writes `lock_acquired_at` /
+* `lock_expires_at` onto a fresh row), runs the summarizer, builds the
+* compaction, then either invokes `summarize.onCompact` (framework-
+* driven apply) or surfaces the compaction on the result for the dev to
+* apply. Releases the lock on settle. Emits
+* `orchestrator.compaction.suggested` always,
+* `orchestrator.compaction.applied` only when `onCompact` succeeded, and
+* `orchestrator.compaction.failed` (carrying the thrown `error` and the
+* `phase` that failed) when the summarizer or `onCompact` throws.
+*
+* Retry policy is skip-and-log (§4 Phase 7): a summarizer failure
+* leaves the session running with unchanged history — the engine
+* treats a thrown summarizer / `onCompact` as "no compaction this
+* turn", emits `orchestrator.compaction.failed`, and returns `undefined`
+* (summarizer) or surfaces the unapplied compaction (`onCompact`).
+*/
+async function runCompaction(ctx, sessionId, history) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0) return;
+	await acquireCompactionLock(ctx, sessionId);
+	try {
+		const compaction = await produceCompaction(summarize, history);
+		ctx.emitter.emit("orchestrator.compaction.suggested", {
+			sessionId,
+			compaction
+		});
+		const onCompact = isCallbackForm(summarize) ? void 0 : summarize.onCompact;
+		if (!onCompact) return {
+			compaction,
+			applied: false
+		};
+		try {
+			await onCompact(compaction, { sessionId });
+			ctx.emitter.emit("orchestrator.compaction.applied", {
+				sessionId,
+				compaction
+			});
+			return {
+				compaction,
+				applied: true
+			};
+		} catch (error) {
+			ctx.emitter.emit("orchestrator.compaction.failed", {
+				sessionId,
+				phase: "onCompact",
+				error
+			});
+			return {
+				compaction,
+				applied: false
+			};
+		}
+	} catch (error) {
+		ctx.emitter.emit("orchestrator.compaction.failed", {
+			sessionId,
+			phase: "summarize",
+			error
+		});
+		return;
+	} finally {
+		await releaseCompactionLock(ctx, sessionId);
+	}
+}
+/**
+* Run a manual compaction for `command("compact", ...)` (§11 / §12.1).
+* Same code path as the post-turn trigger but driven on demand against
+* the supplied history, returning the raw {@link CompactionResult}. The
+* callback form is honored; the config form without a `summarizer`
+* produces the degenerate memo. Does not apply `onCompact` — the
+* command surface returns the compaction for the caller to handle.
+*/
+async function runManualCompaction(ctx, history) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0) return {
+		summary: {
+			role: "system",
+			content: `Summary of ${history.length} message(s).`
+		},
+		replacesFromIndex: 0,
+		replacesToIndex: Math.max(-1, history.length - 1)
+	};
+	return produceCompaction(summarize, history);
+}
+/** Resolve the lock TTL from the summarize config (config form only). */
+function resolveLockMaxWait(ctx) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0 || isCallbackForm(summarize)) return DEFAULT_LOCK_MAX_WAIT;
+	return summarize.lock?.maxWait ?? 3e4;
+}
+/**
+* Write the cooperative compaction lock onto a fresh checkpoint row
+* (§12.2 step 1). The lock lives on the latest persisted row; we load
+* it, stamp the lock columns, and re-save (append-only) so the next
+* turn's Phase 3 observes it.
+*/
+async function acquireCompactionLock(ctx, sessionId) {
+	const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!latest) return;
+	const now = Date.now();
+	const maxWait = resolveLockMaxWait(ctx);
+	await ctx.checkpointStore.save({
+		...latest,
+		lock_acquired_at: new Date(now).toISOString(),
+		lock_expires_at: new Date(now + maxWait).toISOString(),
+		saved_at: new Date(now).toISOString()
+	});
+}
+/**
+* Clear the compaction lock columns (§12.2 step 6) by re-saving the
+* latest row with the lock fields nulled.
+*/
+async function releaseCompactionLock(ctx, sessionId) {
+	const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!latest) return;
+	await ctx.checkpointStore.save({
+		...latest,
+		lock_acquired_at: null,
+		lock_expires_at: null,
+		saved_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+
+//#endregion
+export { runCompaction, runManualCompaction, shouldCompact };
+//# sourceMappingURL=compaction.mjs.map

package/esm/orchestrator/compaction.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/compaction.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  SummarizeCallback,\n  SummarizeConfig,\n} from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { CompactionResult } from \"../contracts/result/orchestrator-result.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { DEFAULT_LOCK_MAX_WAIT } from \"./lock\";\n\n/**\n * Most-recent messages kept verbatim when `summarize.keep` is omitted.\n * Defaulting to 0 would compact the entire history into one memo (losing\n * the live tail every turn), so the object form keeps a small recent\n * window by default — matching the canonical doc examples (`keep: 8`).\n */\nexport const DEFAULT_COMPACTION_KEEP = 8;\n\n/** Whether the configured `summarize` is the fully-pluggable callback form. */\nfunction isCallbackForm(\n  summarize: SummarizeConfig | SummarizeCallback | undefined,\n): summarize is SummarizeCallback {\n  return typeof summarize === \"function\";\n}\n\n/**\n * Decide whether Phase 7 compaction should fire this turn (orchestrator\n * .md §4 Phase 7 / §12.1). v1 trigger is count-based:\n * `summarize.afterTurns` fires once `turnIndex >= afterTurns`. The\n * callback form has no threshold and never auto-fires — it is driven\n * exclusively by `command(\"compact\")` (the manual path). Returns false\n * when `summarize` is unset.\n */\nexport function shouldCompact(\n  ctx: OrchestratorEngineContext,\n  turnIndex: number,\n): boolean {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined || isCallbackForm(summarize)) {\n    return false;\n  }\n\n  const afterTurns = summarize.afterTurns;\n\n  return afterTurns !== undefined && turnIndex >= afterTurns;\n}\n\n/** Result of a Phase-7 run — what the engine folds into the turn. */\nexport type CompactionOutcome = {\n  /** The produced compaction, surfaced on `result.compaction`. */\n  compaction: CompactionResult;\n  /**\n   * Whether `summarize.onCompact` ran AND succeeded — when true the\n   * engine advances `summarized_through` to `replacesToIndex` (§12.2\n   * step 4); when false it leaves it unchanged (§12.2 step 5).\n   */\n  applied: boolean;\n};\n\n/**\n * Run the configured summarizer against the session history and build\n * a {@link CompactionResult} (§12.2 step 2–3). Three resolution paths:\n *\n * - callback form — `summarize(history)` returns the result directly.\n * - config + `summarizer` model — summarize the slice (history minus\n *   the most-recent `keep`) into one synthetic memo turn.\n * - config without a `summarizer` — produce a trivial degenerate memo\n *   (no model available); the dev is expected to supply a summarizer\n *   for real compaction. The range still reflects the kept tail.\n */\nasync function produceCompaction(\n  summarize: SummarizeConfig | SummarizeCallback,\n  history: Message[],\n): Promise<CompactionResult> {\n  if (isCallbackForm(summarize)) {\n    return summarize(history);\n  }\n\n  const keep = summarize.keep ?? DEFAULT_COMPACTION_KEEP;\n  const replacesFromIndex = 0;\n  const replacesToIndex = Math.max(-1, history.length - keep - 1);\n  const slice = history.slice(0, replacesToIndex + 1);\n\n  const summaryText = await summarizeSlice(summarize, slice);\n\n  return {\n    summary: { role: \"system\", content: summaryText },\n    replacesFromIndex,\n    replacesToIndex,\n  };\n}\n\n/**\n * Summarize a slice of history into text. Uses the configured\n * `summarizer` model when present (a single non-streaming completion);\n * otherwise returns a placeholder memo. The summarizer is intentionally\n * the cheap model — never the specialists (§12.4).\n */\nasync function summarizeSlice(\n  summarize: SummarizeConfig,\n  slice: Message[],\n): Promise<string> {\n  if (slice.length === 0) {\n    return \"\";\n  }\n\n  if (!summarize.summarizer) {\n    return `Summary of ${slice.length} prior message(s).`;\n  }\n\n  const transcript = slice\n    .map((message) => `${message.role}: ${stringifyContent(message.content)}`)\n    .join(\"\\n\");\n\n  const response = await summarize.summarizer.complete([\n    {\n      role: \"system\",\n      content:\n        \"Summarize the following conversation slice into a concise memo \" +\n        \"that preserves the facts, decisions, and open threads a later \" +\n        \"turn would need. Reply with the memo only.\",\n    },\n    { role: \"user\", content: transcript },\n  ]);\n\n  return response.content;\n}\n\n/** Coerce a message's content into a flat string for the summarizer prompt. */\nfunction stringifyContent(content: Message[\"content\"]): string {\n  if (typeof content === \"string\") {\n    return content;\n  }\n\n  return JSON.stringify(content);\n}\n\n/**\n * Phase 7 — post-turn compaction (orchestrator.md §3 / §4 Phase 7 /\n * §12.2). Runs AFTER the turn settles; never blocks the caller's\n * resolution path beyond this phase.\n *\n * Acquires the cooperative session lock (writes `lock_acquired_at` /\n * `lock_expires_at` onto a fresh row), runs the summarizer, builds the\n * compaction, then either invokes `summarize.onCompact` (framework-\n * driven apply) or surfaces the compaction on the result for the dev to\n * apply. Releases the lock on settle. Emits\n * `orchestrator.compaction.suggested` always,\n * `orchestrator.compaction.applied` only when `onCompact` succeeded, and\n * `orchestrator.compaction.failed` (carrying the thrown `error` and the\n * `phase` that failed) when the summarizer or `onCompact` throws.\n *\n * Retry policy is skip-and-log (§4 Phase 7): a summarizer failure\n * leaves the session running with unchanged history — the engine\n * treats a thrown summarizer / `onCompact` as \"no compaction this\n * turn\", emits `orchestrator.compaction.failed`, and returns `undefined`\n * (summarizer) or surfaces the unapplied compaction (`onCompact`).\n */\nexport async function runCompaction<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  history: Message[],\n): Promise<CompactionOutcome | undefined> {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined) {\n    return undefined;\n  }\n\n  await acquireCompactionLock(ctx, sessionId);\n\n  try {\n    const compaction = await produceCompaction(summarize, history);\n\n    ctx.emitter.emit(\"orchestrator.compaction.suggested\", {\n      sessionId,\n      compaction,\n    });\n\n    const onCompact = isCallbackForm(summarize) ? undefined : summarize.onCompact;\n\n    if (!onCompact) {\n      return { compaction, applied: false };\n    }\n\n    try {\n      await onCompact(compaction, { sessionId });\n\n      ctx.emitter.emit(\"orchestrator.compaction.applied\", {\n        sessionId,\n        compaction,\n      });\n\n      return { compaction, applied: true };\n    } catch (error) {\n      // onCompact threw — surface the compaction for the dev to apply,\n      // leave summarized_through unchanged (§12.2 step 4 failure path).\n      ctx.emitter.emit(\"orchestrator.compaction.failed\", {\n        sessionId,\n        phase: \"onCompact\",\n        error,\n      });\n\n      return { compaction, applied: false };\n    }\n  } catch (error) {\n    // Summarizer failed — skip-and-log; session keeps running unchanged.\n    ctx.emitter.emit(\"orchestrator.compaction.failed\", {\n      sessionId,\n      phase: \"summarize\",\n      error,\n    });\n\n    return undefined;\n  } finally {\n    await releaseCompactionLock(ctx, sessionId);\n  }\n}\n\n/**\n * Run a manual compaction for `command(\"compact\", ...)` (§11 / §12.1).\n * Same code path as the post-turn trigger but driven on demand against\n * the supplied history, returning the raw {@link CompactionResult}. The\n * callback form is honored; the config form without a `summarizer`\n * produces the degenerate memo. Does not apply `onCompact` — the\n * command surface returns the compaction for the caller to handle.\n */\nexport async function runManualCompaction<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  history: Message[],\n): Promise<CompactionResult> {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined) {\n    // No summarize policy configured — produce a degenerate memo over\n    // the full supplied history so the command always resolves.\n    return {\n      summary: { role: \"system\", content: `Summary of ${history.length} message(s).` },\n      replacesFromIndex: 0,\n      replacesToIndex: Math.max(-1, history.length - 1),\n    };\n  }\n\n  return produceCompaction(summarize, history);\n}\n\n/** Resolve the lock TTL from the summarize config (config form only). */\nfunction resolveLockMaxWait(ctx: OrchestratorEngineContext): number {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined || isCallbackForm(summarize)) {\n    return DEFAULT_LOCK_MAX_WAIT;\n  }\n\n  return summarize.lock?.maxWait ?? DEFAULT_LOCK_MAX_WAIT;\n}\n\n/**\n * Write the cooperative compaction lock onto a fresh checkpoint row\n * (§12.2 step 1). The lock lives on the latest persisted row; we load\n * it, stamp the lock columns, and re-save (append-only) so the next\n * turn's Phase 3 observes it.\n */\nasync function acquireCompactionLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n): Promise<void> {\n  const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!latest) {\n    return;\n  }\n\n  const now = Date.now();\n  const maxWait = resolveLockMaxWait(ctx as OrchestratorEngineContext);\n\n  await ctx.checkpointStore.save({\n    ...latest,\n    lock_acquired_at: new Date(now).toISOString(),\n    lock_expires_at: new Date(now + maxWait).toISOString(),\n    saved_at: new Date(now).toISOString(),\n  });\n}\n\n/**\n * Clear the compaction lock columns (§12.2 step 6) by re-saving the\n * latest row with the lock fields nulled.\n */\nasync function releaseCompactionLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n): Promise<void> {\n  const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!latest) {\n    return;\n  }\n\n  await ctx.checkpointStore.save({\n    ...latest,\n    lock_acquired_at: null,\n    lock_expires_at: null,\n    saved_at: new Date().toISOString(),\n  });\n}\n"],"mappings":"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"}