@kodax-ai/kodax 0.7.50 → 0.7.52

package/dist/types-chunks/{process.d-BbiXD24v.d.ts → process.d-Bj82oJhD.d.ts}

@@ -1,5 +1,318 @@
-import { Y as KodaXToolDefinition, n as KodaXMessage, E as KodaXReasoningMode, _ as KodaXToolResultContentItem, U as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-rPRl2LSB.js';
-import { a as KodaXCompactMemorySeed, k as KodaXSessionArtifactLedgerEntry } from './types.d-BnjX2Gn4.js';
+import { o as KodaXMessage, $ as KodaXToolDefinition, G as KodaXReasoningMode, a1 as KodaXToolResultContentItem, X as KodaXThinkingBlock, J as KodaXRedactedThinkingBlock } from './base.d-BBNUF9nz.js';
+
+/**
+ * @kodax-ai/agent Types
+ *
+ * 通用 Agent 类型定义
+ */
+
+type KodaXJsonPrimitive = string | number | boolean | null;
+type KodaXJsonValue = KodaXJsonPrimitive | KodaXJsonValue[] | {
+    [key: string]: KodaXJsonValue;
+};
+/**
+ * Session error metadata - 会话错误元数据
+ * Used for error recovery and session cleanup - 用于错误恢复和会话清理
+ */
+interface SessionErrorMetadata {
+    /** Last error message - 最后的错误消息 */
+    lastError?: string;
+    /** Last error timestamp - 最后错误时间戳 */
+    lastErrorTime?: number;
+    /** Consecutive error count - 连续错误计数 */
+    consecutiveErrors: number;
+}
+interface KodaXExtensionSessionRecord {
+    id: string;
+    extensionId: string;
+    type: string;
+    ts: number;
+    data?: KodaXJsonValue;
+    dedupeKey?: string;
+}
+type KodaXExtensionSessionState = Record<string, Record<string, KodaXJsonValue>>;
+interface KodaXSessionEntryBase {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+interface KodaXSessionMessageEntry extends KodaXSessionEntryBase {
+    type: 'message';
+    message: KodaXMessage;
+}
+interface KodaXSessionCompactionEntry extends KodaXSessionEntryBase {
+    type: 'compaction';
+    summary: string;
+    firstKeptEntryId?: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    artifactLedgerId?: string;
+    reason?: string;
+    details?: KodaXJsonValue;
+    memorySeed?: KodaXCompactMemorySeed;
+    /**
+     * FEATURE_072: post-compact ledger summary + file-content messages that
+     * are inlined after the compaction summary at slicer time
+     * (`getSessionMessagesFromLineage`). Stored here so they leave the active
+     * path automatically when a new compaction entry is appended.
+     *
+     * NOTE: attachments are emitted by the slicer, NOT by `getContextMessagesForEntry`
+     * — preserving the latter's 1-to-1 contract that `entryMatchesContextMessage`
+     * and FEATURE_073's future slicing both depend on.
+     */
+    postCompactAttachments?: readonly KodaXMessage[];
+}
+interface KodaXSessionBranchSummaryEntry extends KodaXSessionEntryBase {
+    type: 'branch_summary';
+    summary: string;
+    fromId?: string;
+    details?: KodaXJsonValue;
+}
+interface KodaXSessionLabelEntry extends KodaXSessionEntryBase {
+    type: 'label';
+    targetId: string;
+    label?: string;
+}
+interface KodaXSessionArchiveMarkerEntry extends KodaXSessionEntryBase {
+    type: 'archive_marker';
+    /** Links to the corresponding batch in the .archive.jsonl sidecar file */
+    archiveBatchId: string;
+    /** Number of entries that were archived in this batch */
+    archivedEntryCount: number;
+    /** Brief summary of the archived content */
+    summary: string;
+}
+type KodaXGoalStatus = 'active' | 'paused' | 'budget_limited' | 'blocked' | 'complete';
+/**
+ * Persistent user-set goal state. v0.7.44 FEATURE_192 — backs the
+ * `/goal` slash command and the get_goal / create_goal / update_goal
+ * tools.
+ *
+ * Persistence model: each lifecycle event (create / update / pause /
+ * resume / clear / budget_limited / blocked / complete) appends a
+ * `KodaXSessionGoalEntry` carrying a frozen `KodaXGoalState` snapshot
+ * to the session lineage. `readLatestGoalFromBranch` walks the active
+ * branch's message-entry IDs and returns the latest goal entry whose
+ * parentId belongs to that branch — so forks and rewinds naturally
+ * drop goals attached to abandoned message paths.
+ */
+interface KodaXGoalState {
+    readonly version: 1;
+    /** `${createdAt}-${rand}` — stable across updates of the same goal. */
+    readonly id: string;
+    readonly objective: string;
+    readonly status: KodaXGoalStatus;
+    /** Optional explicit token budget; null when the user did not set one. */
+    readonly tokenBudget: number | null;
+    readonly tokensUsed: number;
+    readonly timeUsedSeconds: number;
+    /** Consecutive turns the model has reported the same blocker. */
+    readonly blockerTurnCount: number;
+    /** The blocker_kind string the model last reported, or null. */
+    readonly lastBlockerKind: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+type KodaXGoalEventType = 'created' | 'updated' | 'paused' | 'resumed' | 'cleared' | 'budget_limited' | 'blocked' | 'complete';
+interface KodaXSessionGoalEntry extends KodaXSessionEntryBase {
+    type: 'goal';
+    /** Snapshot at time of event; `null` only when `event === 'cleared'`. */
+    goal: KodaXGoalState | null;
+    event: KodaXGoalEventType;
+}
+type KodaXSessionEntry = KodaXSessionMessageEntry | KodaXSessionCompactionEntry | KodaXSessionBranchSummaryEntry | KodaXSessionLabelEntry | KodaXSessionArchiveMarkerEntry | KodaXSessionGoalEntry;
+interface KodaXSessionArtifactLedgerEntry {
+    id: string;
+    kind: 'file_read' | 'file_modified' | 'file_created' | 'file_deleted' | 'path_scope' | 'search_scope' | 'command_scope' | 'check_result' | 'decision' | 'image_input' | 'tombstone';
+    sourceTool?: string;
+    action?: string;
+    target: string;
+    displayTarget?: string;
+    summary?: string;
+    sessionEntryId?: string;
+    timestamp: string;
+    metadata?: Record<string, KodaXJsonValue>;
+}
+interface KodaXCompactMemoryProgress {
+    completed: string[];
+    inProgress: string[];
+    blockers: string[];
+}
+interface KodaXCompactMemorySeed {
+    objective?: string;
+    constraints: string[];
+    progress: KodaXCompactMemoryProgress;
+    keyDecisions: string[];
+    nextSteps: string[];
+    keyContext: string[];
+    importantTargets: string[];
+    tombstones: string[];
+}
+interface KodaXSessionLineage {
+    version: 2;
+    activeEntryId: string | null;
+    entries: KodaXSessionEntry[];
+}
+interface KodaXSessionNavigationOptions {
+    summarizeCurrentBranch?: boolean;
+}
+interface KodaXSessionTreeNode {
+    entry: Exclude<KodaXSessionEntry, KodaXSessionLabelEntry | KodaXSessionGoalEntry>;
+    children: KodaXSessionTreeNode[];
+    label?: string;
+    active: boolean;
+}
+type KodaXSessionScope = 'user' | 'managed-task-worker';
+type KodaXSessionUiTextHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint';
+type KodaXSessionUiHistoryItemType = KodaXSessionUiTextHistoryItemType | 'tool_group';
+interface KodaXSessionUiTextHistoryItem {
+    type: KodaXSessionUiTextHistoryItemType;
+    text: string;
+    icon?: string;
+    compactText?: string;
+}
+type KodaXSessionUiToolCallStatus = 'success' | 'error' | 'cancelled' | 'awaiting_approval';
+interface KodaXSessionUiToolCall {
+    id: string;
+    name: string;
+    status: KodaXSessionUiToolCallStatus;
+    input?: {
+        [key: string]: KodaXJsonValue;
+    };
+    preview?: string;
+    output?: string;
+    error?: string;
+    startTime?: number;
+    endTime?: number;
+}
+interface KodaXSessionUiToolGroupHistoryItem {
+    type: 'tool_group';
+    tools: KodaXSessionUiToolCall[];
+}
+type KodaXSessionUiHistoryItem = KodaXSessionUiTextHistoryItem | KodaXSessionUiToolGroupHistoryItem;
+type KodaXSessionWorkspaceKind = 'detected' | 'managed';
+interface KodaXSessionRuntimeInfo {
+    canonicalRepoRoot?: string;
+    workspaceRoot?: string;
+    executionCwd?: string;
+    branch?: string;
+    workspaceKind?: KodaXSessionWorkspaceKind;
+}
+interface KodaXSessionData {
+    messages: KodaXMessage[];
+    title: string;
+    gitRoot: string;
+    /** Consumer-owned private string persisted with the session. */
+    tag?: string;
+    runtimeInfo?: KodaXSessionRuntimeInfo;
+    scope?: KodaXSessionScope;
+    uiHistory?: KodaXSessionUiHistoryItem[];
+    errorMetadata?: SessionErrorMetadata;
+    extensionState?: KodaXExtensionSessionState;
+    extensionRecords?: KodaXExtensionSessionRecord[];
+    lineage?: KodaXSessionLineage;
+    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
+}
+interface KodaXSessionMeta {
+    _type: 'meta';
+    title: string;
+    id: string;
+    gitRoot: string;
+    /** Consumer-owned private string persisted with the session. */
+    tag?: string;
+    runtimeInfo?: KodaXSessionRuntimeInfo;
+    createdAt: string;
+    scope?: KodaXSessionScope;
+    uiHistory?: KodaXSessionUiHistoryItem[];
+    extensionState?: KodaXExtensionSessionState;
+    extensionRecordCount?: number;
+    artifactLedgerCount?: number;
+    lineageVersion?: 2;
+    activeEntryId?: string | null;
+    lineageEntryCount?: number;
+    activeMessageCount?: number;
+    /** Error metadata for recovery - 错误元数据用于恢复 */
+    errorMetadata?: SessionErrorMetadata;
+}
+/**
+ * Extension-scoped persistence entry.
+ *
+ * Each entry belongs to a namespace (extensionId) and carries
+ * a string key, a JSON-safe value, and an opaque version tag
+ * used for optimistic concurrency control.
+ */
+interface KodaXExtensionStoreEntry {
+    key: string;
+    value: KodaXJsonValue;
+    version: string;
+    updatedAt: number;
+}
+/**
+ * Extension persistence store interface (FEATURE_034 manual persistence).
+ *
+ * Implementations provide a durable key-value store scoped to a single
+ * extension identity.  The store is independent of session lifecycle —
+ * data survives across sessions and restarts.
+ */
+interface KodaXExtensionStore {
+    /**
+     * Read a single key.
+     * Returns `undefined` when the key does not exist.
+     */
+    get(key: string): Promise<KodaXExtensionStoreEntry | undefined>;
+    /**
+     * Write a key-value pair.
+     *
+     * When `expectedVersion` is provided the write only succeeds when the
+     * stored entry's version still matches (optimistic concurrency).
+     * Returns the new entry on success, or `false` on version mismatch.
+     */
+    put(key: string, value: KodaXJsonValue, options?: {
+        expectedVersion?: string;
+    }): Promise<KodaXExtensionStoreEntry | false>;
+    /**
+     * Remove a key.
+     * Returns `true` when the key existed and was removed.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * List all keys (optionally filtered by prefix).
+     */
+    list(options?: {
+        prefix?: string;
+    }): Promise<string[]>;
+    /**
+     * Clear all keys (optionally filtered by prefix).
+     * Returns the number of entries removed.
+     */
+    clear(options?: {
+        prefix?: string;
+    }): Promise<number>;
+}
+interface KodaXSessionStorage {
+    save(id: string, data: KodaXSessionData): Promise<void>;
+    load(id: string): Promise<KodaXSessionData | null>;
+    getLineage?(id: string): Promise<KodaXSessionLineage | null>;
+    setActiveEntry?(id: string, selector: string, options?: KodaXSessionNavigationOptions): Promise<KodaXSessionData | null>;
+    setLabel?(id: string, selector: string, label?: string): Promise<KodaXSessionData | null>;
+    rewind?(id: string, selector?: string): Promise<KodaXSessionData | null>;
+    fork?(id: string, selector?: string, options?: {
+        sessionId?: string;
+        title?: string;
+    }): Promise<{
+        sessionId: string;
+        data: KodaXSessionData;
+    } | null>;
+    list?(gitRoot?: string): Promise<Array<{
+        id: string;
+        title: string;
+        msgCount: number;
+        tag?: string;
+        runtimeInfo?: KodaXSessionRuntimeInfo;
+    }>>;
+    delete?(id: string): Promise<void>;
+    deleteAll?(gitRoot?: string): Promise<void>;
+}
 
 /**
  * Layer A Primitive: Agent / Handoff / Guardrail / AgentReasoningProfile
@@ -1667,157 +1980,6 @@ declare class Runner {
 /** @internal Exposed so preset dispatchers can extract the assistant text from a KodaXResult. */
 declare function extractAssistantTextFromMessage(message: AgentMessage): string;
 
-/**
- * Guardrail Runtime — FEATURE_085 (v0.7.26).
- *
- * Three-tier runtime for Agent guardrails:
- *
- *   - `InputGuardrail`: runs once before the first LLM turn, inspects the
- *     full input transcript, may allow / rewrite / block / escalate.
- *   - `OutputGuardrail`: runs once before returning, inspects the final
- *     assistant message, may allow / rewrite / block / escalate.
- *   - `ToolGuardrail`: runs before and/or after each tool invocation,
- *     inspects the call / result, may allow / rewrite / block / escalate.
- *
- * The four verdict actions:
- *
- *   - `allow`: continue with the current value.
- *   - `rewrite`: replace the current value with `payload`.
- *   - `block`: throw `GuardrailBlockedError` (for input/output) or surface
- *     an error tool_result (for tool-before); the LLM / caller sees a
- *     rejection and must adapt.
- *   - `escalate`: throw `GuardrailEscalateError`; the SDK consumer catches
- *     and decides whether to prompt the user, retry under different
- *     constraints, etc.
- *
- * Every guardrail invocation emits a `GuardrailSpan` under the agent's
- * span when tracing is active.
- *
- * @experimental API shape may adjust during v0.7.x rollout.
- */
-
-/**
- * Shared execution context passed to every guardrail.
- *
- * `messages` is the live conversation transcript at the moment this
- * guardrail fires. For tool-side guardrails this is the transcript at
- * call-site time — it does NOT yet include the assistant turn that
- * emitted the current tool_use, since that turn is appended only after
- * the full tool batch settles. Optional so existing guardrails that
- * don't read context still type-check; populated by the Runner for all
- * production hook points.
- *
- * Added in FEATURE_092 (v0.7.33) so the auto-mode classifier guardrail
- * can extract intent context (user prompt + prior tool_use / tool_result
- * blocks) without reaching into Runner internals.
- */
-interface GuardrailContext {
-    readonly agent: Agent;
-    readonly abortSignal?: AbortSignal;
-    readonly messages?: readonly AgentMessage[];
-}
-/**
- * Outcome of a single guardrail check. `payload` shape depends on the hook
- * point — see the specific guardrail interface for the expected type.
- */
-type GuardrailVerdict = {
-    readonly action: 'allow';
-} | {
-    readonly action: 'rewrite';
-    readonly payload: unknown;
-    readonly reason?: string;
-} | {
-    readonly action: 'block';
-    readonly reason: string;
-} | {
-    readonly action: 'escalate';
-    readonly reason: string;
-};
-/**
- * Input-side guardrail. Expected `rewrite` payload shape:
- * `readonly AgentMessage[]` — the replacement transcript.
- */
-interface InputGuardrail extends Guardrail {
-    readonly kind: 'input';
-    check(input: readonly AgentMessage[], ctx: GuardrailContext): Promise<GuardrailVerdict>;
-}
-/**
- * Output-side guardrail. Expected `rewrite` payload shape:
- * `AgentMessage` — the replacement final assistant message.
- */
-interface OutputGuardrail extends Guardrail {
-    readonly kind: 'output';
-    check(output: AgentMessage, ctx: GuardrailContext): Promise<GuardrailVerdict>;
-}
-/**
- * Tool-side guardrail. `beforeTool` rewrite payload shape: `RunnerToolCall`
- * (replacement call). `afterTool` rewrite payload shape: `RunnerToolResult`
- * (replacement result). Either hook is optional.
- */
-interface ToolGuardrail extends Guardrail {
-    readonly kind: 'tool';
-    beforeTool?(call: RunnerToolCall, ctx: GuardrailContext): Promise<GuardrailVerdict>;
-    afterTool?(call: RunnerToolCall, result: RunnerToolResult, ctx: GuardrailContext): Promise<GuardrailVerdict>;
-}
-/**
- * Thrown when any guardrail returns `{ action: 'block' }`. The Runner
- * propagates this up to the caller — the run is aborted at that point.
- */
-declare class GuardrailBlockedError extends Error {
-    readonly guardrailName: string;
-    readonly hookPoint: 'input' | 'output' | 'tool';
-    constructor(guardrailName: string, hookPoint: 'input' | 'output' | 'tool', reason: string);
-}
-/**
- * Thrown when any guardrail returns `{ action: 'escalate' }`. Callers can
- * catch and prompt the user or apply a stricter policy before retrying.
- */
-declare class GuardrailEscalateError extends Error {
-    readonly guardrailName: string;
-    readonly hookPoint: 'input' | 'output' | 'tool';
-    constructor(guardrailName: string, hookPoint: 'input' | 'output' | 'tool', reason: string);
-}
-/** Filter a guardrail list by hook-point. */
-declare function collectGuardrails(guardrails: readonly Guardrail[] | undefined): {
-    input: readonly InputGuardrail[];
-    output: readonly OutputGuardrail[];
-    tool: readonly ToolGuardrail[];
-};
-/**
- * Run all input guardrails in declaration order. Returns the (possibly
- * rewritten) transcript. Throws on block / escalate.
- */
-declare function runInputGuardrails(transcript: readonly AgentMessage[], guardrails: readonly InputGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<readonly AgentMessage[]>;
-/**
- * Run all output guardrails in declaration order. Returns the (possibly
- * rewritten) final assistant message. Throws on block / escalate.
- */
-declare function runOutputGuardrails(output: AgentMessage, guardrails: readonly OutputGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<AgentMessage>;
-/**
- * Outcome of the before-tool guardrail stage.
- *   - `{ kind: 'allow', call }`: continue to executeRunnerToolCall with `call`
- *   - `{ kind: 'block', result }`: skip execution; return `result` as the
- *     tool_result to the LLM (so it sees the rejection and can adapt)
- */
-type ToolBeforeOutcome = {
-    readonly kind: 'allow';
-    readonly call: RunnerToolCall;
-} | {
-    readonly kind: 'block';
-    readonly result: RunnerToolResult;
-};
-/**
- * Run before-tool guardrails in declaration order. Rewrite replaces the
- * tool call. Block surfaces an error tool_result to the LLM instead of
- * throwing — the LLM sees the rejection and adapts. Escalate still throws.
- */
-declare function runToolBeforeGuardrails(call: RunnerToolCall, guardrails: readonly ToolGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<ToolBeforeOutcome>;
-/**
- * Run after-tool guardrails in declaration order. Rewrite replaces the
- * result content. Block replaces with an error result. Escalate throws.
- */
-declare function runToolAfterGuardrails(call: RunnerToolCall, result: RunnerToolResult, guardrails: readonly ToolGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<RunnerToolResult>;
-
 /**
  * FEATURE_222 — user-interaction primitive (agent layer).
  *
@@ -1884,124 +2046,6 @@ declare function setActiveUserInteraction(interaction: UserInteraction | undefin
 /** The live user-interaction surface, or undefined when none is active. */
 declare function getActiveUserInteraction(): UserInteraction | undefined;
 
-/**
- * @kodax-ai/agent/messaging — Message queue types
- *
- * FEATURE_115 (v0.7.36): agentId-scoped 2-tier priority queue infrastructure.
- *
- * Per ADR-021: messaging is a generic agent-platform primitive (not coding-
- * specific). Downstream consumers:
- *   - @kodax-ai/coding runner-driven mid-turn drain
- *   - @kodax-ai/repl InkREPL ESC soft-pause + text injection (FEATURE_111 absorbed)
- *   - subagent task-notification routing (FEATURE_155 idle-yield wakeup)
- *
- * Phase 0.6 study (`c:/tmp/claude-code-actual-usage.md`): Claude Code's
- * `'now'` priority has zero production usage; KodaX simplifies to 2 tiers.
- */
-type MessagePriority = 'user' | 'background';
-type MessageMode = 'prompt' | 'task-notification' | 'system-reminder';
-interface QueuedMessage {
-    /** Stable id for tracing / dedup. Format: `msg-<sequence>`. */
-    readonly id: string;
-    readonly priority: MessagePriority;
-    /**
-     * Routing key:
-     *   undefined = main thread / coordinator agent
-     *   'agent-id-XYZ' = subagent / specific consumer
-     *
-     * Drain consumers MUST filter by agentId match — undefined matches only
-     * undefined-agentId messages, not "any agent".
-     */
-    readonly agentId?: string;
-    readonly mode: MessageMode;
-    readonly content: string;
-    /** Wall-clock timestamp (`Date.now()`) for tracing only — not used for ordering. */
-    readonly enqueuedAt: number;
-}
-interface DequeueFilter {
-    /**
-     * Only return messages with this agentId.
-     * undefined matches messages with no agentId (main-thread messages only).
-     */
-    readonly agentId?: string;
-    /**
-     * Highest priority level included in the drain.
-     *   'user'       → only user priority drained, background stays queued
-     *   'background' → both user + background drained (Sleep-gated case)
-     */
-    readonly maxPriority: MessagePriority;
-    /**
-     * Optional cap on number of messages drained in this call.
-     * Defaults to unlimited (drains all matching).
-     */
-    readonly limit?: number;
-    /**
-     * FEATURE_159 (v0.7.40) — optional mode filter. Lets REPL split the
-     * single queue into mode-typed views (e.g. `mode:'prompt'` for user
-     * input vs `mode:'task-notification'` for child completion banners)
-     * without separate queues. When omitted, all modes match.
-     */
-    readonly mode?: MessageMode;
-    /**
-     * FEATURE_159 (v0.7.40) — optional precise-id filter. Single-message
-     * targeted removal — drives Esc-pop-this-uuid in REPL. When set, all
-     * other filters still apply (agentId / priority / mode mismatches still
-     * skip the message), so callers can't accidentally remove a message
-     * outside their scope.
-     */
-    readonly id?: string;
-    /**
-     * FEATURE_159 (v0.7.40) — optional escape-hatch predicate, AND-ed with
-     * the structured filters. Lets SDK consumers express conditions the
-     * typed fields don't cover (e.g. timestamp ranges, content-match) without
-     * forcing every new use case to extend `DequeueFilter`. KodaX-internal
-     * code should prefer the typed fields for readability; this is the
-     * "data-driven main path + predicate escape" pattern.
-     *
-     * Evaluated AFTER the typed filters succeed — so a `predicate` that
-     * inspects `message.content` never runs on messages outside the
-     * caller's `agentId` / `mode` / `id` scope.
-     */
-    readonly predicate?: (message: QueuedMessage) => boolean;
-}
-/**
- * FEATURE_159 (v0.7.40) — structured queue event emitted to subscribers.
- *
- * Replaces the prior `() => void` bare-notify signal. Carries the kind +
- * affected messages so SDK observability consumers (logging, tracing,
- * metrics) can react per-event without re-diffing snapshots.
- *
- * Event granularity rules:
- *   - `enqueued` fires ONCE per `enqueue()` call (always 1 message).
- *   - `dequeued` fires ONCE per `dequeue()` call that removed ≥1 message,
- *     carrying ALL drained messages in priority+FIFO order. No-op drains
- *     (filter matched nothing) fire no event — quiet by design so the
- *     `waitForWakeEvent` 100ms poll doesn't spam idle subscribers.
- *   - `cleared` fires ONCE per `clear()` call that removed ≥1 message,
- *     carrying the pre-clear messages. Empty-queue clear fires nothing.
- *
- * The `useSyncExternalStore` React hook ignores the event payload (it
- * only needs the change signal); SDK / tracer consumers read the event.
- */
-type QueueEvent = {
-    readonly kind: 'enqueued';
-    readonly message: QueuedMessage;
-} | {
-    readonly kind: 'dequeued';
-    readonly messages: readonly QueuedMessage[];
-} | {
-    readonly kind: 'cleared';
-    readonly messages: readonly QueuedMessage[];
-};
-/** FEATURE_159 — `MessageQueue.subscribe` listener signature. */
-type QueueEventListener = (event: QueueEvent) => void;
-interface EnqueueInput {
-    readonly priority: MessagePriority;
-    readonly mode: MessageMode;
-    readonly content: string;
-    readonly agentId?: string;
-}
-
 /**
  * Child task registry primitive — generic fan-out tracking.
  *
@@ -2468,7 +2512,7 @@ interface FileOperations {
  * injected clock). The run graph models agent relationships as a
  * thread/edge/event stream, not just a final summary blob.
  */
-type WorkflowEventType = 'workflow_started' | 'phase_started' | 'phase_finished' | 'agent_spawned' | 'agent_message_sent' | 'agent_completed' | 'agent_summary_updated' | 'agent_stopped' | 'workflow_log' | 'artifact_written' | 'synthesis_completed' | 'workflow_completed' | 'workflow_stopped' | 'workflow_failed';
+type WorkflowEventType = 'workflow_started' | 'phase_started' | 'phase_finished' | 'agent_spawned' | 'agent_message_sent' | 'agent_completed' | 'agent_unverified' | 'agent_failed' | 'agent_summary_updated' | 'agent_stopped' | 'workflow_log' | 'artifact_written' | 'synthesis_completed' | 'workflow_completed' | 'workflow_stopped' | 'workflow_failed';
 interface WorkflowEvent {
     /** Monotonic sequence number — stable append ordering. */
     readonly seq: number;
@@ -2504,12 +2548,32 @@ declare class WorkflowEventRecorder {
  * dependency (ADR-021 layer independence).
  */
 /** Lifecycle status of a single workflow-spawned agent. */
-type WorkflowTaskStatus = 'running' | 'completed' | 'failed' | 'stopped';
+type WorkflowTaskStatus = 'running' | 'completed' | 'completed_unverified' | 'failed' | 'stopped';
 /** Routing hint for which provider/model tier the child should use. */
 type WorkflowModelHint = 'fast' | 'balanced' | 'deep';
 /** Isolation policy for a spawned agent. `shared-cwd` is the default
  *  (FEATURE_188); `worktree` is opt-in for high-risk parallel writes. */
 type WorkflowIsolation = 'shared-cwd' | 'worktree';
+/**
+ * Machine-checkable postconditions for a workflow child task. The agent
+ * package only defines the contract; concrete backends decide which evidence
+ * they can verify.
+ */
+interface WorkflowTaskVerification {
+    readonly enforcement?: 'hard' | 'warn';
+    readonly requiresMutation?: boolean;
+    readonly requiredChangedPaths?: readonly string[];
+    readonly minFinalTextChars?: number;
+    readonly rejectPreparatoryFinalText?: boolean;
+}
+interface WorkflowTaskVerificationResult {
+    readonly ok: boolean;
+    readonly enforcement?: 'hard' | 'warn';
+    readonly reasons: readonly string[];
+    readonly changedPaths?: readonly string[];
+    readonly mutationToolCalls?: readonly string[];
+    readonly mutationEvidence?: boolean;
+}
 interface WorkflowSpawnAgentInput {
     /** Human-readable label for the agent — surfaces in events / UI. */
     readonly name: string;
@@ -2525,6 +2589,8 @@ interface WorkflowSpawnAgentInput {
     readonly isolation?: WorkflowIsolation;
     /** Evidence refs (`task_id:<id>` etc.) seeded into the child context. */
     readonly evidenceRefs?: readonly string[];
+    /** Optional machine-checkable postconditions for this child task. */
+    readonly verification?: WorkflowTaskVerification;
 }
 /** Returned by `spawnAgent` — the child is in-flight, not yet complete. */
 interface WorkflowTaskHandle {
@@ -2554,6 +2620,10 @@ interface WorkflowTaskResult {
     readonly digestFailed?: boolean;
     /** True when a digest was scheduled asynchronously and may arrive via `agent_summary_updated`. */
     readonly digestPending?: boolean;
+    /** Task postcondition check, when a backend evaluated one. */
+    readonly verification?: WorkflowTaskVerificationResult;
+    /** True when the child exhausted its iteration budget before completing. */
+    readonly limitReached?: boolean;
     /** Best-known provider/model used by the child, for host correlation only. */
     readonly provider?: string;
     readonly model?: string;
@@ -2782,6 +2852,7 @@ interface WorkflowProcessSnapshot {
     readonly sourceRunId?: string;
     readonly sourceWorkflowName?: string;
     readonly revisionOf?: string;
+    readonly hostMetadata?: Record<string, string>;
     readonly activePhaseId?: string;
     readonly activePhaseIndex?: number;
     readonly phaseCount?: number;
@@ -2815,6 +2886,7 @@ interface WorkflowProcessTrackerOptions {
     readonly sourceRunId?: string;
     readonly sourceWorkflowName?: string;
     readonly revisionOf?: string;
+    readonly hostMetadata?: Record<string, string>;
     readonly phases?: readonly string[];
     readonly maxAgents?: number;
     readonly plannedAgents?: number;
@@ -2835,7 +2907,8 @@ interface WorkflowProcessTracker {
     getSnapshot(): WorkflowProcessSnapshot;
 }
 declare function isFinalWorkflowProcessStatus(status: WorkflowProcessStatus): boolean;
+declare function normalizeHostMetadata(value: unknown): Record<string, string> | undefined;
 declare function createWorkflowProcessTracker(options: WorkflowProcessTrackerOptions): WorkflowProcessTracker;
 
-export { DEFAULT_SYSTEM_CAP as D, GuardrailBlockedError as H, GuardrailEscalateError as J, InvariantSession as T, MAX_TOOL_LOOP_ITERATIONS as U, Tracer as aR, Runner as af, SpanImpl as ax, requestTaskStop as b$, WorkflowEventRecorder as b0, _resetAdmittedAgentBindings as bC, _resetPresetDispatchers as bD, buildAssistantMessageFromLlmResult as bE, buildSystemPrompt as bF, buildToolResultMessage as bG, collectGuardrails as bH, createAgent as bI, createHandoff as bJ, createInMemorySession as bK, createInvariantSessionForAgent as bL, createStateWriter as bM, createTrace as bN, createWorkflowProcessTracker as bO, defaultTracer as bP, detectInstructionsInjection as bQ, discoverInstances as bR, executeRunnerToolCall as bS, extractAssistantTextFromMessage as bT, getActiveUserInteraction as bU, getAdmittedAgentBindings as bV, isFinalWorkflowProcessStatus as bW, isRunnableTool as bX, isRunnerLlmResult as bY, registerChildTask as bZ, registerPresetDispatcher as b_, runAdmissionAudit as c0, runInputGuardrails as c1, runOutputGuardrails as c2, runToolAfterGuardrails as c3, runToolBeforeGuardrails as c4, setActiveUserInteraction as c5, setAdmittedAgentBindings as c6 };
-export type { PersistedSessionState as $, AdmissionAuditOptions as A, Guardrail as B, ChildTaskRegistry as C, EnqueueInput as E, FanoutSpanData as F, GenerationSpanData as G, GuardrailContext as I, GuardrailSpanData as K, GuardrailVerdict as L, Handoff as M, HandoffSpanData as N, InMemorySessionOptions as O, InputGuardrail as P, InstanceDiscoveryFs as Q, InvariantId as R, InvariantResult as S, ManifestPatch as V, MessageEntry as W, MessageMode as X, MessagePriority as Y, ObserveCtx as Z, OutputGuardrail as _, AdmissionCtx as a, WorkflowEventCorrelation as a$, PresetDispatcher as a0, PresetTracingContext as a1, QualityInvariant as a2, QueueEventListener as a3, QueuedMessage as a4, ReadonlyMutationTracker as a5, ReadonlyRecorder as a6, ReasoningDepth as a7, RecentlyModifiedFile as a8, RequestTaskStopOptions as a9, StateWriter as aA, StateWriterFs as aB, StateWriterOptions as aC, StopHookContext as aD, StopHookFn as aE, StopHookResult as aF, StopHookSpanData as aG, SystemCap as aH, TaskAbortRegistry as aI, TerminalCtx as aJ, ToolBeforeOutcome as aK, ToolCallSpanData as aL, ToolCapability as aM, ToolGuardrail as aN, ToolPermission as aO, Trace as aP, TraceOptions as aQ, TracerOptions as aS, UserInteraction as aT, WorkflowAgentBackend as aU, WorkflowApi as aV, WorkflowApproval as aW, WorkflowApprovalSummary as aX, WorkflowArtifactRef as aY, WorkflowBudget as aZ, WorkflowEvent as a_, RequestTaskStopResult as aa, RunEvent as ab, RunOptions as ac, RunResult as ad, RunnableTool as ae, RunnerEvent as ag, RunnerLlmResult as ah, RunnerLlmReturn as ai, RunnerToolCall as aj, RunnerToolContext as ak, RunnerToolObserver as al, RunnerToolResult as am, Session as an, SessionDispatchResult as ao, SessionEntry as ap, SessionExtension as aq, SessionForkOptions as ar, SessionMeta as as, SessionStateSnapshot as at, Span as au, SpanData as av, SpanError as aw, SpanImplOptions as ay, StartTraceOptions as az, AdmissionVerdict as b, WorkflowEventType as b1, WorkflowIsolation as b2, WorkflowLimits as b3, WorkflowLogEvent as b4, WorkflowMeta as b5, WorkflowModelHint as b6, WorkflowModule as b7, WorkflowParallelOptions as b8, WorkflowProcessArtifact as b9, WorkflowTaskUsage as bA, WorkflowWaitOptions as bB, WorkflowProcessCounts as ba, WorkflowProcessEvent as bb, WorkflowProcessItem as bc, WorkflowProcessItemKind as bd, WorkflowProcessItemStatus as be, WorkflowProcessProgress as bf, WorkflowProcessSnapshot as bg, WorkflowProcessSource as bh, WorkflowProcessStatus as bi, WorkflowProcessSummaryStatus as bj, WorkflowProcessTokenUsage as bk, WorkflowProcessTracker as bl, WorkflowProcessTrackerOptions as bm, WorkflowRun as bn, WorkflowRunState as bo, WorkflowRunStatus as bp, WorkflowSpawnAgentInput as bq, WorkflowSynthesis as br, WorkflowSynthesizeInput as bs, WorkflowTaskHandle as bt, WorkflowTaskResult as bu, WorkflowTaskSnapshot as bv, WorkflowTaskStatus as bw, WorkflowTaskSummaryEventUpdate as bx, WorkflowTaskSummaryKind as by, WorkflowTaskSummaryUpdate as bz, AdmittedHandle as c, Agent as d, AgentManifest as e, AgentMessage as f, AgentMiddlewareDeclaration as g, AgentReasoningProfile as h, AgentSpanData as i, AgentTool as j, AskUserMultiOptions as k, AskUserQuestionItem as l, AskUserQuestionOptions as m, CompactionAnchor as n, CompactionConfig as o, CompactionDetails as p, CompactionResult as q, CompactionSpanData as r, CompactionUpdate as s, CurrentTodoSummary as t, Deliverable as u, DequeueFilter as v, DiscoveredInstance as w, DiscoveryOptions as x, EvidenceSpanData as y, FileOperations as z };
+export { DEFAULT_SYSTEM_CAP as D, InvariantSession as M, Runner as aC, SpanImpl as aV, MAX_TOOL_LOOP_ITERATIONS as ak, _resetPresetDispatchers as b$, _resetAdmittedAgentBindings as b_, Tracer as bb, WorkflowEventRecorder as bm, buildAssistantMessageFromLlmResult as c0, buildSystemPrompt as c1, buildToolResultMessage as c2, createAgent as c3, createHandoff as c4, createInMemorySession as c5, createInvariantSessionForAgent as c6, createStateWriter as c7, createTrace as c8, createWorkflowProcessTracker as c9, defaultTracer as ca, detectInstructionsInjection as cb, discoverInstances as cc, executeRunnerToolCall as cd, extractAssistantTextFromMessage as ce, getActiveUserInteraction as cf, getAdmittedAgentBindings as cg, isFinalWorkflowProcessStatus as ch, isRunnableTool as ci, isRunnerLlmResult as cj, normalizeHostMetadata as ck, registerChildTask as cl, registerPresetDispatcher as cm, requestTaskStop as cn, runAdmissionAudit as co, setActiveUserInteraction as cp, setAdmittedAgentBindings as cq };
+export type { KodaXSessionData as $, AdmissionAuditOptions as A, HandoffSpanData as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, InMemorySessionOptions as I, InstanceDiscoveryFs as J, InvariantId as K, InvariantResult as L, KodaXCompactMemoryProgress as N, KodaXCompactMemorySeed as O, KodaXExtensionSessionRecord as P, KodaXExtensionSessionState as Q, KodaXExtensionStore as R, KodaXExtensionStoreEntry as S, KodaXGoalEventType as T, KodaXGoalState as U, KodaXGoalStatus as V, KodaXJsonValue as W, KodaXSessionArchiveMarkerEntry as X, KodaXSessionArtifactLedgerEntry as Y, KodaXSessionBranchSummaryEntry as Z, KodaXSessionCompactionEntry as _, AdmissionCtx as a, StopHookContext as a$, KodaXSessionEntry as a0, KodaXSessionEntryBase as a1, KodaXSessionGoalEntry as a2, KodaXSessionLabelEntry as a3, KodaXSessionLineage as a4, KodaXSessionMessageEntry as a5, KodaXSessionMeta as a6, KodaXSessionNavigationOptions as a7, KodaXSessionRuntimeInfo as a8, KodaXSessionScope as a9, RunResult as aA, RunnableTool as aB, RunnerEvent as aD, RunnerLlmResult as aE, RunnerLlmReturn as aF, RunnerToolCall as aG, RunnerToolContext as aH, RunnerToolObserver as aI, RunnerToolResult as aJ, Session as aK, SessionDispatchResult as aL, SessionEntry as aM, SessionErrorMetadata as aN, SessionExtension as aO, SessionForkOptions as aP, SessionMeta as aQ, SessionStateSnapshot as aR, Span as aS, SpanData as aT, SpanError as aU, SpanImplOptions as aW, StartTraceOptions as aX, StateWriter as aY, StateWriterFs as aZ, StateWriterOptions as a_, KodaXSessionStorage as aa, KodaXSessionTreeNode as ab, KodaXSessionUiHistoryItem as ac, KodaXSessionUiHistoryItemType as ad, KodaXSessionUiTextHistoryItem as ae, KodaXSessionUiTextHistoryItemType as af, KodaXSessionUiToolCall as ag, KodaXSessionUiToolCallStatus as ah, KodaXSessionUiToolGroupHistoryItem as ai, KodaXSessionWorkspaceKind as aj, ManifestPatch as al, MessageEntry as am, ObserveCtx as an, PersistedSessionState as ao, PresetDispatcher as ap, PresetTracingContext as aq, QualityInvariant as ar, ReadonlyMutationTracker as as, ReadonlyRecorder as at, ReasoningDepth as au, RecentlyModifiedFile as av, RequestTaskStopOptions as aw, RequestTaskStopResult as ax, RunEvent as ay, RunOptions as az, AdmissionVerdict as b, StopHookFn as b0, StopHookResult as b1, StopHookSpanData as b2, SystemCap as b3, TaskAbortRegistry as b4, TerminalCtx as b5, ToolCallSpanData as b6, ToolCapability as b7, ToolPermission as b8, Trace as b9, WorkflowProcessItemStatus as bA, WorkflowProcessProgress as bB, WorkflowProcessSnapshot as bC, WorkflowProcessSource as bD, WorkflowProcessStatus as bE, WorkflowProcessSummaryStatus as bF, WorkflowProcessTokenUsage as bG, WorkflowProcessTracker as bH, WorkflowProcessTrackerOptions as bI, WorkflowRun as bJ, WorkflowRunState as bK, WorkflowRunStatus as bL, WorkflowSpawnAgentInput as bM, WorkflowSynthesis as bN, WorkflowSynthesizeInput as bO, WorkflowTaskHandle as bP, WorkflowTaskResult as bQ, WorkflowTaskSnapshot as bR, WorkflowTaskStatus as bS, WorkflowTaskSummaryEventUpdate as bT, WorkflowTaskSummaryKind as bU, WorkflowTaskSummaryUpdate as bV, WorkflowTaskUsage as bW, WorkflowTaskVerification as bX, WorkflowTaskVerificationResult as bY, WorkflowWaitOptions as bZ, TraceOptions as ba, TracerOptions as bc, UserInteraction as bd, WorkflowAgentBackend as be, WorkflowApi as bf, WorkflowApproval as bg, WorkflowApprovalSummary as bh, WorkflowArtifactRef as bi, WorkflowBudget as bj, WorkflowEvent as bk, WorkflowEventCorrelation as bl, WorkflowEventType as bn, WorkflowIsolation as bo, WorkflowLimits as bp, WorkflowLogEvent as bq, WorkflowMeta as br, WorkflowModelHint as bs, WorkflowModule as bt, WorkflowParallelOptions as bu, WorkflowProcessArtifact as bv, WorkflowProcessCounts as bw, WorkflowProcessEvent as bx, WorkflowProcessItem as by, WorkflowProcessItemKind as bz, AdmittedHandle as c, Agent as d, AgentManifest as e, AgentMessage as f, AgentMiddlewareDeclaration as g, AgentReasoningProfile as h, AgentSpanData as i, AgentTool as j, AskUserMultiOptions as k, AskUserQuestionItem as l, AskUserQuestionOptions as m, CompactionAnchor as n, CompactionConfig as o, CompactionDetails as p, CompactionResult as q, CompactionSpanData as r, CompactionUpdate as s, CurrentTodoSummary as t, Deliverable as u, DiscoveredInstance as v, DiscoveryOptions as w, FileOperations as x, Guardrail as y, GuardrailSpanData as z };