@warlock.js/ai 4.1.1

package/esm/contracts/supervisor/supervisor-execute-options.type.d.mts

@@ -0,0 +1,90 @@
+import { Message } from "../conversation-message.type.mjs";
+import { SupervisorEventHandlers } from "./supervisor-config.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor-execute-options.type.d.ts
+/**
+ * Per-call options for `supervisor.execute()`. Everything here is
+ * scoped to a single run — factory-level knobs live on
+ * `SupervisorConfig`.
+ *
+ * @example
+ * const controller = new AbortController();
+ * const result = await supervisor.execute("order #123 late", {
+ *   runId: "support-2026-04-23-123",
+ *   signal: controller.signal,
+ *   on: {
+ *     "supervisor.router.decided": ({ next }) => console.log("->", next),
+ *   },
+ * });
+ */
+type SupervisorExecuteOptions = {
+  /**
+   * Caller-chosen run identifier — reused as the cache key when
+   * `store` is configured. Auto-generated (`sup_<rand>`) when omitted.
+   */
+  runId?: string;
+  /**
+   * Cancellation handle. Between-iteration cancellation is
+   * guaranteed; mid-iteration aborts are propagated into every
+   * in-flight child `execute()` (agents, workflows, router).
+   */
+  signal?: AbortSignal;
+  /**
+   * Per-execution event handlers — tier 3 of the 3-tier model.
+   * Fire last, after definition-level and instance-level listeners.
+   */
+  on?: SupervisorEventHandlers;
+  /**
+   * Read-only request-scoped bag, surfaced on every `ctx.context`
+   * inside `route` / `evaluate` / intent callbacks / router-entry
+   * `placeholders` + `input` / per-intent `placeholders` + `input` +
+   * `next`. Use it to thread per-request data — `userId`, `traceId`,
+   * locale, DB clients, feature flags — without forcing supervisors
+   * to be re-instantiated per request.
+   *
+   * Shallow-copied + frozen at intake, so callbacks can't mutate the
+   * caller's object. NOT persisted in snapshots; re-supply on
+   * `resume(runId, { context })`.
+   */
+  context?: Record<string, unknown>;
+  /**
+   * Prior conversation messages — read-only context threaded into
+   * `route` / `evaluate` / dispatch callbacks via `ctx.history`, and
+   * forwarded verbatim to every dispatched agent (and the receptionist
+   * `ack` agent, when configured) as `agent.execute(input, { history })`.
+   *
+   * Mirrors `AgentExecuteOptions.history` so a supervisor can be slotted
+   * into a chat pipeline as a drop-in replacement for a single agent
+   * without the caller juggling history across primitives.
+   *
+   * NOT persisted in snapshots — re-supply on `resume(runId, { history })`
+   * if the resumed run still needs prior conversation context.
+   */
+  history?: Message[];
+  /**
+   * Opaque caller-supplied identifier that groups multiple `execute()`
+   * calls into one conceptual user session / request. Mirrored onto
+   * every report node this run produces so flat dashboard queries
+   * don't need to walk the tree.
+   *
+   * Auto-propagated to every dispatched intent, the router, the
+   * receptionist `ack`, and any nested composite invoked through
+   * `asTool`. Execution state stays isolated; only observability
+   * identity is shared.
+   */
+  sessionId?: string;
+};
+/**
+ * Options accepted by `supervisor.resume(runId, options?)`.
+ *
+ * `force: true` bypasses the signature drift check — use only when
+ * you have verified that the definition change is safe for the
+ * in-flight snapshot. `SupervisorDriftError` is otherwise thrown
+ * without executing anything.
+ */
+type SupervisorResumeOptions = SupervisorExecuteOptions & {
+  force?: boolean;
+};
+//#endregion
+export { SupervisorExecuteOptions, SupervisorResumeOptions };
+//# sourceMappingURL=supervisor-execute-options.type.d.mts.map

package/esm/contracts/supervisor/supervisor-execute-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-execute-options.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-execute-options.type.ts"],"mappings":";;;;;;AAkBA;;;;;;;;;;;;;KAAY,wBAAA;EA6BV;;;;EAxBA,KAAA;EAkDS;AAAA;AAWX;;;EAvDE,MAAA,GAAS,WAAA;EAwDJ;;;;EAnDL,EAAA,GAAK,uBAAA;;;;;;;;;;;;;EAaL,OAAA,GAAU,MAAA;;;;;;;;;;;;;;EAcV,OAAA,GAAU,OAAA;;;;;;;;;;;;EAYV,SAAA;AAAA;;;;;;;;;KAWU,uBAAA,GAA0B,wBAAwB;EAC5D,KAAK;AAAA"}

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

@@ -0,0 +1,24 @@
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor-input.type.d.ts
+/**
+ * Accepted input shape for `supervisor.execute(input)` and the
+ * matching field on every supervisor context (`RouteContext`,
+ * `EvaluateContext`, `IterationSnapshot`).
+ *
+ * Two shapes carry every realistic case without bloating the factory
+ * with a fourth generic:
+ *
+ * - `string` — raw user message, the most common case.
+ * - `Record<string, unknown>` — structured payload (e.g. `{ orderId,
+ *   reason, customerId }`) when the supervisor needs more than a
+ *   sentence to start its work.
+ *
+ * Callers wanting stronger static typing can wrap the supervisor in
+ * their own typed function — the runtime accepts both shapes
+ * uniformly. Object inputs are JSON-stringified when forwarded to a
+ * child agent without an explicit `entry.input(ctx)` override; supply
+ * the override when the agent should see anything other than `JSON.stringify(input)`.
+ */
+type SupervisorInput = string | Record<string, unknown>;
+//#endregion
+export { SupervisorInput };
+//# sourceMappingURL=supervisor-input.type.d.mts.map

package/esm/contracts/supervisor/supervisor-input.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-input.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-input.type.ts"],"mappings":";;AAmBA;;;;AAA6C;;;;;;;;;;;;;;KAAjC,eAAA,YAA2B,MAAM"}

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

@@ -0,0 +1,49 @@
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor-snapshot.type.d.ts
+/**
+ * Lifecycle status of a supervisor run, recorded on the persisted
+ * snapshot so resume can decide whether a run is still in flight.
+ *
+ * - `"running"` — the iteration loop is active; a resume is
+ *   legitimate if the process crashed.
+ * - `"completed"` — the supervisor terminated successfully; resume
+ *   is a no-op and returns the final state.
+ * - `"cancelled"` — aborted via `AbortSignal`; resume is allowed
+ *   (the caller decides whether to retry).
+ * - `"failed"` — terminated with an error; resume after the fix.
+ */
+type SupervisorSnapshotStatus = "running" | "completed" | "cancelled" | "failed";
+/**
+ * Persisted shape written to the configured `KVStore` after every
+ * iteration settles. Exists so `supervisor.resume(runId)` can
+ * re-hydrate the history + iteration counter and continue from the
+ * next turn.
+ *
+ * `signature` is a structural fingerprint covering the agent keys,
+ * their resolved descriptions, the router's identity (if any), and
+ * whether `route` was configured. `resume()` compares this against
+ * the current supervisor's signature; mismatch throws
+ * `SupervisorDriftError` (bypassable with `{ force: true }`).
+ *
+ * @example
+ * const snapshot: SupervisorSnapshot = await store.get(`supervisor:${runId}`);
+ * if (snapshot?.status === "running") {
+ *   await supervisor.resume(runId);
+ * }
+ */
+type SupervisorSnapshot = {
+  runId: string;
+  supervisorName: string;
+  signature: string; /** The original `execute(input)` value — needed on resume. */
+  input: SupervisorInput; /** Index of the last *completed* iteration; -1 before any settle. */
+  iteration: number;
+  snapshots: IterationSnapshot[];
+  status: SupervisorSnapshotStatus;
+  startedAt: string;
+  savedAt: string;
+};
+//#endregion
+export { SupervisorSnapshot, SupervisorSnapshotStatus };
+//# sourceMappingURL=supervisor-snapshot.type.d.mts.map

package/esm/contracts/supervisor/supervisor-snapshot.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-snapshot.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-snapshot.type.ts"],"mappings":";;;;;;;AAcA;;;;AAAoC;AAwBpC;;;;KAxBY,wBAAA;;;;;;;;;;;;;;;;;AAmCH;;KAXG,kBAAA;EACV,KAAA;EACA,cAAA;EACA,SAAA;EAEA,KAAA,EAL4B,eAAA;EAO5B,SAAA;EACA,SAAA,EAAW,iBAAA;EACX,MAAA,EAAQ,wBAAA;EACR,SAAA;EACA,OAAA;AAAA"}

package/esm/contracts/supervisor/supervisor-stream-event.type.d.mts

@@ -0,0 +1,16 @@
+import { SupervisorEventMap } from "../events/event-map.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor-stream-event.type.d.ts
+/**
+ * Discriminated union of every event consumers see when iterating
+ * `supervisor.stream()`. Mirrors `SupervisorEventMap` keys one-for-one
+ * with payloads widened by adding the `type` discriminator, so
+ * `for await` consumers can narrow via `event.type === "supervisor.xyz"`
+ * the same way agent-stream consumers narrow on `"agent.xyz"`.
+ */
+type SupervisorStreamEvent = { [K in keyof SupervisorEventMap]: {
+  type: K;
+} & SupervisorEventMap[K] }[keyof SupervisorEventMap];
+//#endregion
+export { SupervisorStreamEvent };
+//# sourceMappingURL=supervisor-stream-event.type.d.mts.map

package/esm/contracts/supervisor/supervisor-stream-event.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-stream-event.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-stream-event.type.ts"],"mappings":";;;;;AASA;;;;;KAAY,qBAAA,iBACE,kBAAA;EAAuB,IAAA,EAAM,CAAA;AAAA,IAAM,kBAAA,CAAmB,CAAA,UAC5D,kBAAA"}

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

@@ -0,0 +1,126 @@
+import { ExecutableContract } from "../executable.contract.mjs";
+import { StreamContract } from "../stream/stream.contract.mjs";
+import { ToolContract } from "../../tool/tool.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { SupervisorEventHandler } from "./supervisor-config.type.mjs";
+import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor-execute-options.type.mjs";
+import { SupervisorStreamEvent } from "./supervisor-stream-event.type.mjs";
+import { SupervisorResult } from "../result/supervisor-result.type.mjs";
+import { SupervisorEventMap } from "../events/event-map.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor.contract.d.ts
+/**
+ * Options accepted by `supervisor.asTool()`, mirroring
+ * `workflow.asTool()` / `agent.asTool()`. Exposes the supervisor as
+ * a tool an outer agent can invoke inside its tool-call loop.
+ *
+ * `inputSchema` types the tool's `input` payload — the supervisor
+ * receives the result of coercing the payload into a string (via
+ * the same `stringifyInput` helper the other primitives use) as its
+ * `execute(input)` argument.
+ */
+type SupervisorAsToolOptions<TToolInput> = {
+  name?: string;
+  description?: string;
+  inputSchema: StandardSchemaV1<TToolInput>;
+};
+/**
+ * Runtime handle returned by `ai.supervisor(config)`. Third
+ * implementer of `ExecutableContract` alongside `AgentContract` and
+ * `WorkflowInstance`, so orchestrators and nested supervisors can
+ * dispatch any primitive through the same uniform surface.
+ *
+ * Implements the 3-tier event subscription model (definition →
+ * instance → per-call), with events fired in that order on every
+ * emission. See `SupervisorEventMap` for the full surface.
+ *
+ * @example
+ * const support = ai.supervisor({
+ *   name: "customer-support",
+ *   router: routerAgent,
+ *   intents: { triage, resolver },
+ *   output: z.object({ response: z.string() }),
+ * });
+ *
+ * // Fire-and-forget — await the typed result
+ * const { data, report, usage, error } = await support.execute(ticket);
+ *
+ * // Or stream every lifecycle event in real time
+ * const stream = support.stream(ticket);
+ * stream.on({
+ *   "supervisor.router.decided": ({ next }) => console.log("→", next),
+ *   "supervisor.agent.streaming": ({ intent, delta }) =>
+ *     process.stdout.write(`[${intent}] ${delta}`),
+ * });
+ * const result = await stream.result;
+ *
+ * // Resume a crashed run from the persisted snapshot
+ * const recovered = await support.resume("support-run-42");
+ *
+ * // Expose the supervisor as a tool for an outer agent
+ * const tool = support.asTool({
+ *   name: "handle_support_ticket",
+ *   description: "Processes a customer support ticket end-to-end.",
+ *   inputSchema: z.object({ ticket: z.string() }),
+ * });
+ */
+interface SupervisorContract<TOutput = unknown> extends ExecutableContract<SupervisorInput, SupervisorExecuteOptions, SupervisorResult<TOutput>> {
+  /** Stable identifier — mirrors the config's `name`. */
+  readonly name: string;
+  /**
+   * Structural fingerprint of the supervisor definition — agent
+   * keys + their resolved descriptions + router identity (if set) +
+   * whether `route` was configured. Persisted on every snapshot so
+   * `resume()` can detect drift.
+   */
+  readonly signature: string;
+  /**
+   * Run the supervisor end-to-end. Returns the uniform `{ data,
+   * report, usage, error }` shape. Never throws on runtime failure —
+   * errors surface via `result.error`. Authoring-time misconfig
+   * throws at factory call, not here.
+   */
+  execute(input: SupervisorInput, options?: SupervisorExecuteOptions): Promise<SupervisorResult<TOutput>>;
+  /**
+   * Stream every lifecycle event in real time. Returns a
+   * `StreamContract` whose `result` resolves to the same value
+   * `execute()` would produce. Child agent streaming bubbles up as
+   * `supervisor.agent.streaming` — UI consumers can render per-
+   * agent tokens with zero extra wiring.
+   */
+  stream(input: SupervisorInput, options?: SupervisorExecuteOptions): StreamContract<SupervisorResult<TOutput>, SupervisorStreamEvent>;
+  /**
+   * Resume a supervisor run from its persisted snapshot. Requires
+   * `store` to have been configured on the supervisor. Throws
+   * `SupervisorDriftError` when the current definition's signature
+   * doesn't match the snapshot's, unless `{ force: true }` is set.
+   *
+   * Idempotency across side-effectful agents is the caller's
+   * responsibility — same contract as `workflow.resume()`.
+   */
+  resume(runId: string, options?: SupervisorResumeOptions): Promise<SupervisorResult<TOutput>>;
+  /**
+   * Subscribe an instance-level handler — tier 2 of the 3-tier
+   * model. Fires on every run of this supervisor instance, between
+   * definition-level and per-call handlers. Returns an unsubscribe
+   * function equivalent to `off(event, handler)`.
+   */
+  on<K extends keyof SupervisorEventMap>(event: K, handler: SupervisorEventHandler<K>): () => void;
+  /**
+   * Remove a previously-subscribed instance-level handler. No-op
+   * when the handler was never registered or already removed.
+   */
+  off<K extends keyof SupervisorEventMap>(event: K, handler: SupervisorEventHandler<K>): void;
+  /**
+   * Wrap this supervisor as a `ToolContract` so an outer agent can
+   * invoke it inside its tool-call loop. The tool calls
+   * `supervisor.execute(input)` internally; supervisor failures
+   * surface as `ToolExecutionError` with `cause` set to the original
+   * typed error.
+   */
+  asTool<TToolInput = string>(options: SupervisorAsToolOptions<TToolInput>): ToolContract<TToolInput, TOutput>;
+}
+//#endregion
+export { SupervisorAsToolOptions, SupervisorContract };
+//# sourceMappingURL=supervisor.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor.contract.ts"],"mappings":";;;;;;;;;;;;;;AAwBA;;;;;;;;KAAY,uBAAA;EACV,IAAA;EACA,WAAA;EACA,WAAA,EAAa,gBAAgB,CAAC,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA2Cf,kBAAA,4BAA8C,kBAAA,CAC7D,eAAA,EACA,wBAAA,EACA,gBAAA,CAAiB,OAAA;EAAjB;EAAA,SAGS,IAAA;EAAA;;;;;;EAAA,SAQA,SAAA;EAWN;;;;;;EAHH,OAAA,CACE,KAAA,EAAO,eAAA,EACP,OAAA,GAAU,wBAAA,GACT,OAAA,CAAQ,gBAAA,CAAiB,OAAA;EAW1B;;;;;;;EAFF,MAAA,CACE,KAAA,EAAO,eAAA,EACP,OAAA,GAAU,wBAAA,GACT,cAAA,CAAe,gBAAA,CAAiB,OAAA,GAAU,qBAAA;EAWvB;;;;;;;;;EAAtB,MAAA,CAAO,KAAA,UAAe,OAAA,GAAU,uBAAA,GAA0B,OAAA,CAAQ,gBAAA,CAAiB,OAAA;EAQF;;;;;;EAAjF,EAAA,iBAAmB,kBAAA,EAAoB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,sBAAA,CAAuB,CAAA;EAMtB;;;;EAA3D,GAAA,iBAAoB,kBAAA,EAAoB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,sBAAA,CAAuB,CAAA;EAUvE;;;;;;;EADX,MAAA,sBACE,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAChC,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}

package/esm/contracts/system-prompt.contract.d.mts

@@ -0,0 +1,118 @@
+import { Placeholders } from "./placeholders.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/system-prompt.contract.d.ts
+/**
+ * Base contract shared by every block that can appear inside a
+ * `SystemPromptContract` — currently persona and instruction, with room for
+ * future block kinds (examples, guardrails, etc.) without breaking changes.
+ *
+ * Blocks are discriminated by a string `type` tag — not `instanceof` — so
+ * runtime checks remain robust across duplicate package copies, bundler
+ * scopes, and user-supplied implementations that don't extend our classes.
+ *
+ * @example
+ * // Narrow via the discriminator
+ * if (block.type === "persona") {
+ *   // block is PersonaContract
+ * }
+ */
+interface SystemPromptBlockContract {
+  /** Discriminator for the concrete block kind. */
+  readonly type: string;
+  /** Raw template text, before placeholder resolution. */
+  readonly text: string;
+  /** Render the block with placeholders substituted in. */
+  resolve(placeholders?: Placeholders): string;
+}
+/**
+ * Contract for a persona block — the "who the agent is" layer of a system
+ * prompt. A persona owns a single template string and resolves its own
+ * placeholders, so the same `Persona` instance can be reused across many
+ * `SystemPrompt`s or agents without recomputation.
+ *
+ * @example
+ * const alex: PersonaContract = ai.persona("You are Alex, a TypeScript expert.");
+ * alex.resolve(); // "You are Alex, a TypeScript expert."
+ */
+interface PersonaContract extends SystemPromptBlockContract {
+  readonly type: "persona";
+}
+/**
+ * Contract for a single instruction block — one directive in a layered
+ * system prompt. Each instruction owns its own template string and resolves
+ * its placeholders independently, so the same `Instruction` instance can be
+ * reused across different `SystemPrompt`s with different placeholder maps.
+ *
+ * @example
+ * const replyInLanguage: InstructionContract =
+ *   ai.instruction("Respond in {{language|English}}.");
+ *
+ * replyInLanguage.resolve({ language: "Arabic" });
+ * // "Respond in Arabic."
+ */
+interface InstructionContract extends SystemPromptBlockContract {
+  readonly type: "instruction";
+}
+/**
+ * Immutable builder for composing a layered system prompt out of persona and
+ * instruction blocks. Every mutating method returns a fresh builder — the
+ * original is never mutated, so base prompts can be forked into specialized
+ * variants without side effects.
+ *
+ * Blocks are stored in a single ordered list and rendered in insertion order.
+ * The array-form factory (`systemPrompt([...])`) gives you full control over
+ * placement; the chainable form defaults to persona-first by prepending new
+ * personas (or replacing an existing one in place).
+ *
+ * Both `persona()` and `instruction()` accept either a raw string (auto-
+ * wrapped into a `Persona` / `Instruction`) or a pre-built contract
+ * instance. Passing instances lets the same block be reused across many
+ * prompts with each prompt supplying its own placeholder map at resolve time.
+ *
+ * @example
+ * // Chainable form
+ * const alex = ai.persona("You are Alex, a TypeScript expert.");
+ * const replyIn = ai.instruction("Respond in {{language|English}}.");
+ *
+ * const prompt = ai.systemPrompt()
+ *   .persona(alex)
+ *   .instruction(replyIn)
+ *   .instruction("Always include working code examples.");
+ *
+ * @example
+ * // Array form — insertion order is preserved exactly
+ * const prompt = ai.systemPrompt([
+ *   ai.persona("You are Alex, a TypeScript expert."),
+ *   ai.instruction("Respond in {{language|English}}."),
+ *   ai.instruction("Always include working code examples."),
+ * ]);
+ *
+ * const arabic = prompt.resolve({ language: "Arabic" });
+ */
+interface SystemPromptContract {
+  /** All blocks in render order. Read-only snapshot — use `persona()` / `instruction()` to derive a new builder. */
+  readonly blocks: readonly SystemPromptBlockContract[];
+  /**
+   * Set (or replace) the persona block. Returns a new builder. If a persona
+   * already exists it's replaced in place (preserving its position);
+   * otherwise the new persona is prepended. Only one persona per prompt.
+   */
+  persona(persona: PersonaContract | string): SystemPromptContract;
+  /**
+   * Append an instruction block. Returns a new builder. Multiple calls
+   * accumulate — instructions render in the order they were added.
+   */
+  instruction(instruction: InstructionContract | string): SystemPromptContract;
+  /**
+   * Resolve all placeholders across every block, producing the final system
+   * prompt string. Blocks render in insertion order, separated by a blank line.
+   *
+   * Supports `{{key}}`, `{{nested.key}}`, and `{{key|default}}` syntax.
+   *
+   * @param placeholders - Values to inject into `{{mustache}}` slots.
+   */
+  resolve(placeholders?: Placeholders): string;
+}
+//#endregion
+export { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract };
+//# sourceMappingURL=system-prompt.contract.d.mts.map

package/esm/contracts/system-prompt.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/system-prompt.contract.ts"],"mappings":";;;;;AAiBA;;;;;;;;;;AAQqC;AAarC;;UArBiB,yBAAA;EAqBwB;EAAA,SAnB9B,IAAA;EAoCM;EAAA,SAjCN,IAAA;;EAGT,OAAA,CAAQ,YAAA,GAAe,YAAY;AAAA;AAsErC;;;;;;;;;;AAAA,UAzDiB,eAAA,SAAwB,yBAAyB;EAAA,SACvD,IAAI;AAAA;;;;;;;;;;;;;AAiFsB;UAjEpB,mBAAA,SAA4B,yBAAyB;EAAA,SAC3D,IAAI;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuCE,oBAAA;;WAEN,MAAA,WAAiB,yBAAA;;;;;;EAO1B,OAAA,CAAQ,OAAA,EAAS,eAAA,YAA2B,oBAAA;;;;;EAM5C,WAAA,CAAY,WAAA,EAAa,mBAAA,YAA+B,oBAAA;;;;;;;;;EAUxD,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA"}

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

@@ -0,0 +1,161 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/tool.contract.d.ts
+/**
+ * Optional metadata attached to a tool for documentation and tooling.
+ *
+ * @example
+ * const meta: ToolMeta = { category: "search", version: "1.0" };
+ */
+type ToolMeta = Record<"label" | "actionLabel" | (string & {}), unknown>;
+/**
+ * Discriminated mode controlling whether the tool's result feeds back
+ * to the model.
+ *
+ * - **`feedback`** (default) — standard tool behavior. The model emits
+ *   a tool call, the agent dispatches the tool, the result is appended
+ *   to the conversation as a `role: "tool"` message, and the agent
+ *   makes another LLM trip so the model can read the result and
+ *   respond. Use for tools whose output the model needs to narrate
+ *   (search, lookup, classification with a reply that depends on it).
+ *
+ * - **`silent`** — fire-and-forget mechanics. The tool's *result* is
+ *   not fed back to the model. When every tool call in a single
+ *   generation is `silent`, the agent loop terminates after dispatch:
+ *   the prose the model streamed alongside the tool call IS the final
+ *   reply. Use for pure side-effect tools where the model already
+ *   knows what to say before the tool runs (state mutations, locale
+ *   pinning, topic classification updates, telemetry pings).
+ *
+ * **What "silent" applies to.** Strictly the LLM-feedback channel.
+ * The tool itself runs to completion through middleware (logging,
+ * cost tracking, telemetry) like any other — only the model-feedback
+ * leg is closed.
+ *
+ * **Constraints for silent tools.** Should be cheap, idempotent, and
+ * side-effect-only. No slow ops, no expensive network calls — the
+ * customer is waiting on the prose stream that already finished, but
+ * the request is still open until the silent tool resolves.
+ *
+ * **Mixed-mode trips.** If a single generation contains both
+ * `feedback` and `silent` tool calls, the loop continues — the
+ * feedback tool's result still needs to round-trip. The "all silent
+ * → terminate" rule only kicks in when EVERY tool call is silent.
+ */
+type ToolMode = "feedback" | "silent";
+/**
+ * Per-call context threaded into a tool handler as the optional second
+ * argument (Phase 5 / decisions §35).
+ *
+ * **Role.** Carry system-only data that should NOT round-trip through
+ * the LLM. The tool's `return` value is what the agent sees;
+ * `ctx.artifacts` is what the system captures. Strict separation of
+ * channels — neither leaks into the other.
+ *
+ * **Lifecycle.** When dispatched under a supervisor, the bag starts
+ * empty at every iteration boundary, accumulates across all tool
+ * calls in that iteration, and merges into supervisor state via
+ * `artifactsSchema` / `finalizeArtifacts` at iteration end. When the
+ * tool runs standalone (`tool.invoke(input)` without a ctx), a
+ * degraded `{ artifacts: {} }` is supplied — mutations are harmless
+ * no-ops.
+ *
+ * @example
+ * ai.tool({
+ *   name: "search_catalog",
+ *   input: v.object({ query: v.string() }),
+ *   execute: async (input, ctx) => {
+ *     const items = await searchItems(input.query);
+ *
+ *     // Side-channel: blocks land in supervisor state, not the LLM.
+ *     ctx.artifacts.blocks ??= [];
+ *     ctx.artifacts.blocks.push({ type: "items", itemIds: items.map(i => i.id) });
+ *
+ *     // Return value: what the agent sees and reasons over.
+ *     return { total: items.length };
+ *   },
+ * });
+ */
+type ToolContext<TArtifacts = Record<string, unknown>> = {
+  /**
+   * Mutable bag for system-only data. Writes here never reach the
+   * LLM. Shape is typed by the registering supervisor's
+   * `artifactsSchema` when present; defaults to
+   * `Record<string, unknown>` for tools used outside a supervisor.
+   */
+  artifacts: TArtifacts; /** Same signal threaded through dispatch — for cancellation-aware tools. */
+  signal?: AbortSignal;
+};
+/**
+ * Contract that every tool must implement.
+ * Tools are callable functions exposed to the LLM during agent execution.
+ *
+ * @example
+ * import { z } from "zod"; // or any Standard Schema compatible library
+ *
+ * const searchTool: ToolConfig<{ query: string }, { results: string[] }> = {
+ *   name: "searchWeb",
+ *   description: "Search the web for current information",
+ *   input: z.object({ query: z.string() }),
+ *   execute: async ({ query }) => ({ results: ["result1", "result2"] }),
+ * };
+ */
+interface ToolConfig<TInput = unknown, TOutput = unknown> {
+  /** Unique tool name exposed to the LLM */
+  name: string;
+  /** Human-readable description of what the tool does */
+  description: string;
+  /**
+   * Dev-curated version string mirrored onto every report node this
+   * tool produces. Free-form — semver, date, hash. Bump when the
+   * tool's behavior changes in a way that matters for stored
+   * trip-archive queries (schema rev, new API endpoint, semantic
+   * change). The framework neither parses nor compares it.
+   */
+  version?: string;
+  /**
+   * Present-progressive UI string surfaced on `agent.tool.calling` /
+   * `agent.tool.called` events for streaming UX (e.g.
+   * `"Searching the catalog"`). Distinct from `description`, which
+   * the LLM reads — `action` is for humans/UI.
+   *
+   * Two forms:
+   * - **string** — static, used as-is.
+   * - **function** — receives the validated input and returns a
+   *   string, so callers can include input data
+   *   (`(input) => \`Searching for "${input.query}"\``).
+   *
+   * Resolved at the framework boundary; consumers receive a
+   * pre-resolved string in `ToolEventMeta.action`.
+   */
+  action?: string | ((input: TInput) => string);
+  /** Optional metadata for documentation or tooling */
+  meta?: ToolMeta;
+  /**
+   * Result-feedback mode. Defaults to `"feedback"` (standard
+   * round-trip behavior) when unset. See {@link ToolMode} for the
+   * full contract on `"silent"` semantics, constraints, and the
+   * mixed-mode rule.
+   */
+  mode?: ToolMode;
+  /**
+   * Standard Schema-compatible input schema.
+   * Any schema library implementing @standard-schema/spec works here
+   * (e.g. Zod, Valibot, ArkType, warlock's seal).
+   */
+  input?: StandardSchemaV1<TInput>;
+  /**
+   * Execute the tool with validated input.
+   * Called by the agent runtime after the LLM requests this tool.
+   *
+   * The optional second `ctx` parameter (Phase 5 / decisions §35)
+   * carries a `ToolContext` with a mutable `artifacts` bag for
+   * system-only side data. Tools written with the single-arg
+   * signature continue to work unchanged — the framework supplies a
+   * degraded ctx when one isn't threaded through.
+   */
+  execute(input: TInput, ctx?: ToolContext): Promise<TOutput>;
+}
+//#endregion
+export { ToolConfig, ToolContext, ToolMeta, ToolMode };
+//# sourceMappingURL=tool.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/tool.contract.ts"],"mappings":";;;;;AAQA;;;;KAAY,QAAA,GAAW,MAAM;AAoC7B;;;;AAAoB;AAmCpB;;;;;;;;;;;;;;;AASsB;AAiBtB;;;;;;;;;;;;;AA7DA,KAAY,QAAA;;;;;;;;;;;;;;;;;;;;;;;;AAmHgD;;;;;;;;;;KAhFhD,WAAA,cAAyB,MAAA;;;;;;;EAOnC,SAAA,EAAW,UAAA;EAEX,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;;;;;;UAiBM,UAAA;;EAEf,IAAA;;EAEA,WAAA;;;;;;;;EAQA,OAAA;;;;;;;;;;;;;;;;EAgBA,MAAA,cAAoB,KAAA,EAAO,MAAA;;EAE3B,IAAA,GAAO,QAAA;;;;;;;EAOP,IAAA,GAAO,QAAA;;;;;;EAMP,KAAA,GAAQ,gBAAA,CAAiB,MAAA;;;;;;;;;;;EAWzB,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA"}

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

@@ -0,0 +1,6 @@
+import { NextStepResult } from "./next-step-result.type.mjs";
+import { RetryBackoff, RetryConfig } from "./retry-config.type.mjs";
+import { WorkflowContext } from "./workflow-context.type.mjs";
+import { StepAgentInput, StepDefinition, StepLocalEvents, StepOutputSpec } from "./step.contract.mjs";
+import { WorkflowDefinition, WorkflowEventHandler, WorkflowEventHandlers, WorkflowExecuteOptions, WorkflowInstance, WorkflowResumeOptions, WorkflowRunOptions } from "./workflow.contract.mjs";
+import { WorkflowSnapshot } from "./workflow-snapshot.type.mjs";

package/esm/contracts/workflow/next-step-result.type.d.mts

@@ -0,0 +1,17 @@
+//#region ../../@warlock.js/ai/src/contracts/workflow/next-step-result.type.d.ts
+/**
+ * Return shape for `nextStep` callbacks — controls workflow routing.
+ *
+ * - `{ goto: string }` — jump to a named step
+ * - `{ end: true }` — terminate the workflow successfully
+ * - `void` / `undefined` — fall through (next declared step, or next
+ *   level of routing resolution)
+ */
+type NextStepResult = {
+  goto: string;
+} | {
+  end: true;
+} | void | undefined;
+//#endregion
+export { NextStepResult };
+//# sourceMappingURL=next-step-result.type.d.mts.map

package/esm/contracts/workflow/next-step-result.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-step-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/next-step-result.type.ts"],"mappings":";;AAQA;;;;AAES;;;KAFG,cAAA;EACN,IAAA;AAAA;EACA,GAAG;AAAA"}