@kodax-ai/kodax 0.7.56 → 0.7.58

package/dist/types-chunks/capability-learning.d-DRV80ISB.d.ts

@@ -0,0 +1,29 @@
+import { F as KodaXReasoningProfile } from './types.d-Ci5YPFEh.js';
+
+type CapabilityCacheSource = 'observed' | 'probed';
+interface CapabilityCacheEntry {
+    /** Efforts this provider/model rejected; removed from the effective ladder. */
+    readonly rejected: readonly string[];
+    /** How the rejection was learned. */
+    readonly source: CapabilityCacheSource;
+    /** ISO timestamp of the last update. */
+    readonly updatedAt: string;
+}
+/** Keyed by `provider/model`. */
+type CapabilityCache = Record<string, CapabilityCacheEntry>;
+declare function capabilityCacheKey(provider: string, model: string | undefined): string;
+/**
+ * Narrow a reasoning profile by learned hard rejections.
+ *
+ * Learning only removes rungs. Provider acceptance is not proof that an effort
+ * is semantically distinct, but a hard rejection is ground truth that the rung
+ * should not be sent again for this provider/model.
+ */
+declare function narrowReasoningProfile(profile: KodaXReasoningProfile, rejected: readonly string[]): KodaXReasoningProfile;
+declare function getRejectedEfforts(cache: CapabilityCache, provider: string, model: string | undefined): readonly string[];
+declare function addRejectedEffort(cache: CapabilityCache, provider: string, model: string | undefined, effort: string, source: CapabilityCacheSource, updatedAt: string): CapabilityCache;
+declare function removeCacheEntry(cache: CapabilityCache, provider?: string, model?: string): CapabilityCache;
+declare function sanitizeCapabilityCache(raw: unknown): CapabilityCache;
+
+export { addRejectedEffort as c, capabilityCacheKey as d, getRejectedEfforts as g, narrowReasoningProfile as n, removeCacheEntry as r, sanitizeCapabilityCache as s };
+export type { CapabilityCache as C, CapabilityCacheEntry as a, CapabilityCacheSource as b };

package/dist/types-chunks/{cost-tracker.d-wRtyEW9d.d.ts → cost-tracker.d-CBLk1fiD.d.ts}

@@ -1,3 +1,25 @@
+interface KodaXLlmTimeoutConfig {
+    /** Main provider request hard timeout, in seconds. Default 600s. */
+    readonly requestTimeoutSec?: number;
+    /** Idle timeout between stream deltas, in seconds. Set 0 to disable. Default 0. */
+    readonly streamIdleTimeoutSec?: number;
+    /** Per stream chunk timeout, in seconds. Default 30s. */
+    readonly chunkTimeoutSec?: number;
+    /** Maximum retry delay, in seconds. Default 60s. */
+    readonly maxRetryDelaySec?: number;
+}
+interface KodaXResolvedLlmTimeoutConfig {
+    readonly requestTimeoutMs?: number;
+    readonly streamIdleTimeoutMs?: number;
+    readonly chunkTimeoutMs?: number;
+    readonly maxRetryDelayMs?: number;
+}
+declare function timeoutSecToMs(value: number | undefined, label: string, opts?: {
+    readonly allowZero?: boolean;
+}): number | undefined;
+declare function parseTimeoutSecEnvMs(raw: string | undefined): number | undefined;
+declare function resolveLlmTimeoutConfig(timeouts: KodaXLlmTimeoutConfig | undefined): KodaXResolvedLlmTimeoutConfig | undefined;
+
 /**
  * KodaX Cost Rates - Multi-Provider pricing table
  *
@@ -106,5 +128,5 @@ declare function getSummary(tracker: CostTracker): SessionCostSummary;
 declare function formatCost(usd: number): string;
 declare function formatCostReport(summary: SessionCostSummary): string;
 
-export { DEFAULT_COST_RATES as D, createCostTracker as b, calculateCost as c, formatCostReport as d, getSummary as e, formatCost as f, getCostRate as g, recordUsage as h, recordRetry as r };
-export type { CostRate as C, ProviderCostSummary as P, RetryRecord as R, SessionCostSummary as S, TokenUsageRecord as T, CostTracker as a };
+export { DEFAULT_COST_RATES as D, calculateCost as c, createCostTracker as d, formatCostReport as e, formatCost as f, getCostRate as g, getSummary as h, recordUsage as i, resolveLlmTimeoutConfig as j, parseTimeoutSecEnvMs as p, recordRetry as r, timeoutSecToMs as t };
+export type { CostRate as C, KodaXLlmTimeoutConfig as K, ProviderCostSummary as P, RetryRecord as R, SessionCostSummary as S, TokenUsageRecord as T, CostTracker as a, KodaXResolvedLlmTimeoutConfig as b };

package/dist/types-chunks/{guardrail.d-DQQknOfb.d.ts → guardrail.d-iK7FwMdW.d.ts}

@@ -1,8 +1,8 @@
 import { M as McpConnectMode, a as McpServerConfig, b as McpServersConfig, c as McpTransportKind } from './config.d-CJy1WENT.js';
-import { K as KodaXBaseProvider } from './base.d-CwPfI8WQ.js';
-import { a as CostTracker } from './cost-tracker.d-wRtyEW9d.js';
-import { aG as RunnerToolCall } from './process.d-BdiIUr8T.js';
-import { f as ToolGuardrail } from './types.d-BKuHSiR0.js';
+import { K as KodaXBaseProvider } from './base.d-BA9Doaj_.js';
+import { a as CostTracker } from './cost-tracker.d-CBLk1fiD.js';
+import { aO as RunnerToolCall } from './process.d-DHow2y2G.js';
+import { g as ToolGuardrail } from './types.d-D4ZA8LJV.js';
 
 /**
  * FEATURE_200 Phase F (v0.7.45) — MCP domain types extracted from types.ts.
@@ -360,6 +360,21 @@ signals?: readonly ToolCallSignal[]) => Promise<AutoModeAskUserVerdict>;
 interface AutoModeGuardrailConfig {
     readonly rules: AutoRules;
     readonly claudeMd?: string;
+    /**
+     * FEATURE_092 follow-up (auto-mode classifier AGENTS.md staleness fix):
+     * live getter for the project AGENTS.md content. Takes precedence over the
+     * static `claudeMd` string and is evaluated INSIDE the classify path on
+     * every call — same live-getter pattern as `getDefaultProvider` /
+     * `getDefaultModel` (v0.7.34 hotfix-3).
+     *
+     * The bug it fixes: the guardrail is a lazy-cached singleton, so a
+     * captured `claudeMd` string froze the project rules at first
+     * construction. Even `/reload` couldn't refresh it — the classifier kept
+     * judging tool calls against a stale AGENTS.md snapshot. The REPL wires
+     * this to `loadAgentsFiles` (mtime-cached), so the classifier sees the
+     * same fresh project rules the system prompt does.
+     */
+    readonly getClaudeMd?: () => string | undefined;
     /**
      * FEATURE_092 phase 2b.7b: optional user-prompt callback for escalate
      * paths. See `AutoModeAskUser` for semantics.
@@ -470,14 +485,21 @@ interface AutoModeGuardrailConfig {
     /**
      * Speculative-classify quiet window (ms). When a classifier promise
      * settles within this window, the guardrail uses the verdict directly
-     * (no confirm dialog). When the window expires, the call escalates to
-     * the user; the background classifier is left running for cost-tracker
-     * settlement but its eventual result is discarded in v1 (UI doesn't
-     * adopt late verdicts yet).
+     * with no perceptible latency.
+     *
+     * Issue 143 (WS1): when the window expires the guardrail does NOT
+     * hard-escalate — it waits for the real classifier verdict and adopts it
+     * (late-verdict adoption). The window therefore only controls "fast path
+     * vs wait", never "dialog vs no dialog": an `allow` never surfaces a
+     * confirm dialog regardless of how long the classifier takes, and only an
+     * `escalate` verdict (explicit LLM escalation, classifier timeout, or infra
+     * error — all mapped to `escalate` by classify()) reaches the user.
+     * The background classifier's cost is settled exactly once inside
+     * classify(), so awaiting it after window expiry does not double-count.
      *
      * Precedence: explicit arg > `KODAX_AUTO_SPECULATIVE_WINDOW_MS` env >
-     * `DEFAULT_WINDOW_MS = 500`. Set to 0 to disable speculative race
-     * (degrades to synchronous classify).
+     * `DEFAULT_WINDOW_MS = 500`. Set to 0 to disable the speculative race
+     * (degrades to a synchronous classify — identical verdict outcome).
      */
     readonly speculativeWindowMs?: number;
 }

package/dist/types-chunks/{manager.d-DLmDhX3i.d.ts → manager.d-DBD7SOTT.d.ts}

@@ -47,6 +47,11 @@ interface McpCatalogSearchOptions {
 }
 declare function defaultMcpCacheDir(): string;
 declare function createMcpCapabilityId(serverId: string, kind: McpCapabilityKind, name: string): string;
+/**
+ * Applied defensively at handler, provider, and parse boundaries.
+ * Keep this idempotent so stacked normalization remains harmless.
+ */
+declare function normalizeMcpCapabilityId(id: string): string;
 declare function parseMcpCapabilityId(id: string): {
     serverId: string;
     kind: McpCapabilityKind;
@@ -678,7 +683,7 @@ declare class McpManager {
     }): Promise<readonly McpCatalogItem[]>;
     /** v0.7.42 — escape hatch for advanced uses; usually consumers use {@link listTools}. */
     describe(id: string): Promise<McpCapabilityDescriptor | undefined>;
-    /** v0.7.42 — invoke a tool by capability id (`mcp://<serverId>/<kind>/<name>`). */
+    /** v0.7.42 — invoke a tool by capability id (`mcp:<serverId>:tool:<name>`). */
     execute(id: string, input: Record<string, unknown>): Promise<CapabilityResult>;
     /** v0.7.42 — read a resource by capability id. */
     read(id: string, options?: Record<string, unknown>): Promise<CapabilityResult>;
@@ -692,5 +697,5 @@ declare class McpManager {
  */
 declare function createMcpManager(servers: McpServersConfig | undefined, options?: McpProviderOptions): McpManager;
 
-export { buildInitializeCapabilities as C, createMcpCapabilityId as E, createMcpManager as F, createMcpTransport as G, defaultMcpCacheDir as H, discoverAuthorizationServerMetadata as I, discoverOAuthEndpoints as J, discoverProtectedResourceMetadata as K, extractInsufficientScope as L, McpAuthRequiredError as M, extractResourceMetadataUrl as N, getMcpCachePaths as Q, loadValidToken as R, parseMcpCapabilityId as S, performOAuthLogin as T, registerOAuthClient as U, searchMcpCatalog as V, McpCapabilityProvider as c, McpExpiredSessionError as h, McpManager as j, McpServerRuntime as s };
+export { buildInitializeCapabilities as C, createMcpCapabilityId as E, createMcpManager as F, createMcpTransport as G, defaultMcpCacheDir as H, discoverAuthorizationServerMetadata as I, discoverOAuthEndpoints as J, discoverProtectedResourceMetadata as K, extractInsufficientScope as L, McpAuthRequiredError as M, extractResourceMetadataUrl as N, getMcpCachePaths as Q, loadValidToken as R, normalizeMcpCapabilityId as S, parseMcpCapabilityId as T, performOAuthLogin as U, registerOAuthClient as V, searchMcpCatalog as X, McpCapabilityProvider as c, McpExpiredSessionError as h, McpManager as j, McpServerRuntime as s };
 export type { AuthorizationServerMetadata as A, ProtectedResourceMetadata as B, DiscoveredOAuthEndpoints as D, OAuthClientInfo as O, PerformOAuthLoginOptions as P, WwwAuthenticateChallenge as W, McpCapabilityDescriptor as a, McpCapabilityKind as b, McpCapabilityRisk as d, McpCatalogItem as e, McpElicitRequest as f, McpElicitResult as g, McpIcon as i, McpProviderOptions as k, McpReverseCapabilities as l, McpRoot as m, McpSamplingRequest as n, McpSamplingResult as o, McpServerCatalog as p, McpServerCatalogSnapshot as q, McpServerLogs as r, McpServerRuntimeDiagnostics as t, McpServerStatus as u, McpServerToolList as v, McpToolTaskSupport as w, McpTransport as x, McpTransportEvents as y, OAuthLoginConsent as z };

package/dist/types-chunks/{process.d-BdiIUr8T.d.ts → process.d-DHow2y2G.d.ts}

@@ -1,4 +1,4 @@
-import { n as KodaXMessage, Y as KodaXToolDefinition, E as KodaXReasoningMode, _ as KodaXToolResultContentItem, U as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-BJmoMf5H.js';
+import { j as KodaXMessage, _ as KodaXToolDefinition, E as KodaXReasoningMode, a6 as KodaXWireReasoningEffort, a0 as KodaXToolResultContentItem, V as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-Ci5YPFEh.js';
 
 /**
  * @kodax-ai/agent Types
@@ -163,7 +163,7 @@ interface KodaXSessionTreeNode {
     active: boolean;
 }
 type KodaXSessionScope = 'user' | 'managed-task-worker';
-type KodaXSessionUiTextHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint';
+type KodaXSessionUiTextHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint' | 'sidecar';
 type KodaXSessionUiHistoryItemType = KodaXSessionUiTextHistoryItemType | 'tool_group';
 interface KodaXSessionUiTextHistoryItem {
     type: KodaXSessionUiTextHistoryItemType;
@@ -197,6 +197,22 @@ interface KodaXSessionRuntimeInfo {
     executionCwd?: string;
     branch?: string;
     workspaceKind?: KodaXSessionWorkspaceKind;
+    /** SDK consumer surface/profile label, e.g. `'code'` | `'partner'`. */
+    surface?: string;
+    /** SDK consumer profile id (stable name or UUID). */
+    profileId?: string;
+    /** SDK consumer profile version. */
+    profileVersion?: string;
+    /** LLM provider alias active at session start, e.g. `'anthropic'`. */
+    provider?: string;
+    /** Model identifier active at session start. */
+    model?: string;
+    /** Reasoning mode active at session start. */
+    reasoningMode?: string;
+    /** Permission mode active at session start, e.g. `'auto'` | `'plan'`. */
+    permissionMode?: string;
+    /** Agent mode active at session start, e.g. `'sa'` | `'ama'` | `'amaw'`. */
+    agentMode?: string;
 }
 interface KodaXSessionData {
     messages: KodaXMessage[];
@@ -447,6 +463,7 @@ interface Agent<TContext = unknown> {
     readonly outputSchema?: unknown;
     readonly model?: string;
     readonly provider?: string;
+    readonly effort?: KodaXWireReasoningEffort;
     /**
      * FEATURE_100 (v0.7.29) substrate executor: when set, `Runner.run`
      * delegates execution to this function instead of consulting the
@@ -1855,6 +1872,9 @@ interface StopHookContext {
  * FEATURE_184 (v0.7.45) — Stop hook return surface.
  */
 type StopHookResult = undefined | string | {
+    readonly reanimate: string;
+    readonly source?: string;
+} | {
     readonly abort: true;
     readonly reason: string;
 };
@@ -2005,6 +2025,19 @@ interface AskUserQuestionItem {
         value: string;
     }>;
     multiSelect?: boolean;
+    /**
+     * FEATURE_222 — only meaningful when `multiSelect` is true. The host should
+     * reject (re-prompt / show an error, do NOT resolve) a selection with fewer
+     * than `minSelections` items. Absent ⇒ no lower bound.
+     */
+    minSelections?: number;
+    /**
+     * FEATURE_222 — only meaningful when `multiSelect` is true. The host should
+     * reject a selection with more than `maxSelections` items. Absent ⇒ no upper
+     * bound. Lets a host render + validate "pick at most N" structurally instead
+     * of parsing it out of natural-language question text.
+     */
+    maxSelections?: number;
 }
 /** Options for multi-question mode — multiple independent questions in one call. */
 interface AskUserMultiOptions {
@@ -2021,8 +2054,31 @@ interface AskUserQuestionOptions {
         value: string;
     }>;
     multiSelect?: boolean;
+    /** FEATURE_222 — see {@link AskUserQuestionItem.minSelections}. */
+    minSelections?: number;
+    /** FEATURE_222 — see {@link AskUserQuestionItem.maxSelections}. */
+    maxSelections?: number;
     default?: string;
 }
+/**
+ * FEATURE_222 — reserved option value a host may append as a synthetic option
+ * (e.g. a "← Back" entry) in `askUserMulti`'s per-question flow to mean "return
+ * to the previous question" instead of answering the current one. Only
+ * meaningful for `questions[]` index > 0 (there is no previous before the
+ * first). The coding `ask_user_question` tool rejects this as a normal
+ * `option.value` supplied by the model, so a host may safely reuse it for its
+ * own back-navigation UI. A host that ignores this constant simply never offers
+ * back-navigation — the default multi-question flow is unaffected either way.
+ */
+declare const ASK_USER_BACK_SIGNAL = "__back__";
+/**
+ * FEATURE_222 — narrow an `askUser` result to a single string for the many
+ * callers that only ever ask single-select questions (they never set
+ * `multiSelect: true`, so the array branch is unreachable at runtime). Collapses
+ * an unexpected array to its first element so a mis-configured host degrades
+ * predictably instead of leaking `[object Array]` into a string comparison.
+ */
+declare function asSingleSelection(answer: string | string[]): string;
 /**
  * The host-provided user-interaction surface. Each method is optional — a
  * headless host omits them and callers degrade gracefully. This is the single
@@ -2030,11 +2086,19 @@ interface AskUserQuestionOptions {
  * elicitation reverse capability.
  */
 interface UserInteraction {
-    /** Ask one question (select mode by default). Resolves the chosen value. */
-    askUser?: (options: AskUserQuestionOptions) => Promise<string>;
-    /** Ask several independent questions sequentially. Resolves a value map, or
-     *  undefined when the user cancels. */
-    askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string> | undefined>;
+    /**
+     * Ask one question (select mode by default). Single-select (multiSelect
+     * falsy) resolves the chosen value as a string — unchanged. Multi-select
+     * (multiSelect: true) resolves the selected values as a `string[]`. The union
+     * is a backward-compatible superset: a host still returning a plain string
+     * satisfies this contract, but a multi-select host SHOULD return `string[]`
+     * so option values containing `, ` are not corrupted by a join.
+     */
+    askUser?: (options: AskUserQuestionOptions) => Promise<string | string[]>;
+    /** Ask several independent questions sequentially. Resolves a per-question
+     *  value map (each entry a string for single-select, `string[]` for
+     *  multi-select), or undefined when the user cancels. */
+    askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string | string[]> | undefined>;
     /** Ask for free-text input. Resolves the text, or undefined when cancelled. */
     askUserInput?: (options: {
         question: string;
@@ -2046,6 +2110,35 @@ declare function setActiveUserInteraction(interaction: UserInteraction | undefin
 /** The live user-interaction surface, or undefined when none is active. */
 declare function getActiveUserInteraction(): UserInteraction | undefined;
 
+type KodaXImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+type KodaXVideoMediaType = 'video/mp4' | 'video/mpeg' | 'video/quicktime' | 'video/x-msvideo' | 'video/x-flv' | 'video/webm' | 'video/x-ms-wmv' | 'video/3gpp';
+type KodaXInputArtifactSource = 'user-inline' | 'clipboard' | 'drag-drop' | 'file-picker';
+interface KodaXImageInputArtifact {
+    readonly kind: 'image';
+    readonly path: string;
+    readonly mediaType?: KodaXImageMediaType;
+    readonly source?: KodaXInputArtifactSource;
+    readonly description?: string;
+}
+interface KodaXFileInputArtifact {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly mediaType?: string;
+    readonly mimeType?: string;
+    readonly name?: string;
+    readonly source?: KodaXInputArtifactSource;
+    readonly description?: string;
+}
+interface KodaXVideoInputArtifact {
+    readonly kind: 'video';
+    readonly path: string;
+    readonly mediaType: KodaXVideoMediaType;
+    readonly name?: string;
+    readonly source?: KodaXInputArtifactSource;
+    readonly description?: string;
+}
+type KodaXInputArtifact = KodaXImageInputArtifact | KodaXFileInputArtifact | KodaXVideoInputArtifact;
+
 /**
  * Child task registry primitive — generic fan-out tracking.
  *
@@ -2577,20 +2670,51 @@ interface WorkflowTaskVerificationResult {
 interface WorkflowSpawnAgentInput {
     /** Human-readable label for the agent — surfaces in events / UI. */
     readonly name: string;
+    /**
+     * Optional progress-group tag (FEATURE_246 Part E). When set, this agent is
+     * grouped under a phase of that name in the progress display — the per-agent
+     * equivalent of wrapping a block in `wf.phase(name, fn)`, matching the harness
+     * `agent(..., { phase })`. The phase group is created on first use. Agents
+     * with no `phase` fall under the currently-active `wf.phase(...)` block (if any).
+     */
+    readonly phase?: string;
     /** The task prompt handed to the child agent. */
     readonly prompt: string;
     /** When true, the child runs with a read-only tool whitelist. */
     readonly readOnly?: boolean;
     /** Route to a registered specialist agent (FEATURE_191). */
     readonly subagentType?: string;
-    /** Provider/model tier hint (FEATURE_120 model_hint → env tier). */
+    /**
+     * Per-agent model TIER (FEATURE_120 model_hint). The script expresses semantic
+     * intent — 'fast' (cheap), 'deep' (strong), 'balanced' (default) — NOT a
+     * concrete model name: the authoring model has no cognition of which
+     * providers/models a given operator has configured. The operator maps the
+     * tiers to concrete models via env (KODAX_FAST/DEEP_PROVIDER/MODEL); when a
+     * tier is unconfigured the child inherits the parent provider/model, so a
+     * hint is always a safe no-op at worst. 'fast' applies to read-only children
+     * only (write/codegen stays on the parent tier — a quality guard).
+     */
     readonly modelHint?: WorkflowModelHint;
     /** Isolation policy; defaults to `shared-cwd`. */
     readonly isolation?: WorkflowIsolation;
+    /** Per-child reasoning effort hint (e.g. 'low' | 'medium' | 'high' | 'max').
+     *  The backend maps it onto the child's reasoning resolver; omit to inherit
+     *  the parent/default effort. Opaque string so the agent layer needs no
+     *  coding effort-enum dependency. */
+    readonly effort?: string;
     /** 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;
+    /**
+     * Optional JSON Schema (FEATURE_246 Part B). When set, the child is asked to
+     * end with a fenced JSON block matching the schema; the backend parses and
+     * validates it (with one bounded repair turn on a hard miss) and returns the
+     * parsed object on `WorkflowTaskResult.structured`. Orthogonal to
+     * `verification` (which checks side-effects, not return shape). Carried as an
+     * opaque value so the agent layer needs no JSON-Schema dependency.
+     */
+    readonly outputSchema?: unknown;
 }
 /** Returned by `spawnAgent` — the child is in-flight, not yet complete. */
 interface WorkflowTaskHandle {
@@ -2614,6 +2738,10 @@ interface WorkflowTaskResult {
     readonly name: string;
     readonly status: WorkflowTaskStatus;
     readonly finalText: string;
+    /** Schema-validated structured result (FEATURE_246 Part B), present when the
+     *  spawn carried `outputSchema` and a JSON value was parsed from the child's
+     *  output. The workflow script consumes it directly (e.g. `result.structured`). */
+    readonly structured?: unknown;
     /** Short user-facing digest, separate from the full finalText used for synthesis/audit. */
     readonly digest?: string;
     /** True when a digest was attempted but failed (error/timeout/empty); the UI then labels the excerpt fallback. */
@@ -2691,8 +2819,12 @@ interface WorkflowApi {
     phase<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /** Start a child agent; returns immediately with a handle. */
     spawnAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskHandle>;
-    /** spawnAgent + wait convenience; returns the terminal result. */
-    runAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskResult>;
+    /** spawnAgent + wait convenience; returns the terminal result, or `null` if
+     *  the child ended failed/stopped (FEATURE_246 Part E lenient failure — the
+     *  harness `agent()` semantics, so scripts can `.filter(Boolean)` instead of
+     *  wrapping every call in try/catch). Abort and budget/agent-cap limits still
+     *  throw. */
+    runAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskResult | null>;
     /** Await a spawned agent's terminal result. */
     wait(taskId: string, opts?: WorkflowWaitOptions): Promise<WorkflowTaskResult>;
     /** Snapshot a (possibly running) agent. */
@@ -2706,12 +2838,36 @@ interface WorkflowApi {
     stop(taskId: string, reason: string): Promise<void>;
     /** Run lazy thunks concurrently under the concurrency gate. Thunks
      *  MUST be `() => Promise<T>` (not already-started promises) so the
-     *  runtime can bound concurrency. */
-    parallel<T>(items: readonly (() => Promise<T>)[], opts?: WorkflowParallelOptions): Promise<T[]>;
+     *  runtime can bound concurrency. A thunk that throws (or whose agent fails)
+     *  resolves to `null` in the result array — the call itself never rejects, so
+     *  `.filter(Boolean)` before use (FEATURE_246 Part E, harness parity). Abort
+     *  still tears down the whole run. */
+    parallel<T>(items: readonly (() => Promise<T>)[], opts?: WorkflowParallelOptions): Promise<(T | null)[]>;
+    /**
+     * Stream items through ordered stages with NO barrier between stages: an
+     * item advances to stage N+1 as soon as its own stage N resolves,
+     * independent of other items (wall-clock = slowest single chain, not
+     * sum-of-slowest-per-stage). Each stage receives `(prev, item, index)`
+     * where `prev` is the previous stage's result (the original item at
+     * stage 1). A stage that throws drops that item to `null` and skips its
+     * remaining stages; results preserve input order. Agent spawns inside
+     * stages stay bounded by the workflow `maxConcurrency` gate. Optional:
+     * the restricted-script bootstrap always provides it; SDK consumers get
+     * it from the runtime. */
+    pipeline?(items: readonly unknown[], ...stages: readonly ((prev: unknown, item: unknown, index: number) => unknown)[]): Promise<unknown[]>;
     /** Synthesize across inputs. Runs as a gated agent through the runtime
      *  (spawn → wait), so it counts toward maxAgents / concurrency / budget
      *  and emits run-graph events — it is NOT a backend side-channel. */
     synthesize(input: WorkflowSynthesizeInput): Promise<WorkflowSynthesis>;
+    /**
+     * Run another saved/built-in workflow inline as a sub-step (FEATURE_246 Part E,
+     * harness parity). Resolves the module by name via the host-injected resolver
+     * and runs it under THIS run's runtime — sharing the same concurrency cap,
+     * agent counter, token budget, and abort signal. **One level only**: calling
+     * `workflow(...)` from inside a nested workflow throws. Returns whatever the
+     * sub-workflow's `run` returns. Optional: present when a resolver is wired
+     * (the restricted-script bootstrap provides it; SDK consumers may omit). */
+    workflow?(name: string, args?: unknown): Promise<unknown>;
     /** Persist a named artifact. */
     artifact(name: string, value: unknown): Promise<WorkflowArtifactRef>;
     /** Emit a free-text progress log event. */
@@ -2910,5 +3066,5 @@ declare function isFinalWorkflowProcessStatus(status: WorkflowProcessStatus): bo
 declare function normalizeHostMetadata(value: unknown): Record<string, string> | undefined;
 declare function createWorkflowProcessTracker(options: WorkflowProcessTrackerOptions): WorkflowProcessTracker;
 
-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 };
+export { ASK_USER_BACK_SIGNAL as A, DEFAULT_SYSTEM_CAP as D, InvariantSession as N, Runner as aK, MAX_TOOL_LOOP_ITERATIONS as as, SpanImpl as b1, Tracer as bj, WorkflowEventRecorder as bu, _resetAdmittedAgentBindings as c6, _resetPresetDispatchers as c7, asSingleSelection as c8, buildAssistantMessageFromLlmResult as c9, buildSystemPrompt as ca, buildToolResultMessage as cb, createAgent as cc, createHandoff as cd, createInMemorySession as ce, createInvariantSessionForAgent as cf, createStateWriter as cg, createTrace as ch, createWorkflowProcessTracker as ci, defaultTracer as cj, detectInstructionsInjection as ck, discoverInstances as cl, executeRunnerToolCall as cm, extractAssistantTextFromMessage as cn, getActiveUserInteraction as co, getAdmittedAgentBindings as cp, isFinalWorkflowProcessStatus as cq, isRunnableTool as cr, isRunnerLlmResult as cs, normalizeHostMetadata as ct, registerChildTask as cu, registerPresetDispatcher as cv, requestTaskStop as cw, runAdmissionAudit as cx, setActiveUserInteraction as cy, setAdmittedAgentBindings as cz };
+export type { KodaXInputArtifactSource as $, GuardrailSpanData as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, HandoffSpanData as I, InMemorySessionOptions as J, InstanceDiscoveryFs as K, InvariantId as L, InvariantResult as M, KodaXCompactMemoryProgress as O, KodaXCompactMemorySeed as P, KodaXExtensionSessionRecord as Q, KodaXExtensionSessionState as R, KodaXExtensionStore as S, KodaXExtensionStoreEntry as T, KodaXFileInputArtifact as U, KodaXGoalEventType as V, KodaXGoalState as W, KodaXGoalStatus as X, KodaXImageInputArtifact as Y, KodaXImageMediaType as Z, KodaXInputArtifact as _, AdmissionAuditOptions as a, SpanData as a$, KodaXJsonValue as a0, KodaXSessionArchiveMarkerEntry as a1, KodaXSessionArtifactLedgerEntry as a2, KodaXSessionBranchSummaryEntry as a3, KodaXSessionCompactionEntry as a4, KodaXSessionData as a5, KodaXSessionEntry as a6, KodaXSessionEntryBase as a7, KodaXSessionGoalEntry as a8, KodaXSessionLabelEntry as a9, ReadonlyMutationTracker as aA, ReadonlyRecorder as aB, ReasoningDepth as aC, RecentlyModifiedFile as aD, RequestTaskStopOptions as aE, RequestTaskStopResult as aF, RunEvent as aG, RunOptions as aH, RunResult as aI, RunnableTool as aJ, RunnerEvent as aL, RunnerLlmResult as aM, RunnerLlmReturn as aN, RunnerToolCall as aO, RunnerToolContext as aP, RunnerToolObserver as aQ, RunnerToolResult as aR, Session as aS, SessionDispatchResult as aT, SessionEntry as aU, SessionErrorMetadata as aV, SessionExtension as aW, SessionForkOptions as aX, SessionMeta as aY, SessionStateSnapshot as aZ, Span as a_, KodaXSessionLineage as aa, KodaXSessionMessageEntry as ab, KodaXSessionMeta as ac, KodaXSessionNavigationOptions as ad, KodaXSessionRuntimeInfo as ae, KodaXSessionScope as af, KodaXSessionStorage as ag, KodaXSessionTreeNode as ah, KodaXSessionUiHistoryItem as ai, KodaXSessionUiHistoryItemType as aj, KodaXSessionUiTextHistoryItem as ak, KodaXSessionUiTextHistoryItemType as al, KodaXSessionUiToolCall as am, KodaXSessionUiToolCallStatus as an, KodaXSessionUiToolGroupHistoryItem as ao, KodaXSessionWorkspaceKind as ap, KodaXVideoInputArtifact as aq, KodaXVideoMediaType as ar, ManifestPatch as at, MessageEntry as au, ObserveCtx as av, PersistedSessionState as aw, PresetDispatcher as ax, PresetTracingContext as ay, QualityInvariant as az, AdmissionCtx as b, WorkflowTaskSummaryEventUpdate as b$, SpanError as b0, SpanImplOptions as b2, StartTraceOptions as b3, StateWriter as b4, StateWriterFs as b5, StateWriterOptions as b6, StopHookContext as b7, StopHookFn as b8, StopHookResult as b9, WorkflowModelHint as bA, WorkflowModule as bB, WorkflowParallelOptions as bC, WorkflowProcessArtifact as bD, WorkflowProcessCounts as bE, WorkflowProcessEvent as bF, WorkflowProcessItem as bG, WorkflowProcessItemKind as bH, WorkflowProcessItemStatus as bI, WorkflowProcessProgress as bJ, WorkflowProcessSnapshot as bK, WorkflowProcessSource as bL, WorkflowProcessStatus as bM, WorkflowProcessSummaryStatus as bN, WorkflowProcessTokenUsage as bO, WorkflowProcessTracker as bP, WorkflowProcessTrackerOptions as bQ, WorkflowRun as bR, WorkflowRunState as bS, WorkflowRunStatus as bT, WorkflowSpawnAgentInput as bU, WorkflowSynthesis as bV, WorkflowSynthesizeInput as bW, WorkflowTaskHandle as bX, WorkflowTaskResult as bY, WorkflowTaskSnapshot as bZ, WorkflowTaskStatus as b_, StopHookSpanData as ba, SystemCap as bb, TaskAbortRegistry as bc, TerminalCtx as bd, ToolCallSpanData as be, ToolCapability as bf, ToolPermission as bg, Trace as bh, TraceOptions as bi, TracerOptions as bk, UserInteraction as bl, WorkflowAgentBackend as bm, WorkflowApi as bn, WorkflowApproval as bo, WorkflowApprovalSummary as bp, WorkflowArtifactRef as bq, WorkflowBudget as br, WorkflowEvent as bs, WorkflowEventCorrelation as bt, WorkflowEventType as bv, WorkflowIsolation as bw, WorkflowLimits as bx, WorkflowLogEvent as by, WorkflowMeta as bz, AdmissionVerdict as c, WorkflowTaskSummaryKind as c0, WorkflowTaskSummaryUpdate as c1, WorkflowTaskUsage as c2, WorkflowTaskVerification as c3, WorkflowTaskVerificationResult as c4, WorkflowWaitOptions as c5, AdmittedHandle as d, Agent as e, AgentManifest as f, AgentMessage as g, AgentMiddlewareDeclaration as h, AgentReasoningProfile as i, AgentSpanData as j, AgentTool as k, AskUserMultiOptions as l, AskUserQuestionItem as m, AskUserQuestionOptions as n, CompactionAnchor as o, CompactionConfig as p, CompactionDetails as q, CompactionResult as r, CompactionSpanData as s, CompactionUpdate as t, CurrentTodoSummary as u, Deliverable as v, DiscoveredInstance as w, DiscoveryOptions as x, FileOperations as y, Guardrail as z };