@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/legibility/source.d.ts

@@ -0,0 +1,132 @@
+/**
+ * A purpose-built TS/TSX scanner: the one place this subpath decides what part
+ * of a file is CODE and what part is COPY A HUMAN READS.
+ *
+ * Every legibility check needs the same distinction, and getting it from
+ * per-check regexes is what makes a lint gate imprecise enough to be turned off.
+ * `grep -i artifact` over one product's `apps/web/src` returns 11 hits and every
+ * single one is an import specifier, a prop name, or a doc comment — zero are on
+ * screen. A checker that reports those 11 is deleted within a week, and then it
+ * guards nothing.
+ *
+ * So this module lexes instead: one pass produces (a) classified SEGMENTS —
+ * comments, string literals, template chunks, JSX text, JSX attribute values —
+ * and (b) a JSX ELEMENT TREE with spans, attributes, and the enclosing
+ * expression container. Checks read those, never the raw bytes.
+ *
+ * It is a lexer, not a type-aware parser, and that boundary is deliberate: this
+ * package ships one runtime dependency and adding `typescript` to every
+ * consumer's install to lint copy is the wrong trade. What a lexer cannot do —
+ * resolve a string through a variable, follow a component's props to its render
+ * — is out of scope by construction and documented per check.
+ *
+ * Node-agnostic: pure string in, data out. The `fs` walking lives in `scan.ts`.
+ */
+/** What a stretch of source is, once the lexer has decided. */
+export type SegmentKind = 
+/** `//…` or `/*…*​/` — never user-visible; every check skips these. */
+'comment'
+/** A `'…'` / `"…"` literal in code position. Visible only in some contexts. */
+ | 'string'
+/** One literal chunk of a template literal (the `${…}` holes are code). */
+ | 'template'
+/** Text between JSX tags. The highest-confidence user-visible signal there is. */
+ | 'jsx-text'
+/** A `name="…"` attribute value on a JSX element. */
+ | 'jsx-attribute';
+/** One classified stretch of source. */
+export interface SourceSegment {
+    readonly kind: SegmentKind;
+    /** Offset of the first character of the segment's VALUE (inside the quotes). */
+    readonly start: number;
+    /** Offset just past the segment's value. */
+    readonly end: number;
+    /** The value text, quotes stripped, escapes left as written. */
+    readonly value: string;
+    /** For `jsx-attribute`: the attribute name. For `jsx-text`: absent. */
+    readonly attribute?: string;
+    /** For `jsx-attribute` / `jsx-text`: the owning element's tag name. */
+    readonly tag?: string;
+}
+/** One attribute on a JSX element. */
+export interface JsxAttribute {
+    readonly name: string;
+    readonly start: number;
+    /** The literal value when written `name="…"`; null when `name={…}` or bare. */
+    readonly value: string | null;
+    /** True when written `name={…}` — the value is code, not copy. */
+    readonly expression: boolean;
+}
+/** One JSX element, with the span every subtree question needs. */
+export interface JsxElement {
+    /** Tag as written (`div`, `Button`, `Card.Header`); `''` for a fragment. */
+    readonly tag: string;
+    readonly attributes: JsxAttribute[];
+    readonly children: JsxElement[];
+    parent: JsxElement | null;
+    /** Offset of the opening `<`. */
+    readonly start: number;
+    /** Offset just past the opening tag's `>`. */
+    openEnd: number;
+    /** Offset just past the element's end (`/>` or `</tag>`). */
+    end: number;
+    /**
+     * Offset of the `{` of the nearest enclosing JSX expression container, or
+     * null at the top of a return/assignment. This is what scopes an empty state
+     * to its own conditional branch instead of to the whole page.
+     */
+    readonly containerStart: number | null;
+}
+/** Everything one pass over a file produces. */
+export interface ScannedSource {
+    readonly text: string;
+    readonly segments: readonly SourceSegment[];
+    /** Every element, in document (open-tag) order. */
+    readonly elements: readonly JsxElement[];
+    /**
+     * `text` with every comment, string body and template body replaced by
+     * spaces, offsets preserved. Structural regexes (catch bodies, fetch calls)
+     * run over this so a `catch` inside a string can never be a finding.
+     */
+    readonly masked: string;
+}
+/** 1-based line/column for a byte offset. */
+export interface SourcePosition {
+    readonly line: number;
+    readonly column: number;
+}
+/**
+ * Lex one TS/TSX source.
+ *
+ * The loop keeps a frame stack. A code frame pops back to its JSX parent when
+ * an unmatched `}` closes the expression container that opened it; a JSX tag
+ * frame becomes a children frame at `>` and pops at `/>`.
+ */
+export declare function scanSource(text: string): ScannedSource;
+/** Line-start offsets, for `positionAt`. */
+export declare function lineIndex(text: string): number[];
+/** 1-based line/column of `offset`, given a `lineIndex` result. */
+export declare function positionAt(starts: readonly number[], offset: number): SourcePosition;
+/** The innermost element whose span contains `offset`. */
+export declare function elementAt(elements: readonly JsxElement[], offset: number): JsxElement | null;
+/**
+ * The nearest enclosing FUNCTION body containing `offset`, over MASKED text.
+ *
+ * Walks outward from the innermost block until one is introduced by `)` +
+ * optional `=>`, `function …`, or a method head — the scope a handler occupies.
+ * This is what keeps a check from joining a request in one handler to a success
+ * message in another, which is the difference between a report worth reading
+ * and one that gets the gate switched off.
+ */
+export declare function enclosingFunctionBlock(masked: string, offset: number): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * The innermost `{ … }` block containing `offset`, over MASKED text.
+ * Returns null when `offset` sits at top level.
+ */
+export declare function enclosingBlock(masked: string, offset: number): {
+    start: number;
+    end: number;
+} | null;

package/dist/legibility/suppress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Suppression: how a product says "this one is deliberate" without switching
+ * the gate off.
+ *
+ * The design constraint is the whole reason this gate exists at all. A checker
+ * that cannot be silenced per-line gets silenced per-repo — the config flag is
+ * flipped once, in a rush, and nobody ever flips it back. So every finding is
+ * individually suppressible; and because a silent suppression is
+ * indistinguishable from a disabled check six months later, a suppression
+ * without a written reason is ITSELF a finding, and does not suppress.
+ *
+ *   // legibility-ignore engineering-vocabulary — "conflict" is the term of art
+ *   // a litigator uses; renaming it would make the screen less clear, not more
+ *   <p>Conflict check cleared</p>
+ *
+ * Forms:
+ *   - a comment on its own line suppresses the NEXT line that has content
+ *   - a trailing comment suppresses ITS OWN line
+ *   - `legibility-ignore-file <check>` suppresses the check for the whole file
+ *   - several checks may be named, comma-separated
+ *   - JSX comments (`{​/* … *​/}`) work, since they lex as comments too
+ *
+ * Honoured suppressions are returned, not swallowed: the report prints the
+ * count and `--list-suppressions` prints every one with its reason, so the
+ * exemptions stay as visible as the failures.
+ */
+import type { ScannedFile } from './scan';
+import { type LegibilityCheckId, type RawFinding } from './types';
+export interface SuppressionIndex {
+    /** Decide a finding: honoured suppression, or not. */
+    reasonFor(check: LegibilityCheckId, line: number): string | null;
+    /** Findings the suppression syntax itself produced (missing reason, unknown check). */
+    readonly selfFindings: readonly RawFinding[];
+}
+/** Parse every `legibility-ignore` directive in one lexed file. */
+export declare function buildSuppressionIndex(file: ScannedFile): SuppressionIndex;

package/dist/legibility/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The vocabulary of the legibility gate: what a finding is, what a suppression
+ * is, and what a product configures.
+ *
+ * Kept in its own module so the checks, the report formatter and the bin all
+ * agree on one shape, and so a consumer can import the types without pulling in
+ * `node:fs`.
+ */
+/** The checks this gate runs. Each is individually suppressible, by name. */
+export type LegibilityCheckId = 
+/** Words on screen that belong to the codebase, not to the reader. */
+'engineering-vocabulary'
+/** An empty/zero state whose subtree offers no next action. */
+ | 'dead-end-empty-state'
+/** A success state set without inspecting the response that would deny it. */
+ | 'unchecked-success'
+/** A `catch` that neither surfaces the failure nor rethrows it. */
+ | 'silent-failure'
+/** A route no navigation entry and no in-source link can reach. */
+ | 'unreachable-capability'
+/** A suppression comment that names a check but gives no reason. */
+ | 'suppression-without-reason';
+export declare const LEGIBILITY_CHECKS: readonly LegibilityCheckId[];
+/** One defect, at one place, with the fix named. */
+export interface LegibilityFinding {
+    readonly check: LegibilityCheckId;
+    /** Path as reported — relative to the working directory when it is inside it. */
+    readonly file: string;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+    /** What is wrong, in one sentence a reviewer can act on. */
+    readonly message: string;
+    /** What to do about it. Every finding carries one; a finding without a fix is a complaint. */
+    readonly remedy: string;
+    /** The offending source, trimmed to one readable line. */
+    readonly evidence: string;
+}
+/** A suppression that was honoured, with the reason its author wrote. */
+export interface LegibilitySuppression {
+    readonly check: LegibilityCheckId;
+    readonly reason: string;
+    readonly file: string;
+    readonly line: number;
+}
+export interface LegibilityReport {
+    readonly ok: boolean;
+    readonly findings: readonly LegibilityFinding[];
+    /** Honoured suppressions — printed, never silent. */
+    readonly suppressed: readonly LegibilitySuppression[];
+    readonly filesScanned: number;
+    readonly checksRun: readonly LegibilityCheckId[];
+}
+/** A banned term plus the sentence that replaces it. */
+export interface BannedTerm {
+    /** Matched case-insensitively at word boundaries against visible copy. */
+    readonly term: string;
+    /** What to write instead — printed with the finding. */
+    readonly instead: string;
+}
+export interface VocabularyOptions {
+    /** Replaces the default list outright. */
+    readonly terms?: readonly BannedTerm[];
+    /** Added to the default list — the common case for a product's own jargon. */
+    readonly extraTerms?: readonly BannedTerm[];
+    /** Removed from the default list, for a word that is genuinely the reader's. */
+    readonly allowTerms?: readonly string[];
+    /**
+     * Additional JSX attributes / object keys whose string value is user-visible
+     * copy (the defaults cover `title`, `label`, `placeholder`, `empty*`, …).
+     */
+    readonly extraCopyKeys?: readonly string[];
+    /**
+     * Additional call names whose first string argument is user-visible copy
+     * (defaults cover `toast*`, `alert`, `setError`, `new Error`).
+     */
+    readonly extraCopyCalls?: readonly string[];
+    /**
+     * Also read strings filling an object key named like copy
+     * (`description: '…'`). OFF by default: measured as the tier that reports
+     * system prompts, MCP tool descriptions and document templates — text no
+     * reader ever sees. Turn it on when your data modules really do hold UI copy.
+     */
+    readonly includeObjectCopy?: boolean;
+}
+export interface EmptyStateOptions {
+    /** Extra tags that count as an action (defaults: button, a, input, form, *Button, *Link, …). */
+    readonly extraActionTags?: readonly string[];
+    /** Extra props that count as an action (defaults: onClick, onSubmit, href, to, action, …). */
+    readonly extraActionProps?: readonly string[];
+    /** Extra regexes (as source strings) that identify empty-state copy. */
+    readonly extraEmptyPatterns?: readonly string[];
+    /**
+     * Also report a zero-state that sits directly under a heading. OFF by
+     * default: measured as the largest false-positive class — a titled section
+     * with nothing in it labels a screen the reader is already oriented on, and a
+     * detail page carrying four of them buries the one screen that is entirely
+     * empty.
+     */
+    readonly reportSectionZeroStates?: boolean;
+}
+export interface SuccessOptions {
+    /**
+     * Callees that resolve on a failed request instead of throwing. `fetch` is the
+     * default and the reason this check exists; add your own thin wrapper here.
+     */
+    readonly httpCalls?: readonly string[];
+    /** Extra identifiers that mean "the user has been told it worked". */
+    readonly extraSuccessSignals?: readonly string[];
+    /**
+     * Calls that inspect a response and throw on a bad status
+     * (`assertOk(res)`). Their presence in the same function counts as checking.
+     */
+    readonly okGuards?: readonly string[];
+}
+export interface SilentFailureOptions {
+    /** Extra identifiers that count as surfacing a failure to the user. */
+    readonly extraErrorSinks?: readonly string[];
+    /**
+     * Path substrings whose modules cannot reach a browser, and whose handlers
+     * are therefore not this check's business. Defaults to react-router's
+     * server-only conventions (`/.server/`, `/routes/api.`); pass `[]` to read
+     * every module, at the measured cost of a large false-positive class
+     * (best-effort telemetry, audit writes and cache fallbacks).
+     */
+    readonly readerlessPaths?: readonly string[];
+}
+export interface ReachabilityOptions {
+    /**
+     * A react-router `routes.ts` (the `@react-router/dev/routes` shape:
+     * `route()` / `index()` / `layout()` / `prefix()`).
+     */
+    readonly routeConfigFile?: string;
+    /** Route paths supplied directly, for a product on another router. */
+    readonly routePaths?: readonly string[];
+    /** Files that define navigation. Their path literals are the nav entries. */
+    readonly navFiles?: readonly string[];
+    /** Route paths (or prefixes ending in `/*`) that need no door — defaults to `api/*`. */
+    readonly ignore?: readonly string[];
+    /**
+     * Treat a route whose module is not a `.tsx` file as a resource endpoint
+     * rather than a screen. Default true — react-router resource routes are `.ts`.
+     */
+    readonly ignoreNonTsxRoutes?: boolean;
+}
+/** What a product writes in `legibility.config.mjs`. */
+export interface LegibilityConfig {
+    /** Source directories to scan, recursively. At least one. */
+    readonly srcDirs: readonly string[];
+    /** Turn a check off wholesale. Prefer a per-line suppression with a reason. */
+    readonly checks?: Partial<Record<LegibilityCheckId, boolean>>;
+    readonly vocabulary?: VocabularyOptions;
+    readonly emptyState?: EmptyStateOptions;
+    readonly success?: SuccessOptions;
+    readonly silentFailure?: SilentFailureOptions;
+    readonly reachability?: ReachabilityOptions;
+    /** Path substrings to skip, added to the defaults (tests, fixtures, generated). */
+    readonly ignorePaths?: readonly string[];
+}
+/** A finding before file/line resolution — what a check returns. */
+export interface RawFinding {
+    readonly check: LegibilityCheckId;
+    readonly offset: number;
+    readonly message: string;
+    readonly remedy: string;
+    readonly evidence: string;
+}

package/dist/legibility/walk-sources.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The node-only recursive source walker `/legibility` and `/theme-contract`
+ * both need: collect scannable files under a directory, skipping vendor and
+ * generated output. Extracted here because it drifted into two copies one day
+ * apart with different skip lists — `/theme-contract`'s was missing
+ * `.react-router` / `.wrangler` / `.turbo`, so it descended into and linted
+ * framework-generated output the newer list correctly skips.
+ *
+ * Zero dependencies beyond `node:fs`/`node:path`, so either subpath can import
+ * it without pulling in the other's unrelated surface (`/legibility`'s own
+ * hand-written lexer, in particular).
+ */
+/**
+ * Recursively collect scannable files under `dir`.
+ *
+ * `ignore` is matched by substring against the full path — the caller's own
+ * exclusions (test files, fixtures, `.d.ts`, generated route types, …) layer
+ * on top of the shared `GENERATED_SKIP_DIRS` floor rather than being baked in
+ * here, since which files count as "source" is a per-checker policy.
+ */
+export declare function walkSources(dir: string, ignore?: readonly string[], skipDirs?: ReadonlySet<string>): string[];

package/dist/{agent-activity-C8ZG0F0M.d.ts → missions/agent-activity.d.ts}

@@ -9,7 +9,7 @@
  * `step.updated`); the client re-validates with {@link stepAgentActivity}
  * because the value rides loader/JSON boundaries as untyped metadata.
  */
-interface StepAgentActivity {
+export interface StepAgentActivity {
     taskId: string;
     /** Delegation profile: coder | researcher | ui-auditor | product-defined. */
     tool: string;
@@ -30,7 +30,7 @@ interface StepAgentActivity {
     spanId?: string;
 }
 /** Step state extended with the activity lane a loader/seed route attaches. */
-type WithAgentActivity<Step> = Step & {
+export type WithAgentActivity<Step> = Step & {
     agentActivity?: StepAgentActivity[];
 };
 /**
@@ -38,6 +38,4 @@ type WithAgentActivity<Step> = Step & {
  * missing any required field are dropped (a torn row must not crash the lane);
  * optional fields are kept only when well-typed.
  */
-declare function stepAgentActivity(step: object): StepAgentActivity[];
-
-export { type StepAgentActivity as S, type WithAgentActivity as W, stepAgentActivity as s };
+export declare function stepAgentActivity(step: object): StepAgentActivity[];

package/dist/missions/engine.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Mission execution engine — drives one mission's plan to completion under a
+ * SINGLE serialized owner (a Cloudflare Workflow, a Durable Object alarm, a
+ * queue consumer — one per mission). The owner wraps each `runStep` call in its
+ * durable-step primitive (e.g. Workflows `step.do(step.id, …)`) so a completed
+ * step's result is persisted and replayed instead of re-run after a mid-run
+ * restart. This module holds the logic that must be correct independent of any
+ * runtime, so it is injectable and unit-testable with the dispatch mocked.
+ *
+ * Idempotency is layered, belt-and-suspenders:
+ *   1. The owner's durable-step cache replays a completed step's result.
+ *   2. `runStep` re-reads the mission first; a step already `done` (with a
+ *      resultRef) returns the cached pointer WITHOUT re-dispatching — this
+ *      closes the at-least-once window where a callback re-runs after the
+ *      side effect committed but before the owner durably recorded it.
+ *   3. The cursor advances only after a step is `done`, so a fresh run resumes
+ *      from `mission.cursor` and never re-touches earlier steps.
+ *
+ * Seams (the product supplies domain; the engine owns mechanism):
+ *   - {@link SandboxDispatch} — how a step actually executes.
+ *   - {@link MissionEngineOptions.estimateStepCostUsd} — per-step USD estimate.
+ *   - {@link MissionGateOptions.classifyStep} — which steps need approval.
+ *   - {@link MissionApprovalsPort} — where gate proposals live and how they
+ *     resolve.
+ */
+import type { MissionCostLedger, MissionOutcome, MissionRecord, MissionService, MissionStatus, MissionStep } from './service';
+import { type MissionEventSink } from './events';
+/**
+ * A side-effecting unit of per-step work. The owner supplies the real
+ * implementation (e.g. a detached sandbox-session dispatcher); tests supply a
+ * mock. MUST return a SMALL pointer — large output is written to the product's
+ * storage and only the resultRef is returned.
+ */
+export type SandboxDispatch = (input: SandboxDispatchInput) => Promise<SandboxDispatchResult>;
+/** Define input parameters for dispatching a mission step in the sandbox environment */
+export interface SandboxDispatchInput {
+    mission: MissionRecord;
+    step: MissionStep;
+    stepIndex: number;
+}
+/** Define the result of a completed sandbox dispatch including artifact reference and optional cost details */
+export interface SandboxDispatchDoneResult {
+    kind?: 'done';
+    /** Small pointer at the produced artifact/output (vault path, asset id, exec
+     *  digest). Stored on the step as `resultRef`; never the full payload. */
+    resultRef: string;
+    /** Optional one-line status surfaced on the step row. */
+    sublabel?: string;
+    /** Optional marginal spend for this step. `ledgerDelta` carries platform-
+     *  reported truth (real token counts, wall time); `deltaUsd` is set ONLY when
+     *  a provider-authored price is known. Omit fields rather than synthesizing
+     *  zeros — the engine substitutes its injected per-step estimate for a
+     *  missing deltaUsd and records that estimate in the ledger. */
+    cost?: {
+        deltaUsd?: number;
+        ledgerDelta?: Partial<MissionCostLedger>;
+    };
+}
+/** The dispatched step's detached session is still executing on the platform.
+ *  The owner sleeps `pollAfterMs` and re-invokes the step; the dispatch is
+ *  idempotent on the session ref, so the re-invocation settles the same session
+ *  rather than starting a second run. */
+export interface SandboxDispatchInProgressResult {
+    kind: 'in_progress';
+    sessionRef: string;
+    pollAfterMs: number;
+    sublabel?: string;
+}
+/** Resolve the result of a sandbox dispatch as done or in progress */
+export type SandboxDispatchResult = SandboxDispatchDoneResult | SandboxDispatchInProgressResult;
+/** Outcome of running a single step. `cached` distinguishes a replay/skip
+ *  (step was already done) from a fresh execution so the engine and its tests
+ *  can assert the dispatch was NOT re-invoked. */
+export type StepOutcome = {
+    kind: 'done';
+    resultRef: string;
+    cached: boolean;
+} | {
+    kind: 'in_progress';
+    sessionRef: string;
+    pollAfterMs: number;
+    sublabel?: string;
+} | {
+    kind: 'skipped-cursor';
+    reason: string;
+} | {
+    kind: 'failed';
+    error: string;
+    fatal: boolean;
+};
+/** Outcome of running the whole plan from the cursor to the end. */
+export type PlanOutcome = {
+    kind: 'completed';
+    summary: string;
+} | {
+    kind: 'in_progress';
+    stepId: string;
+    sessionRef: string;
+    pollAfterMs: number;
+    sublabel?: string;
+} | {
+    kind: 'failed';
+    failedStepId: string;
+    error: string;
+} | {
+    kind: 'halted';
+    status: MissionStatus;
+    reason?: string | null;
+} | {
+    kind: 'terminal';
+    status: MissionStatus;
+} | {
+    kind: 'not-found';
+};
+/** Define options to control mission plan execution with optional pre-step veto logic */
+export interface MissionPlanRunOptions {
+    /** Pre-step veto (kill switch, schedule window). A non-null return pauses the
+     *  mission with that reason before the step's side effect starts. */
+    beforeStep?: (mission: MissionRecord, step: MissionStep) => Promise<string | null>;
+}
+/** Thrown to make the owner's durable-step wrapper retry. The single-owner
+ *  invariant makes a genuine concurrent change rare (it means another writer
+ *  touched the row), so retrying — rather than corrupting state by forcing a
+ *  stale write — is the correct response. Distinct from a task failure, which
+ *  is recorded on the step. */
+export declare class MissionConcurrencyError extends Error {
+    constructor(message: string);
+}
+/** Thrown by a {@link SandboxDispatch} for a TRANSIENT failure (platform blip,
+ *  exec-time network fault) that should be re-attempted. `runStep` RE-THROWS it
+ *  so the owner engages its bounded retry+backoff; the step is left `running`
+ *  and the re-dispatch is made idempotent by the cached-done guard. A
+ *  deterministic failure must be a plain Error instead — that is recorded as a
+ *  fatal `failed` step and is never retried (no money-burning loop on a
+ *  deterministic error). */
+export declare class RetryableStepError extends Error {
+    constructor(message: string);
+}
+/** Resolution states a gate proposal can be in. `approved`/`executed` unblock
+ *  the gated step; everything else keeps the mission parked. */
+export type MissionProposalResolution = 'pending' | 'approved' | 'rejected' | 'executed' | 'ignored';
+/** Define mission gate categories as step, budget, or volume */
+export type MissionGateKind = 'step' | 'budget' | 'volume';
+/** Product classification of one step. Returned by
+ *  {@link MissionGateOptions.classifyStep}; the matching rules (regexes, intent
+ *  vocabularies, path allowlists) are product domain and never live here. */
+export interface StepGateClassification {
+    /** Product approval-type label persisted on the proposal ('generate',
+     *  'integration_invoke', …). */
+    type: string;
+    /** Counted against the per-mission external-action volume cap. */
+    externalAction?: boolean;
+    estCostUsd?: number | null;
+}
+/** A gate proposal the engine asks the product to persist. The id is
+ *  deterministic per (gate, mission, step) — see the `*ProposalId` helpers —
+ *  so a replay re-finds the same proposal instead of duplicating it. The
+ *  product composes its own title/description from the structured fields. */
+export interface MissionGateProposal {
+    id: string;
+    missionId: string;
+    stepId: string;
+    gate: MissionGateKind;
+    mission: MissionRecord;
+    step: MissionStep;
+    /** Present for `gate: 'step'` — the classification that triggered the gate. */
+    classification?: StepGateClassification;
+    /** Present for `gate: 'budget'`. */
+    budget?: {
+        spentUsd: number;
+        budgetUsd: number;
+        estimatedCostUsd: number;
+    };
+    /** Present for `gate: 'volume'`. */
+    volume?: {
+        externalActionCount: number;
+        cap: number;
+    };
+}
+/** Approval persistence seam — the product implements this over its own
+ *  proposal table and resolution flow. */
+export interface MissionApprovalsPort {
+    /** Resolution of the proposal with this id, or null when none exists. */
+    findResolution(proposalId: string): Promise<MissionProposalResolution | null>;
+    /** Persist a new gate proposal (id is deterministic; called at most once per
+     *  (gate, mission, step) absent a resolution). */
+    createProposal(proposal: MissionGateProposal): Promise<void>;
+    /** Count of this mission's `gate: 'step'` proposals whose classification was
+     *  `externalAction: true` — the denominator of the volume cap. */
+    countExternalActionProposals(missionId: string): Promise<number>;
+}
+/** Define configuration options for mission gating including approvals, step classification, and action limits */
+export interface MissionGateOptions {
+    approvals: MissionApprovalsPort;
+    /** Which steps need human approval, and as what. Return null for an ungated
+     *  step. The rules are product domain (intent regexes, kind tables). */
+    classifyStep: (step: MissionStep) => StepGateClassification | null;
+    /** Max external-action approvals per mission before an approved override is
+     *  required to request another. Default 5. */
+    externalActionCap?: number;
+}
+/** Define configuration options for initializing and controlling the mission engine behavior */
+export interface MissionEngineOptions {
+    service: MissionService;
+    /** Per-step USD estimate. Load-bearing twice: the budget gate parks on it
+     *  BEFORE a step runs, and the engine records it as the step's spend when the
+     *  dispatch reports no provider-authored price — using one estimator keeps
+     *  spend and gate consistent. */
+    estimateStepCostUsd: (step: MissionStep) => number;
+    /** Best-effort live notifier. Fired AFTER each guarded write commits, so a
+     *  broadcast always reflects persisted state; re-fired on idempotent replays
+     *  so a reconnecting client converges. Never awaited; a throwing sink can
+     *  never fail a step. Default: drop everything. */
+    sink?: MissionEventSink;
+    /** Approval gating. Omitted → no classification/volume gates, and a budget
+     *  overrun pauses the mission (fail closed) instead of parking it
+     *  waiting_approval behind an override proposal. */
+    gates?: MissionGateOptions;
+    /** Step kinds whose failure does NOT abort the whole mission — enrichment
+     *  steps the plan can complete without. Every other kind is fatal-on-failure.
+     *  Default `['optional', 'best-effort']`. */
+    nonFatalStepKinds?: readonly string[];
+}
+/** Resolve mission plan steps with concurrency control and durable state management */
+export interface MissionEngine {
+    /** Run exactly one plan step. Idempotent: re-invoking for a step already
+     *  `done` returns the cached pointer without re-dispatching. A lost guarded
+     *  race throws {@link MissionConcurrencyError} so the owner's durable-step
+     *  wrapper retries instead of writing a stale value. */
+    runStep(missionId: string, stepId: string, dispatch: SandboxDispatch): Promise<StepOutcome>;
+    /** Walk the plan from the durable cursor to the end, re-reading the mission
+     *  between steps so a pause/stop control that lands while a step is running
+     *  is honored before the next side effect. `runStep` is the owner's boundary:
+     *  in production `(step) => durableStep.do(step.id, () => engine.runStep(…))`;
+     *  in tests `engine.runStep` directly. */
+    runPlan(missionId: string, runStep: (step: MissionStep, stepIndex: number) => Promise<StepOutcome>, options?: MissionPlanRunOptions): Promise<PlanOutcome>;
+    /** Record spend durable-first, live second: the guarded ledger write commits,
+     *  then the sink sees the new total. A guarded failure returns unchanged. */
+    recordCost(missionId: string, deltaUsd: number, ledgerDelta?: Partial<MissionCostLedger>): Promise<MissionOutcome<MissionRecord>>;
+    /** Pause durable-first, live second (the paused event fires only on a real
+     *  edge, not an idempotent re-pause). */
+    pauseMission(missionId: string, reason: string): Promise<MissionOutcome<MissionRecord>>;
+}
+/** Deterministic proposal id for a step-classification gate. */
+export declare function stepGateProposalId(missionId: string, stepId: string): string;
+/** Deterministic proposal id for a budget-overrun override. */
+export declare function budgetGateProposalId(missionId: string, stepId: string): string;
+/** Deterministic proposal id for an external-action volume-cap override. */
+export declare function volumeGateProposalId(missionId: string, stepId: string): string;
+/** Create a mission engine configured with options to manage mission execution and error handling */
+export declare function createMissionEngine(options: MissionEngineOptions): MissionEngine;