stitchkit 0.94.0 → 0.95.0

package/dist/contract/runtime-context.d.ts

@@ -0,0 +1,131 @@
+import type { TransportSource } from './define.js';
+/**
+ * Shallow-merge a contract-wide `meta` default with an endpoint's own — endpoint
+ * keys win. Returns `undefined` when neither side declares anything, because
+ * readers test `method.meta?.x` and an empty object would read as "declared".
+ * One level deep by design: a deep merge invites "how do I unset an inherited
+ * key", which has no answer without a sentinel. → ADR 0036.
+ */
+export declare function mergeMeta(contractMeta: Record<string, unknown> | undefined, endpointMeta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/** Self-reported MCP host identity. Attribution only — never an auth principal. */
+export interface McpClientInfo {
+    name: string;
+    version: string;
+}
+/** Outcome of one opt-in MCP multi-round input attempt. */
+export type McpRoundOutcome = 'input_required' | 'declined' | 'cancelled' | 'invalid' | 'complete';
+/**
+ * Validated metadata for the active managed MCP tool call.
+ *
+ * `clientInfo` is supplied by the MCP host. It is useful for display and
+ * operational attribution, but MUST NOT be used for authentication,
+ * authorization, tenant selection or rate limiting.
+ */
+export interface McpCallContext {
+    era: 'modern' | 'legacy';
+    method: string;
+    toolName: string;
+    protocolVersion?: string;
+    clientInfo?: McpClientInfo;
+    outcome?: McpRoundOutcome;
+    round?: number;
+    /**
+     * The host's progress token for this call, when it asked for progress.
+     *
+     * Declarative, like everything else on this type: it says the host is
+     * listening. Reporting is `ctx.reportProgress`, which is a function and
+     * therefore deliberately NOT here — this type is also the type of
+     * `RequestEvent.mcp`, and an audit row's shape must not claim to carry
+     * behaviour.
+     */
+    progressToken?: string | number;
+}
+/**
+ * One progress update a tool handler sends to the host mid-call.
+ *
+ * `progress` is a number the protocol requires. It is optional here because a
+ * handler often has a stage to name and no scale to name it on — "uploading",
+ * "rendering frame 12" — and the honest answer to "how far along" is then the
+ * ordinal of the update itself, which is what gets sent. That is a fact about
+ * what happened, not a percentage nobody measured; `total` stays absent, so a
+ * host renders it as an unbounded counter rather than a bar at 3%.
+ */
+export interface McpProgressUpdate {
+    /** Human-facing stage, shown by the host while the call is still running. */
+    message?: string;
+    /** How far along, on whatever scale `total` implies. */
+    progress?: number;
+    /** The scale, when the operation knows it. */
+    total?: number;
+}
+/**
+ * Send one progress update for the call in flight.
+ *
+ * Present on every tool call and a no-op unless the host asked for progress by
+ * sending a token, so a handler never branches on transport. It never throws
+ * and never rejects: a message about work must not be able to kill the work it
+ * describes. Fire-and-forget — the returned promise settles when the
+ * notification has been handed to the transport, and ignoring it is correct.
+ */
+export type McpReportProgress = (update: McpProgressUpdate) => Promise<void>;
+export interface RuntimeContext {
+    params: unknown;
+    input: unknown;
+    files?: Record<string, unknown>;
+    /** Original decoded JSON request text when the endpoint declares `rawBody: true`. */
+    rawBody?: string;
+    source: TransportSource;
+    /**
+     * The raw Web `Request`, its parsed `URL` and `Headers` — set on the HTTP
+     * transport (and reachable in every lifecycle hook, including `onError` on a
+     * validation failure). Absent on the non-HTTP transports (MCP / agent / CLI /
+     * a bring-your-own lane), which carry no `Request`, so they are optional and a
+     * reader narrows them. Web Fetch types only — the core stays Fetch-clean
+     * (→ ADR 0013).
+     */
+    req?: Request;
+    url?: URL;
+    headers?: Headers;
+    traceId?: string;
+    spanId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    /** Transport cancellation for the active call (MCP and future cancellable lanes). */
+    signal?: AbortSignal;
+    /** Validated metadata for an MCP call; absent on every other transport. */
+    mcp?: McpCallContext;
+    /**
+     * Report progress on the call in flight.
+     *
+     * Present on every TOOL call — MCP, agent and CLI — and a no-op wherever
+     * nobody is listening, so a handler never branches on transport to say what
+     * it is doing. Absent on the HTTP transport, which has no channel for it;
+     * that is why the field is optional and a handler that also serves HTTP
+     * writes `ctx.reportProgress?.(…)`.
+     */
+    reportProgress?: McpReportProgress;
+    [key: string]: unknown;
+}
+export interface HandlerContext<TParams = undefined, TInput = undefined> {
+    params: TParams;
+    input: TInput;
+    files?: Record<string, unknown>;
+    /** Original decoded JSON request text when the endpoint declares `rawBody: true`. */
+    rawBody?: string;
+    source: TransportSource;
+    /** Raw Web `Request` / `URL` / `Headers` — set on the HTTP transport, absent
+     *  on the tool transports (see {@link RuntimeContext}). */
+    req?: Request;
+    url?: URL;
+    headers?: Headers;
+    traceId?: string;
+    spanId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    /** Validated metadata for an MCP call; absent on every other transport. */
+    mcp?: McpCallContext;
+    /** Report progress on the call in flight — a no-op when none was asked for. */
+    reportProgress?: McpReportProgress;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=runtime-context.d.ts.map

package/dist/contract/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../../src/contract/runtime-context.ts"],"names":[],"mappings":"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"}

package/dist/contract/tool-options.d.ts

@@ -0,0 +1,105 @@
+/**
+ * What an endpoint may declare for its tool surfaces: the UI resource, the annotations, and the MCP input rounds with their resolver.
+ */
+import type { z } from 'zod';
+import type { DeclaredToolView } from './tool-view.js';
+/**
+ * MCP Apps UI metadata for a tool (SEP-1865). When set, the tool's MCP
+ * registration carries `_meta.ui`, so a host renders the named `ui://` resource
+ * as an interactive widget for this tool's results. The resource itself is
+ * served separately (see `McpServerBuildConfig.resources`).
+ */
+export interface EndpointUiMeta {
+    /** `ui://…` resource the host renders for this tool's results. */
+    resourceUri: string;
+    /** Who sees the tool — `'model'` (in the tool list) and/or `'app'` (widget-only). */
+    visibility?: readonly ('model' | 'app')[];
+}
+/**
+ * MCP `ToolAnnotations` — behavioural hints a host reads to group tools and pick
+ * permission defaults (read-only auto-allow, destructive needs approval) and to
+ * show a human label. Hints only — never a security boundary.
+ */
+export interface EndpointToolAnnotations {
+    /** Human-friendly display name (e.g. "Explore Models" instead of `list_models`). */
+    title?: string;
+    /** Tool does not mutate state — hosts may auto-allow and group as read-only. */
+    readOnlyHint?: boolean;
+    /** Tool may perform destructive updates (ignored when `readOnlyHint` is true). */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same args have no additional effect. */
+    idempotentHint?: boolean;
+    /** Tool interacts with an open/external world (not a closed set). */
+    openWorldHint?: boolean;
+}
+/** One typed form elicitation required before an MCP tool handler may execute. */
+export interface EndpointMcpInputRequired<TKey extends string = string, TSchema extends z.ZodObject = z.ZodObject> {
+    /** Stable response key carried across MRTR rounds. */
+    key: TKey;
+    /** Human-facing prompt shown by the MCP host. */
+    message: string;
+    /** Flat primitive object schema accepted from the host. */
+    schema: TSchema;
+}
+/**
+ * What the tool call looks like when the questions are chosen — the same
+ * `params` / `input` the handler would receive, parsed by the contract's own
+ * schemas.
+ */
+export interface McpInputRequiredCall {
+    params: unknown;
+    input: unknown;
+}
+/**
+ * Choose this call's elicitation rounds from its arguments.
+ *
+ * The static list is declared before any call exists, which is enough when the
+ * questions are a property of the operation. It is not enough when they are a
+ * property of the ARGUMENTS — one model takes `aspect_ratio`, another takes
+ * `duration`, a third needs an input image — and there the declared list can
+ * only be empty, so the tool description ends up teaching the model to work
+ * around a mechanism the protocol already has.
+ *
+ * Returning an empty list is a legitimate answer: this call needs nothing, run
+ * it. Everything else about the mechanism is unchanged — the state is still
+ * signed, still bound to the principal, the operation and the argument digest,
+ * and still counted against `maxRounds`.
+ *
+ * The resolved list is fingerprinted into the signed state and re-checked on
+ * every round, so a resolver that answers differently mid-conversation is
+ * refused rather than silently asking round 2's question under round 1's key.
+ */
+export type McpInputRequiredResolver<TRequests extends readonly EndpointMcpInputRequired[] = readonly EndpointMcpInputRequired[]> = (call: McpInputRequiredCall) => TRequests | Promise<TRequests>;
+/** MCP-only execution policy attached to a contract or runtime tool. */
+export interface EndpointMcpPolicy<TRequests extends readonly EndpointMcpInputRequired[] = readonly EndpointMcpInputRequired[]> {
+    /**
+     * Ordered elicitation rounds — a fixed list, or a function of the parsed
+     * arguments. Every key must be unique, in either form.
+     */
+    inputRequired: TRequests | McpInputRequiredResolver<TRequests>;
+}
+/**
+ * Everything a tool surface — MCP, AGENT, CLI — reads from an endpoint that
+ * HTTP does not: the name a model calls, the view it is answered with, the MCP
+ * widget, host hints and elicitation rounds. One group, so an endpoint that can
+ * never be a tool refuses all of it with one key, and a new tool option is
+ * added in one place. `expose` is not in it: it chooses transports, HTTP
+ * included. → ADR 0196.
+ */
+export interface EndpointToolOptions {
+    /** The tool name on MCP / AGENT / CLI; unique per transport within a contract. */
+    name?: string;
+    /**
+     * The answer on the tool surface when it is not the HTTP answer: input
+     * defaults, a narrower output, a projection. Declared only by `withToolView`,
+     * which types `project` against the endpoint's schemas.
+     */
+    view?: DeclaredToolView;
+    /** MCP Apps widget for this tool's results (MCP transport only). */
+    ui?: EndpointUiMeta;
+    /** MCP behavioural hints (read-only / destructive / title) for hosts. */
+    annotations?: EndpointToolAnnotations;
+    /** Opt-in multi-round input gate; ignored by HTTP, Agent and CLI. */
+    mcp?: EndpointMcpPolicy;
+}
+//# sourceMappingURL=tool-options.d.ts.map

package/dist/contract/tool-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-options.d.ts","sourceRoot":"","sources":["../../src/contract/tool-options.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kFAAkF;IAClF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,kFAAkF;AAClF,MAAM,WAAW,wBAAwB,CACvC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS;IAEzC,sDAAsD;IACtD,GAAG,EAAE,IAAI,CAAC;IACV,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,wBAAwB,CAClC,SAAS,SAAS,SAAS,wBAAwB,EAAE,GAAG,SAAS,wBAAwB,EAAE,IACzF,CAAC,IAAI,EAAE,oBAAoB,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEnE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB,CAChC,SAAS,SAAS,SAAS,wBAAwB,EAAE,GAAG,SAAS,wBAAwB,EAAE;IAE3F;;;OAGG;IACH,aAAa,EAAE,SAAS,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC;CAChE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,oEAAoE;IACpE,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,qEAAqE;IACrE,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB"}

package/dist/contract/tool-view.d.ts

@@ -77,6 +77,16 @@ export interface SlicedToolView<E, V extends ZodType> {
     output: V;
     project?: undefined;
 }
+/**
+ * A tool view that changes only what a tool call is given: the answer is the
+ * endpoint's full `output`, exactly as HTTP answers. The most common view — a
+ * model needs a lighter call, not a different answer.
+ */
+export interface DefaultsOnlyToolView<E> {
+    defaults: EndpointInputDefaults<E>;
+    output?: undefined;
+    project?: undefined;
+}
 /** The type error a slice produces when the full result does not fit its schema. */
 export interface ToolViewSliceMismatch {
     'toolView.output must accept the full output — add a project, or narrow the schema': never;
@@ -118,9 +128,12 @@ export type WithToolView<E> = Omit<E, 'tool'> & {
  * ```
  *
  * A view without `project` slices the full result by `output`; the full
- * result must then fit that schema, which the return type checks. The view
- * lands in `tool.view`, beside the endpoint's other tool options.
+ * result must then fit that schema, which the return type checks. A view of
+ * `defaults` alone changes only the tool call's input — the answer is the full
+ * `output`, as on HTTP. The view lands in `tool.view`, beside the endpoint's
+ * other tool options.
  */
+export declare function withToolView<const E extends ToolViewEndpoint>(endpoint: E & ToolTransportEndpoint<E>, view: DefaultsOnlyToolView<E>): WithToolView<E>;
 export declare function withToolView<const E extends ToolViewEndpoint, V extends ZodType>(endpoint: E & ToolTransportEndpoint<E>, view: ProjectedToolView<E, V>): WithToolView<E>;
 export declare function withToolView<const E extends ToolViewEndpoint>(endpoint: E & ToolTransportEndpoint<E>, view: ReshapedToolView<E>): WithToolView<E>;
 export declare function withToolView<const E extends ToolViewEndpoint, V extends ZodType>(endpoint: E & ToolTransportEndpoint<E>, view: SlicedToolView<E, V>): [EndpointFullOutput<E>] extends [z.input<V>] ? WithToolView<E> : ToolViewSliceMismatch;

package/dist/contract/tool-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/contract/tool-view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/contract/tool-view.ts"],"names":[],"mappings":"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"}

package/dist/durability/contract.d.ts

@@ -22,6 +22,8 @@ export declare const DURABILITY_STEP_EVENT_KIND = "durability/step";
 export declare const DURABILITY_PARK_EVENT_KIND = "durability/park";
 /** Event kind recording an external event delivered to a parked wait. */
 export declare const DURABILITY_EVENT_EVENT_KIND = "durability/event";
+/** Event kind recording one phase of an at-most-once effect: intent, accepted or uncertain. */
+export declare const DURABILITY_EFFECT_EVENT_KIND = "durability/effect";
 export declare const StepEventPayloadSchema: z.ZodObject<{
     runId: z.ZodString;
     stepName: z.ZodString;
@@ -44,6 +46,25 @@ export declare const DeliveredEventPayloadSchema: z.ZodObject<{
     id: z.ZodString;
     encoded: z.ZodString;
 }, z.core.$strip>;
+export declare const EffectEventPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    runId: z.ZodString;
+    effectName: z.ZodString;
+    phase: z.ZodLiteral<"intent">;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    effectName: z.ZodString;
+    phase: z.ZodLiteral<"accepted">;
+    encoded: z.ZodString;
+    via: z.ZodEnum<{
+        reconcile: "reconcile";
+        run: "run";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    effectName: z.ZodString;
+    phase: z.ZodLiteral<"uncertain">;
+}, z.core.$strip>], "phase">;
+export type EffectEventPayload = z.infer<typeof EffectEventPayloadSchema>;
 export type ParkEventPayload = z.infer<typeof ParkEventPayloadSchema>;
 export type StepEventPayload = z.infer<typeof StepEventPayloadSchema>;
 /**
@@ -83,6 +104,37 @@ export interface StepRunOptions {
     /** Aborting refuses to *start* a body and releases a park; it never removes a record already written. */
     signal?: AbortSignal;
 }
+/**
+ * What an effect ended as. `uncertain` is a third answer, not a failure to
+ * produce one: the effect may have happened, the recipient has no record of it,
+ * and nothing here will try it again.
+ */
+export type EffectOutcome<P> = {
+    readonly outcome: 'accepted';
+    readonly proof: P;
+} | {
+    readonly outcome: 'uncertain';
+};
+/** The two halves of an effect in another system. */
+export interface EffectHandlers<P> {
+    /**
+     * Perform the effect, once, and return what the recipient named it — a
+     * message id, a turn id. Called at most once per name, across every process
+     * that shares the ledger.
+     */
+    run(): P | Promise<P>;
+    /**
+     * Find the effect at the recipient by the caller's own identity for it, and
+     * return the same proof — or `null` when the recipient has no record. Called
+     * only when an intent was recorded and no outcome was: the process that ran
+     * the effect stopped before it could say how it ended.
+     */
+    reconcile(signal: AbortSignal): P | null | Promise<P | null>;
+}
+export interface EffectRunOptions extends StepRunOptions {
+    /** How long `reconcile` may take, in milliseconds; its `signal` aborts at the deadline. Default 30 000. */
+    reconcileTimeoutMs?: number;
+}
 export interface LocalStepDurability {
     /**
      * Run `name` once and durably record its JSON result.
@@ -131,6 +183,22 @@ export interface LocalStepDurability {
         id: string;
         payload?: unknown;
     }): Promise<void>;
+    /**
+     * Perform an effect in another system at most once.
+     *
+     * `step` records its result AFTER the body, so a body cut short by a crash
+     * runs again — right for a computation, wrong for sending a message, where a
+     * repeat is worse than a loss. Here the intent is recorded BEFORE `run`, and
+     * its outcome after. A later call that finds the intent without an outcome
+     * calls `reconcile`, never `run`: found is `accepted` with the proof, not
+     * found is `uncertain`, and both are recorded, so neither is asked again.
+     *
+     * A `run` that throws leaves the intent standing — whether the effect
+     * happened is exactly what is not known — and the call rejects with
+     * `EffectUnresolvedError`; the next call reconciles. The proof is JSON of at
+     * most 64 KiB: an identity, not a payload.
+     */
+    effect<P extends z.infer<ReturnType<typeof z.json>>>(name: string, handlers: EffectHandlers<P>, options?: EffectRunOptions): Promise<EffectOutcome<P>>;
 }
 /**
  * The record for `name` cannot be trusted.
@@ -152,6 +220,21 @@ export declare class StepResultNotSerializableError extends Error {
 export declare class StepAbortedError extends Error {
     constructor(stepName: string);
 }
+/**
+ * An effect whose outcome could not be settled by this call.
+ *
+ * Its intent is recorded and stays recorded, so `run` is never called for this
+ * name again; the next call reconciles instead. `reason` says which step did
+ * not finish: `run` threw, `reconcile` threw or overran its deadline, or the
+ * proof could not be recorded.
+ */
+export declare class EffectUnresolvedError extends Error {
+    readonly effectName: string;
+    readonly reason: 'run-failed' | 'reconcile-failed' | 'reconcile-timeout' | 'proof-rejected';
+    constructor(effectName: string, reason: 'run-failed' | 'reconcile-failed' | 'reconcile-timeout' | 'proof-rejected', options?: {
+        cause?: unknown;
+    });
+}
 /**
  * A park or delivered-event record cannot be trusted.
  *

package/dist/durability/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/durability/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/durability/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC5E,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACvE;AAED,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAE9D,+FAA+F;AAC/F,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAEhE,eAAO,MAAM,sBAAsB;;;;iBAKjC,CAAC;AAiBH,eAAO,MAAM,sBAAsB;;;;;;;;;;2BAGjC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;iBAMtC,CAAC;AAIH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;4BAWnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,IAAI,MAAM,CAAC;IACd,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACzC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QACN,GAAG,IAAI,MAAM,CAAC;QACd,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG;YAAE,MAAM,IAAI,IAAI,CAAA;SAAE,CAAC;KACrE,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,yGAAyG;IACzG,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEtC,qDAAqD;AACrD,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;OAIG;IACH,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,2GAA2G;IAC3G,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,EAC/C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,8EAA8E;IAC9E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC7D,4CAA4C;IAC5C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EACjB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EACpC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,EACjD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED,uEAAuE;AACvE,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,YAAY,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAK3C;CACF;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,QAAQ,EAAE,MAAM,EAG3B;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,MAAM,EACX,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB;IANtB,YACW,UAAU,EAAE,MAAM,EAClB,MAAM,EACX,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAI9B;CACF;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,IAAI,EAAE,MAAM,EAGvB;CACF"}

package/dist/durability/effect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * An effect in another system, performed at most once.
+ *
+ * The rule a consumer had written by hand seven times, and one copy of which
+ * had drifted: record the intent BEFORE the effect; record what the recipient
+ * named it after; an intent found without an outcome is settled only by the
+ * recipient's own record — found is `accepted`, not found is `uncertain` — and
+ * `uncertain` is never retried. The copy that drifted wrote nothing before a
+ * permission reply, so a lost acknowledgement sent the reply twice.
+ */
+import type { z } from 'zod';
+import { type EffectHandlers, type EffectOutcome, type EffectRunOptions, type StepDurabilityLedger } from './contract.js';
+import { type DurabilityLedgerView } from './ledger.js';
+export interface EffectLedgerContext {
+    readonly store: StepDurabilityLedger;
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly signal: AbortSignal | undefined;
+    readLedger(): Promise<DurabilityLedgerView>;
+}
+type Proof = z.infer<ReturnType<typeof z.json>>;
+export declare function executeEffect<P extends Proof>(context: EffectLedgerContext, name: string, handlers: EffectHandlers<P>, options: EffectRunOptions | undefined): Promise<EffectOutcome<P>>;
+export {};
+//# sourceMappingURL=effect.d.ts.map

package/dist/durability/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../src/durability/effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,oBAAoB,EAA+B,MAAM,UAAU,CAAC;AAMlF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,UAAU,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7C;AAED,KAAK,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAkFhD,wBAAsB,aAAa,CAAC,CAAC,SAAS,KAAK,EACjD,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,gBAAgB,GAAG,SAAS,GACpC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA0B3B"}

package/dist/durability/engine.d.ts

@@ -1,6 +1,6 @@
 import { type LocalStepDurability, type LocalStepDurabilityOptions } from './contract.js';
-export type { LocalStepDurability, LocalStepDurabilityOptions, StepDurabilityLedger, StepRunOptions, } from './contract.js';
-export { DURABILITY_STEP_EVENT_KIND, ParkAbortedError, ParkRecordDecodeError, StepAbortedError, StepResultDecodeError, StepResultNotSerializableError, } from './contract.js';
+export type { EffectHandlers, EffectOutcome, EffectRunOptions, LocalStepDurability, LocalStepDurabilityOptions, StepDurabilityLedger, StepRunOptions, } from './contract.js';
+export { DURABILITY_STEP_EVENT_KIND, EffectUnresolvedError, ParkAbortedError, ParkRecordDecodeError, StepAbortedError, StepResultDecodeError, StepResultNotSerializableError, } from './contract.js';
 /**
  * A local step-durability port over an `AgentRuntimeStore`.
  *

package/dist/durability/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/durability/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAKhC,MAAM,YAAY,CAAC;AAkBpB,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AAmBpB;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAqNrB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/durability/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAGhC,MAAM,YAAY,CAAC;AAepB,YAAY,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AAmBpB;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAsLrB"}

package/dist/durability/events.d.ts

@@ -14,6 +14,7 @@ export declare const AgentStoreEventKindSchema: z.ZodEnum<{
     "approval/response-rejected": "approval/response-rejected";
     "child/spawned": "child/spawned";
     "child/state": "child/state";
+    "durability/effect": "durability/effect";
     "durability/event": "durability/event";
     "durability/park": "durability/park";
     "durability/step": "durability/step";
@@ -52,6 +53,7 @@ export declare const AppendAgentStoreEventSchema: z.ZodObject<{
         "approval/response-rejected": "approval/response-rejected";
         "child/spawned": "child/spawned";
         "child/state": "child/state";
+        "durability/effect": "durability/effect";
         "durability/event": "durability/event";
         "durability/park": "durability/park";
         "durability/step": "durability/step";

package/dist/durability/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/durability/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,6BAA6B;;;;;;;;;kBAW/B,CAAC;AAEZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQ7B,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,0BAA0B;;;;;kBAYpC,CAAC;AAEJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;kBAK3B,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/durability/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;EAwBpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,6BAA6B;;;;;;;;;kBAW/B,CAAC;AAEZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQ7B,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,0BAA0B;;;;;kBAYpC,CAAC;AAEJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;kBAK3B,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/durability/ledger.d.ts

@@ -1,12 +1,23 @@
 import { type ParkEventPayload, type StepDurabilityLedger } from './contract.js';
 export declare function stepKey(conversationId: string, runId: string, stepName: string): string;
+export declare function effectKey(conversationId: string, runId: string, effectName: string): string;
 export declare function sleepParkKey(conversationId: string, runId: string, name: string): string;
 export declare function waitParkKey(conversationId: string, runId: string, event: string, id: string): string;
 export declare function parkEventKey(conversationId: string, payload: ParkEventPayload): string;
 export declare function encodeStepResult(stepName: string, value: unknown): string;
 export declare function encodeDeliveredPayload(event: string, id: string, payload: unknown): string;
+/** What the ledger says about one effect: an intent, and at most one outcome. */
+export type EffectRecord = {
+    readonly outcome: undefined;
+} | {
+    readonly outcome: 'accepted';
+    readonly proof: unknown;
+} | {
+    readonly outcome: 'uncertain';
+};
 export interface DurabilityLedgerView {
     readonly steps: Map<string, unknown>;
+    readonly effects: Map<string, EffectRecord>;
     readonly parks: Map<string, ParkEventPayload>;
     readonly deliveries: Map<string, unknown>;
     nextSeq: number;

package/dist/durability/ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/durability/ledger.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EAK1B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExF;AAED,wBAAgB,WAAW,CACzB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,MAAM,CAER;AAED,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAItF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAWzE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAa1F;AAmED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAsC/B"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/durability/ledger.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EAK1B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,wBAAgB,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExF;AAED,wBAAgB,WAAW,CACzB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,MAAM,CAER;AAED,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAItF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAWzE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAa1F;AAmED,iFAAiF;AACjF,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AA4BtC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}

package/dist/durability/parks.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The two parks — a durable sleep and a wait for a delivered event — as
+ * functions over one engine's context. A park is recorded before it waits, so a
+ * reconstruction resumes from the record instead of parking again.
+ */
+import { type DurabilityClock, type StepDurabilityLedger, type StepRunOptions } from './contract.js';
+import { type DurabilityLedgerView } from './ledger.js';
+import { type InFlightDurability } from './scheduler.js';
+/** What a park needs from the engine that owns it. */
+export interface ParkContext {
+    readonly store: StepDurabilityLedger;
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly signal: AbortSignal | undefined;
+    readonly subscribe: ((wake: () => void) => () => void) | undefined;
+    readonly clock: DurabilityClock;
+    readonly waiters: InFlightDurability['waiters'];
+    readLedger(): Promise<DurabilityLedgerView>;
+}
+export declare function executeSleep(park: ParkContext, name: string, seconds: number, runOptions: StepRunOptions | undefined): Promise<void>;
+export declare function executeWait<T>(park: ParkContext, eventName: string, id: string, runOptions: StepRunOptions | undefined): Promise<T>;
+//# sourceMappingURL=parks.d.ts.map

package/dist/durability/parks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parks.d.ts","sourceRoot":"","sources":["../../src/durability/parks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,eAAe,EAGpB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,oBAAoB,EAA6B,MAAM,UAAU,CAAC;AAChF,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,aAAa,CAAC;AAErB,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,UAAU,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7C;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,cAAc,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,cAAc,GAAG,SAAS,GACrC,OAAO,CAAC,CAAC,CAAC,CAmCZ"}

package/dist/durability/scheduler.d.ts

@@ -12,6 +12,7 @@ export declare const systemClock: DurabilityClock;
  */
 export interface InFlightDurability {
     steps: Map<string, Promise<unknown>>;
+    effects: Map<string, Promise<unknown>>;
     parks: Map<string, Promise<unknown>>;
     waiters: Map<string, Set<() => void>>;
 }

package/dist/durability/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/durability/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC/F,eAAO,MAAM,WAAW,EAAE,eAOzB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;CACvC;AACD,eAAO,MAAM,MAAM,mDAA0D,CAAC;AAE9E,wBAAgB,aAAa,CAAC,WAAW,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3F;AA2BD,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,UAAU,UAAU;IAClB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C,wDAAwD;IACxD,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAC1C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,UAAU,CA2BZ"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/durability/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC/F,eAAO,MAAM,WAAW,EAAE,eAOzB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;CACvC;AACD,eAAO,MAAM,MAAM,mDAA0D,CAAC;AAE9E,wBAAgB,aAAa,CAAC,WAAW,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3F;AA2BD,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,UAAU,UAAU;IAClB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C,wDAAwD;IACxD,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAC1C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,UAAU,CA2BZ"}

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -3,11 +3,11 @@ import {
   AgentCodingToolLimitsSchema,
   AgentCodingToolPathAuthorizationSchema,
   createAgentCodingTools
-} from "../../index-kj2wbeta.js";
-import"../../index-bn2cjajt.js";
+} from "../../index-het2he5g.js";
+import"../../index-px2gm2jp.js";
 import"../../index-qmy6zq75.js";
-import"../../index-v38qyerb.js";
-import"../../index-dydjcp8z.js";
+import"../../index-xw3s75nj.js";
+import"../../index-np4m8hd3.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";