@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/missions/plan-parse.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Parsing for the agent-authored `:::mission` block — the bridge from a chat
+ * prompt contract to the engine's MissionStep[] shape. The block format:
+ *
+ *   :::mission
+ *   title: <mission title>
+ *   <id>: <kind> | <intent>
+ *   :::
+ *
+ * The allowed kind vocabulary is a PARAMETER — products pass their own list to
+ * match their prompt directive; {@link DEFAULT_MISSION_STEP_KINDS} is the
+ * default. Kinds label intent for gating and UX; they never select a different
+ * execution path.
+ */
+import type { MissionStep } from './service';
+/** Default step-kind vocabulary. `best-effort` matches the engine's default
+ *  non-fatal kind (a failure does not abort the mission); the rest are
+ *  fatal-on-failure agent sub-tasks. */
+export declare const DEFAULT_MISSION_STEP_KINDS: readonly string[];
+/** Define the structure representing a parsed mission step with id, kind, and intent fields */
+export interface ParsedMissionStep {
+    id: string;
+    kind: string;
+    intent: string;
+}
+/** Describe a mission with a title and an ordered list of parsed steps */
+export interface ParsedMission {
+    title: string;
+    steps: ParsedMissionStep[];
+}
+/** Define options to specify allowed lowercase step kinds for parsing mission blocks */
+export interface ParseMissionBlocksOptions {
+    /** Allowed step kinds (lowercase). Default {@link DEFAULT_MISSION_STEP_KINDS}. */
+    kinds?: readonly string[];
+}
+/**
+ * Parse every well-formed `:::mission` block. A block without a title or
+ * without at least one valid step yields nothing (it is malformed — never
+ * guess a plan from loose prose). Unknown kinds and malformed step lines are
+ * dropped; an empty result lets the caller skip the block rather than start an
+ * empty mission.
+ */
+export declare function parseMissionBlocks(fullContent: string, options?: ParseMissionBlocksOptions): ParsedMission[];
+/**
+ * Materialize parsed steps into the engine's MissionStep[] shape. Rejects a
+ * duplicate step id (fail loud — the owner keys its durable step cache by
+ * step id and `createMission` rejects duplicates anyway; catching it here
+ * gives a clearer diagnostic). Every step starts `pending` with zero attempts.
+ */
+export declare function buildAgentMissionPlan(steps: ParsedMissionStep[]): MissionStep[];

package/dist/missions/service.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Durable mission state — the guarded status machine for a multi-step agent run.
+ *
+ * A mission is a persisted plan (ordered steps), a cursor (count of completed
+ * steps), a cost ledger + budget, and a status machine. This module owns the
+ * legal transitions and the guarded mutation surface; it does NOT execute steps
+ * (the engine in `./engine` does) and it does NOT own persistence — products
+ * implement {@link MissionStorePort} over their own tables. Every state change
+ * appends a {@link MissionAuditEvent} so the run timeline is a single durable
+ * audit trail.
+ *
+ * Concurrency contract: a mission MUST be driven by a single serialized owner
+ * (a Durable Object, a Cloudflare Workflow, a queue consumer — one per
+ * mission). The service is the typed guard layer, not a serializer: every
+ * mutation re-reads the record and asks the store for a compare-and-set write
+ * guarded on the values it read. When the guard misses, the row changed under
+ * us and the caller gets `{ succeeded: false, conflict: true }` — never a
+ * silent clobber, never a stale overwrite.
+ */
+export type MissionStatus = 'scheduled' | 'running' | 'paused' | 'waiting_approval' | 'blocked' | 'succeeded' | 'failed' | 'aborted' | 'cancelled';
+/** Define possible statuses for a mission step during its execution lifecycle */
+export type MissionStepStatus = 'pending' | 'running' | 'waiting_approval' | 'done' | 'failed';
+/** Define the structure and state details of a mission step within a workflow system */
+export interface MissionStep {
+    id: string;
+    /** What the step should accomplish — an intent, never an implementation. */
+    intent: string;
+    /** Product-defined kind label. Labels intent for gating/UX; it never selects
+     *  a different execution path. */
+    kind: string;
+    status: MissionStepStatus;
+    /** Count of genuine `* -> running` edges (retries inflate this; idempotent
+     *  re-asserts do not). */
+    attempts: number;
+    /** One-line live status surfaced on the step row ("7/15 refs"). */
+    sublabel?: string;
+    /** Small pointer at the produced artifact (vault path, asset id) — never the
+     *  full payload. */
+    resultRef?: string;
+}
+/** Define the structure for tracking mission token usage, cost, duration, and LLM call counts */
+export interface MissionCostLedger {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    wallMs: number;
+    llmCalls: number;
+}
+/** The durable mission row, shape-normalized. Timestamps are epoch ms. */
+export interface MissionRecord {
+    id: string;
+    workspaceId: string;
+    status: MissionStatus;
+    /** Product-defined origin label ('chat', 'manual', 'cron', …). */
+    trigger: string;
+    summary: string | null;
+    plan: MissionStep[];
+    /** Count of durably-completed steps; the next step to run is `plan[cursor]`. */
+    cursor: number;
+    cost: MissionCostLedger | null;
+    budgetUsd: number | null;
+    spentUsd: number;
+    pauseReason: string | null;
+    /** The single owning engine's instance id, write-once (see `setEngineRef`). */
+    engineRef: string | null;
+    scheduledAt: number | null;
+    startedAt: number;
+    completedAt: number | null;
+    metadata: Record<string, unknown> | null;
+}
+/**
+ * Discriminated outcome for guarded operations. Callers MUST inspect
+ * `succeeded` before reading `value` — illegal transitions and missing rows
+ * surface here, never as a throw-and-swallow or a silent no-op. `conflict`
+ * distinguishes a lost guarded race (retryable — re-read and re-apply) from a
+ * logic rejection (illegal edge, missing step — deterministic, never retried).
+ */
+export type MissionOutcome<T> = {
+    succeeded: true;
+    value: T;
+} | {
+    succeeded: false;
+    error: string;
+    conflict: boolean;
+};
+/** Fields a guarded write compares against the values the caller read. A SQL
+ *  implementation compares JSON columns as serialized text
+ *  (`coalesce(col, 'null') = JSON.stringify(expected)`), matching how the
+ *  in-memory store compares. An absent field is unguarded. */
+export interface MissionUpdateGuard {
+    status?: MissionStatus;
+    cursor?: number;
+    plan?: MissionStep[];
+    cost?: MissionCostLedger | null;
+    metadata?: Record<string, unknown> | null;
+    /** Guard that no engine has bound yet (the write-once bind). */
+    engineRefIsNull?: true;
+}
+/** Fields a guarded write sets when the guard holds. `null` values are real
+ *  writes (clear the column), not skips. */
+export interface MissionUpdatePatch {
+    status?: MissionStatus;
+    pauseReason?: string | null;
+    summary?: string;
+    completedAt?: number | null;
+    plan?: MissionStep[];
+    cursor?: number;
+    cost?: MissionCostLedger;
+    spentUsd?: number;
+    metadata?: Record<string, unknown>;
+    engineRef?: string;
+}
+/** One audit-trail row. Appended after every committed state change, so an
+ *  event always denotes a real transition (no phantom rows on rejected or
+ *  no-op calls). */
+export interface MissionAuditEvent {
+    missionId: string;
+    workspaceId: string;
+    level: 'info' | 'warn' | 'error';
+    /** Machine-readable transition name ('mission.created', 'mission.step.done',
+     *  'mission.cursor', 'mission.cost', 'mission.paused', …). */
+    step: string;
+    message: string;
+    metadata: Record<string, unknown>;
+    at: number;
+}
+/**
+ * Persistence seam — the product implements this over its own tables. The
+ * invariant the implementation MUST keep: `update` applies `patch` ONLY when
+ * every guard field still equals the stored value, and returns `null` when the
+ * guard misses. That null is how a concurrent write surfaces as a typed
+ * failure instead of a clobber.
+ */
+export interface MissionStorePort {
+    load(id: string): Promise<MissionRecord | null>;
+    /** `extras` are the opaque product-column values from
+     *  `CreateMissionInput.extras` — write them in the SAME statement as the
+     *  record (single-write creation) or ignore them if the table has no extra
+     *  columns. */
+    insert(record: MissionRecord, extras?: Record<string, unknown>): Promise<MissionRecord>;
+    update(id: string, guard: MissionUpdateGuard, patch: MissionUpdatePatch): Promise<MissionRecord | null>;
+    appendEvent(event: MissionAuditEvent): Promise<void>;
+}
+/** Statuses a mission can never leave — the run is done. */
+export declare function isMissionTerminal(status: MissionStatus): boolean;
+/** The cooperative kill switch: a stop request rides metadata so it survives
+ *  any status and is honored by the engine before the next side effect. */
+export declare function isMissionStopRequested(mission: MissionRecord): boolean;
+/** Define input parameters for creating a mission including optional deterministic id and unique plan steps */
+export interface CreateMissionInput {
+    /** Explicit row id. Omit to use the service's id generator. Pass a
+     *  DETERMINISTIC id (derived from the originating turn) when the caller may
+     *  re-create the same mission under at-least-once delivery — the duplicate
+     *  insert then trips the store's uniqueness instead of spawning a second run. */
+    id?: string;
+    workspaceId: string;
+    /** Becomes the mission summary. */
+    title: string;
+    /** Plan step ids MUST be unique: the owning workflow keys its durable step
+     *  cache by step id, so a collision would silently replay the wrong result.
+     *  A duplicate is rejected here (fail loud). */
+    plan: MissionStep[];
+    budgetUsd?: number | null;
+    /** Epoch ms. Present → the mission starts `scheduled` instead of `running`. */
+    scheduledAt?: number | null;
+    trigger: string;
+    /** Caller-defined context stamped onto the record (thread ids, source turn,
+     *  model). Read back via `mission.metadata`; the engine only reads
+     *  `stopRequested` from it. */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * Opaque product-column values handed VERBATIM to `MissionStorePort.insert`
+     * (e.g. a `workflowId` FK on the product's mission table), so creation is a
+     * single write — no post-insert stamp. The service never reads, validates,
+     * or persists them itself; they exist only on the insert call.
+     */
+    extras?: Record<string, unknown>;
+}
+/** Define a patch to update the status and optional metadata of a step in a process */
+export interface SetStepStatusPatch {
+    sublabel?: string;
+    resultRef?: string;
+    error?: string;
+    /**
+     * Spend committed ATOMICALLY with the step transition. Folding the cost into
+     * the SAME guarded write makes step completion the per-step idempotency key:
+     * a same-status replay (the step is already `done`) short-circuits as a no-op
+     * BEFORE the write, so the charge lands exactly once even when an engine
+     * RESUME re-dispatches a step whose cost previously committed. `deltaUsd` is
+     * the marginal spend; `ledgerDelta` carries the token/wall/llm breakdown.
+     */
+    cost?: {
+        deltaUsd: number;
+        ledgerDelta?: Partial<MissionCostLedger>;
+    };
+}
+/** Define input parameters to complete a mission with status and optional summary */
+export interface CompleteMissionInput {
+    ok: boolean;
+    summary?: string;
+}
+/** Define methods to create, retrieve, and update missions with controlled engine binding and metadata merging */
+export interface MissionService {
+    createMission(input: CreateMissionInput): Promise<MissionRecord>;
+    getMission(id: string): Promise<MissionRecord | null>;
+    /** Bind the executing engine's instance id, write-once from the single
+     *  owner: re-asserting the same ref is a no-op; binding a DIFFERENT ref over
+     *  an existing one is rejected so a second owner can never steal the run. */
+    setEngineRef(id: string, engineRef: string): Promise<MissionOutcome<MissionRecord>>;
+    /** Shallow-merge keys into metadata. Guarded on the metadata read, so racing
+     *  merges surface as conflicts instead of silently dropping keys. */
+    mergeMetadata(id: string, patch: Record<string, unknown>): Promise<MissionOutcome<MissionRecord>>;
+    /** Mutate one plan step's status (+ optional sublabel/resultRef) and append a
+     *  transition event. Rejects unknown steps and illegal step edges. Does NOT
+     *  move the cursor — call `advanceCursor` for that. */
+    setStepStatus(id: string, stepId: string, status: MissionStepStatus, patch?: SetStepStatusPatch): Promise<MissionOutcome<MissionRecord>>;
+    /** Move the done-count cursor forward by one. Rejects advancing past the end
+     *  of the plan so the caller learns the mission has no further work. */
+    advanceCursor(id: string): Promise<MissionOutcome<MissionRecord>>;
+    /** Increment spentUsd and merge a partial ledger into the cumulative ledger.
+     *  `deltaUsd` is the marginal spend; `ledgerDelta` carries the token/wall/
+     *  llm-call breakdown for the same unit of work. */
+    addCost(id: string, deltaUsd: number, ledgerDelta?: Partial<MissionCostLedger>): Promise<MissionOutcome<MissionRecord>>;
+    pause(id: string, reason: string): Promise<MissionOutcome<MissionRecord>>;
+    resume(id: string): Promise<MissionOutcome<MissionRecord>>;
+    abort(id: string): Promise<MissionOutcome<MissionRecord>>;
+    /** Flip one step and the whole mission to waiting_approval together. The
+     *  mission transition is validated FIRST so an illegal source is rejected
+     *  without mutating the step — no half-applied state. */
+    markWaitingApproval(id: string, stepId: string): Promise<MissionOutcome<MissionRecord>>;
+    complete(id: string, input: CompleteMissionInput): Promise<MissionOutcome<MissionRecord>>;
+}
+/** Define options for configuring mission service behavior including storage, time, and ID generation */
+export interface MissionServiceOptions {
+    store: MissionStorePort;
+    /** Injectable clock (epoch ms). Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Row-id generator when `CreateMissionInput.id` is omitted. Default
+     * `crypto.randomUUID()` — a 36-char dashed UUID. Inject your own when your
+     * mission table already has an id shape (e.g. 32-hex matching D1 row
+     * defaults): the service stamps the generated id verbatim onto the inserted
+     * record, so a mismatch with the rest of your schema surfaces only at the
+     * product layer. Keep id shape parity here, not in the store.
+     */
+    generateId?: () => string;
+}
+/** Create a mission service that manages mission records and audit events with customizable options */
+export declare function createMissionService(options: MissionServiceOptions): MissionService;
+/** Define an in-memory mission store that tracks events and allows direct record writes */
+export interface InMemoryMissionStore extends MissionStorePort {
+    /** The full audit trail, append order. */
+    events(): MissionAuditEvent[];
+    /** Unguarded direct write — simulates a concurrent owner or a crash-shaped
+     *  state in tests. Production writers go through the guarded `update`. */
+    put(record: MissionRecord): void;
+}
+/**
+ * In-memory {@link MissionStorePort} — the portable backend for tests and
+ * sandbox/eval shells. Guard comparison uses JSON serialization of the read
+ * value, the same contract a SQL implementation honors by comparing stored
+ * JSON text. Records are deep-copied on every boundary so callers can never
+ * mutate stored state around the guards.
+ */
+export declare function createInMemoryMissionStore(): InMemoryMissionStore;

package/dist/{failover-D-3UXXTb.d.ts → model-resolution/failover.d.ts}

@@ -29,15 +29,15 @@
  * on every model (bad request, auth, content filter): retrying those down a
  * chain burns latency and money to reach the same failure.
  */
-declare const UPSTREAM_UNAVAILABLE_CODES: readonly string[];
+export declare const UPSTREAM_UNAVAILABLE_CODES: readonly string[];
 /** HTTP statuses that indicate an upstream capacity/availability problem. */
-declare const UPSTREAM_UNAVAILABLE_STATUSES: readonly number[];
+export declare const UPSTREAM_UNAVAILABLE_STATUSES: readonly number[];
 /**
  * The HTTP status a message states in prose, or `undefined` when it states
  * none. Deliberately NOT "any three digits in the string" — an unanchored digit
  * scan would read a token count or a duration as a status.
  */
-declare function readHttpStatusHint(text: string): number | undefined;
+export declare function readHttpStatusHint(text: string): number | undefined;
 /**
  * True when `signal` — a thrown error OR a resolved result payload — indicates
  * the model's upstream is unavailable and another model is worth trying.
@@ -47,16 +47,16 @@ declare function readHttpStatusHint(text: string): number | undefined;
  * explicit failure marker (`success: false`, or an `error`/`errorCode` field) —
  * a successful result is never misread as an outage.
  */
-declare function isUpstreamUnavailable(signal: unknown): boolean;
+export declare function isUpstreamUnavailable(signal: unknown): boolean;
 /** One model tried, and how it went. */
-interface ModelFailoverAttempt {
+export interface ModelFailoverAttempt {
     model: string;
     ok: boolean;
     /** Why this model was abandoned. Absent when `ok`. */
     reason?: string;
 }
 /** The outcome of a failover run: the value plus the full attempt trail. */
-interface ModelFailoverResult<T> {
+export interface ModelFailoverResult<T> {
     value: T;
     /** The model that actually produced `value`. */
     model: string;
@@ -65,12 +65,12 @@ interface ModelFailoverResult<T> {
     usedFallback: boolean;
 }
 /** Every model in the chain failed; carries the trail for logging. */
-declare class ModelFailoverExhaustedError extends Error {
+export declare class ModelFailoverExhaustedError extends Error {
     readonly attempts: ModelFailoverAttempt[];
     constructor(attempts: ModelFailoverAttempt[]);
 }
 /** Inputs to {@link runWithModelFailover}. */
-interface RunWithModelFailoverInput<T> {
+export interface RunWithModelFailoverInput<T> {
     /** Preferred model first, then fallbacks in descending preference. */
     models: readonly string[];
     /** Executes one turn with the given model. */
@@ -96,11 +96,9 @@ interface RunWithModelFailoverInput<T> {
  *
  * @throws ModelFailoverExhaustedError when every model reports an outage.
  */
-declare function runWithModelFailover<T>(input: RunWithModelFailoverInput<T>): Promise<ModelFailoverResult<T>>;
+export declare function runWithModelFailover<T>(input: RunWithModelFailoverInput<T>): Promise<ModelFailoverResult<T>>;
 /**
  * Build a failover chain: the preferred model first, then `fallbacks`, with
  * duplicates removed so a model is never retried twice in one turn.
  */
-declare function buildModelChain(preferred: string, fallbacks: readonly string[]): string[];
-
-export { type ModelFailoverAttempt as M, type RunWithModelFailoverInput as R, UPSTREAM_UNAVAILABLE_CODES as U, ModelFailoverExhaustedError as a, type ModelFailoverResult as b, UPSTREAM_UNAVAILABLE_STATUSES as c, buildModelChain as d, runWithModelFailover as e, isUpstreamUnavailable as i, readHttpStatusHint as r };
+export declare function buildModelChain(preferred: string, fallbacks: readonly string[]): string[];

package/dist/model-resolution/index.d.ts

@@ -1,5 +1,3 @@
-export { M as ModelFailoverAttempt, a as ModelFailoverExhaustedError, b as ModelFailoverResult, R as RunWithModelFailoverInput, U as UPSTREAM_UNAVAILABLE_CODES, c as UPSTREAM_UNAVAILABLE_STATUSES, d as buildModelChain, i as isUpstreamUnavailable, r as readHttpStatusHint, e as runWithModelFailover } from '../failover-D-3UXXTb.js';
-
 /**
  * Canonical chat-model resolution — identical across every agent app.
  *
@@ -19,35 +17,35 @@ export { M as ModelFailoverAttempt, a as ModelFailoverExhaustedError, b as Model
  *   (exact, or a bare id resolved to its canonical id when the suffix is unique).
  */
 /** The router /v1/models entry shape this module reads. Minimal on purpose. */
-interface ModelInfo {
+export interface ModelInfo {
     id: string;
     name?: string;
     _provider?: string;
     provider?: string;
 }
 /** Define possible origins for the chat model configuration values */
-type ChatModelSource = 'request' | 'workspace' | 'env' | 'default';
+export type ChatModelSource = 'request' | 'workspace' | 'env' | 'default';
 /** Resolve a chat model with its identifier and source information */
-interface ResolvedChatModel {
+export interface ResolvedChatModel {
     model: string;
     source: ChatModelSource;
 }
 /** Represent successful chat model validation with a true status and a validated string value */
-interface ChatModelValidationSuccess {
+export interface ChatModelValidationSuccess {
     succeeded: true;
     value: string;
 }
 /** Describe a failed chat model validation result with an error message */
-interface ChatModelValidationFailure {
+export interface ChatModelValidationFailure {
     succeeded: false;
     error: string;
 }
 /** Resolve the outcome of validating a chat model as either success or failure */
-type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure;
+export type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure;
 /** The catalog-fetch boundary: maps a router base URL to the raw model list. */
-type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>;
+export type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>;
 /** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */
-interface ResolveChatModelInput {
+export interface ResolveChatModelInput {
     /** Per-request override (highest precedence). */
     requestModel?: string;
     /** Persisted workspace-pinned model. */
@@ -60,9 +58,9 @@ interface ResolveChatModelInput {
 }
 /** Resolve the chat-turn model by the one canonical precedence. Blank values are
  *  treated as absent. */
-declare function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel;
+export declare function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel;
 /** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */
-interface ValidateChatModelIdInput {
+export interface ValidateChatModelIdInput {
     /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */
     allowlist?: Iterable<string>;
     /** The operator-set env model value — always admitted (operator-trusted). */
@@ -79,12 +77,11 @@ interface ValidateChatModelIdInput {
  * the suffix is unique across the catalog — an ambiguous suffix is rejected
  * rather than silently assigned a provider.
  */
-declare function validateChatModelId(modelId: unknown, input: ValidateChatModelIdInput): Promise<ChatModelValidationResult>;
+export declare function validateChatModelId(modelId: unknown, input: ValidateChatModelIdInput): Promise<ChatModelValidationResult>;
 /** Resolve and return a trimmed string model ID or undefined for invalid or empty input */
-declare function cleanModelId(value: unknown): string | undefined;
+export declare function cleanModelId(value: unknown): string | undefined;
 /** Validate if a model ID string conforms to length and character format requirements */
-declare function isWellFormedModelId(modelId: string): boolean;
+export declare function isWellFormedModelId(modelId: string): boolean;
 /** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */
-declare function catalogIdsForModel(model: ModelInfo): string[];
-
-export { type ChatModelSource, type ChatModelValidationFailure, type ChatModelValidationResult, type ChatModelValidationSuccess, type LoadModels, type ModelInfo, type ResolveChatModelInput, type ResolvedChatModel, type ValidateChatModelIdInput, catalogIdsForModel, cleanModelId, isWellFormedModelId, resolveChatModel, validateChatModelId };
+export declare function catalogIdsForModel(model: ModelInfo): string[];
+export { isUpstreamUnavailable, readHttpStatusHint, runWithModelFailover, buildModelChain, ModelFailoverExhaustedError, UPSTREAM_UNAVAILABLE_CODES, UPSTREAM_UNAVAILABLE_STATUSES, type ModelFailoverAttempt, type ModelFailoverResult, type RunWithModelFailoverInput, } from './failover';

package/dist/object-store/index.d.ts

@@ -33,7 +33,7 @@
 /** Options for a single {@link ObjectStore.put}. Both fields are optional; a
  *  store that needs a fixed content length (e.g. R2 with a `ReadableStream`
  *  body) uses `contentLength` when present. */
-interface PutObjectOptions {
+export interface PutObjectOptions {
     /** MIME type recorded with the object (returned by `get`/`head`). Advisory:
      *  the proxied download route always serves `application/octet-stream`. */
     contentType?: string;
@@ -44,7 +44,7 @@ interface PutObjectOptions {
 /** A retrieved object. `stream()` is the ONLY way to read the bytes — there is
  *  deliberately no `text()`/`arrayBuffer()`, so a large object never buffers
  *  into the isolate heap. */
-interface ObjectBody {
+export interface ObjectBody {
     /** The object's bytes as a `ReadableStream` (backed by R2's `.body`). */
     stream(): ReadableStream;
     /** Size in bytes. */
@@ -57,7 +57,7 @@ interface ObjectBody {
  * throw for a missing key (a miss is a normal control-flow outcome, not an
  * error); `delete` is idempotent.
  */
-interface ObjectStore {
+export interface ObjectStore {
     put(key: string, body: ReadableStream | Uint8Array, opts?: PutObjectOptions): Promise<void>;
     /** `null` on a miss — never throws for a missing key. */
     get(key: string): Promise<ObjectBody | null>;
@@ -69,7 +69,7 @@ interface ObjectStore {
     delete(key: string): Promise<void>;
 }
 /** Head/metadata shape of a stored object (structural match of R2's `R2Object`). */
-interface R2LikeObjectHead {
+export interface R2LikeObjectHead {
     size: number;
     httpMetadata?: {
         contentType?: string;
@@ -77,7 +77,7 @@ interface R2LikeObjectHead {
 }
 /** Body shape of a retrieved object (structural match of R2's `R2ObjectBody`).
  *  `body` is the streamed content — the impl reads this, never `.text()`. */
-interface R2LikeObjectBody extends R2LikeObjectHead {
+export interface R2LikeObjectBody extends R2LikeObjectHead {
     body: ReadableStream;
 }
 /**
@@ -86,7 +86,7 @@ interface R2LikeObjectBody extends R2LikeObjectHead {
  * without this package ever importing `@cloudflare/workers-types` (which would
  * otherwise leak into the public `.d.ts`).
  */
-interface R2LikeBucket {
+export interface R2LikeBucket {
     put(key: string, value: ReadableStream | Uint8Array | ArrayBuffer, options?: {
         httpMetadata?: {
             contentType?: string;
@@ -102,7 +102,7 @@ interface R2LikeBucket {
  * `.text()`/`.arrayBuffer()`, so a large file flows through the worker rather
  * than buffering into the isolate.
  */
-declare function createR2ObjectStore({ bucket }: {
+export declare function createR2ObjectStore({ bucket }: {
     bucket: R2LikeBucket;
 }): ObjectStore;
 /**
@@ -115,10 +115,10 @@ declare function createR2ObjectStore({ bucket }: {
  * attacker-controlled id can never widen the key beyond its own operator+
  * customer prefix.
  */
-declare function assertSafeKeySegment(s: string): string;
+export declare function assertSafeKeySegment(s: string): string;
 /** Inputs to {@link objectKey}. `customerId` is optional — an unattributed
  *  upload lands under the reserved `_unattributed` customer segment. */
-interface ObjectKeyParts {
+export interface ObjectKeyParts {
     operatorId: string;
     /** Optional — omitted/undefined groups the upload under `_unattributed`. */
     customerId?: string;
@@ -134,9 +134,9 @@ interface ObjectKeyParts {
  * privilege wall — a caller cannot later swap them without breaking the
  * signature.
  */
-declare function objectKey({ operatorId, customerId, uploadId, filename }: ObjectKeyParts): string;
+export declare function objectKey({ operatorId, customerId, uploadId, filename }: ObjectKeyParts): string;
 /** Arguments to {@link signObjectUrl}. */
-interface SignObjectUrlArgs {
+export interface SignObjectUrlArgs {
     /** The exact object key to authorize (from {@link objectKey}). */
     key: string;
     /** Absolute expiry in epoch MILLISECONDS (e.g. `Date.now() + 5 * 60_000` for a
@@ -159,10 +159,10 @@ interface SignObjectUrlArgs {
  * keep it SHORT — ~5 minutes is the recommended default for a privilege-walled
  * document.
  */
-declare function signObjectUrl({ key, exp, secret }: SignObjectUrlArgs): Promise<string>;
+export declare function signObjectUrl({ key, exp, secret }: SignObjectUrlArgs): Promise<string>;
 /** Result of {@link verifyObjectUrl}: the canonical key on success, nothing
  *  distinguishing on failure (so a rejection leaks no detail). */
-type VerifyObjectUrlResult = {
+export type VerifyObjectUrlResult = {
     ok: true;
     key: string;
 } | {
@@ -180,7 +180,7 @@ type VerifyObjectUrlResult = {
  * near-correct signature is not distinguishable by timing. Async because the
  * HMAC primitive is WebCrypto.
  */
-declare function verifyObjectUrl(request: Request, { secret }: {
+export declare function verifyObjectUrl(request: Request, { secret }: {
     secret: string;
 }): Promise<VerifyObjectUrlResult>;
 /**
@@ -196,9 +196,7 @@ declare function verifyObjectUrl(request: Request, { secret }: {
  *   `Content-Type: application/octet-stream`, and `X-Content-Type-Options:
  *   nosniff`, so the worker never serves active/inline content.
  */
-declare function createProxiedArtifactRoute({ store, secret, }: {
+export declare function createProxiedArtifactRoute({ store, secret, }: {
     store: ObjectStore;
     secret: string;
 }): (request: Request) => Promise<Response>;
-
-export { type ObjectBody, type ObjectKeyParts, type ObjectStore, type PutObjectOptions, type R2LikeBucket, type R2LikeObjectBody, type R2LikeObjectHead, type SignObjectUrlArgs, type VerifyObjectUrlResult, assertSafeKeySegment, createProxiedArtifactRoute, createR2ObjectStore, objectKey, signObjectUrl, verifyObjectUrl };

package/dist/openui/action.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What travels when a user presses a button on a page the agent authored.
+ *
+ * The submission is a plain REST body, not a chat turn. That is the entire
+ * point of this module: pressing "Recalculate" on an agent-authored form must
+ * cost the same as pressing a button on a hand-built screen — one product route
+ * call, no model tokens, no sandbox wake-up. The wire shape here is therefore
+ * deliberately small and self-contained: an action id, the form it belongs to,
+ * that form's current values, and enough addressing for the product to find the
+ * page. Nothing in it references a session, a turn, or a run.
+ */
+import { type OpenUIFormValues } from './values';
+/** What the browser POSTs when an action fires. */
+export interface OpenUIActionSubmission {
+    /** The action's stable id, as authored on the page. */
+    actionId: string;
+    /** The form whose values are attached, when the action sits in one. */
+    formId?: string;
+    /** Current values of that form, keyed by field id. Empty for a bare action. */
+    values: OpenUIFormValues;
+    /** The node the action was rendered on, when the page carries several. */
+    nodeId?: string;
+    /** Vault path of the persisted `render_ui` artifact this page came from. */
+    artifactPath?: string;
+}
+/** Parsed submission, or the reason the body was refused. */
+export type OpenUIActionBodyValidation = {
+    ok: true;
+    submission: OpenUIActionSubmission;
+} | {
+    ok: false;
+    code: OpenUIActionBodyErrorCode;
+    error: string;
+};
+/** Why a submission body was refused before any handler ran. */
+export type OpenUIActionBodyErrorCode = 'OPENUI_ACTION_ID_MISSING' | 'OPENUI_ACTION_ID_INVALID' | 'OPENUI_FORM_ID_INVALID' | 'OPENUI_NODE_ID_INVALID' | 'OPENUI_ARTIFACT_PATH_INVALID' | 'OPENUI_VALUES_INVALID' | 'OPENUI_FIELD_ID_INVALID' | 'OPENUI_FIELD_VALUE_INVALID';
+/** Ids the host accepts on the wire: identifier-safe, same rule as field ids. */
+export declare function isSafeOpenUIActionId(id: string): boolean;
+/**
+ * Validate a raw JSON body into a submission. Every rejection names a code so
+ * the browser can tell "the page sent something malformed" from "the product
+ * refused the action".
+ */
+export declare function validateOpenUIActionBody(body: Record<string, unknown>): OpenUIActionBodyValidation;
+/**
+ * One plain line recording what the user did, for the product to carry into the
+ * NEXT turn's context.
+ *
+ * The action itself spends no model tokens; without a record of it the agent
+ * would later reason about a page the user has already changed. Appending this
+ * to the thread (as a note, a system line, or a stored part) is how the agent
+ * catches up on the next turn the user actually pays for.
+ */
+export declare function describeOpenUIAction(submission: OpenUIActionSubmission): string;

package/dist/openui/authoring.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the model is told about writing an interactive page.
+ *
+ * An agent will not emit a node vocabulary nobody described to it, so the
+ * vocabulary and the prompt text that teaches it have to ship together. This
+ * module is that text plus the machine-readable field/action shape it
+ * describes, so five products do not each write their own (subtly different)
+ * version into a system prompt.
+ *
+ * OPT-IN, DELIBERATELY. The input nodes render only where the host's renderer
+ * knows them and the host passes an action handler. Advertise this guide only
+ * once both are true for your product — otherwise the agent writes forms the
+ * page will drop.
+ */
+import type { OpenUIFieldKind } from './values';
+/** The input kinds this guide teaches, in the order it lists them. */
+export declare const OPENUI_INPUT_KINDS: readonly OpenUIFieldKind[];
+/**
+ * The interactive vocabulary, written for a model.
+ *
+ * Appended to `render_ui`'s description by
+ * `buildAppToolOpenAITools(taxonomy, { interactiveUi: true })`, and usable
+ * directly in a system prompt for the inline ```` ```openui ```` path.
+ */
+export declare const OPENUI_INTERACTIVE_AUTHORING_GUIDE: string;