@warlock.js/ai 4.4.0 → 4.6.0

package/esm/human/contracts/interrupt-store.contract.d.mts

@@ -0,0 +1,112 @@
+import { ApprovalRequest } from "./approval.type.mjs";
+
+//#region ../@warlock.js/ai/src/human/contracts/interrupt-store.contract.d.ts
+/**
+ * Lifecycle status of a persisted interrupt.
+ *
+ * `"pending"` until a decision lands; the record is marked
+ * `"resolved"` (then deleted) once `ai.human.resume(...)` applies a
+ * decision. Discriminator is `status` (a closed string union), so a
+ * caller can branch idempotently — a second resume of a `"resolved"`
+ * (or already-deleted) interrupt is a no-op, never a double-apply.
+ */
+type PendingInterruptStatus = "pending" | "resolved";
+/**
+ * A persisted, awaiting-decision interrupt — the durable counterpart of
+ * an in-flight {@link ApprovalRequest}.
+ *
+ * Mirrors the shape the snapshot/checkpoint stores persist: a flat
+ * record keyed by a single id (`interruptId`) that the store round-trips
+ * verbatim. The `request` is everything a reviewer (in another process,
+ * hours later) needs to rule on the call; `status` tracks the lifecycle;
+ * `savedAt` is the ISO-8601 write time.
+ */
+interface PendingInterrupt {
+  /** Stable id; the store keys the record on it. */
+  interruptId: string;
+  /** The pending call the human is asked to rule on. */
+  request: ApprovalRequest;
+  /** `"pending"` until a decision lands; then `"resolved"` and deleted. */
+  status: PendingInterruptStatus;
+  /** When the record was written, as an ISO-8601 timestamp. */
+  savedAt: string;
+}
+/**
+ * Durable store for {@link PendingInterrupt} records — the persistence
+ * seam behind durable human-in-the-loop approval.
+ *
+ * Deliberately shaped like the `@warlock.js/ai`
+ * `SnapshotStore` / `CheckpointStore` contracts (`load` / `save` /
+ * `delete` / optional `list` / `schema`), so a consumer already running
+ * an orchestrator can reuse the **same** `pg.Pool` / redis client for
+ * the interrupt table. Keyed by `interruptId`. Schema is never
+ * auto-migrated — {@link InterruptStore.schema} returns a DDL string the
+ * dev runs through their own migration tooling.
+ *
+ * Implementations: `ai.human.interrupt.{memory,pg,redis}()`. The memory
+ * impl ships first (pure in-process `Map`, zero deps); pg/redis lazily
+ * import their client via {@link PgClientLike} / {@link RedisClientLike}
+ * so neither driver is a hard dependency.
+ */
+interface InterruptStore {
+  /**
+   * Persist a pending interrupt, keyed by its own `interruptId`.
+   * Overwrites any prior record for the same id (a call has exactly one
+   * live interrupt).
+   */
+  save(record: PendingInterrupt): Promise<void>;
+  /**
+   * Load the interrupt for an `interruptId`, or `undefined` when none is
+   * recorded (never raised, or already resolved + deleted).
+   */
+  load(interruptId: string): Promise<PendingInterrupt | undefined>;
+  /**
+   * Drop the interrupt for an `interruptId`. Idempotent — deleting an
+   * absent id is a no-op.
+   */
+  delete(interruptId: string): Promise<void>;
+  /**
+   * List the interrupt ids the store knows, optionally filtered by a
+   * prefix. Optional — stores that can't enumerate (e.g. a key/value
+   * driver with no `SCAN`) omit it.
+   */
+  list?(prefix?: string): Promise<string[]>;
+  /**
+   * Return the DDL string for this store's backing table. The dev runs
+   * it through their migration tool; the framework never auto-migrates.
+   * Stores with no backing table (memory, redis) return an empty string
+   * so callers can treat `schema()` uniformly across drivers.
+   */
+  schema(): string;
+}
+/**
+ * Minimal `pg`-compatible client surface the Postgres
+ * {@link InterruptStore} depends on. Both `pg.Pool` and `pg.Client`
+ * satisfy it — the store only ever calls `query`.
+ *
+ * `@warlock.js/ai` takes **no** hard dependency on `pg`; the dev
+ * installs it (an optional peer) and passes the client in. Structurally
+ * identical to the orchestrator stores' `PgClientLike`, so a single pool
+ * can back the checkpoint/snapshot stores and the interrupt table alike.
+ */
+interface PgClientLike {
+  query(text: string, params?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+}
+/**
+ * Minimal `redis`-compatible client surface the Redis
+ * {@link InterruptStore} depends on.
+ *
+ * `@warlock.js/ai` takes **no** hard dependency on `redis`; the dev
+ * installs it (an optional peer) and passes the connected client in. The
+ * store only calls `get` / `set` / `del`.
+ */
+interface RedisClientLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(key: string): Promise<number>;
+}
+//#endregion
+export { InterruptStore, PendingInterrupt, PendingInterruptStatus, PgClientLike, RedisClientLike };
+//# sourceMappingURL=interrupt-store.contract.d.mts.map

package/esm/human/contracts/interrupt-store.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt-store.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/interrupt-store.contract.ts"],"mappings":";;;;;AAWA;;;;AAAkC;AAYlC;;KAZY,sBAAA;;;;;;;;;AAuBH;AAoBT;UA/BiB,gBAAA;;EAEf,WAAA;EAmCgC;EAhChC,OAAA,EAAS,eAAA;EAsCkB;EAnC3B,MAAA,EAAQ,sBAAsB;EAgDN;EA7CxB,OAAA;AAAA;;;;;;;;;;;;;;;;;AAqDM;UAjCS,cAAA;EA8CY;;;;;EAxC3B,IAAA,CAAK,MAAA,EAAQ,gBAAA,GAAmB,OAAA;EAyCS;;;AAAc;EAnCvD,IAAA,CAAK,WAAA,WAAsB,OAAA,CAAQ,gBAAA;EA8CL;;;;EAxC9B,MAAA,CAAO,WAAA,WAAsB,OAAA;EA2CJ;;;;;EApCzB,IAAA,EAAM,MAAA,YAAkB,OAAA;EAmCpB;;;;;;EA3BJ,MAAA;AAAA;AA4ByB;;;;;;;;;;AAAA,UAfV,YAAA;EACf,KAAA,CAAM,IAAA,UAAc,MAAA,eAAqB,OAAO;IAAG,IAAA;EAAA;AAAA;;;;;;;;;UAWpC,eAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA;EAClB,GAAA,CAAI,GAAA,UAAa,KAAA,aAAkB,IAAA,cAAkB,OAAA;EACrD,GAAA,CAAI,GAAA,WAAc,OAAA;AAAA"}

package/esm/human/contracts/resume.type.d.mts

@@ -0,0 +1,77 @@
+import { AgentResult } from "../../contracts/result/agent-result.type.mjs";
+import { AgentContract } from "../../contracts/agent/agent.contract.mjs";
+import { AgentExecuteOptions } from "../../contracts/agent/agent-options.type.mjs";
+import { ApprovalDecision } from "./approval.type.mjs";
+import { InterruptStore } from "./interrupt-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/human/contracts/resume.type.d.ts
+/**
+ * Options for `ai.human.resume(interruptId, decision, options)` — the
+ * out-of-process resume entry point behind durable human-in-the-loop
+ * approval.
+ *
+ * The `store` is always required: it is where the persisted
+ * {@link import("./interrupt-store.contract").PendingInterrupt} is loaded
+ * from and deleted after the decision is applied.
+ *
+ * **Two resume shapes share this one options bag:**
+ * - **apply-only** — omit `agent`. The decision is loaded, validated
+ *   against the persisted request, the pending record is deleted, and the
+ *   `{ interruptId, decision }` is returned for the caller to re-drive the
+ *   agent itself (e.g. a custom transport). No turn is re-run.
+ * - **re-run** — pass `agent` (and optionally an `input` override). v1
+ *   durable resume re-executes the agent turn with the decision
+ *   **pre-seeded**, so the gated tool call this time resolves to the
+ *   human's ruling instead of pausing again. The original prompt is
+ *   re-used unless `input` overrides it.
+ */
+interface ResumeOptions<TOutput = unknown> {
+  /**
+   * The durable store holding the {@link PendingInterrupt}. Loaded to find
+   * the original request, then deleted once the decision is applied.
+   */
+  store: InterruptStore;
+  /**
+   * The agent to re-drive with the decision pre-seeded. Omit for the
+   * apply-only shape (load + validate + delete, return the decision for a
+   * caller-owned re-drive).
+   */
+  agent?: AgentContract<TOutput>;
+  /**
+   * Prompt for the re-run. Defaults to the original prompt captured on the
+   * persisted {@link PendingInterrupt} request context; pass it to override
+   * (e.g. to append the reviewer's note). Ignored when `agent` is omitted.
+   */
+  input?: string;
+  /**
+   * Extra options forwarded to `agent.execute(input, executeOptions)` on
+   * the re-run (history, placeholders, output schema, signal, …). Ignored
+   * when `agent` is omitted.
+   */
+  executeOptions?: AgentExecuteOptions<TOutput>;
+}
+/**
+ * Outcome of `ai.human.resume(...)`.
+ *
+ * A discriminated union keyed on `type` (never `kind`):
+ * - `"applied"` — a live `"pending"` interrupt was found, the decision was
+ *   applied, and the record deleted. When the caller passed an `agent`,
+ *   `result` carries the re-run's {@link AgentResult}; otherwise the caller
+ *   re-drives the agent itself using the returned `decision`.
+ * - `"already-resolved"` — no live interrupt for this id (already resolved
+ *   + deleted, or never raised). Idempotent no-op — the decision is **not**
+ *   re-applied and no turn is re-run, mirroring the orchestrator resume's
+ *   drain idempotency.
+ */
+type ResumeResult<TOutput = unknown> = {
+  type: "applied"; /** The id of the interrupt the decision was applied to. */
+  interruptId: string; /** The decision that was applied. */
+  decision: ApprovalDecision; /** The re-run agent result, present only when an `agent` was supplied. */
+  result?: AgentResult<TOutput>;
+} | {
+  type: "already-resolved"; /** The id that had no live interrupt to resume. */
+  interruptId: string;
+};
+//#endregion
+export { ResumeOptions, ResumeResult };
+//# sourceMappingURL=resume.type.d.mts.map

package/esm/human/contracts/resume.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/resume.type.ts"],"mappings":";;;;;;;;;AA0BA;;;;;;;;;;;;;;;;;;UAAiB,aAAA;EA0BsB;;AAAO;AAgB9C;EArCE,KAAA,EAAO,cAAA;EAqCe;;;;;EA9BtB,KAAA,GAAQ,aAAA,CAAc,OAAA;EA8BC;;;;;EAvBvB,KAAA;EA+Ba;;;;;EAxBb,cAAA,GAAiB,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;;;;;KAgB3B,YAAA;EAEN,IAAA;EAEA,WAAA;EAEA,QAAA,EAAU,gBAAA;EAEV,MAAA,GAAS,WAAA,CAAY,OAAA;AAAA;EAGrB,IAAA;EAEA,WAAA;AAAA"}

package/esm/human/errors.d.mts

@@ -0,0 +1,84 @@
+import { AIError, AIErrorOptions } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/human/errors.d.ts
+/**
+ * Stable, machine-readable codes this package raises.
+ *
+ * `@warlock.js/ai`'s `AIErrorCode` is a closed union that (by design)
+ * does not enumerate satellite-package codes, and this package must not
+ * modify the core union. These codes are therefore declared locally and
+ * narrowed into the base `AIError` `code` slot at the single `super(...)`
+ * call — the runtime string is exactly what a consumer branches on via
+ * `error.code`, identical to every other `AIError`.
+ */
+type HumanErrorCode = "INTERRUPT_SUSPENDED" | "APPROVAL_REJECTED";
+/**
+ * Payload for {@link InterruptSuspendedError}. `interruptId` is the key a
+ * later `ai.human.resume(interruptId, decision)` call uses to replay the
+ * decision against the persisted interrupt.
+ */
+type InterruptSuspendedErrorOptions = AIErrorOptions & {
+  /** Id of the persisted interrupt awaiting a decision. */interruptId: string;
+};
+/**
+ * A durable approval handler suspended the run rather than denying the
+ * call.
+ *
+ * **Role.** The sentinel a durable {@link import("./contracts").ApprovalHandler}
+ * throws after persisting a
+ * {@link import("./contracts").PendingInterrupt}. The approval
+ * middleware recognizes its own sentinel (an `instanceof` check) and
+ * re-throws so the agent run unwinds; the dispatch records it as a failed
+ * tool call carrying this typed error. The caller reads
+ * `error.interruptId` off the surfaced `result.error`, surfaces it to the
+ * reviewer, and later calls `ai.human.resume(...)`.
+ *
+ * Surfaced via `result.error` like every other `AIError` — the middleware
+ * never lets it escape `execute()`.
+ *
+ * @example
+ * if (result.error instanceof InterruptSuspendedError) {
+ *   await notifyReviewer(result.error.interruptId);
+ *   return { status: "awaiting-approval", interruptId: result.error.interruptId };
+ * }
+ */
+declare class InterruptSuspendedError extends AIError {
+  /** Id of the persisted interrupt awaiting a human decision. */
+  readonly interruptId: string;
+  constructor(message: string, options: InterruptSuspendedErrorOptions);
+}
+/**
+ * Payload for {@link ApprovalRejectedError}. `reason` is the reviewer's
+ * explanation, surfaced to the model on the next trip so it can
+ * self-correct; `toolName` names the call that was rejected.
+ */
+type ApprovalRejectedErrorOptions = AIErrorOptions & {
+  /** The reviewer's explanation for rejecting the call. */reason: string; /** Name of the tool whose call was rejected. */
+  toolName: string;
+};
+/**
+ * A human rejected a gated tool call.
+ *
+ * **Role.** The typed result of an `{ type: "reject", reason }` decision.
+ * The approval middleware throws it from `tool.before`; the agent
+ * dispatch records a failed tool call and writes a `role: "tool"`
+ * message carrying `reason`, so the **next trip lets the model
+ * self-correct** — exactly the existing tool-error feedback path.
+ *
+ * Surfaced via `result.error` like every other `AIError`.
+ *
+ * @example
+ * if (result.error instanceof ApprovalRejectedError) {
+ *   logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);
+ * }
+ */
+declare class ApprovalRejectedError extends AIError {
+  /** The reviewer's explanation for rejecting the call. */
+  readonly reason: string;
+  /** Name of the tool whose call was rejected. */
+  readonly toolName: string;
+  constructor(message: string, options: ApprovalRejectedErrorOptions);
+}
+//#endregion
+export { ApprovalRejectedError, ApprovalRejectedErrorOptions, HumanErrorCode, InterruptSuspendedError, InterruptSuspendedErrorOptions };
+//# sourceMappingURL=errors.d.mts.map

package/esm/human/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/errors.ts"],"mappings":";;;;;AAaA;;;;AAA0B;AAO1B;;;KAPY,cAAA;AASC;AAyBb;;;;AAzBa,KAFD,8BAAA,GAAiC,cAAc;EA6BzC,yDA3BhB,WAAW;AAAA;;;;AA6BgE;AAa7E;;;;;;;;AAIU;AAmBV;;;;;;;;;cAxCa,uBAAA,SAAgC,OAAO;EA+Cd;EAAA,SA7CpB,WAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,8BAAA;AAAA;;;;;;KAanC,4BAAA,GAA+B,cAAc;2DAEvD,MAAA;EAEA,QAAA;AAAA;;;;;;;;;;;;;;;;;cAmBW,qBAAA,SAA8B,OAAO;;WAEhC,MAAA;;WAGA,QAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,4BAAA;AAAA"}

package/esm/human/errors.mjs

@@ -0,0 +1,60 @@
+import { AIError } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/human/errors.ts
+/**
+* A durable approval handler suspended the run rather than denying the
+* call.
+*
+* **Role.** The sentinel a durable {@link import("./contracts").ApprovalHandler}
+* throws after persisting a
+* {@link import("./contracts").PendingInterrupt}. The approval
+* middleware recognizes its own sentinel (an `instanceof` check) and
+* re-throws so the agent run unwinds; the dispatch records it as a failed
+* tool call carrying this typed error. The caller reads
+* `error.interruptId` off the surfaced `result.error`, surfaces it to the
+* reviewer, and later calls `ai.human.resume(...)`.
+*
+* Surfaced via `result.error` like every other `AIError` — the middleware
+* never lets it escape `execute()`.
+*
+* @example
+* if (result.error instanceof InterruptSuspendedError) {
+*   await notifyReviewer(result.error.interruptId);
+*   return { status: "awaiting-approval", interruptId: result.error.interruptId };
+* }
+*/
+var InterruptSuspendedError = class extends AIError {
+	constructor(message, options) {
+		super("INTERRUPT_SUSPENDED", message, options);
+		this.name = "InterruptSuspendedError";
+		this.interruptId = options.interruptId;
+	}
+};
+/**
+* A human rejected a gated tool call.
+*
+* **Role.** The typed result of an `{ type: "reject", reason }` decision.
+* The approval middleware throws it from `tool.before`; the agent
+* dispatch records a failed tool call and writes a `role: "tool"`
+* message carrying `reason`, so the **next trip lets the model
+* self-correct** — exactly the existing tool-error feedback path.
+*
+* Surfaced via `result.error` like every other `AIError`.
+*
+* @example
+* if (result.error instanceof ApprovalRejectedError) {
+*   logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);
+* }
+*/
+var ApprovalRejectedError = class extends AIError {
+	constructor(message, options) {
+		super("APPROVAL_REJECTED", message, options);
+		this.name = "ApprovalRejectedError";
+		this.reason = options.reason;
+		this.toolName = options.toolName;
+	}
+};
+
+//#endregion
+export { ApprovalRejectedError, InterruptSuspendedError };
+//# sourceMappingURL=errors.mjs.map

package/esm/human/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/errors.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"../errors/ai-error\";\nimport type { AIErrorCode } from \"../errors/error-code.type\";\n\n/**\n * Stable, machine-readable codes this package raises.\n *\n * `@warlock.js/ai`'s `AIErrorCode` is a closed union that (by design)\n * does not enumerate satellite-package codes, and this package must not\n * modify the core union. These codes are therefore declared locally and\n * narrowed into the base `AIError` `code` slot at the single `super(...)`\n * call — the runtime string is exactly what a consumer branches on via\n * `error.code`, identical to every other `AIError`.\n */\nexport type HumanErrorCode = \"INTERRUPT_SUSPENDED\" | \"APPROVAL_REJECTED\";\n\n/**\n * Payload for {@link InterruptSuspendedError}. `interruptId` is the key a\n * later `ai.human.resume(interruptId, decision)` call uses to replay the\n * decision against the persisted interrupt.\n */\nexport type InterruptSuspendedErrorOptions = AIErrorOptions & {\n  /** Id of the persisted interrupt awaiting a decision. */\n  interruptId: string;\n};\n\n/**\n * A durable approval handler suspended the run rather than denying the\n * call.\n *\n * **Role.** The sentinel a durable {@link import(\"./contracts\").ApprovalHandler}\n * throws after persisting a\n * {@link import(\"./contracts\").PendingInterrupt}. The approval\n * middleware recognizes its own sentinel (an `instanceof` check) and\n * re-throws so the agent run unwinds; the dispatch records it as a failed\n * tool call carrying this typed error. The caller reads\n * `error.interruptId` off the surfaced `result.error`, surfaces it to the\n * reviewer, and later calls `ai.human.resume(...)`.\n *\n * Surfaced via `result.error` like every other `AIError` — the middleware\n * never lets it escape `execute()`.\n *\n * @example\n * if (result.error instanceof InterruptSuspendedError) {\n *   await notifyReviewer(result.error.interruptId);\n *   return { status: \"awaiting-approval\", interruptId: result.error.interruptId };\n * }\n */\nexport class InterruptSuspendedError extends AIError {\n  /** Id of the persisted interrupt awaiting a human decision. */\n  public readonly interruptId: string;\n\n  public constructor(message: string, options: InterruptSuspendedErrorOptions) {\n    super(\"INTERRUPT_SUSPENDED\" as AIErrorCode, message, options);\n\n    this.name = \"InterruptSuspendedError\";\n    this.interruptId = options.interruptId;\n  }\n}\n\n/**\n * Payload for {@link ApprovalRejectedError}. `reason` is the reviewer's\n * explanation, surfaced to the model on the next trip so it can\n * self-correct; `toolName` names the call that was rejected.\n */\nexport type ApprovalRejectedErrorOptions = AIErrorOptions & {\n  /** The reviewer's explanation for rejecting the call. */\n  reason: string;\n  /** Name of the tool whose call was rejected. */\n  toolName: string;\n};\n\n/**\n * A human rejected a gated tool call.\n *\n * **Role.** The typed result of an `{ type: \"reject\", reason }` decision.\n * The approval middleware throws it from `tool.before`; the agent\n * dispatch records a failed tool call and writes a `role: \"tool\"`\n * message carrying `reason`, so the **next trip lets the model\n * self-correct** — exactly the existing tool-error feedback path.\n *\n * Surfaced via `result.error` like every other `AIError`.\n *\n * @example\n * if (result.error instanceof ApprovalRejectedError) {\n *   logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);\n * }\n */\nexport class ApprovalRejectedError extends AIError {\n  /** The reviewer's explanation for rejecting the call. */\n  public readonly reason: string;\n\n  /** Name of the tool whose call was rejected. */\n  public readonly toolName: string;\n\n  public constructor(message: string, options: ApprovalRejectedErrorOptions) {\n    super(\"APPROVAL_REJECTED\" as AIErrorCode, message, options);\n\n    this.name = \"ApprovalRejectedError\";\n    this.reason = options.reason;\n    this.toolName = options.toolName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,IAAa,0BAAb,cAA6C,QAAQ;CAInD,AAAO,YAAY,SAAiB,SAAyC;EAC3E,MAAM,uBAAsC,SAAS,OAAO;EAE5D,KAAK,OAAO;EACZ,KAAK,cAAc,QAAQ;CAC7B;AACF;;;;;;;;;;;;;;;;;AA8BA,IAAa,wBAAb,cAA2C,QAAQ;CAOjD,AAAO,YAAY,SAAiB,SAAuC;EACzE,MAAM,qBAAoC,SAAS,OAAO;EAE1D,KAAK,OAAO;EACZ,KAAK,SAAS,QAAQ;EACtB,KAAK,WAAW,QAAQ;CAC1B;AACF"}

package/esm/human/human-approval.d.mts

@@ -0,0 +1,57 @@
+import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
+import { HumanApprovalOptions } from "./contracts/human-approval.type.mjs";
+//#region ../@warlock.js/ai/src/human/human-approval.d.ts
+/**
+ * Human-in-the-loop approval gate for an agent's tool calls — the
+ * middleware behind `ai.human.approval(options)`.
+ *
+ * **Role.** Pauses *before a specific tool call* and routes it to a human
+ * who can **approve** (run the real tool unchanged), **reject** (the model
+ * sees a typed error and self-corrects), or **edit** (run the tool with
+ * reviewer-replaced args). The dangerous subset is chosen by an
+ * {@link import("./contracts").InterruptPolicy} (allowlist / denylist /
+ * predicate); every other call passes through untouched.
+ *
+ * **One hook.** Declares only `tool.before`. On each tool dispatch it:
+ * 1. evaluates the policy — not gated → returns `void`, the real tool runs;
+ * 2. for a gated call, builds an {@link ApprovalRequest} and calls the
+ *    {@link import("./contracts").ApprovalHandler};
+ * 3. applies the returned {@link ApprovalDecision}:
+ *    - `approve` → returns `void`, the real tool runs;
+ *    - `reject` → short-circuits a failed `ToolInvokeResult` carrying an
+ *      {@link ApprovalRejectedError} (the reviewer's `reason` reaches the
+ *      model);
+ *    - `edit` → rewrites `ctx.request.input` to the reviewer's args and
+ *      returns `void`, so the real tool runs with the edited args (schema
+ *      validation still applies — bad edits surface as a tool error).
+ *
+ * **Durable mode.** When a `store` is configured and the handler throws
+ * {@link InterruptSuspendedError} (after persisting the interrupt
+ * out-of-band), the middleware catches its **own** sentinel and
+ * short-circuits a failed result carrying it — so the caller reads
+ * `result.error.interruptId` and later calls
+ * `ai.human.resume(interruptId, decision)`. The middleware **never throws
+ * out of the pipeline**: every outcome (skip, approve, reject, edit,
+ * suspend) returns normally; only a *handler bug* (a non-sentinel throw)
+ * propagates, and even then the agent dispatch funnels it onto
+ * `result.error` — `execute()` still never throws.
+ *
+ * @param options - Policy, handler, optional durable store, optional name.
+ * @returns An {@link AgentMiddleware} declaring a single `tool.before` hook.
+ *
+ * @example
+ * const support = ai.agent({
+ *   model,
+ *   tools: [refundCustomer],
+ *   middleware: [
+ *     humanApproval({
+ *       policy: { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
+ *       handler: async (req) => ui.prompt(req), // { type: "edit", args: { amount: 5 } }
+ *     }),
+ *   ],
+ * });
+ */
+declare function humanApproval(options: HumanApprovalOptions): AgentMiddleware;
+//#endregion
+export { humanApproval };
+//# sourceMappingURL=human-approval.d.mts.map

package/esm/human/human-approval.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-approval.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/human-approval.ts"],"mappings":";;;;;;AAyKA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA7D,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}

package/esm/human/human-approval.mjs

@@ -0,0 +1,170 @@
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { ApprovalRejectedError, InterruptSuspendedError } from "./errors.mjs";
+import { evaluatePolicy } from "./policy.mjs";
+import { takeSeededDecision } from "./resume-seed.mjs";
+
+//#region ../@warlock.js/ai/src/human/human-approval.ts
+/** Default middleware name when {@link HumanApprovalOptions.name} is omitted. */
+const DEFAULT_NAME = "human-approval";
+/** Zero usage for a synthetic, no-LLM-spend short-circuit result. */
+const ZERO_USAGE = Object.freeze({
+	input: 0,
+	output: 0,
+	total: 0
+});
+/**
+* Derive the read-only {@link PolicyContext} the policy + request are
+* built from out of the wrapping {@link MiddlewareToolContext}.
+*/
+function toPolicyContext(ctx) {
+	return {
+		toolName: ctx.tool.name,
+		toolDescription: ctx.tool.description,
+		args: ctx.request.input,
+		agentName: ctx.agent.name,
+		tripIndex: ctx.tripIndex,
+		sessionId: ctx.options?.sessionId
+	};
+}
+/**
+* Generate a stable, unique id for a pending interrupt. Shaped
+* `${agentName}.${sessionId ?? "nosession"}.${tripIndex}.${random}` so a
+* reviewer can eyeball the originating run, while the trailing random
+* segment guarantees per-call uniqueness even within one trip.
+*/
+function makeInterruptId(ctx) {
+	const session = ctx.options?.sessionId ?? "nosession";
+	const random = generateRunId("interrupt");
+	return `${ctx.agent.name}.${session}.${ctx.tripIndex}.${random}`;
+}
+/**
+* Build the {@link ApprovalRequest} a human rules on, from the tool
+* context and the policy-derived tags.
+*/
+function buildRequest(ctx, interruptId, tags) {
+	return {
+		interruptId,
+		toolName: ctx.tool.name,
+		toolDescription: ctx.tool.description,
+		args: ctx.request.input,
+		context: {
+			agentName: ctx.agent.name,
+			tripIndex: ctx.tripIndex,
+			sessionId: ctx.options?.sessionId,
+			originalInput: ctx.input,
+			...tags ? { tags } : {}
+		},
+		requestedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* Synthesize a failed {@link ToolInvokeResult} carrying a typed error.
+*
+* The approval middleware returns this from `tool.before` to
+* **short-circuit** the real tool without throwing: the pipeline treats a
+* defined return as the tool's result, the agent records a failed
+* `ToolCall`, and the model sees `{ error }` on the next trip — exactly
+* the existing tool-error feedback path. Used for both `reject`
+* (`ApprovalRejectedError`) and durable suspend (`InterruptSuspendedError`).
+*/
+function failedResult(error, toolName) {
+	const runId = generateRunId("tool");
+	const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		error,
+		usage: ZERO_USAGE,
+		report: {
+			runId,
+			rootRunId: runId,
+			name: toolName,
+			type: "tool",
+			status: "failed",
+			startedAt: nowIso,
+			endedAt: nowIso,
+			duration: 0,
+			usage: ZERO_USAGE,
+			children: []
+		}
+	};
+}
+/**
+* Human-in-the-loop approval gate for an agent's tool calls — the
+* middleware behind `ai.human.approval(options)`.
+*
+* **Role.** Pauses *before a specific tool call* and routes it to a human
+* who can **approve** (run the real tool unchanged), **reject** (the model
+* sees a typed error and self-corrects), or **edit** (run the tool with
+* reviewer-replaced args). The dangerous subset is chosen by an
+* {@link import("./contracts").InterruptPolicy} (allowlist / denylist /
+* predicate); every other call passes through untouched.
+*
+* **One hook.** Declares only `tool.before`. On each tool dispatch it:
+* 1. evaluates the policy — not gated → returns `void`, the real tool runs;
+* 2. for a gated call, builds an {@link ApprovalRequest} and calls the
+*    {@link import("./contracts").ApprovalHandler};
+* 3. applies the returned {@link ApprovalDecision}:
+*    - `approve` → returns `void`, the real tool runs;
+*    - `reject` → short-circuits a failed `ToolInvokeResult` carrying an
+*      {@link ApprovalRejectedError} (the reviewer's `reason` reaches the
+*      model);
+*    - `edit` → rewrites `ctx.request.input` to the reviewer's args and
+*      returns `void`, so the real tool runs with the edited args (schema
+*      validation still applies — bad edits surface as a tool error).
+*
+* **Durable mode.** When a `store` is configured and the handler throws
+* {@link InterruptSuspendedError} (after persisting the interrupt
+* out-of-band), the middleware catches its **own** sentinel and
+* short-circuits a failed result carrying it — so the caller reads
+* `result.error.interruptId` and later calls
+* `ai.human.resume(interruptId, decision)`. The middleware **never throws
+* out of the pipeline**: every outcome (skip, approve, reject, edit,
+* suspend) returns normally; only a *handler bug* (a non-sentinel throw)
+* propagates, and even then the agent dispatch funnels it onto
+* `result.error` — `execute()` still never throws.
+*
+* @param options - Policy, handler, optional durable store, optional name.
+* @returns An {@link AgentMiddleware} declaring a single `tool.before` hook.
+*
+* @example
+* const support = ai.agent({
+*   model,
+*   tools: [refundCustomer],
+*   middleware: [
+*     humanApproval({
+*       policy: { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
+*       handler: async (req) => ui.prompt(req), // { type: "edit", args: { amount: 5 } }
+*     }),
+*   ],
+* });
+*/
+function humanApproval(options) {
+	const name = options.name ?? DEFAULT_NAME;
+	const { policy, handler } = options;
+	return {
+		name,
+		tool: { async before(ctx) {
+			const verdict = evaluatePolicy(policy, toPolicyContext(ctx));
+			if (!verdict.requiresApproval) return;
+			const request = buildRequest(ctx, makeInterruptId(ctx), verdict.tags);
+			const seeded = takeSeededDecision(ctx.agent.name);
+			let decision;
+			if (seeded !== void 0) decision = seeded;
+			else try {
+				decision = await handler(request);
+			} catch (thrown) {
+				if (thrown instanceof InterruptSuspendedError) return failedResult(thrown, ctx.tool.name);
+				throw thrown;
+			}
+			if (decision.type === "approve") return;
+			if (decision.type === "reject") return failedResult(new ApprovalRejectedError(`Tool call "${ctx.tool.name}" rejected by reviewer — ${decision.reason}`, {
+				reason: decision.reason,
+				toolName: ctx.tool.name
+			}), ctx.tool.name);
+			ctx.request.input = decision.args;
+		} }
+	};
+}
+
+//#endregion
+export { humanApproval };
+//# sourceMappingURL=human-approval.mjs.map

package/esm/human/human-approval.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-approval.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/human-approval.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../contracts/middleware/middleware.contract\";\nimport type { MiddlewareToolContext } from \"../contracts/middleware/middleware-context.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { AIError } from \"../errors/ai-error\";\nimport type { ToolInvokeResult } from \"../tool/tool\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport type {\n  ApprovalDecision,\n  ApprovalRequest,\n  HumanApprovalOptions,\n  PolicyContext,\n} from \"./contracts\";\nimport { ApprovalRejectedError, InterruptSuspendedError } from \"./errors\";\nimport { evaluatePolicy } from \"./policy\";\nimport { takeSeededDecision } from \"./resume-seed\";\n\n/** Default middleware name when {@link HumanApprovalOptions.name} is omitted. */\nconst DEFAULT_NAME = \"human-approval\";\n\n/** Zero usage for a synthetic, no-LLM-spend short-circuit result. */\nconst ZERO_USAGE: Usage = Object.freeze({ input: 0, output: 0, total: 0 });\n\n/**\n * Mutable view of {@link MiddlewareToolContext.request} used only to\n * apply an `edit` decision. The context types `request.input` as\n * `readonly`, but the agent dispatch reads `request.input` (the SAME\n * object) when it invokes the real tool *after* the `tool.before`\n * pipeline returns — so reassigning it here is how an edited-args\n * decision reaches the tool. This narrow local type makes that one\n * deliberate write explicit instead of casting away the whole context.\n */\ninterface MutableToolRequest {\n  input: unknown;\n}\n\n/**\n * Derive the read-only {@link PolicyContext} the policy + request are\n * built from out of the wrapping {@link MiddlewareToolContext}.\n */\nfunction toPolicyContext(ctx: MiddlewareToolContext): PolicyContext {\n  return {\n    toolName: ctx.tool.name,\n    toolDescription: ctx.tool.description,\n    args: ctx.request.input,\n    agentName: ctx.agent.name,\n    tripIndex: ctx.tripIndex,\n    sessionId: ctx.options?.sessionId,\n  };\n}\n\n/**\n * Generate a stable, unique id for a pending interrupt. Shaped\n * `${agentName}.${sessionId ?? \"nosession\"}.${tripIndex}.${random}` so a\n * reviewer can eyeball the originating run, while the trailing random\n * segment guarantees per-call uniqueness even within one trip.\n */\nfunction makeInterruptId(ctx: MiddlewareToolContext): string {\n  const session = ctx.options?.sessionId ?? \"nosession\";\n  const random = generateRunId(\"interrupt\");\n\n  return `${ctx.agent.name}.${session}.${ctx.tripIndex}.${random}`;\n}\n\n/**\n * Build the {@link ApprovalRequest} a human rules on, from the tool\n * context and the policy-derived tags.\n */\nfunction buildRequest(\n  ctx: MiddlewareToolContext,\n  interruptId: string,\n  tags: string[] | undefined,\n): ApprovalRequest {\n  return {\n    interruptId,\n    toolName: ctx.tool.name,\n    toolDescription: ctx.tool.description,\n    args: ctx.request.input,\n    context: {\n      agentName: ctx.agent.name,\n      tripIndex: ctx.tripIndex,\n      sessionId: ctx.options?.sessionId,\n      originalInput: ctx.input,\n      ...(tags ? { tags } : {}),\n    },\n    requestedAt: new Date().toISOString(),\n  };\n}\n\n/**\n * Synthesize a failed {@link ToolInvokeResult} carrying a typed error.\n *\n * The approval middleware returns this from `tool.before` to\n * **short-circuit** the real tool without throwing: the pipeline treats a\n * defined return as the tool's result, the agent records a failed\n * `ToolCall`, and the model sees `{ error }` on the next trip — exactly\n * the existing tool-error feedback path. Used for both `reject`\n * (`ApprovalRejectedError`) and durable suspend (`InterruptSuspendedError`).\n */\nfunction failedResult(error: AIError, toolName: string): ToolInvokeResult<unknown> {\n  const runId = generateRunId(\"tool\");\n  const nowIso = new Date().toISOString();\n\n  const report: BaseReport = {\n    runId,\n    rootRunId: runId,\n    name: toolName,\n    type: \"tool\",\n    status: \"failed\",\n    startedAt: nowIso,\n    endedAt: nowIso,\n    duration: 0,\n    usage: ZERO_USAGE,\n    children: [],\n  };\n\n  return { error, usage: ZERO_USAGE, report };\n}\n\n/**\n * Human-in-the-loop approval gate for an agent's tool calls — the\n * middleware behind `ai.human.approval(options)`.\n *\n * **Role.** Pauses *before a specific tool call* and routes it to a human\n * who can **approve** (run the real tool unchanged), **reject** (the model\n * sees a typed error and self-corrects), or **edit** (run the tool with\n * reviewer-replaced args). The dangerous subset is chosen by an\n * {@link import(\"./contracts\").InterruptPolicy} (allowlist / denylist /\n * predicate); every other call passes through untouched.\n *\n * **One hook.** Declares only `tool.before`. On each tool dispatch it:\n * 1. evaluates the policy — not gated → returns `void`, the real tool runs;\n * 2. for a gated call, builds an {@link ApprovalRequest} and calls the\n *    {@link import(\"./contracts\").ApprovalHandler};\n * 3. applies the returned {@link ApprovalDecision}:\n *    - `approve` → returns `void`, the real tool runs;\n *    - `reject` → short-circuits a failed `ToolInvokeResult` carrying an\n *      {@link ApprovalRejectedError} (the reviewer's `reason` reaches the\n *      model);\n *    - `edit` → rewrites `ctx.request.input` to the reviewer's args and\n *      returns `void`, so the real tool runs with the edited args (schema\n *      validation still applies — bad edits surface as a tool error).\n *\n * **Durable mode.** When a `store` is configured and the handler throws\n * {@link InterruptSuspendedError} (after persisting the interrupt\n * out-of-band), the middleware catches its **own** sentinel and\n * short-circuits a failed result carrying it — so the caller reads\n * `result.error.interruptId` and later calls\n * `ai.human.resume(interruptId, decision)`. The middleware **never throws\n * out of the pipeline**: every outcome (skip, approve, reject, edit,\n * suspend) returns normally; only a *handler bug* (a non-sentinel throw)\n * propagates, and even then the agent dispatch funnels it onto\n * `result.error` — `execute()` still never throws.\n *\n * @param options - Policy, handler, optional durable store, optional name.\n * @returns An {@link AgentMiddleware} declaring a single `tool.before` hook.\n *\n * @example\n * const support = ai.agent({\n *   model,\n *   tools: [refundCustomer],\n *   middleware: [\n *     humanApproval({\n *       policy: { type: \"allowlist\", tools: [\"refundCustomer\"], tags: () => [\"money\"] },\n *       handler: async (req) => ui.prompt(req), // { type: \"edit\", args: { amount: 5 } }\n *     }),\n *   ],\n * });\n */\nexport function humanApproval(options: HumanApprovalOptions): AgentMiddleware {\n  const name = options.name ?? DEFAULT_NAME;\n  const { policy, handler } = options;\n\n  return {\n    name,\n    tool: {\n      async before(\n        ctx: MiddlewareToolContext,\n      ): Promise<ToolInvokeResult<unknown> | void> {\n        const verdict = evaluatePolicy(policy, toPolicyContext(ctx));\n\n        // Not gated — let the real tool run unchanged.\n        if (!verdict.requiresApproval) {\n          return;\n        }\n\n        const interruptId = makeInterruptId(ctx);\n        const request = buildRequest(ctx, interruptId, verdict.tags);\n\n        // Durable resume: `ai.human.resume(...)` re-runs this same agent\n        // with the human's decision pre-seeded (keyed by agent name). On a\n        // hit we replay the seeded decision exactly once and skip the\n        // author's handler entirely — the gated call resolves to the\n        // ruling instead of pausing again.\n        const seeded = takeSeededDecision(ctx.agent.name);\n\n        let decision: ApprovalDecision;\n\n        if (seeded !== undefined) {\n          decision = seeded;\n        } else {\n          try {\n            decision = await handler(request);\n          } catch (thrown) {\n            // A durable handler signals suspension by throwing our OWN\n            // sentinel after persisting the interrupt. Recognize it and\n            // short-circuit a failed result carrying it — the caller reads\n            // `error.interruptId` and resumes later. Any OTHER throw is a\n            // handler bug; re-throw so the agent dispatch funnels it onto\n            // `result.error` (we never swallow a bug into silent approval).\n            if (thrown instanceof InterruptSuspendedError) {\n              return failedResult(thrown, ctx.tool.name);\n            }\n\n            throw thrown;\n          }\n        }\n\n        if (decision.type === \"approve\") {\n          // Run the real tool with the model's original args.\n          return;\n        }\n\n        if (decision.type === \"reject\") {\n          const error = new ApprovalRejectedError(\n            `Tool call \"${ctx.tool.name}\" rejected by reviewer — ${decision.reason}`,\n            { reason: decision.reason, toolName: ctx.tool.name },\n          );\n\n          return failedResult(error, ctx.tool.name);\n        }\n\n        // `edit` — rewrite the pending args, then let the real tool run.\n        // The agent dispatch reads `request.input` (this same object) when\n        // it invokes the tool after this hook returns, so the reassignment\n        // takes effect. Bad edits still fail the tool's own schema check.\n        (ctx.request as unknown as MutableToolRequest).input = decision.args;\n\n        return;\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;AAkBA,MAAM,eAAe;;AAGrB,MAAM,aAAoB,OAAO,OAAO;CAAE,OAAO;CAAG,QAAQ;CAAG,OAAO;AAAE,CAAC;;;;;AAmBzE,SAAS,gBAAgB,KAA2C;CAClE,OAAO;EACL,UAAU,IAAI,KAAK;EACnB,iBAAiB,IAAI,KAAK;EAC1B,MAAM,IAAI,QAAQ;EAClB,WAAW,IAAI,MAAM;EACrB,WAAW,IAAI;EACf,WAAW,IAAI,SAAS;CAC1B;AACF;;;;;;;AAQA,SAAS,gBAAgB,KAAoC;CAC3D,MAAM,UAAU,IAAI,SAAS,aAAa;CAC1C,MAAM,SAAS,cAAc,WAAW;CAExC,OAAO,GAAG,IAAI,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,UAAU,GAAG;AAC1D;;;;;AAMA,SAAS,aACP,KACA,aACA,MACiB;CACjB,OAAO;EACL;EACA,UAAU,IAAI,KAAK;EACnB,iBAAiB,IAAI,KAAK;EAC1B,MAAM,IAAI,QAAQ;EAClB,SAAS;GACP,WAAW,IAAI,MAAM;GACrB,WAAW,IAAI;GACf,WAAW,IAAI,SAAS;GACxB,eAAe,IAAI;GACnB,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC;EACzB;EACA,8BAAa,IAAI,KAAK,EAAC,CAAC,YAAY;CACtC;AACF;;;;;;;;;;;AAYA,SAAS,aAAa,OAAgB,UAA6C;CACjF,MAAM,QAAQ,cAAc,MAAM;CAClC,MAAM,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAetC,OAAO;EAAE;EAAO,OAAO;EAAY;GAZjC;GACA,WAAW;GACX,MAAM;GACN,MAAM;GACN,QAAQ;GACR,WAAW;GACX,SAAS;GACT,UAAU;GACV,OAAO;GACP,UAAU,CAAC;EAG2B;CAAE;AAC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,QAAQ,YAAY;CAE5B,OAAO;EACL;EACA,MAAM,EACJ,MAAM,OACJ,KAC2C;GAC3C,MAAM,UAAU,eAAe,QAAQ,gBAAgB,GAAG,CAAC;GAG3D,IAAI,CAAC,QAAQ,kBACX;GAIF,MAAM,UAAU,aAAa,KADT,gBAAgB,GACQ,GAAG,QAAQ,IAAI;GAO3D,MAAM,SAAS,mBAAmB,IAAI,MAAM,IAAI;GAEhD,IAAI;GAEJ,IAAI,WAAW,QACb,WAAW;QAEX,IAAI;IACF,WAAW,MAAM,QAAQ,OAAO;GAClC,SAAS,QAAQ;IAOf,IAAI,kBAAkB,yBACpB,OAAO,aAAa,QAAQ,IAAI,KAAK,IAAI;IAG3C,MAAM;GACR;GAGF,IAAI,SAAS,SAAS,WAEpB;GAGF,IAAI,SAAS,SAAS,UAMpB,OAAO,aAAa,IALF,sBAChB,cAAc,IAAI,KAAK,KAAK,2BAA2B,SAAS,UAChE;IAAE,QAAQ,SAAS;IAAQ,UAAU,IAAI,KAAK;GAAK,CAG7B,GAAG,IAAI,KAAK,IAAI;GAO1C,AAAC,IAAI,QAA0C,QAAQ,SAAS;EAGlE,EACF;CACF;AACF"}