@full-self-browsing/lattice 1.3.0 → 1.5.0

package/dist/run-crew-Bnve5dyI.d.ts

@@ -0,0 +1,721 @@
+import { Jt as SessionStore, T as Usage, bn as RunEventSink, ct as ToolDefinition, d as ProviderRunRequest, f as ProviderRunResponse, gt as LatticeRunError, l as ProviderRef, mn as OutputContractMap, mt as ToolUseRequest, r as ProviderAdapter, u as ProviderRegistryInput, xn as TracerLike } from "./provider-C2IfKsvz.js";
+import { s as ArtifactRef, x as PolicySpec } from "./artifact-Bg6mJGnm.js";
+import { c as ReceiptEnvelope, n as InferOutputMap, p as ReceiptSigner } from "./infer-DLqp5QIM.js";
+import { n as StorageLike } from "./storage-DJKmsaEI.js";
+import { n as standardSchemaToJsonSchema } from "./schema-CNfa_VEy.js";
+import { n as CapabilityContract, t as BudgetInvariant } from "./contract-S3oJGlc9.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/contract/bands.d.ts
+/**
+ * Hook lifecycle event vocabulary -- separate from RunEventKind by design.
+ *
+ * Phase 19 (v1.2) additively extends with BEFORE_AGENT_ITERATION and
+ * AFTER_AGENT_ITERATION — emitted by `runAgent` around each iteration's
+ * provider call. Existing four events continue to fire inside each
+ * iteration (BEFORE/AFTER_PROVIDER per native call; BEFORE/AFTER_TOOL
+ * per dispatched tool).
+ */
+type HookLifecycleEvent = "BEFORE_PROVIDER" | "AFTER_PROVIDER" | "BEFORE_TOOL" | "AFTER_TOOL" | "BEFORE_AGENT_ITERATION" | "AFTER_AGENT_ITERATION";
+/**
+ * SAFETY-band veto mechanism — Phase 19.
+ *
+ * Handlers can deny an iteration by calling `controls.deny(reason)`. The
+ * pipeline records the latest reason and exposes it via `lastDenialReason()`.
+ * The reason resets at the start of each `run()` call.
+ *
+ * Composition convention: the agent runtime invokes BEFORE_AGENT_ITERATION
+ * before provider call, then checks `pipeline.lastDenialReason()`. If set,
+ * the iteration aborts with `agent-iteration-denied` failure.
+ */
+interface HookDenyDirective {
+  readonly reason: string;
+}
+/**
+ * Controls passed to each handler as an optional second argument.
+ *
+ * Backward compat: existing single-argument handlers (Phase 15 + Phase 16)
+ * ignore this and continue to work unchanged.
+ */
+interface HookControls {
+  /** Set a denial reason; the latest call wins per `run()`. */
+  readonly deny: (reason: string) => void;
+}
+/**
+ * Priority bands. Lower number = higher priority (runs first).
+ *
+ * SAFETY (0)        -- safety / breaker hooks; cannot be overridden by lower bands
+ * OBSERVABILITY (1) -- logging, metrics, audit; runs after safety, before extension
+ * EXTENSION (2)     -- user-supplied hooks; runs last
+ *
+ * Within a band, handlers run in registration order.
+ */
+declare const BAND: {
+  readonly SAFETY: 0;
+  readonly OBSERVABILITY: 1;
+  readonly EXTENSION: 2;
+};
+type Band = typeof BAND[keyof typeof BAND];
+/**
+ * Handler input -- frozen snapshot of the caller's context at run() time.
+ *
+ * structuredClone-then-Object.freeze: handlers receive a deep-cloned,
+ * surface-frozen view. Mutations on the handler side do NOT leak back to
+ * the calling site.
+ *
+ * The handler's return value is currently ignored; future revisions may
+ * add a typed return that downstream bands consume.
+ */
+interface HookHandler<TContext = unknown> {
+  (context: Readonly<TContext>, controls?: HookControls): void | Promise<void>;
+}
+interface RegisterOptions {
+  readonly band: Band;
+  readonly matcher?: RegExp;
+  readonly budgetMs?: number;
+}
+/**
+ * The HookPipeline interface returned by createHookPipeline().
+ *
+ * IMMUTABILITY: once freeze() is called, register() throws an Error whose
+ * .name === "PIPELINE_FROZEN". freeze() is irreversible by design --
+ * protects against late-binding hook injection mid-session.
+ */
+interface HookPipeline {
+  readonly kind: "hook-pipeline";
+  register<TContext = unknown>(event: HookLifecycleEvent, handler: HookHandler<TContext>, options: RegisterOptions): void;
+  freeze(): void;
+  isFrozen(): boolean;
+  run<TContext = unknown>(event: HookLifecycleEvent, context: TContext): Promise<void>;
+  /**
+   * Phase 19: returns the latest denial reason set by any handler during
+   * the most recent `run()` call. Resets to `null` at the start of each run.
+   * Read by the agent runtime to detect SAFETY-band veto.
+   */
+  lastDenialReason(): string | null;
+}
+interface CreateHookPipelineOptions {
+  readonly tracer?: TracerLike;
+  readonly sessionId?: string;
+  readonly defaultBudgetMs?: number;
+}
+/**
+ * Factory: build a fresh hook pipeline.
+ */
+declare function createHookPipeline(options?: CreateHookPipelineOptions): HookPipeline;
+//#endregion
+//#region src/runtime/config.d.ts
+interface LatticeConfig {
+  readonly providers?: ProviderRegistryInput;
+  readonly storage?: StorageLike | false;
+  readonly sessions?: SessionStore | false;
+  readonly defaults?: {
+    readonly policy?: PolicySpec;
+  };
+  readonly tracing?: TracerLike | false;
+  readonly events?: RunEventSink | readonly RunEventSink[];
+  /**
+   * Phase 9 — when configured, every terminal branch of `ai.run` emits a
+   * signed `CapabilityReceipt` attached to `RunResult.receipt`. When absent,
+   * no receipts are issued and `RunResult.receipt` is undefined.
+   */
+  readonly signer?: ReceiptSigner;
+}
+type NormalizedProviderEntry = ProviderRef | ProviderAdapter;
+interface NormalizedLatticeConfig {
+  readonly providers: readonly NormalizedProviderEntry[];
+  readonly storage?: StorageLike;
+  readonly sessions?: SessionStore;
+  readonly defaults: {
+    readonly policy?: PolicySpec;
+  };
+  readonly tracing?: TracerLike;
+  readonly events: readonly RunEventSink[];
+  readonly signer?: ReceiptSigner;
+}
+//#endregion
+//#region src/agent/format-tools.d.ts
+/**
+ * One turn in the running conversation.
+ *
+ * `role: "tool"` is used for tool-result turns; `toolCallId` and `toolName`
+ * are populated so the model can correlate the result with its prior
+ * `tool_call` envelope.
+ */
+interface ConversationTurn {
+  readonly role: "user" | "assistant" | "tool";
+  readonly content: string;
+  readonly toolCallId?: string;
+  readonly toolName?: string;
+}
+type FormatToolsMode = "native" | "prompt-reencoded" | "auto";
+interface FormatToolsOptions {
+  /**
+   * Tool-use protocol mode. Defaults to `"auto"`, which currently resolves
+   * to `"prompt-reencoded"` for ALL 7 providers (Phase 19 simplification —
+   * native tool_use deferred to a follow-on milestone). Reserved for
+   * forward compatibility.
+   */
+  readonly mode?: FormatToolsMode;
+  /**
+   * Optional system prompt to prepend. Useful for setting persona /
+   * domain-specific instructions on top of the tool-use envelope.
+   */
+  readonly system?: string;
+}
+interface FormattedToolsHandle {
+  /**
+   * Builds the single `task` string passed to `ProviderAdapter.execute()`.
+   * Encodes the conversation, available tools, and response-envelope
+   * instructions.
+   */
+  readonly buildTask: (conversation: readonly ConversationTurn[]) => string;
+  /**
+   * Phase 39 (v1.3): body-only sibling of `buildTask` — identical turn
+   * rendering minus the leading system block, so the byte-stable
+   * `describeForSystem()` prefix can be hoisted once per crew for
+   * prompt-cache sharing without duplication (39-05).
+   *
+   * Invariant: `describeForSystem() + "\n" + buildTaskBody(conversation)`
+   * reconstructs `buildTask(conversation)` byte-for-byte.
+   */
+  readonly buildTaskBody: (conversation: readonly ConversationTurn[]) => string;
+  /**
+   * Parses the assistant's response text. Returns:
+   *   - `ToolUseRequest[]` when the response contains one or more tool-call
+   *     envelopes (parsed in declaration order).
+   *   - `null` when the response is a final answer (no tool-call envelopes
+   *     detected).
+   *
+   * The parser is forgiving: it tolerates extra prose around the JSON
+   * envelope (markdown fences, leading explanations) and the model
+   * occasionally drifting on whitespace.
+   */
+  readonly parseToolUse: (responseText: string) => ReadonlyArray<ToolUseRequest> | null;
+  /**
+   * Returns the static system block describing available tools. Useful for
+   * tracing / logging the exact tool-description text fed to the model.
+   */
+  readonly describeForSystem: () => string;
+  /**
+   * Effective mode this handle resolved to (`"prompt-reencoded"` for all
+   * v1.2 providers). Exposed for inspectability.
+   */
+  readonly mode: "prompt-reencoded";
+}
+declare const toolSchemaToJsonSchema: typeof standardSchemaToJsonSchema;
+/**
+ * Builds the prompt-reencoded tool-use protocol handle for any provider.
+ *
+ * Phase 19 ships a uniform implementation across all 7 logical providers
+ * (openai, openai-compat, anthropic, gemini, xai, openrouter, lm-studio).
+ * The `providerName` argument is accepted for forward compatibility but
+ * does not branch the implementation in v1.2.
+ */
+declare function formatToolsForProvider(providerName: string, tools: ReadonlyArray<ToolDefinition>, options?: FormatToolsOptions): FormattedToolsHandle;
+//#endregion
+//#region src/runtime/survivability.d.ts
+/**
+ * MV3-survivability adapter contract -- Phase 5 (FSB v0.10.0-attempt-2).
+ *
+ * This module is a SIBLING of create-ai.ts (the Lattice runtime facade) and
+ * a SIBLING of contract/bands.ts (the hook pipeline factory) and
+ * contract/checkpoint.ts (the per-step receipt hook). It does NOT modify
+ * any of them; the SurvivabilityAdapter contract is composed from those
+ * surfaces by the consumer (FSB's lattice-runtime-adapter.js in Plan 05-05).
+ *
+ * What is the survivability problem?
+ *   Some host runtimes can evict the execution context mid-flow with no
+ *   synchronous shutdown signal:
+ *     - Chrome MV3 service workers: evicted after 30s silence OR 5min idle.
+ *     - Cloudflare Workers: evicted at end of each request unless waitUntil.
+ *     - AWS Lambda: process freeze + thaw across invocations.
+ *   Lattice's existing runtime (create-ai.ts) assumes the process stays
+ *   live for the duration of a run. The SurvivabilityAdapter contract is
+ *   the seam where a host runtime tells Lattice "here is how to serialize
+ *   my state, here is how to deserialize it back, here is how to resume
+ *   work after I get evicted and recreated."
+ *
+ * What this module SHIPS:
+ *   - SurvivabilityAdapter<TState> interface (4 methods)
+ *   - SerializedSnapshot type (string-encodable opaque envelope)
+ *   - EvictionHook<TState> type (pre-eviction callback signature)
+ *   - ResumePolicy literal-union (post-restore reconstruction verdict)
+ *   - UnsubscribeFn type
+ *   - createNoopSurvivabilityAdapter() reference implementation
+ *
+ * What this module DOES NOT ship:
+ *   - chrome.storage.session integration (FSB-side; Plan 05-05).
+ *   - offscreen-document message bus (FSB-side; Plan 05-04).
+ *   - Auto-wiring into create-ai.ts runtime (deferred indefinitely; the
+ *     contract is consumer-controlled).
+ *   - Mid-API-request / mid-tool-dispatch recovery dispatcher (CONSERVATIVE
+ *     recovery wiring is deferred to a follow-on FSB milestone per
+ *     CONTEXT.md D-22; only the ResumePolicy taxonomy lands here).
+ *
+ * Composition conventions (NOT enforced; documented for callers):
+ *   D-09: onEviction hooks SHOULD register in BAND.SAFETY band on the
+ *         caller's HookPipeline so they run FIRST per Phase 2 priority
+ *         ordering. This module does NOT auto-register; it ships the
+ *         contract only.
+ *   D-10: serialize(state) MAY include the latest checkpoint receipt
+ *         envelope (Phase 3 createCheckpointHook output) inside the
+ *         SerializedSnapshot.payload; deserialize() reconstructs session
+ *         identifiers from the v1.1 receipt body's step-marker fields
+ *         (stepName, stepIndex, parentStepName, previousStepName,
+ *         sessionId, timestamp). The payload is opaque to Lattice -- the
+ *         host runtime defines the shape.
+ *
+ * ResumePolicy taxonomy (CD-E resolution per attempt-1 02-04-PLAN.md):
+ *   - SAFE: the snapshot was captured at a safe boundary (BEFORE_ITERATION
+ *     or BEFORE_NEXT_ITERATION_SCHEDULE step markers) and can be replayed
+ *     deterministically. The host runtime may re-arm the loop.
+ *   - RECOVERY_AMBIGUOUS: the snapshot was captured during a tool dispatch
+ *     where re-execution risk is non-zero (file write, network POST without
+ *     Idempotency-Key, side-effecting browser action). Host should escalate
+ *     to the user before deciding.
+ *   - ON_ERROR_SW_EVICTION_MID_REQUEST: the eviction happened mid-API-call
+ *     (the provider request was in flight). 6 of 7 FSB providers do NOT
+ *     document Idempotency-Key headers; replay risks duplicate charges +
+ *     duplicate responses. Host should treat the run as failed and surface
+ *     the error to the user.
+ *   - ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH: the eviction happened mid-
+ *     tool-dispatch (a browser action was in progress). Re-execution risk
+ *     is similar to mid-API-call but lands in a different recovery branch
+ *     (the host may inspect the page state before deciding).
+ *
+ * SerializedSnapshot is intentionally opaque + string-encodable. The
+ * host runtime defines the payload shape; Lattice's only requirement
+ * is that serialize() followed by deserialize() round-trips the state.
+ *
+ * Ed25519 receipt envelope contract (carries forward from Phase 1-3):
+ *   Callers MAY embed a v1.1 ReceiptEnvelope inside SerializedSnapshot.payload
+ *   for signed checkpoint round-trip. verifyReceipt against the embedded
+ *   envelope MUST return result.ok === true after a serialize -> deserialize
+ *   cycle (Test 12). This validates that JSON.stringify + JSON.parse over
+ *   the envelope preserves the JCS-canonical body bytes used by DSSE PAE.
+ *
+ * Threat model (Phase 5 CONTEXT.md security block):
+ *   - PII via serialized state: callers MUST ensure SerializedSnapshot.payload
+ *     contains only stable identifiers + user-controlled state the user has
+ *     already consented to persist. Mirrors Phase 2 D-04 receipt-body contract
+ *     (step-marker fields are stable identifiers, not free-form user input).
+ *   - Snapshot tampering: the noop adapter does NOT sign the snapshot.
+ *     Callers that need cryptographic integrity SHOULD embed a signed
+ *     ReceiptEnvelope inside the payload + verify it on deserialize.
+ *     Phase 5 ships the contract; signature wrapping is a follow-on.
+ *
+ * Vocabulary separation (carries forward Phase 2 D-12 + Phase 3 D-02):
+ *   ResumePolicy is the survivability vocabulary -- separate from
+ *   RunEventKind (tracing) AND separate from HookLifecycleEvent (bands).
+ *   The three vocabularies meet only when a host runtime composes them.
+ */
+/**
+ * String-encodable opaque snapshot. The host runtime defines the payload
+ * shape; Lattice's only requirement is that serialize() followed by
+ * deserialize() round-trips the original state object.
+ *
+ * Why string-encodable? MV3's chrome.storage.session and most cross-process
+ * storage layers accept structured-clone-safe values. JSON-string payloads
+ * are the lowest-common-denominator that survives MV3 SW eviction +
+ * Cloudflare Worker freeze + Lambda thaw. Callers MAY use a richer payload
+ * shape (Uint8Array, Blob) IF the host runtime supports it; the contract
+ * does not constrain payload format beyond "deserialize round-trips it".
+ */
+interface SerializedSnapshot {
+  readonly kind: "survivability-snapshot";
+  readonly version: "lattice-survivability/v1";
+  readonly payload: string;
+  readonly capturedAt: string;
+}
+/**
+ * Pre-eviction callback. The host runtime CAN attempt to call this hook
+ * before the execution context is evicted, but MAY NOT be able to in
+ * every case (MV3 eviction has no synchronous signal -- the SW just
+ * stops). Callers should treat onEviction as best-effort: useful for
+ * gathering final state when the eviction is announced (e.g., user-
+ * initiated stop) but not load-bearing for involuntary eviction.
+ *
+ * The hook receives the current TState by reference. Mutations on the
+ * hook side leak to the caller's state -- this is deliberate (the hook
+ * is the LAST chance to update state before eviction). Callers who want
+ * structuredClone semantics SHOULD wrap state in their own freeze layer.
+ */
+type EvictionHook<TState> = (state: TState) => void | Promise<void>;
+/**
+ * Return value of onEviction(); calling unsubscribes the hook.
+ *
+ * Idempotent -- calling twice has the same effect as calling once.
+ */
+type UnsubscribeFn = () => void;
+/**
+ * Resume policy taxonomy. The host runtime calls adapter.resume(snapshot)
+ * after eviction + restore; the returned policy tells the host runtime
+ * how to react.
+ *
+ * The 4 literal members carry forward from FSB v0.10.0-attempt-1's
+ * 02-04-PLAN.md CONSERVATIVE recovery dispatch (preserved at
+ * .planning/milestones/v0.10.0-attempt-1-pre-pivot/02-state-inspectability-
+ * carve-out/02-04-PLAN.md). Per CONTEXT.md CD-E this is the locked union.
+ */
+type ResumePolicy = "SAFE" | "RECOVERY_AMBIGUOUS" | "ON_ERROR_SW_EVICTION_MID_REQUEST" | "ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH";
+/**
+ * The SurvivabilityAdapter contract. Host runtimes implement this; Lattice
+ * runs against the interface.
+ *
+ * 4 methods (D-08 locked):
+ *   - serialize(state): convert in-memory state to SerializedSnapshot
+ *   - deserialize(snapshot): inverse of serialize
+ *   - onEviction(hook): register a best-effort pre-eviction callback
+ *   - resume(snapshot): return ResumePolicy verdict for the post-restore
+ *     reconstruction. The host runtime acts on the policy.
+ *
+ * Adapters are POLYMORPHIC over TState -- the host runtime parameterizes
+ * the type. Lattice's vitest covers the contract surface with a noop
+ * adapter where TState = Record<string, unknown> for ergonomics.
+ */
+interface SurvivabilityAdapter<TState> {
+  readonly kind: "survivability-adapter";
+  readonly id: string;
+  serialize(state: TState): SerializedSnapshot;
+  deserialize(snapshot: SerializedSnapshot): TState;
+  onEviction(hook: EvictionHook<TState>): UnsubscribeFn;
+  resume(snapshot: SerializedSnapshot): Promise<ResumePolicy>;
+}
+/**
+ * Factory options for the reference noop adapter.
+ *
+ * - id: optional. Defaults to "noop-survivability". Useful when callers
+ *   want to distinguish multiple adapter instances in test fixtures.
+ * - policy: optional. Sets the default ResumePolicy returned by resume().
+ *   Defaults to "SAFE" (matches noop adapter semantics: no recovery
+ *   ambiguity if nothing was ever persisted).
+ */
+interface NoopSurvivabilityAdapterOptions {
+  readonly id?: string;
+  readonly policy?: ResumePolicy;
+}
+/**
+ * Reference implementation of SurvivabilityAdapter<TState>. Records
+ * eviction events but does NOT persist; serialize / deserialize round-
+ * trip via JSON.stringify / JSON.parse. Analog to createFakeProvider
+ * in the providers/ module -- gives Lattice's vitest a complete shape-
+ * conformance target before the real (FSB-side) adapter ships in
+ * Plan 05-05.
+ *
+ * Per CONTEXT.md D-11 the noop adapter ships in Lattice (not FSB)
+ * because it covers the contract surface in Lattice's own test suite;
+ * FSB's real chrome.storage.session-backed adapter is glue layer.
+ */
+declare function createNoopSurvivabilityAdapter<TState = Record<string, unknown>>(options?: NoopSurvivabilityAdapterOptions): SurvivabilityAdapter<TState>;
+//#endregion
+//#region src/agent/host.d.ts
+/**
+ * Snapshot shape the agent loop serializes between iterations. The full
+ * shape is opaque to callers (they only see it through SerializedSnapshot
+ * via the configured SurvivabilityAdapter) but it's exported so reference
+ * implementations and tests can inspect the round-trip.
+ */
+interface AgentSnapshot {
+  readonly version: "agent-snapshot/v1";
+  readonly iterationIndex: number;
+  readonly conversation: readonly ConversationTurn[];
+  readonly cumulativeUsage: Usage;
+  readonly providerName: string;
+  readonly capturedAt: string;
+  /**
+   * Phase 39 (v1.3): dispatch ancestry chain of crew `AgentSpec` ids
+   * (root-first). Absent = root agent (single-agent runs never set it).
+   * Optional so existing serialized `agent-snapshot/v1` snapshots
+   * deserialize unchanged — the version literal stays `"agent-snapshot/v1"`
+   * (D-05; Pitfall 8). The crew dispatcher threads the chain through
+   * dispatch context in 39-05; cycle prevention rejects any dispatch whose
+   * target id already appears in the chain.
+   */
+  readonly ancestry?: readonly string[];
+}
+/**
+ * Scheduler seam — controls how the agent loop yields between iterations.
+ *
+ * `scheduleNext(iterationIndex)` is called AFTER an AFTER_AGENT_ITERATION
+ * emission and BEFORE the next iteration's BEFORE_AGENT_ITERATION. The
+ * scheduler decides when to resume — synchronously (sync loop), on next
+ * tick (setTimeout/queueMicrotask), via a queue (Durable Object), or any
+ * other strategy.
+ *
+ * Default (noop): resolves immediately.
+ */
+interface AgentScheduler {
+  scheduleNext(iterationIndex: number): Promise<void>;
+}
+/**
+ * Transport seam — controls how a provider call is dispatched.
+ *
+ * `call(provider, request)` wraps the provider's `execute()` invocation.
+ * Default (noop): pass-through (`provider.execute!(request)`). Cross-process
+ * bridges (FSB's offscreen-document host) override to dispatch via
+ * `chrome.runtime.sendMessage`.
+ *
+ * Per the Phase 19 INV-03 parity invariant, the transport seam does NOT
+ * modify the `ProviderAdapter` interface — it operates on top of the
+ * existing `execute()` method.
+ */
+interface AgentTransport {
+  call(provider: ProviderAdapter, request: ProviderRunRequest): Promise<ProviderRunResponse>;
+}
+/**
+ * Storage seam — controls how agent state persists between iterations for
+ * resume after host eviction.
+ *
+ * Phase 20 composes this with the Phase 18 `SurvivabilityAdapter`:
+ *   - The adapter serializes `AgentSnapshot` to `SerializedSnapshot` on
+ *     each AFTER_AGENT_ITERATION; storage.save() persists the snapshot.
+ *   - On run start, the agent loop calls storage.load(). If a non-null
+ *     snapshot is returned, the adapter deserializes it; the loop resumes
+ *     at the recorded iteration index.
+ *   - On success, the loop calls storage.clear() so the next run starts
+ *     fresh.
+ *
+ * Default (noop): save() is a no-op, load() returns null, clear() is a
+ * no-op. Suitable for Node tests where eviction never occurs.
+ */
+interface AgentStorage {
+  save(snapshot: SerializedSnapshot): Promise<void>;
+  load(): Promise<SerializedSnapshot | null>;
+  clear(): Promise<void>;
+}
+/**
+ * The host adapter — three optional seams, all swappable independently.
+ *
+ * Callers pass `host` on `AgentIntent`. The agent runtime falls back to
+ * `createNoopAgentHost()` when `intent.host` is absent (so Phase 19
+ * single-shot Node usage continues to work without explicit configuration).
+ */
+interface AgentHost {
+  readonly kind: "agent-host";
+  readonly scheduler?: AgentScheduler;
+  readonly transport?: AgentTransport;
+  readonly storage?: AgentStorage;
+}
+/**
+ * Reference implementation suitable for Node tests + the Phase 19 default
+ * behavior.
+ *
+ * - scheduler: resolves immediately (no yield between iterations).
+ * - transport: pass-through to provider.execute().
+ * - storage: save() / clear() are no-ops; load() always returns null.
+ *
+ * Equivalent to passing no host at all.
+ */
+declare function createNoopAgentHost(): AgentHost;
+//#endregion
+//#region src/agent/types.d.ts
+type DefaultAgentOutputs = {
+  readonly answer: "text";
+};
+/**
+ * Per-iteration record stored on `AgentSuccess.iterations` for inspectability.
+ *
+ * `toolCalls` carries content-addressed args/result hashes (sha256) so
+ * downstream receipts can reference them without inlining the bodies.
+ *
+ * `deniedReason` is populated on iterations whose `BEFORE_AGENT_ITERATION`
+ * SAFETY-band handler set `controls.deny(...)`.
+ */
+interface IterationRecord {
+  readonly index: number;
+  readonly provider: string;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly costUsd: number | null;
+  readonly durationMs: number;
+  readonly toolCalls: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    readonly argsHash: string;
+    readonly resultHash: string;
+  }>;
+  readonly deniedReason?: string;
+  readonly receipt?: ReceiptEnvelope;
+}
+/**
+ * Input shape accepted by `ai.runAgent(intent)`.
+ *
+ * All fields except `task` and `tools` are optional. The runtime supplies
+ * sensible defaults (in-process host, fresh pipeline, no signer, no tracer).
+ *
+ * `TOutputs` parameterizes the final-answer schema map; defaults to a free-form
+ * `{ answer: "text" }` shape when the field is omitted. Validation runs once
+ * against the final assistant message (no intermediate iteration validation).
+ */
+interface AgentIntent<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly task: string;
+  readonly tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>;
+  readonly host?: AgentHost;
+  /**
+   * Phase 20 (v1.2): when the agent loop resumes from a host.storage snapshot,
+   * the configured SurvivabilityAdapter handles the serialize/deserialize
+   * round-trip. When absent, runtime defaults to
+   * `createNoopSurvivabilityAdapter<AgentSnapshot>()`.
+   */
+  readonly survivabilityAdapter?: SurvivabilityAdapter<AgentSnapshot>;
+  readonly contract?: CapabilityContract;
+  readonly policy?: PolicySpec;
+  readonly outputs?: TOutputs;
+  readonly pipeline?: HookPipeline;
+  readonly signer?: ReceiptSigner;
+  readonly tracer?: TracerLike;
+  /**
+   * When `false`, the runtime will NOT auto-register `createCheckpointHook`
+   * even if `signer` is provided. Callers who want full manual control over
+   * receipt minting set this to `false` and register their own hook.
+   * Defaults to `true` (auto-register when signer present).
+   */
+  readonly autoRegisterCheckpoint?: boolean;
+}
+/**
+ * Success result returned by `ai.runAgent` when the loop reaches a final
+ * answer and (when `outputs` is declared) the final answer validates.
+ *
+ * `iterations[]` records every iteration that ran — including the one that
+ * produced the final answer. `receipt` is the outermost receipt minted at
+ * loop close when `signer` is configured (separate from per-iteration
+ * receipts on `iterations[i].receipt`).
+ */
+interface AgentSuccess<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly kind: "success";
+  readonly output: InferOutputMap<TOutputs>;
+  readonly artifacts?: readonly ArtifactRef[];
+  readonly usage: Usage;
+  readonly iterations: ReadonlyArray<IterationRecord>;
+  readonly receipt?: ReceiptEnvelope;
+}
+/**
+ * Failure kinds specific to the agent loop. v1.1 `LatticeRunError.kind`
+ * values remain valid (provider errors, no-contract-match, validation-failed,
+ * tripwire-violated) and are reused verbatim. Phase 19 adds three
+ * agent-specific kinds. Phase 39 (v1.3) adds `crew-budget-exceeded` —
+ * crew-level shared-pool exhaustion, terminal across the parent/child
+ * boundary (D-10).
+ */
+type AgentFailureKind = LatticeRunError["kind"] | "agent-iteration-denied" | "agent-max-iterations" | "agent-wall-time-exceeded" | "crew-budget-exceeded";
+/**
+ * Failure result returned by `ai.runAgent`. Discriminates via `kind`.
+ *
+ * `iterations[]` carries any iterations that completed before the failure
+ * (empty if the failure occurred pre-iteration). For `agent-iteration-denied`,
+ * the failing iteration is the LAST entry and carries `deniedReason`.
+ */
+interface AgentFailure {
+  readonly kind: AgentFailureKind;
+  readonly usage: Usage;
+  readonly iterations: ReadonlyArray<IterationRecord>;
+  readonly reason?: string;
+  readonly cause?: unknown;
+  readonly receipt?: ReceiptEnvelope;
+}
+/**
+ * Discriminated union returned by `ai.runAgent`.
+ */
+type AgentResult<TOutputs extends OutputContractMap = OutputContractMap> = AgentSuccess<TOutputs> | AgentFailure;
+/**
+ * Typed error raised when a SAFETY-band handler sets `controls.deny(reason)`
+ * during `BEFORE_AGENT_ITERATION`. Carries `terminal: true` semantics to
+ * align with v1.1 `TripwireViolationError`: the failure is NOT retried by
+ * the fallback chain.
+ *
+ * Surfaced via `AgentFailure { kind: "agent-iteration-denied", reason, ... }`
+ * — callers can also catch the typed error if they prefer.
+ */
+declare class AgentDeniedError extends Error {
+  readonly kind: "agent-iteration-denied";
+  readonly terminal: true;
+  readonly reason: string;
+  readonly iterationIndex: number;
+  constructor(reason: string, iterationIndex: number);
+}
+//#endregion
+//#region src/agent/crew/agent-spec.d.ts
+/**
+ * Crew member specification. A literal sibling of `ToolDefinition`
+ * discriminated by `kind: "agent"` (D-03).
+ */
+interface AgentSpec {
+  readonly kind: "agent";
+  readonly id: string;
+  readonly intent: string;
+  readonly tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>;
+  readonly childAgents?: ReadonlyArray<AgentSpec>;
+  readonly summaryReturnSchema: StandardSchemaV1;
+  /** Optional per-agent sub-budget (D-07). */
+  readonly contract?: CapabilityContract;
+}
+/**
+ * Factory for `AgentSpec` values. Mirrors `defineTool` exactly: spread
+ * preserves input identity (no cloning, no mutation) and absent optional
+ * members stay absent (`exactOptionalPropertyTypes`-safe).
+ */
+declare function defineAgent(definition: Omit<AgentSpec, "kind">): AgentSpec;
+//#endregion
+//#region src/agent/crew/crew-policy.d.ts
+/** Per-adapter rate-limit override (keyed by `adapter.id` in `limits`). */
+interface CrewRateLimitOverride {
+  readonly requestsPerMinute?: number;
+  readonly tokensPerMinute?: number;
+}
+/** Crew-level policy contract (D-06, D-11, D-16). */
+interface CrewPolicy {
+  /** Crew-level shared budget pool — `BudgetInvariant` reused verbatim. */
+  readonly budget?: BudgetInvariant;
+  readonly maxTotalIterations?: number;
+  readonly maxIterationsPerAgent?: number;
+  /** Forward-compat field; the v1.3 runtime rejects values > 1 (D-11). */
+  readonly maxConcurrentChildren?: number;
+  /** Delegation depth cap; defaults to 1 (parent→child only, D-05). */
+  readonly maxDepth?: number;
+  /** Per-adapter-id rate-limit overrides (D-16). */
+  readonly limits?: Readonly<Record<string, CrewRateLimitOverride>>;
+  /** "managed" (default) wraps transports in the rate-limit group; "unmanaged" skips it. */
+  readonly coordination?: "managed" | "unmanaged";
+}
+//#endregion
+//#region src/agent/crew/run-crew.d.ts
+interface RunAgentCrewOptions {
+  readonly root: AgentSpec;
+  readonly hosts: {
+    readonly childHost: AgentHost;
+  };
+  readonly policy?: CrewPolicy;
+  /** Crew-level signer threaded into member loops and completion receipts. */
+  readonly signer?: ReceiptSigner;
+  /** Crew-level tracer threaded into member loops. */
+  readonly tracer?: TracerLike;
+  /** Crew-level hook pipeline threaded into member loops. */
+  readonly pipeline?: HookPipeline;
+}
+interface CrewAgentResult {
+  readonly id: string;
+  readonly usage: Usage;
+  readonly iterations: number;
+  readonly receiptCids: readonly string[];
+}
+interface CrewResult {
+  /** Parent result, with parent output untouched on success. */
+  readonly result: AgentResult;
+  /** Per-agent accounting records, including root parent and completed children. */
+  readonly perAgent: ReadonlyArray<CrewAgentResult>;
+  /** Crew aggregate usage: parent total + sum(child totals), no double-counting. */
+  readonly usage: Usage;
+  /** Total iterations across every recorded agent. */
+  readonly totalIterations: number;
+  /** All crew completion receipts, including the crew-root envelope. */
+  readonly receipts: ReadonlyArray<ReceiptEnvelope>;
+  readonly crewRootCid?: string;
+}
+/**
+ * Execute a crew rooted at `options.root`.
+ */
+declare function runAgentCrew(options: RunAgentCrewOptions, config?: LatticeConfig): Promise<CrewResult>;
+//#endregion
+export { FormatToolsMode as A, HookDenyDirective as B, EvictionHook as C, UnsubscribeFn as D, SurvivabilityAdapter as E, LatticeConfig as F, createHookPipeline as G, HookLifecycleEvent as H, NormalizedLatticeConfig as I, BAND as L, FormattedToolsHandle as M, formatToolsForProvider as N, createNoopSurvivabilityAdapter as O, toolSchemaToJsonSchema as P, Band as R, createNoopAgentHost as S, SerializedSnapshot as T, HookPipeline as U, HookHandler as V, RegisterOptions as W, AgentHost as _, CrewPolicy as a, AgentStorage as b, defineAgent as c, AgentFailureKind as d, AgentIntent as f, IterationRecord as g, DefaultAgentOutputs as h, runAgentCrew as i, FormatToolsOptions as j, ConversationTurn as k, AgentDeniedError as l, AgentSuccess as m, CrewResult as n, CrewRateLimitOverride as o, AgentResult as p, RunAgentCrewOptions as r, AgentSpec as s, CrewAgentResult as t, AgentFailure as u, AgentScheduler as v, ResumePolicy as w, AgentTransport as x, AgentSnapshot as y, HookControls as z };
+//# sourceMappingURL=run-crew-Bnve5dyI.d.ts.map