@kodax-ai/kodax 0.7.48 → 0.7.50

package/dist/types-chunks/{types.d-BCnbYG_A.d.ts → process.d-BbiXD24v.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.
@@ -1882,6 +1884,124 @@ 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.
  *
@@ -2339,5 +2459,383 @@ interface FileOperations {
     modifiedFiles: string[];
 }
 
-export { DEFAULT_SYSTEM_CAP as D, GuardrailEscalateError as H, InvariantSession as R, MAX_TOOL_LOOP_ITERATIONS as S, detectInstructionsInjection as a$, Runner as a9, Tracer as aL, _resetAdmittedAgentBindings as aO, _resetPresetDispatchers as aP, buildAssistantMessageFromLlmResult as aQ, buildSystemPrompt as aR, buildToolResultMessage as aS, collectGuardrails as aT, createAgent as aU, createHandoff as aV, createInMemorySession as aW, createInvariantSessionForAgent as aX, createStateWriter as aY, createTrace as aZ, defaultTracer as a_, SpanImpl as ar, discoverInstances as b0, executeRunnerToolCall as b1, extractAssistantTextFromMessage as b2, getActiveUserInteraction as b3, getAdmittedAgentBindings as b4, isRunnableTool as b5, isRunnerLlmResult as b6, registerChildTask as b7, registerPresetDispatcher as b8, requestTaskStop as b9, runAdmissionAudit as ba, runInputGuardrails as bb, runOutputGuardrails as bc, runToolAfterGuardrails as bd, runToolBeforeGuardrails as be, setActiveUserInteraction as bf, setAdmittedAgentBindings as bg, GuardrailBlockedError as z };
-export type { ReadonlyMutationTracker as $, AdmissionAuditOptions as A, GuardrailContext as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, GuardrailSpanData as I, GuardrailVerdict as J, Handoff as K, HandoffSpanData as L, InMemorySessionOptions as M, InputGuardrail as N, InstanceDiscoveryFs as O, InvariantId as P, InvariantResult as Q, ManifestPatch as T, MessageEntry as U, ObserveCtx as V, OutputGuardrail as W, PersistedSessionState as X, PresetDispatcher as Y, PresetTracingContext as Z, QualityInvariant as _, AdmissionCtx as a, ReadonlyRecorder as a0, ReasoningDepth as a1, RecentlyModifiedFile as a2, RequestTaskStopOptions as a3, RequestTaskStopResult as a4, RunEvent as a5, RunOptions as a6, RunResult as a7, RunnableTool as a8, StopHookSpanData as aA, SystemCap as aB, TaskAbortRegistry as aC, TerminalCtx as aD, ToolBeforeOutcome as aE, ToolCallSpanData as aF, ToolCapability as aG, ToolGuardrail as aH, ToolPermission as aI, Trace as aJ, TraceOptions as aK, TracerOptions as aM, UserInteraction as aN, RunnerEvent as aa, RunnerLlmResult as ab, RunnerLlmReturn as ac, RunnerToolCall as ad, RunnerToolContext as ae, RunnerToolObserver as af, RunnerToolResult as ag, Session as ah, SessionDispatchResult as ai, SessionEntry as aj, SessionExtension as ak, SessionForkOptions as al, SessionMeta as am, SessionStateSnapshot as an, Span as ao, SpanData as ap, SpanError as aq, SpanImplOptions as as, StartTraceOptions as at, StateWriter as au, StateWriterFs as av, StateWriterOptions as aw, StopHookContext as ax, StopHookFn as ay, StopHookResult 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, 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 };
+/**
+ * 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_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;
+    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;
+}
+type WorkflowTaskSummaryKind = 'digest' | 'excerpt' | 'digest-failed' | 'pending';
+interface WorkflowTaskSummaryEventUpdate {
+    readonly summary?: string;
+    readonly summaryKind: WorkflowTaskSummaryKind;
+    readonly usage?: WorkflowTaskUsage;
+}
+/** 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;
+    /** True when a digest was scheduled asynchronously and may arrive via `agent_summary_updated`. */
+    readonly digestPending?: boolean;
+    /** Best-known provider/model used by the child, for host correlation only. */
+    readonly provider?: string;
+    readonly model?: string;
+    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. */
+    snapshot(taskId: string): Promise<WorkflowTaskSnapshot>;
+    /** Snapshot a (possibly running) agent.
+     *  @deprecated Prefer `snapshot(taskId)`; `output` is kept as a compatibility alias. */
+    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 late summary stream for presentation-only async digests. */
+    subscribeTaskSummaryUpdates?(listener: (taskId: string, update: WorkflowTaskSummaryEventUpdate) => void): () => 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[];
+}
+
+type WorkflowProcessStatus = 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type WorkflowProcessItemStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped';
+type WorkflowProcessItemKind = 'phase' | 'agent' | 'step' | 'artifact';
+type WorkflowProcessSummaryStatus = 'pending' | 'result' | 'notice' | 'unavailable';
+type WorkflowProcessSource = 'command' | 'amaw' | 'review' | 'sdk' | 'capsule' | 'extension' | 'automation';
+interface WorkflowProcessItem {
+    readonly id: string;
+    readonly title: string;
+    readonly kind: WorkflowProcessItemKind;
+    readonly status: WorkflowProcessItemStatus;
+    readonly phaseId?: string;
+    readonly parentId?: string;
+    readonly agentId?: string;
+    readonly childAgentId?: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly startedAt?: string;
+    readonly endedAt?: string;
+    readonly summary?: string;
+    readonly summaryStatus?: WorkflowProcessSummaryStatus;
+    readonly error?: string;
+}
+interface WorkflowEventCorrelation {
+    readonly workflowRunId: string;
+    readonly childAgentId?: string;
+    readonly phaseId?: string;
+    readonly itemId?: string;
+}
+interface WorkflowProcessCounts {
+    readonly pending: number;
+    readonly running: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly skipped: number;
+}
+interface WorkflowProcessProgress {
+    readonly spawnedAgents: number;
+    readonly finishedAgents: number;
+    readonly activeAgents: number;
+    readonly failedAgents: number;
+    readonly stoppedAgents: number;
+    readonly agentCap?: number;
+    readonly plannedItems?: number;
+}
+interface WorkflowProcessTokenUsage {
+    readonly spent: number;
+    readonly total?: number;
+}
+interface WorkflowProcessArtifact {
+    readonly name: string;
+    readonly path?: string;
+    readonly description?: string;
+}
+interface WorkflowProcessSnapshot {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly displayName?: string;
+    readonly status: WorkflowProcessStatus;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+    readonly elapsedMs?: number;
+    readonly goal?: string;
+    readonly source?: WorkflowProcessSource;
+    readonly savedWorkflowName?: string;
+    readonly sourceRunId?: string;
+    readonly sourceWorkflowName?: string;
+    readonly revisionOf?: string;
+    readonly activePhaseId?: string;
+    readonly activePhaseIndex?: number;
+    readonly phaseCount?: number;
+    readonly items: readonly WorkflowProcessItem[];
+    readonly counts: WorkflowProcessCounts;
+    readonly progress: WorkflowProcessProgress;
+    readonly tokens?: WorkflowProcessTokenUsage;
+    readonly latestMessage?: string;
+    readonly resultSummary?: string;
+    readonly error?: string;
+    readonly artifacts?: readonly WorkflowProcessArtifact[];
+}
+type WorkflowProcessEvent = {
+    readonly type: 'workflow_started';
+    readonly snapshot: WorkflowProcessSnapshot;
+} | {
+    readonly type: 'workflow_updated';
+    readonly snapshot: WorkflowProcessSnapshot;
+    readonly message?: string;
+} | {
+    readonly type: 'workflow_finished';
+    readonly snapshot: WorkflowProcessSnapshot;
+};
+interface WorkflowProcessTrackerOptions {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly displayName?: string;
+    readonly goal?: string;
+    readonly source?: WorkflowProcessSource;
+    readonly savedWorkflowName?: string;
+    readonly sourceRunId?: string;
+    readonly sourceWorkflowName?: string;
+    readonly revisionOf?: string;
+    readonly phases?: readonly string[];
+    readonly maxAgents?: number;
+    readonly plannedAgents?: number;
+    readonly tokenBudget?: number;
+    readonly resultSummary?: string;
+    readonly artifacts?: readonly WorkflowArtifactRef[];
+    readonly now?: () => string;
+}
+interface WorkflowTaskSummaryUpdate {
+    readonly summary?: string;
+    readonly summaryStatus: WorkflowProcessSummaryStatus;
+}
+interface WorkflowProcessTracker {
+    applyEvent(event: WorkflowEvent): WorkflowProcessEvent;
+    updateTaskSummary(taskId: string, update: WorkflowTaskSummaryUpdate): WorkflowProcessEvent | undefined;
+    setStatus(status: WorkflowProcessStatus, message?: string): WorkflowProcessEvent;
+    setResultSummary(resultSummary: string | undefined): WorkflowProcessEvent;
+    getSnapshot(): WorkflowProcessSnapshot;
+}
+declare function isFinalWorkflowProcessStatus(status: WorkflowProcessStatus): boolean;
+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 };

package/dist/types-chunks/{resolver.d-DkgJlEzr.d.ts → resolver.d-CQfaJbht.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';
 
 /**
@@ -61,8 +61,17 @@ declare abstract class KodaXAnthropicCompatProvider extends KodaXBaseProvider {
     abstract readonly name: string;
     readonly supportsThinking = true;
     protected abstract readonly config: KodaXProviderConfig;
-    protected client: Anthropic;
-    protected initClient(): void;
+    private _client?;
+    /**
+     * The SDK client is built lazily on first use. Constructing it requires the
+     * API key (`getApiKey()` throws when the env var is unset), so deferring it
+     * lets callers construct a provider and read static metadata (context
+     * window, model descriptors) without a key. This also keeps key-less unit
+     * tests (which mock the actual LLM calls) from failing at construction time.
+     */
+    protected get client(): Anthropic;
+    protected set client(client: Anthropic);
+    protected buildClient(): Anthropic;
     protected onStaleConnection(): void;
     /**
      * FEATURE_216 v0.7.45 — Lightweight credential verification.
@@ -122,8 +131,17 @@ declare abstract class KodaXOpenAICompatProvider extends KodaXBaseProvider {
     abstract readonly name: string;
     readonly supportsThinking = true;
     protected abstract readonly config: KodaXProviderConfig;
-    protected client: OpenAI;
-    protected initClient(): void;
+    private _client?;
+    /**
+     * The SDK client is built lazily on first use. Constructing it requires the
+     * API key (`getApiKey()` throws when the env var is unset), so deferring it
+     * lets callers construct a provider and read static metadata (context
+     * window, model descriptors) without a key. This also keeps key-less unit
+     * tests (which mock the actual LLM calls) from failing at construction time.
+     */
+    protected get client(): OpenAI;
+    protected set client(client: OpenAI);
+    protected buildClient(): OpenAI;
     protected onStaleConnection(): void;
     /**
      * FEATURE_216 v0.7.45 — Lightweight credential verification.

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-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;
 }