@kodax-ai/kodax 0.7.48 → 0.7.49

package/dist/types-chunks/{file-tracker.d-D7L_SbRm.d.ts → capsule.d-DaPuhyyK.d.ts}

@@ -1,6 +1,6 @@
-import { n as KodaXMessage } from './types.d-Cf-GCzac.js';
-import { f as AgentMessage, aj as SessionEntry, ah as Session, ak as SessionExtension, p as CompactionDetails, x as FileOperations } from './types.d-BCnbYG_A.js';
-import { s as KodaXSessionLineage, i as KodaXJsonValue, a as KodaXCompactMemorySeed, o as KodaXSessionEntry, z as KodaXSessionTreeNode, r as KodaXSessionLabelEntry, q as KodaXSessionGoalEntry, v as KodaXSessionNavigationOptions, k as KodaXSessionArtifactLedgerEntry } from './types.d-B_MIIApc.js';
+import { n as KodaXMessage } from './types.d-rPRl2LSB.js';
+import { f as AgentMessage, ap as SessionEntry, an as Session, a3 as QueueEventListener, a4 as QueuedMessage, E as EnqueueInput, v as DequeueFilter, aq as SessionExtension, p as CompactionDetails, z as FileOperations, b4 as WorkflowMeta, b5 as WorkflowModelHint, b6 as WorkflowModule } from './types.d-BR9oNWup.js';
+import { s as KodaXSessionLineage, i as KodaXJsonValue, a as KodaXCompactMemorySeed, o as KodaXSessionEntry, z as KodaXSessionTreeNode, r as KodaXSessionLabelEntry, q as KodaXSessionGoalEntry, v as KodaXSessionNavigationOptions, k as KodaXSessionArtifactLedgerEntry } from './types.d-BnjX2Gn4.js';
 
 /**
  * @kodax-ai/agent Constants
@@ -271,6 +271,98 @@ declare function getAgentConfigPath(...segments: string[]): string;
  */
 declare function getAppDataDir(appId: string): string;
 
+/**
+ * @kodax-ai/agent/messaging/queue — 2-tier agentId-scoped FIFO message queue.
+ *
+ * FEATURE_115 (v0.7.36).
+ *
+ * Invariants:
+ *   - In-priority FIFO: messages of the same priority drain in enqueue order.
+ *   - Cross-priority precedence: 'user' drains before 'background', regardless
+ *     of enqueue order.
+ *   - agentId routing: messages addressed to agentId X are only visible to
+ *     consumers filtering for that exact agentId. undefined ≠ "any agent" —
+ *     it specifically matches main-thread messages.
+ *   - Not persistent: process restart loses queue state, by design (matches
+ *     TodoStore semantics).
+ *
+ * The queue is process-global by default (`getMessageQueue()`); the class is
+ * also exported for tests / isolated downstream use.
+ */
+
+declare class MessageQueue {
+    private messages;
+    private nextSeq;
+    /**
+     * FEATURE_159 (v0.7.40) — observable subscription set. Same pattern as
+     * Claude Code's `messageQueueManager.ts` `createSignal()` substrate,
+     * but the listener carries a structured `QueueEvent` so SDK
+     * observability consumers (logger, tracer, metrics) can react per-
+     * event without re-diffing snapshots. `useSyncExternalStore` consumers
+     * still work — they ignore the event argument.
+     *
+     * Cached `snapshotRef` keeps reference identity stable across reads
+     * when nothing changed — required by React 18's `useSyncExternalStore`
+     * to avoid render loops.
+     */
+    private listeners;
+    private snapshotRef;
+    private notify;
+    /**
+     * Subscribe to queue mutations. Compatible with React 18's
+     * `useSyncExternalStore(subscribe, getSnapshot)` — the hook passes a
+     * `() => void` callback, which is structurally assignable to the
+     * `QueueEventListener` parameter because TypeScript treats
+     * callback parameter discards as compatible. SDK consumers that
+     * declare a typed `(event: QueueEvent) => void` listener see the
+     * structured event.
+     *
+     * Listener is called synchronously after every mutation; returns an
+     * unsubscribe function.
+     */
+    subscribe: (listener: QueueEventListener) => (() => void);
+    /**
+     * Returns the current frozen queue snapshot. Reference identity is
+     * stable across reads when the queue has not mutated, which is the
+     * contract React's `useSyncExternalStore` relies on.
+     */
+    getSnapshot: () => readonly QueuedMessage[];
+    /** Returns the assigned id of the enqueued message. */
+    enqueue(input: EnqueueInput): string;
+    /**
+     * Drain matching messages, ordered by priority (user > background) then
+     * FIFO within each priority. Removes drained messages from the queue.
+     */
+    dequeue(filter: DequeueFilter): QueuedMessage[];
+    /**
+     * Peek at matching messages without removing them. Returns messages in
+     * the same priority + FIFO order that `dequeue(filter)` would return,
+     * so callers can inspect what the next drain would yield.
+     */
+    peek(filter: DequeueFilter): QueuedMessage[];
+    /** Total queue size across all priorities / agents. */
+    size(): number;
+    /** Count of messages matching the filter. */
+    count(filter: DequeueFilter): number;
+    /** True iff at least one message matches the filter. */
+    has(filter: DequeueFilter): boolean;
+    /** Remove all queued messages — used in tests / process abort scenarios. */
+    clear(): void;
+}
+/**
+ * Returns the process-global MessageQueue singleton, creating it lazily on
+ * first call. Use this for production wiring; instantiate `MessageQueue`
+ * directly in tests / isolated subsystems where a shared instance would
+ * cause cross-test pollution.
+ */
+declare function getMessageQueue(): MessageQueue;
+/**
+ * Test-only reset hook. Production code MUST NOT call this. Underscored
+ * prefix follows the same convention as `_resetInvariantRegistry` /
+ * `_resetAdmittedAgentBindings` / `_resetAdmissionMetrics`.
+ */
+declare function _resetMessageQueueForTests(): void;
+
 /**
  * History cleanup middleware — CAP-002
  *
@@ -636,5 +728,78 @@ declare function mergeFileOps(ops1: FileOperations, ops2: FileOperations): FileO
 declare function extractArtifactLedger(messages: KodaXMessage[]): KodaXSessionArtifactLedgerEntry[];
 declare function mergeArtifactLedger(existing: KodaXSessionArtifactLedgerEntry[], next: KodaXSessionArtifactLedgerEntry[]): KodaXSessionArtifactLedgerEntry[];
 
-export { countActiveLineageMessages as A, countTokens as B, DefaultSummaryCompaction as D, createSessionLineage as E, estimateTokens as F, extractArtifactLedger as G, extractFileOps as H, extractTitleFromMessages as I, findPreviousUserEntryId as J, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, forkSessionLineage as M, generateSessionId as N, getAgentConfigHome as O, PROMISE_PATTERN as P, getAgentConfigPath as Q, getAppDataDir as R, getSessionLineagePath as S, getSessionMessagesFromLineage as T, mergeArtifactLedger as U, mergeFileOps as V, resolveSessionLineageTarget as W, rewindSessionLineage as X, setAgentConfigHome as Y, setSessionLineageActiveEntry as Z, validateAndFixToolHistory as _, KODAX_DEFAULT_TIMEOUT as e, KODAX_HARD_TIMEOUT as f, KODAX_MAX_INCOMPLETE_RETRIES as g, KODAX_MAX_MAXTOKENS_RETRIES as h, KODAX_MAX_RETRIES as i, KODAX_MAX_TOKENS as j, KODAX_RETRY_BASE_DELAY as k, KODAX_STAGGER_DELAY as l, LineageCompaction as n, LineageExtension as q, appendSessionLineageLabel as u, applyLineageTruncation as v, applySessionCompaction as w, archiveOldIslands as x, buildSessionTree as y, cleanupIncompleteToolCalls as z };
-export type { CompactionContext as C, CompactionEntry as a, CompactionEntryPayload as b, CompactionPolicy as c, DefaultSummaryCompactionOptions as d, LineageArtifactLedgerPayload as m, LineageCompactionDelegates as o, LineageEntryType as p, LineageLabelPayload as r, LineageTreeNode as s, PolicyCompactionResult as t };
+declare const WORKFLOW_PATTERN_IDS: readonly ["classify-and-act", "fan-out-and-synthesize", "adversarial-verification", "generate-and-filter", "tournament", "loop-until-done"];
+type WorkflowPatternId = (typeof WORKFLOW_PATTERN_IDS)[number];
+interface WorkflowScriptManifest extends WorkflowMeta {
+    readonly phases: readonly string[];
+    readonly readOnly: boolean;
+    readonly plannedAgents?: number;
+    readonly maxAgents: number;
+    readonly maxConcurrency: number;
+    readonly tokenBudget?: number;
+    readonly mayUseWorktree?: boolean;
+    readonly patterns: readonly WorkflowPatternId[];
+}
+declare function validateWorkflowScriptManifest(value: unknown): WorkflowScriptManifest;
+
+/**
+ * FEATURE_217 (v0.7.49) Phase M — reusable generated workflow capsule.
+ *
+ * Agent owns only the domain-neutral capsule contract. Persistence,
+ * environment preflight, skills, MCP, and REPL UX live in higher layers.
+ */
+
+declare const WORKFLOW_CAPSULE_FORMAT: "kodax.workflow";
+declare const WORKFLOW_CAPSULE_VERSION: 1;
+declare const WORKFLOW_CAPSULE_API_VERSION: 1;
+type WorkflowCapsuleEnvironmentRequirement = 'git-repo' | 'worktree-capable';
+interface WorkflowCapsuleIntent {
+    readonly taskClass: string;
+    readonly originalRequest?: string;
+    readonly reusableFor?: readonly string[];
+    readonly notFor?: readonly string[];
+}
+interface WorkflowCapsuleInputs {
+    readonly description: string;
+    readonly examples?: readonly unknown[];
+}
+interface WorkflowCapsuleRequirements {
+    readonly environment?: readonly WorkflowCapsuleEnvironmentRequirement[];
+    readonly tools?: readonly string[];
+    readonly mcp?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly modelTiers?: readonly WorkflowModelHint[];
+    readonly userInteraction?: boolean;
+}
+interface WorkflowCapsuleProvenance {
+    readonly fromRunId?: string;
+    readonly createdAt: string;
+    readonly kodaxVersion: string;
+}
+interface WorkflowCapsule {
+    readonly format: typeof WORKFLOW_CAPSULE_FORMAT;
+    readonly version: typeof WORKFLOW_CAPSULE_VERSION;
+    readonly workflowApiVersion: typeof WORKFLOW_CAPSULE_API_VERSION;
+    readonly minKodaxVersion: string;
+    readonly manifest: WorkflowScriptManifest;
+    readonly source: string;
+    readonly intent?: WorkflowCapsuleIntent;
+    readonly inputs?: WorkflowCapsuleInputs;
+    readonly requires?: WorkflowCapsuleRequirements;
+    readonly provenance?: WorkflowCapsuleProvenance;
+}
+interface CreateWorkflowCapsuleInput {
+    readonly minKodaxVersion: string;
+    readonly manifest: WorkflowScriptManifest;
+    readonly source: string;
+    readonly intent?: WorkflowCapsuleIntent;
+    readonly inputs?: WorkflowCapsuleInputs;
+    readonly requires?: WorkflowCapsuleRequirements;
+    readonly provenance?: WorkflowCapsuleProvenance;
+}
+declare function validateWorkflowCapsule(value: unknown): WorkflowCapsule;
+declare function createWorkflowCapsule(input: CreateWorkflowCapsuleInput): WorkflowCapsule;
+declare function createWorkflowModuleFromCapsule(capsule: WorkflowCapsule): WorkflowModule;
+
+export { extractFileOps as $, DefaultSummaryCompaction as D, appendSessionLineageLabel as I, applyLineageTruncation as J, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, MessageQueue as M, applySessionCompaction as N, archiveOldIslands as O, PROMISE_PATTERN as P, buildSessionTree as Q, cleanupIncompleteToolCalls as R, countActiveLineageMessages as S, countTokens as T, createSessionLineage as U, createWorkflowCapsule as V, WORKFLOW_CAPSULE_API_VERSION as W, createWorkflowModuleFromCapsule as X, estimateTokens as Y, extractArtifactLedger as Z, _resetMessageQueueForTests as _, extractTitleFromMessages as a0, findPreviousUserEntryId as a1, forkSessionLineage as a2, generateSessionId as a3, getAgentConfigHome as a4, getAgentConfigPath as a5, getAppDataDir as a6, getMessageQueue as a7, getSessionLineagePath as a8, getSessionMessagesFromLineage as a9, mergeArtifactLedger as aa, mergeFileOps as ab, resolveSessionLineageTarget as ac, rewindSessionLineage as ad, setAgentConfigHome as ae, setSessionLineageActiveEntry as af, validateAndFixToolHistory as ag, validateWorkflowCapsule as ah, validateWorkflowScriptManifest as ai, KODAX_DEFAULT_TIMEOUT as f, KODAX_HARD_TIMEOUT as g, KODAX_MAX_INCOMPLETE_RETRIES as h, KODAX_MAX_MAXTOKENS_RETRIES as i, KODAX_MAX_RETRIES as j, KODAX_MAX_TOKENS as k, KODAX_RETRY_BASE_DELAY as l, KODAX_STAGGER_DELAY as m, LineageCompaction as o, LineageExtension as r, WORKFLOW_CAPSULE_FORMAT as v, WORKFLOW_CAPSULE_VERSION as w, WORKFLOW_PATTERN_IDS as x };
+export type { WorkflowCapsuleInputs as A, WorkflowCapsuleIntent as B, CompactionContext as C, WorkflowCapsuleProvenance as E, WorkflowCapsuleRequirements as F, WorkflowPatternId as G, WorkflowScriptManifest as H, CompactionEntry as a, CompactionEntryPayload as b, CompactionPolicy as c, CreateWorkflowCapsuleInput as d, DefaultSummaryCompactionOptions as e, LineageArtifactLedgerPayload as n, LineageCompactionDelegates as p, LineageEntryType as q, LineageLabelPayload as s, LineageTreeNode as t, PolicyCompactionResult as u, WorkflowCapsule as y, WorkflowCapsuleEnvironmentRequirement as z };

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-BCnbYG_A.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.
@@ -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,244 @@ 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_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>;