stitchkit 0.93.0 → 0.94.1

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

@@ -0,0 +1,148 @@
+import { type ZodType, z } from 'zod';
+import type { EndpointDef, ToolEndpointDef, TransportSource } from './define.js';
+/** What a tool view's `project` is told about the call besides the full result. */
+export interface ToolViewCall<TInput = unknown> {
+    /** The parsed input — the value the handler received, tool defaults applied. */
+    input: TInput;
+    /** Which tool transport the call entered on. */
+    source: TransportSource;
+}
+/**
+ * How an endpoint answers on the tool surface — MCP, AGENT and CLI — when that
+ * answer is not its HTTP answer. HTTP, OpenAPI and the typed client keep the
+ * full `input` / `output`; the handler stays one function that never learns
+ * which surface called it. → ADR 0196.
+ *
+ * Declare it with {@link withToolView}: this runtime shape is deliberately
+ * loose, and only the helper types `project` against the endpoint's schemas.
+ */
+export interface EndpointToolView {
+    /**
+     * Input values a tool call gets when it does not pass the key — applied
+     * before the one parse by the endpoint's own `input`, so a model that asks
+     * for nothing is not handed the full record's cost. Keys must be keys of
+     * `input`, and never path params.
+     */
+    defaults?: Readonly<Record<string, unknown>>;
+    /**
+     * The schema of the tool answer. Without `project` the full result is sliced
+     * by it; with `project` the projection is validated against it. Omitted, the
+     * tool answer keeps the full `output` schema and `project` is required.
+     */
+    output?: ZodType<unknown>;
+    /**
+     * A pure, synchronous full → tool-answer function. It adds nothing the full
+     * result does not carry: data the tool needs belongs in the full answer.
+     */
+    project?: (full: never, call: ToolViewCall<never>) => unknown;
+}
+/**
+ * Marks a view as declared by {@link withToolView}. A view written as a bare
+ * object would type `project` against nothing and let a slice that cannot hold
+ * the full answer through; the mark makes the helper the one way to declare it.
+ */
+export declare const DECLARED_TOOL_VIEW: unique symbol;
+/** A tool view as `withToolView` produces it — the only form `tool.view` accepts. */
+export interface DeclaredToolView extends EndpointToolView {
+    readonly [DECLARED_TOOL_VIEW]: true;
+}
+type EndpointInputOutput<E> = E extends {
+    input: infer I extends ZodType;
+} ? z.output<I> : undefined;
+type EndpointInputDefaults<E> = E extends {
+    input: infer I extends ZodType;
+} ? Partial<z.input<I>> : never;
+type EndpointFullOutput<E> = E extends {
+    output: infer O extends ZodType;
+} ? z.output<O> : never;
+type EndpointFullOutputInput<E> = E extends {
+    output: infer O extends ZodType;
+} ? z.input<O> : never;
+type ToolViewProject<E, TResult> = (full: EndpointFullOutput<E>, call: ToolViewCall<EndpointInputOutput<E>>) => TResult;
+/** A tool view whose answer has its own schema, reached by `project`. */
+export interface ProjectedToolView<E, V extends ZodType> {
+    defaults?: EndpointInputDefaults<E>;
+    output: V;
+    project: ToolViewProject<E, z.input<V>>;
+}
+/** A tool view that keeps the full schema and reshapes values within it. */
+export interface ReshapedToolView<E> {
+    defaults?: EndpointInputDefaults<E>;
+    output?: undefined;
+    project: ToolViewProject<E, EndpointFullOutputInput<E>>;
+}
+/** A tool view that slices the full result by a narrower schema. */
+export interface SlicedToolView<E, V extends ZodType> {
+    defaults?: EndpointInputDefaults<E>;
+    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;
+}
+type ToolViewEndpoint = ToolEndpointDef & {
+    output: ZodType<unknown>;
+};
+/** The type error an HTTP-only endpoint produces: a view is an answer for tools. */
+export interface ToolViewNeedsToolTransport {
+    'toolView needs a tool transport — add MCP, AGENT or CLI to expose': never;
+}
+type ToolTransportEndpoint<E> = E extends {
+    expose: readonly ['HTTP'];
+} ? ToolViewNeedsToolTransport : E;
+/** The endpoint with its view in `tool.view`, next to any tool options it already had. */
+export type WithToolView<E> = Omit<E, 'tool'> & {
+    tool: (E extends {
+        tool: infer T extends object;
+    } ? T : unknown) & {
+        view: DeclaredToolView;
+    };
+};
+/**
+ * Declare an endpoint's tool-surface view with `project` typed against the
+ * endpoint's own `input` and `output`.
+ *
+ * ```ts
+ * list: withToolView(
+ *   {
+ *     method: 'GET', path: '/', desc: 'List users', input: ListQuery, output: UserList,
+ *     tool: { name: 'user_list' },
+ *   },
+ *   {
+ *     defaults: { include: [] },
+ *     output: UserCardList,
+ *     project: (full, { input }) => ({ items: full.items.map(toCard) }),
+ *   },
+ * ),
+ * ```
+ *
+ * A view without `project` slices the full result by `output`; the full
+ * 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;
+/**
+ * The declaration-time half of the view rule, for a contract assembled past the
+ * types as much as for one written through `withToolView`: a view only exists
+ * where a tool surface does, and it can only change what a tool call is given
+ * and shown — never which keys the endpoint accepts.
+ */
+export declare function assertToolView(prefix: string, key: string, ep: EndpointDef): void;
+export {};
+//# sourceMappingURL=tool-view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/contract/tool-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE9E,mFAAmF;AACnF,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO;IAC5C,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC;CAC/D;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAAyC,CAAC;AAElF,qFAAqF;AACrF,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CACrC;AAED,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,SAAS,OAAO,CAAA;CAAE,GACtE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,SAAS,CAAC;AACd,KAAK,qBAAqB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,SAAS,OAAO,CAAA;CAAE,GACxE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACnB,KAAK,CAAC;AACV,KAAK,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,SAAS,OAAO,CAAA;CAAE,GACtE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,KAAK,CAAC;AACV,KAAK,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,SAAS,OAAO,CAAA;CAAE,GAC3E,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GACV,KAAK,CAAC;AAEV,KAAK,eAAe,CAAC,CAAC,EAAE,OAAO,IAAI,CACjC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,KACvC,OAAO,CAAC;AAEb,yEAAyE;AACzE,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;IACrD,QAAQ,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;CACzD;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;IAClD,QAAQ,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,mFAAmF,EAAE,KAAK,CAAC;CAC5F;AAED,KAAK,gBAAgB,GAAG,eAAe,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC;AAEvE,oFAAoF;AACpF,MAAM,WAAW,0BAA0B;IACzC,mEAAmE,EAAE,KAAK,CAAC;CAC5E;AAED,KAAK,qBAAqB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,GACnE,0BAA0B,GAC1B,CAAC,CAAC;AAEN,0FAA0F;AAC1F,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAC9C,IAAI,EAAE,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;KAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG;QACjE,IAAI,EAAE,gBAAgB,CAAC;KACxB,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAC3D,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EACtC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,YAAY,CAAC,CAAC,CAAC,CAAC;AACnB,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,SAAS,OAAO,EAC9E,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EACtC,IAAI,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,YAAY,CAAC,CAAC,CAAC,CAAC;AACnB,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAC3D,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EACtC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACxB,YAAY,CAAC,CAAC,CAAC,CAAC;AACnB,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,SAAS,OAAO,EAC9E,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EACtC,IAAI,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC;AAa1F;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,CA0DjF"}

package/dist/declaration/declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration.d.ts","sourceRoot":"","sources":["../../src/declaration/declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAoBpD,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/D;AAUD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAO3B,CAAC;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,uCAQlC,CAAC;AAEJ,yEAAyE;AACzE,eAAO,MAAM,qBAAqB;;;;;kBAOvB,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,aAW9B,CAAC;AAEJ,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,aAEiD,CAAC;AAEpF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;kBAavB,CAAC;AAEZ,kDAAkD;AAClD,eAAO,MAAM,oBAAoB;;;EAAwC,CAAC;AAoG1E,eAAO,MAAM,oBAAoB;;;kBAKtB,CAAC;AAEZ;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;kBAMpC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;kBA0BnB,CAAC;AAEZ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB;;;;kBAezB,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,gFAAgF;AAChF,eAAO,MAAM,kBAAkB;;;;;;;;;;;kBAciD,CAAC;AAEjF,0CAA0C;AAC1C,eAAO,MAAM,6BAA6B;;;EAA+B,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;kBAK1B,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB;;;;kBAMzB,CAAC;AAEZ,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB;;;;;;kBAEtB,CAAC;AAEZ,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB;;;;;;EAA0D,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;kBAclC,CAAC;AAEJ,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0DjC,CAAC;AAyCL,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAKpE;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,kBAAkB,CAU3E;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAC7B,WAAW,EAAE,kBAAkB,EAC/B,IAAI,EAAE,MAAM,GACX,WAAW,GAAG,SAAS,CAEzB"}

package/dist/durability/contract.d.ts

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+import type { AgentStoreEventEnvelope, AgentStoreEventPage, AppendAgentStoreEvent, ReadAgentStoreEvents } from './events.js';
+/**
+ * The durable ledger a local step implementation needs.
+ *
+ * Narrower than `AgentRuntimeStore` on purpose: durability owns no records of
+ * its own, it reads and appends the conversation's canonical event log, so a
+ * store that already satisfies this slice can back it without the rest of the
+ * runtime.
+ *
+ * A park (`sleep`/`waitFor`) is recorded the same way a step result is: as an
+ * ordinary event in this ledger. The local scheduler waits in-process, and a
+ * reconstruction resumes from the records that survived a restart.
+ */
+export interface StepDurabilityLedger {
+    appendEvent(input: AppendAgentStoreEvent): Promise<AgentStoreEventEnvelope>;
+    readEvents(input: ReadAgentStoreEvents): Promise<AgentStoreEventPage>;
+}
+/** Event kind carrying one recorded step result in the canonical ledger. */
+export declare const DURABILITY_STEP_EVENT_KIND = "durability/step";
+/** Event kind recording that a run parked on time or on an external event. */
+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;
+    encoded: z.ZodString;
+}, z.core.$strip>;
+export declare const ParkEventPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    runId: z.ZodString;
+    kind: z.ZodLiteral<"sleep">;
+    name: z.ZodString;
+    deadline: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    kind: z.ZodLiteral<"wait">;
+    event: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>], "kind">;
+export declare const DeliveredEventPayloadSchema: z.ZodObject<{
+    runId: z.ZodString;
+    event: z.ZodString;
+    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>;
+/**
+ * The time source a park uses.
+ *
+ * `now` is the wall clock the durable sleep deadline is stamped from and
+ * re-evaluated against, so a reconstructed park resumes from the recorded
+ * value. A test replaces the pair with a manual clock to advance time without
+ * waiting in real time.
+ */
+export interface DurabilityClock {
+    now(): number;
+    schedule(callback: () => void, delayMs: number): {
+        cancel(): void;
+    };
+}
+export interface LocalStepDurabilityOptions {
+    store: StepDurabilityLedger;
+    conversationId: string;
+    runId: string;
+    signal?: AbortSignal;
+    /** Host-owned notification for ledger writes made by another process. */
+    subscribe?(wake: () => void): () => void;
+    /**
+     * Injectable time source for `sleep`. Defaults to the wall clock and
+     * `setTimeout`; a test passes a manual clock so advancing time
+     * deterministically resumes a park without waiting in real time.
+     */
+    clock?: {
+        now(): number;
+        schedule(callback: () => void, delayMs: number): {
+            cancel(): void;
+        };
+    };
+}
+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.
+     *
+     * The first execution runs `body` and appends the result to the ledger. A
+     * replay — a fresh process, or a second durability object built over the same
+     * store — decodes the record and returns it without calling `body` again.
+     */
+    step<T extends z.infer<ReturnType<typeof z.json>>>(name: string, body: () => T | Promise<T>, options?: StepRunOptions): Promise<T>;
+    /** The decoded result of an already-recorded step, or `undefined` if none. */
+    readRecordedStep(name: string): Promise<unknown | undefined>;
+    /** Whether `name` has a recorded result. */
+    hasRecordedStep(name: string): Promise<boolean>;
+    /**
+     * Wait on a lightweight local timer for `seconds`, retaining a durable deadline.
+     *
+     * The first call records a park with an absolute deadline; a replay whose
+     * deadline has passed returns immediately, one before it waits out the
+     * remainder. `name` is the park's identity within the run and must be stable
+     * across replays. It defaults to the duration, so a caller that parks twice
+     * for the same length must pass distinct names.
+     */
+    sleep(input: {
+        seconds: number;
+        name?: string;
+    }, options?: StepRunOptions): Promise<void>;
+    /**
+     * Park the run until an external event `{ event, id }` is delivered.
+     *
+     * Resolves with the delivered payload. A waiter that starts after delivery
+     * returns immediately, as does a reconstruction that finds the delivery in
+     * the ledger.
+     */
+    waitFor<T = unknown>(input: {
+        event: string;
+        id: string;
+    }, options?: StepRunOptions): Promise<T>;
+    /**
+     * Durably record an external event and wake any waiter for it.
+     *
+     * The record is append-only and survives a restart: reconstruction finds it
+     * and a `waitFor` for the same key resolves without a second delivery.
+     */
+    deliver(input: {
+        event: string;
+        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.
+ *
+ * Thrown instead of re-running `body`: a body is arbitrary and often effectful,
+ * and a record that cannot be decoded is evidence the ledger is not what this
+ * run wrote, never evidence the step never ran.
+ */
+export declare class StepResultDecodeError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A step body returned a value that cannot be represented as JSON. */
+export declare class StepResultNotSerializableError extends Error {
+    constructor(stepName: string, cause: unknown);
+}
+/** The caller aborted before the step body was started. No record was written. */
+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.
+ *
+ * Thrown instead of parking on a record whose shape is not ours: an
+ * undecodable park is evidence the ledger is not what this run wrote, never
+ * evidence the park never happened.
+ */
+export declare class ParkRecordDecodeError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A sleeping or waiting park was aborted before it was satisfied.
+ *
+ * No record is removed: the park stays in the ledger, so a later replay
+ * resumes from the same durable state instead of starting a new park.
+ */
+export declare class ParkAbortedError extends Error {
+    constructor(park: string);
+}
+//# sourceMappingURL=contract.d.ts.map