@kodax-ai/kodax 0.7.47 → 0.7.49

package/dist/types-chunks/{resolver.d-DkgJlEzr.d.ts → resolver.d-B_wm409c.d.ts}

@@ -1,6 +1,6 @@
-import { E as KodaXReasoningMode, V as KodaXThinkingBudgetMap, W as KodaXThinkingDepth, s as KodaXProviderConfig, D as KodaXReasoningCapability, G as KodaXReasoningRequest, R as KodaXTaskType, F as KodaXReasoningOverride, a2 as KodaXVerifyCredentialResult, Y as KodaXToolDefinition, n as KodaXMessage, A as KodaXProviderStreamOptions, L as KodaXStreamResult, o as KodaXModelDescriptor, r as KodaXProviderCapabilityProfile, a3 as KodaXVerifyStrategy, h as KodaXCustomProviderConfig, m as KodaXListModelsResult } from './types.d-Cf-GCzac.js';
+import { E as KodaXReasoningMode, V as KodaXThinkingBudgetMap, W as KodaXThinkingDepth, s as KodaXProviderConfig, D as KodaXReasoningCapability, G as KodaXReasoningRequest, R as KodaXTaskType, F as KodaXReasoningOverride, a2 as KodaXVerifyCredentialResult, Y as KodaXToolDefinition, n as KodaXMessage, A as KodaXProviderStreamOptions, L as KodaXStreamResult, o as KodaXModelDescriptor, r as KodaXProviderCapabilityProfile, a3 as KodaXVerifyStrategy, h as KodaXCustomProviderConfig, m as KodaXListModelsResult } from './types.d-rPRl2LSB.js';
 import Anthropic from '@anthropic-ai/sdk';
-import { K as KodaXBaseProvider } from './base.d-BdJKSPO2.js';
+import { K as KodaXBaseProvider } from './base.d-C4jYVjJh.js';
 import OpenAI from 'openai';
 
 /**

package/dist/types-chunks/{storage.d-B1Jk6ryM.d.ts → storage.d-J2GqOgaX.d.ts}

@@ -1,4 +1,4 @@
-import { n as KodaXSessionData, s as KodaXSessionLineage, v as KodaXSessionNavigationOptions, w as KodaXSessionRuntimeInfo, y as KodaXSessionStorage } from './types.d-B_MIIApc.js';
+import { n as KodaXSessionData, s as KodaXSessionLineage, v as KodaXSessionNavigationOptions, w as KodaXSessionRuntimeInfo, y as KodaXSessionStorage } from './types.d-BnjX2Gn4.js';
 
 /**
  * Session Storage - Session storage abstraction layer
@@ -31,6 +31,7 @@ interface SessionStorage {
         id: string;
         title: string;
         msgCount: number;
+        tag?: string;
         runtimeInfo?: KodaXSessionRuntimeInfo;
     }>>;
     delete?(id: string): Promise<void>;
@@ -58,6 +59,7 @@ declare class MemorySessionStorage implements SessionStorage {
         id: string;
         title: string;
         msgCount: number;
+        tag?: string;
     }>>;
     delete(id: string): Promise<void>;
     deleteAll(_gitRoot?: string): Promise<void>;
@@ -164,6 +166,7 @@ declare class FileSessionStorage implements KodaXSessionStorage {
         id: string;
         title: string;
         msgCount: number;
+        tag?: string;
         runtimeInfo?: KodaXSessionRuntimeInfo;
         archived?: boolean;
         createdAt?: string;

package/dist/types-chunks/{types.d-D2RNa5Y7.d.ts → types.d-BR9oNWup.d.ts}

@@ -1,5 +1,5 @@
-import { Y as KodaXToolDefinition, n as KodaXMessage, E as KodaXReasoningMode, _ as KodaXToolResultContentItem, U as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-Cf-GCzac.js';
-import { a as KodaXCompactMemorySeed, k as KodaXSessionArtifactLedgerEntry } from './types.d-B_MIIApc.js';
+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';
 
 /**
  * Layer A Primitive: Agent / Handoff / Guardrail / AgentReasoningProfile
@@ -1535,6 +1535,8 @@ interface StopHookContext {
     /** Total reanimate budget for this run (`stopHookReanimateBudget`
      *  or default 2). Exposed for transparency. */
     readonly reanimateBudget: number;
+    /** Caller cancellation signal, forwarded so stop hooks can cancel I/O. */
+    readonly abortSignal?: AbortSignal;
 }
 /**
  * FEATURE_184 (v0.7.45) — Stop hook return surface.
@@ -1816,6 +1818,190 @@ declare function runToolBeforeGuardrails(call: RunnerToolCall, guardrails: reado
  */
 declare function runToolAfterGuardrails(call: RunnerToolCall, result: RunnerToolResult, guardrails: readonly ToolGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<RunnerToolResult>;
 
+/**
+ * FEATURE_222 — user-interaction primitive (agent layer).
+ *
+ * "Ask the user a question" is needed at BOTH layers: the coding `ask_user_*`
+ * tools (LLM-initiated) AND the MCP elicitation reverse capability
+ * (server-initiated). The capability historically lived only in
+ * `@kodax-ai/coding`, but the MCP runtime lives one layer below in
+ * `@kodax-ai/agent` and cannot reach up to it. So the primitive is owned here,
+ * at the agent layer, and the host injects ONE implementation that both layers
+ * share — coding re-exports these types for backward compatibility.
+ *
+ * The agent layer is UI-less by design: these are the contract the host
+ * (REPL / ACP / SDK) fulfils with its real interaction surface. A headless host
+ * leaves them undefined and consumers degrade gracefully (cancel / decline).
+ */
+/** A single question item used in multi-question mode. */
+interface AskUserQuestionItem {
+    question: string;
+    header?: string;
+    options: Array<{
+        label: string;
+        description?: string;
+        value: string;
+    }>;
+    multiSelect?: boolean;
+}
+/** Options for multi-question mode — multiple independent questions in one call. */
+interface AskUserMultiOptions {
+    questions: AskUserQuestionItem[];
+}
+/** Options for a single question (select or free-text input). */
+interface AskUserQuestionOptions {
+    question: string;
+    kind?: 'select' | 'input';
+    /** Required for kind="select", ignored for kind="input". */
+    options?: Array<{
+        label: string;
+        description?: string;
+        value: string;
+    }>;
+    multiSelect?: boolean;
+    default?: string;
+}
+/**
+ * The host-provided user-interaction surface. Each method is optional — a
+ * headless host omits them and callers degrade gracefully. This is the single
+ * primitive shared by the coding `ask_user_*` tools and the agent's MCP
+ * 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 for free-text input. Resolves the text, or undefined when cancelled. */
+    askUserInput?: (options: {
+        question: string;
+        default?: string;
+    }) => Promise<string | undefined>;
+}
+/** Register the live user-interaction surface (host calls this when interactive). */
+declare function setActiveUserInteraction(interaction: UserInteraction | undefined): void;
+/** 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.
  *
@@ -2273,5 +2459,244 @@ interface FileOperations {
     modifiedFiles: string[];
 }
 
-export { DEFAULT_SYSTEM_CAP as D, InvariantSession as O, MAX_TOOL_LOOP_ITERATIONS as P, getAdmittedAgentBindings as a$, Runner as a6, Tracer as aI, _resetAdmittedAgentBindings as aK, _resetPresetDispatchers as aL, buildAssistantMessageFromLlmResult as aM, buildSystemPrompt as aN, buildToolResultMessage as aO, collectGuardrails as aP, createAgent as aQ, createHandoff as aR, createInMemorySession as aS, createInvariantSessionForAgent as aT, createStateWriter as aU, createTrace as aV, defaultTracer as aW, detectInstructionsInjection as aX, discoverInstances as aY, executeRunnerToolCall as aZ, extractAssistantTextFromMessage as a_, SpanImpl as ao, isRunnableTool as b0, isRunnerLlmResult as b1, registerChildTask as b2, registerPresetDispatcher as b3, requestTaskStop as b4, runAdmissionAudit as b5, runInputGuardrails as b6, runOutputGuardrails as b7, runToolAfterGuardrails as b8, runToolBeforeGuardrails as b9, setAdmittedAgentBindings as ba, GuardrailBlockedError as w, GuardrailEscalateError as y };
-export type { RecentlyModifiedFile as $, AdmissionAuditOptions as A, GuardrailVerdict as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, HandoffSpanData as I, InMemorySessionOptions as J, InputGuardrail as K, InstanceDiscoveryFs as L, InvariantId as M, InvariantResult as N, ManifestPatch as Q, MessageEntry as R, ObserveCtx as S, OutputGuardrail as T, PersistedSessionState as U, PresetDispatcher as V, PresetTracingContext as W, QualityInvariant as X, ReadonlyMutationTracker as Y, ReadonlyRecorder as Z, ReasoningDepth as _, AdmissionCtx as a, RequestTaskStopOptions as a0, RequestTaskStopResult as a1, RunEvent as a2, RunOptions as a3, RunResult as a4, RunnableTool as a5, RunnerEvent as a7, RunnerLlmResult as a8, RunnerLlmReturn as a9, TerminalCtx as aA, ToolBeforeOutcome as aB, ToolCallSpanData as aC, ToolCapability as aD, ToolGuardrail as aE, ToolPermission as aF, Trace as aG, TraceOptions as aH, TracerOptions as aJ, RunnerToolCall as aa, RunnerToolContext as ab, RunnerToolObserver as ac, RunnerToolResult as ad, Session as ae, SessionDispatchResult as af, SessionEntry as ag, SessionExtension as ah, SessionForkOptions as ai, SessionMeta as aj, SessionStateSnapshot as ak, Span as al, SpanData as am, SpanError as an, SpanImplOptions as ap, StartTraceOptions as aq, StateWriter as ar, StateWriterFs as as, StateWriterOptions as at, StopHookContext as au, StopHookFn as av, StopHookResult as aw, StopHookSpanData as ax, SystemCap as ay, TaskAbortRegistry as az, AdmissionVerdict as b, AdmittedHandle as c, Agent as d, AgentManifest as e, AgentMessage as f, AgentMiddlewareDeclaration as g, AgentReasoningProfile as h, AgentSpanData as i, AgentTool as j, CompactionAnchor as k, CompactionConfig as l, CompactionDetails as m, CompactionResult as n, CompactionSpanData as o, CompactionUpdate as p, CurrentTodoSummary as q, Deliverable as r, DiscoveredInstance as s, DiscoveryOptions as t, FileOperations as u, Guardrail as v, GuardrailContext as x, GuardrailSpanData as z };
+/**
+ * FEATURE_217 (v0.7.49) — Workflow run-graph events.
+ *
+ * Append-only event stream for a workflow run. Each event carries a
+ * monotonic `seq` so ordering is stable and verifiable regardless of
+ * wall-clock (the durable writer in Phase D adds timestamps via an
+ * 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_stopped' | 'artifact_written' | 'synthesis_completed' | 'workflow_completed' | 'workflow_stopped' | 'workflow_failed';
+interface WorkflowEvent {
+    /** Monotonic sequence number — stable append ordering. */
+    readonly seq: number;
+    readonly type: WorkflowEventType;
+    /** Structured payload (agent name/id, phase name, error message, …). */
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * Append-only event recorder. Assigns sequential `seq` and fans each
+ * event out to an optional sink (the durable JSONL writer / UI consumer
+ * subscribes here in Phase D).
+ */
+declare class WorkflowEventRecorder {
+    private readonly sink?;
+    private seq;
+    private readonly events;
+    constructor(sink?: ((event: WorkflowEvent) => void) | undefined);
+    /** Append an event, returning the materialized record. */
+    emit(type: WorkflowEventType, data?: Record<string, unknown>): WorkflowEvent;
+    /** Immutable snapshot of all events emitted so far. */
+    snapshot(): readonly WorkflowEvent[];
+}
+
+/**
+ * FEATURE_217 (v0.7.49) — Dynamic Workflow Harness Runtime: public types.
+ *
+ * Domain-neutral workflow orchestration surface. A workflow *script*
+ * coordinates (decompose / fan-out / loop / wait / stop / verify /
+ * synthesize); it never touches files or shell directly. The actual
+ * agent execution is delegated to an injected `WorkflowAgentBackend`
+ * (the coding layer provides the real one in Phase B; tests inject a
+ * fake). This keeps `@kodax-ai/agent` free of any `@kodax-ai/coding`
+ * dependency (ADR-021 layer independence).
+ */
+/** Lifecycle status of a single workflow-spawned agent. */
+type WorkflowTaskStatus = 'running' | 'completed' | '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';
+interface WorkflowSpawnAgentInput {
+    /** Human-readable label for the agent — surfaces in events / UI. */
+    readonly name: 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). */
+    readonly modelHint?: WorkflowModelHint;
+    /** Isolation policy; defaults to `shared-cwd`. */
+    readonly isolation?: WorkflowIsolation;
+    /** Evidence refs (`task_id:<id>` etc.) seeded into the child context. */
+    readonly evidenceRefs?: readonly string[];
+}
+/** Returned by `spawnAgent` — the child is in-flight, not yet complete. */
+interface WorkflowTaskHandle {
+    readonly taskId: string;
+    readonly name: string;
+}
+interface WorkflowTaskUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+}
+/** Terminal result of a spawned agent (from `wait` / `runAgent`). */
+interface WorkflowTaskResult {
+    readonly taskId: string;
+    readonly name: string;
+    readonly status: WorkflowTaskStatus;
+    readonly finalText: string;
+    /** 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. */
+    readonly digestFailed?: boolean;
+    readonly usage?: WorkflowTaskUsage;
+}
+/** Point-in-time snapshot of a (possibly still-running) agent. */
+interface WorkflowTaskSnapshot {
+    readonly taskId: string;
+    readonly name: string;
+    readonly status: WorkflowTaskStatus;
+    readonly lastText?: string;
+}
+interface WorkflowWaitOptions {
+    readonly timeoutMs?: number;
+}
+interface WorkflowParallelOptions {
+    /** In-flight cap for this parallel block; clamped by workflow
+     *  maxConcurrency. */
+    readonly concurrency?: number;
+}
+interface WorkflowSynthesizeInput {
+    readonly inputs: readonly unknown[] | string | Record<string, unknown>;
+    readonly rubric: string;
+}
+interface WorkflowSynthesis {
+    readonly text: string;
+}
+interface WorkflowArtifactRef {
+    readonly name: string;
+    readonly path?: string;
+}
+interface WorkflowLogEvent {
+    readonly message: string;
+    readonly data?: unknown;
+}
+/**
+ * Token budget accounting. The runtime hard-stops before launching a new
+ * agent once completed children have exhausted the configured budget.
+ */
+interface WorkflowBudget {
+    /** Configured token budget, or null when unbounded. */
+    readonly total: number | null;
+    /** Tokens accounted across completed agents so far. */
+    spent(): number;
+    /** `max(0, total - spent())`, or Infinity when unbounded. */
+    remaining(): number;
+}
+interface WorkflowLimits {
+    /** Total agents spawnable across the whole run lifetime. */
+    readonly maxAgents?: number;
+    /** Maximum simultaneously in-flight agents (via runAgent / parallel). */
+    readonly maxConcurrency?: number;
+    /** Token budget. New spawns stop once completed usage exhausts it. */
+    readonly tokenBudget?: number;
+}
+/**
+ * The surface a workflow script consumes. The script never gets raw
+ * fs/shell — all effects route through agent tools behind the backend.
+ */
+interface WorkflowApi {
+    readonly runId: string;
+    readonly args: unknown;
+    readonly budget: WorkflowBudget;
+    /** Group operations under a named phase (emits phase_started/finished). */
+    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>;
+    /** Await a spawned agent's terminal result. */
+    wait(taskId: string, opts?: WorkflowWaitOptions): Promise<WorkflowTaskResult>;
+    /** Snapshot a (possibly running) agent. */
+    output(taskId: string): Promise<WorkflowTaskSnapshot>;
+    /** Send a message to a running agent (via MessageQueue routing). */
+    send(taskId: string, content: string): Promise<void>;
+    /** Stop a running agent (graceful abort). */
+    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[]>;
+    /** 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>;
+    /** Persist a named artifact. */
+    artifact(name: string, value: unknown): Promise<WorkflowArtifactRef>;
+    /** Emit a free-text progress log event. */
+    log(event: WorkflowLogEvent): void;
+}
+/** Metadata a workflow declares (name, description, default caps). */
+interface WorkflowMeta {
+    readonly name: string;
+    readonly description: string;
+    /** Best-effort expected child-agent count for progress UI; not a hard cap. */
+    readonly plannedAgents?: number;
+    readonly maxAgents?: number;
+    readonly maxConcurrency?: number;
+    readonly tokenBudget?: number;
+    /** True when the workflow only ever spawns read-only agents (no file
+     *  writes) — surfaced in the approval prompt. */
+    readonly readOnly?: boolean;
+    /** Declared phase names, for the approval prompt preview. */
+    readonly phases?: readonly string[];
+}
+/** Summary shown to the user before a workflow's first run. */
+interface WorkflowApprovalSummary {
+    readonly name: string;
+    readonly description: string;
+    readonly phases: readonly string[];
+    readonly plannedAgents?: number;
+    readonly maxAgents: number | null;
+    readonly maxConcurrency: number | null;
+    readonly tokenBudget: number | null;
+    /** Whether the workflow may write files (false for read-only workflows). */
+    readonly writesFiles: boolean;
+}
+/** Approval gate — returns true to proceed, false to cancel the run. */
+type WorkflowApproval = (summary: WorkflowApprovalSummary) => boolean | Promise<boolean>;
+/** A workflow's entry function: coordinates agents via the `WorkflowApi`. */
+type WorkflowRun<TArgs = unknown, TResult = unknown> = (wf: WorkflowApi, args: TArgs) => Promise<TResult>;
+/** A self-contained workflow: metadata + entry function. Built-in
+ *  workflows (Phase C) and saved `.kodax/workflows/*.ts` (Phase E) both
+ *  materialize to this shape. */
+interface WorkflowModule<TArgs = unknown, TResult = unknown> {
+    readonly meta: WorkflowMeta;
+    readonly run: WorkflowRun<TArgs, TResult>;
+}
+/**
+ * Injected execution backend. The coding layer implements this over its
+ * child-dispatch substrate (ChildTaskRegistry / childProgressSnapshots /
+ * MessageQueue / executeChildAgents); tests inject a fake. The agent
+ * runtime depends ONLY on this interface — never on coding.
+ */
+interface WorkflowAgentBackend {
+    spawn(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskHandle>;
+    wait(taskId: string, opts?: WorkflowWaitOptions): Promise<WorkflowTaskResult>;
+    output(taskId: string): Promise<WorkflowTaskSnapshot>;
+    send(taskId: string, content: string): Promise<void>;
+    stop(taskId: string, reason: string): Promise<void>;
+    /** Optional durable artifact writer (Phase D wires the run graph).
+     *  `wf.synthesize` is NOT a backend method — it runs as a gated agent
+     *  through `spawn`/`wait` so it counts toward the runtime's caps. */
+    writeArtifact?(name: string, value: unknown): Promise<WorkflowArtifactRef>;
+}
+type WorkflowRunStatus = 'running' | 'completed' | 'failed' | 'stopped';
+/** Immutable snapshot of a workflow run's accumulated state. */
+interface WorkflowRunState {
+    readonly runId: string;
+    readonly status: WorkflowRunStatus;
+    readonly totalSpawned: number;
+    readonly events: readonly WorkflowEvent[];
+    readonly artifacts: readonly WorkflowArtifactRef[];
+}
+
+export { DEFAULT_SYSTEM_CAP as D, GuardrailBlockedError as H, GuardrailEscalateError as J, InvariantSession as T, MAX_TOOL_LOOP_ITERATIONS as U, WorkflowEventRecorder as a$, Tracer as aR, Runner as af, SpanImpl as ax, extractAssistantTextFromMessage as bA, getActiveUserInteraction as bB, getAdmittedAgentBindings as bC, isRunnableTool as bD, isRunnerLlmResult as bE, registerChildTask as bF, registerPresetDispatcher as bG, requestTaskStop as bH, runAdmissionAudit as bI, runInputGuardrails as bJ, runOutputGuardrails as bK, runToolAfterGuardrails as bL, runToolBeforeGuardrails as bM, setActiveUserInteraction as bN, setAdmittedAgentBindings as bO, _resetAdmittedAgentBindings as bk, _resetPresetDispatchers as bl, buildAssistantMessageFromLlmResult as bm, buildSystemPrompt as bn, buildToolResultMessage as bo, collectGuardrails as bp, createAgent as bq, createHandoff as br, createInMemorySession as bs, createInvariantSessionForAgent as bt, createStateWriter as bu, createTrace as bv, defaultTracer as bw, detectInstructionsInjection as bx, discoverInstances as by, executeRunnerToolCall as bz };
+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, 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 b0, WorkflowIsolation as b1, WorkflowLimits as b2, WorkflowLogEvent as b3, WorkflowMeta as b4, WorkflowModelHint as b5, WorkflowModule as b6, WorkflowParallelOptions as b7, WorkflowRun as b8, WorkflowRunState as b9, WorkflowRunStatus as ba, WorkflowSpawnAgentInput as bb, WorkflowSynthesis as bc, WorkflowSynthesizeInput as bd, WorkflowTaskHandle as be, WorkflowTaskResult as bf, WorkflowTaskSnapshot as bg, WorkflowTaskStatus as bh, WorkflowTaskUsage as bi, WorkflowWaitOptions as bj, 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 };

package/dist/types-chunks/{types.d-B_MIIApc.d.ts → types.d-BnjX2Gn4.d.ts}

@@ -1,4 +1,4 @@
-import { n as KodaXMessage } from './types.d-Cf-GCzac.js';
+import { n as KodaXMessage } from './types.d-rPRl2LSB.js';
 
 /**
  * @kodax-ai/agent Types
@@ -182,6 +182,8 @@ interface KodaXSessionData {
     messages: KodaXMessage[];
     title: string;
     gitRoot: string;
+    /** Consumer-owned private string persisted with the session. */
+    tag?: string;
     runtimeInfo?: KodaXSessionRuntimeInfo;
     scope?: KodaXSessionScope;
     uiHistory?: KodaXSessionUiHistoryItem[];
@@ -196,6 +198,8 @@ interface KodaXSessionMeta {
     title: string;
     id: string;
     gitRoot: string;
+    /** Consumer-owned private string persisted with the session. */
+    tag?: string;
     runtimeInfo?: KodaXSessionRuntimeInfo;
     createdAt: string;
     scope?: KodaXSessionScope;
@@ -283,6 +287,7 @@ interface KodaXSessionStorage {
         id: string;
         title: string;
         msgCount: number;
+        tag?: string;
         runtimeInfo?: KodaXSessionRuntimeInfo;
     }>>;
     delete?(id: string): Promise<void>;

package/dist/types-chunks/{types.d-Cf-GCzac.d.ts → types.d-rPRl2LSB.d.ts}

@@ -474,6 +474,10 @@ interface KodaXProviderStreamOptions {
     sessionId?: string;
     /** Override the provider's default model for a single request */
     modelOverride?: string;
+    /** Force a single tool call for one-shot judge/sidecar requests. */
+    forcedToolName?: string;
+    /** Per-request output budget override for short structured calls. */
+    maxOutputTokensOverride?: number;
     /** AbortSignal for cancelling the stream request */
     signal?: AbortSignal;
 }

package/dist/types-chunks/{utils.d-umRKgMAu.d.ts → utils.d-BJ_-y8gC.d.ts}

@@ -1,7 +1,7 @@
-import { l as BashPrefixExtractor, a4 as KodaXOptions, M as KodaXContextTokenSnapshot, K as KodaXAgentMode, a9 as KodaXRepoIntelligenceMode, A as AgentsFile, i as AutoModeStats, al as KodaXSkillInvocationContext, a1 as KodaXMcpServersConfig } from './bash-prefix-extractor.d-D6hL0Cuv.js';
-import { a as SessionStorage$1 } from './storage.d-B1Jk6ryM.js';
-import { y as KodaXSessionStorage, n as KodaXSessionData, A as KodaXSessionUiHistoryItem, s as KodaXSessionLineage, k as KodaXSessionArtifactLedgerEntry, w as KodaXSessionRuntimeInfo } from './types.d-B_MIIApc.js';
-import { n as KodaXMessage, E as KodaXReasoningMode, r as KodaXProviderCapabilityProfile, F as KodaXReasoningOverride, h as KodaXCustomProviderConfig } from './types.d-Cf-GCzac.js';
+import { i as BashPrefixExtractor, a4 as KodaXOptions, M as KodaXContextTokenSnapshot, K as KodaXAgentMode, a9 as KodaXRepoIntelligenceMode, A as AgentsFile, f as AutoModeStats, al as KodaXSkillInvocationContext, a1 as KodaXMcpServersConfig } from './bash-prefix-extractor.d-CI_xcPhn.js';
+import { a as SessionStorage$1 } from './storage.d-J2GqOgaX.js';
+import { y as KodaXSessionStorage, n as KodaXSessionData, A as KodaXSessionUiHistoryItem, s as KodaXSessionLineage, k as KodaXSessionArtifactLedgerEntry, w as KodaXSessionRuntimeInfo } from './types.d-BnjX2Gn4.js';
+import { n as KodaXMessage, E as KodaXReasoningMode, r as KodaXProviderCapabilityProfile, F as KodaXReasoningOverride, h as KodaXCustomProviderConfig } from './types.d-rPRl2LSB.js';
 import * as readline from 'readline';
 import { SpawnSyncReturns } from 'child_process';
 
@@ -100,15 +100,12 @@ interface InkREPLOptions extends KodaXOptions {
  */
 declare function runInkInteractiveMode(options: InkREPLOptions): Promise<void>;
 
-/**
- * KodaX Interactive REPL Mode - 交互式 REPL 模式
- */
-
 interface SessionStorage extends KodaXSessionStorage {
     list(gitRoot?: string): Promise<Array<{
         id: string;
         title: string;
         msgCount: number;
+        tag?: string;
         runtimeInfo?: KodaXSessionData['runtimeInfo'];
     }>>;
 }
@@ -265,6 +262,36 @@ interface CommandCallbacks {
     reloadAgentsFiles?: () => Promise<AgentsFile[]>;
     confirm?: (message: string) => Promise<boolean>;
     readline?: readline.Interface;
+    onWorkflowBuilderEvent?: (event: {
+        readonly stage: string;
+        readonly message: string;
+    }) => void;
+    onWorkflowRunMessage?: (event: {
+        readonly type: 'info' | 'success' | 'error' | 'event' | 'assistant';
+        readonly text: string;
+        readonly final?: boolean;
+    }) => void;
+    onWorkflowRunUpdate?: (event: {
+        readonly runId: string;
+        readonly workflow: string;
+        readonly status: 'running' | 'completed' | 'failed' | 'stopped';
+        readonly phase?: string;
+        readonly phaseIndex?: number;
+        readonly phaseTotal?: number;
+        readonly startedAt?: number;
+        readonly elapsedMs?: number;
+        readonly activeAgents: readonly string[];
+        readonly totalSpawned: number;
+        readonly plannedAgents?: number;
+        readonly agentCap?: number;
+        readonly tokenBudgetSpent?: number;
+        readonly tokenBudgetTotal?: number;
+        readonly completedAgents: number;
+        readonly failedAgents: number;
+        readonly stoppedAgents: number;
+        readonly message?: string;
+        readonly locale?: 'en' | 'zh';
+    }) => void;
     startCompacting?: () => void;
     stopCompacting?: () => void;
     /**
@@ -307,6 +334,7 @@ interface CommandResultData {
     data?: unknown;
     skillContent?: string;
     invocation?: CommandInvocationRequest;
+    workflow?: CommandWorkflowInvocationRequest;
 }
 interface CommandInvocationRequest extends CommandExecutionMetadata {
     prompt: string;
@@ -315,6 +343,11 @@ interface CommandInvocationRequest extends CommandExecutionMetadata {
     path?: string;
     skillInvocation?: KodaXSkillInvocationContext;
 }
+interface CommandWorkflowInvocationRequest {
+    request: string;
+    source: 'command' | 'natural-language';
+    displayName: string;
+}
 type CommandResult$1 = boolean | CommandResultData;
 type CommandHandler = (args: string[], context: InteractiveContext, callbacks: CommandCallbacks, currentConfig: CurrentConfig) => Promise<CommandResult$1 | void>;
 /**
@@ -358,6 +391,7 @@ declare function parseCommand(input: string): {
 type CommandResult = boolean | {
     skillContent?: string;
     invocation?: CommandInvocationRequest;
+    workflow?: CommandWorkflowInvocationRequest;
 };
 declare function executeCommand(parsed: {
     command: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodax-ai/kodax",
-  "version": "0.7.47",
+  "version": "0.7.49",
   "description": "极致轻量化 Coding Agent - TypeScript 实现，支持 12 个 LLM 提供商，可发布为免 Node 单文件二进制",
   "type": "module",
   "private": false,