@kodax-ai/kodax 0.7.41 → 0.7.42

package/dist/types-chunks/{history-cleanup.d-q1vAvCss.d.ts → history-cleanup.d-DznrzEiU.d.ts}

@@ -1,5 +1,5 @@
-import { o as KodaXMessage } from './capability.d-BxNgd1-c.js';
-import { a as AgentMessage, a7 as SpanData, a6 as Span, a8 as SpanError, A as Agent, _ as RunnerLlmReturn, G as Guardrail, a1 as RunnerToolObserver } from './instance-discovery.d-DZhp77vb.js';
+import { m as KodaXMessage } from './types.d-B1uGoVTE.js';
+import { a as AgentMessage, x as SpanData, w as Span, y as SpanError, A as Agent, q as RunnerLlmReturn, G as Guardrail, t as RunnerToolObserver } from './instance-discovery.d-BsKnIwpg.js';
 
 /**
  * @kodax-ai/agent Constants
@@ -977,14 +977,34 @@ interface RunOptions {
      */
     readonly toolObserver?: RunnerToolObserver;
     /**
-     * v0.7.26 parity: compaction hook. Called AFTER each iteration's
-     * tool_result has been appended to the transcript (or after the
-     * assistant message when there are no tool calls), before the next
-     * LLM turn. Return the replacement transcript to trigger compaction;
-     * return the same array (or undefined) to skip. Legacy agent.ts ran
-     * `intelligentCompact` on the same boundary, so Runner-driven parity
-     * requires this hook point. The Runner owns the transcript mutably,
-     * so this is the only point consumers can insert a compacted view.
+     * Compaction hook. Fires at the TOP of every tool-loop iteration,
+     * BEFORE the LLM call. Return the replacement transcript to trigger
+     * compaction; return the same array (or undefined) to skip. The Runner
+     * owns the transcript mutably, so this is the only point consumers can
+     * insert a compacted view before the next provider.stream invocation.
+     *
+     * **Trigger frequency**: every iteration of every Runner.run() call.
+     * - Iteration 0 fires BEFORE the first LLM call (covers idle-yield
+     *   resume / new user activation where the transcript already exceeds
+     *   threshold from accumulated prior turns).
+     * - Iteration N (N≥1) fires after the previous iteration's tool_result
+     *   was appended, same "before next LLM call" timing as the legacy
+     *   post-tool-result firing point.
+     * - Text-only iterations are covered: the next Runner.run() invocation
+     *   (when the user/parent re-engages) runs iter 0 → hook fires before
+     *   the new LLM call.
+     *
+     * **Why not after tool_result append (legacy v0.7.26 location)**: that
+     * boundary skipped text-only termination — Runner exits at line ~611
+     * without firing the hook, so idle-yield + text-only end-of-turn
+     * sessions grew unbounded between checks. claudecode (`query.ts:307-454`),
+     * pi-mono (`agent-session.ts:949`), opencode (`processor.ts:609-613`),
+     * and KodaX SA (`run-substrate.ts:621-627`) all check at the per-LLM-
+     * call boundary. FEATURE_179 (v0.7.42) brought the AMA Runner path
+     * into line — the failure scenario was a Worker session that grew
+     * 165K → 180K through text-only end-of-turn + idle-yield, then
+     * triggered at 181K (61K over the 120K threshold) only after the next
+     * tool call landed.
      */
     readonly compactionHook?: (transcript: readonly AgentMessage[]) => Promise<readonly AgentMessage[] | undefined>;
     /**
@@ -1090,7 +1110,84 @@ interface RunOptions {
         readonly to: Agent;
         readonly iteration: number;
     }) => void | Promise<void>;
+    /**
+     * FEATURE_184 (v0.7.45) — Stop Hook primitive.
+     *
+     * Fires when the model terminates a turn with no `tool_use` blocks
+     * (text-only response). The hook receives the post-output-guardrail
+     * transcript and the final assistant text, and returns one of:
+     *
+     * - `undefined` → accept the termination, fall through to the normal
+     *   terminal path (assertTerminal + return). This is the no-op default.
+     * - `string` → "blockingErrors" / reanimate. Runner synthesizes a
+     *   `{role: 'user', content: <string>}` message, appends it to the
+     *   transcript + session, and continues the loop. Bounded by
+     *   `stopHookReanimateBudget` (default 2); exceeded budget converts
+     *   the string return to a forced abort.
+     * - `{abort: true, reason}` → preventContinuation / halt-and-surface.
+     *   Run returns immediately with `output = reason` and
+     *   `stoppedByHook = true`. assertTerminal still fires before the
+     *   return so invariant violations on the halted state surface
+     *   normally.
+     *
+     * Errors thrown by the hook are caught and treated as `undefined`
+     * (fail-open). A span is emitted for observability. Matches the
+     * `compactionHook` failure semantics — a buggy hook must never
+     * abort the run.
+     *
+     * Design reference: claudecode `query.ts:1282-1305` blockingErrors +
+     * `query.ts:1278` preventContinuation. Generalizes the deterministic
+     * shell-script Stop hook surface to an LLM-driven Sidecar Verifier
+     * (the v0.7.45 first consumer; see FEATURE_184 Phase D).
+     */
+    readonly stopHook?: StopHookFn;
+    /**
+     * FEATURE_184 (v0.7.45) — Reanimate budget for `stopHook`. Default 2.
+     *
+     * When `stopHook` returns a string AND `reanimateCount` has already
+     * reached this budget, the string return is forcibly converted to an
+     * abort with reason `"reanimate budget exhausted: <string>"`. Prevents
+     * unbounded reanimate loops when the hook + model disagree on
+     * completion forever.
+     */
+    readonly stopHookReanimateBudget?: number;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook context handed to the caller's
+ * `stopHook` when the model terminates a turn text-only.
+ */
+interface StopHookContext {
+    /** Transcript snapshot at the moment the hook fires. Includes the
+     *  just-pushed final assistant message. Readonly — the hook must not
+     *  mutate; to influence the run return a `string` (reanimate) or
+     *  `{abort, reason}` instead. */
+    readonly transcript: readonly AgentMessage[];
+    /** Convenience field: the final assistant message's text content. */
+    readonly lastAssistantText: string;
+    /** Why the turn ended. For Phase A this is always `'natural-end'`
+     *  (model emitted no `tool_use`). Future signal sources (explicit
+     *  COMPLETE protocol emission, harness-injected stop) can extend
+     *  the union without breaking existing hooks. */
+    readonly signal: 'natural-end';
+    /** How many times the hook has already reanimated this run. Starts
+     *  at 0; incremented after each `string` return. Hooks can use this
+     *  for telemetry but enforcement is Runner-side. */
+    readonly reanimateCount: number;
+    /** Total reanimate budget for this run (`stopHookReanimateBudget`
+     *  or default 2). Exposed for transparency. */
+    readonly reanimateBudget: number;
 }
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook return surface.
+ */
+type StopHookResult = undefined | string | {
+    readonly abort: true;
+    readonly reason: string;
+};
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook signature.
+ */
+type StopHookFn = (ctx: StopHookContext) => StopHookResult | Promise<StopHookResult>;
 /**
  * Result returned by `Runner.run`.
  */
@@ -1099,6 +1196,12 @@ interface RunResult<TData = unknown> {
     readonly messages: readonly AgentMessage[];
     readonly sessionId?: string;
     readonly data?: TData;
+    /** FEATURE_184 (v0.7.45): `true` when the run terminated because
+     *  the caller's `stopHook` returned `{abort: true}` OR because the
+     *  hook's `string` return exceeded `stopHookReanimateBudget`. The
+     *  abort reason is in `output`. Sidecar Verifier sets this when it
+     *  outputs a `blocked` verdict (halt + surface to user). */
+    readonly stoppedByHook?: boolean;
 }
 /**
  * Stream events emitted by `Runner.runStream`. The event surface is
@@ -1203,6 +1306,112 @@ declare class Runner {
 /** @internal Exposed so preset dispatchers can extract the assistant text from a KodaXResult. */
 declare function extractAssistantTextFromMessage(message: AgentMessage): string;
 
+/**
+ * v0.7.35.1 FEATURE_145 — Agent config home, 3-tier resolution.
+ *
+ * Centralizes the user-config directory used to be hardcoded across
+ * ~30 sites in 6 packages as `path.join(os.homedir(), '.kodax', ...)`.
+ * That pattern had two problems:
+ *
+ *   1. **Drift**: each new caller in a future feature was a fresh
+ *      hardcode site; nothing stopped a caller from using the wrong
+ *      string (`'kodax'` instead of `'.kodax'`, etc.).
+ *   2. **Substrate consumer coupling**: when `@kodax-ai/agent` is reused
+ *      by a downstream agent (e.g. `@kodax-ai/ops-agent`,
+ *      `@kodax-ai/data-analysis-agent`), there was no way to redirect the
+ *      runtime config dir — every derivative agent was forced to
+ *      share the `~/.kodax/` namespace.
+ *
+ * The helper exposes a 3-tier priority chain:
+ *
+ *   1. **Programmatic override** via {@link setAgentConfigHome} —
+ *      highest priority. Substrate consumers call this once at boot,
+ *      before any subsystem reads the path.
+ *   2. **`KODAX_HOME` env var** — middle priority. Used by shell / CI /
+ *      test isolation / multi-tenant shared machines. (Already honored
+ *      historically by `@kodax-ai/llm/src/reasoning-overrides.ts`; this
+ *      helper makes it the canonical path for all packages.)
+ *   3. **`~/.kodax/`** — lowest priority. Default for the standalone
+ *      kodax CLI. With DI not set + env not set, the resolver returns
+ *      the same byte sequence as the prior hardcoded
+ *      `path.join(os.homedir(), '.kodax')` calls — so the migration
+ *      from hardcoded sites to this helper is byte-equivalent for the
+ *      existing user base.
+ *
+ * Why a process-level singleton (and not per-call DI):
+ * the ~30 fs callsites are buried in library helpers (construction /
+ * mcp catalog / oauth tokens / paste-cache etc.). Threading a
+ * `configHome` parameter through every helper would change ~50
+ * function signatures, and every caller would have to remember to
+ * thread it — a single forgotten thread silently falls back to
+ * default. Singleton matches the `process.env.NODE_ENV` pattern: a
+ * process really has a single config home (no legitimate use case
+ * for a process to interleave reads/writes against `~/.kodax/` AND
+ * `~/.opsagent/` simultaneously).
+ *
+ * NOT migrated:
+ *   - `@kodax-ai/llm/src/reasoning-overrides.ts:49` keeps its inline
+ *     `process.env.KODAX_HOME ?? path.join(os.homedir(), '.kodax')`
+ *     fallback because moving it to this helper would create an
+ *     `@kodax-ai/llm → @kodax-ai/agent` dependency cycle (agent already
+ *     imports ai). The two implementations have identical observable
+ *     behavior at the env / default tiers; the programmatic override
+ *     tier doesn't apply to ai-layer code.
+ *   - **Project-relative** `.kodax/` paths (e.g. `path.join(projectRoot,
+ *     '.kodax', 'AGENTS.md')`) are NOT migrated — those name a
+ *     different concept (per-project config) and use a different root.
+ *   - **CWD-relative** subpath constants like `path.join('.kodax',
+ *     'constructed', '_audit.jsonl')` (joined with a project root by
+ *     the caller) are likewise project-scoped and stay as-is.
+ */
+/**
+ * Set the agent config home programmatically. Highest priority in
+ * {@link getAgentConfigHome}'s 3-tier chain.
+ *
+ * Substrate consumers (e.g. an agent built on top of `@kodax-ai/agent`)
+ * should call this once at process boot, before any subsystem reads
+ * the path. Pass `undefined` to reset (used in tests).
+ */
+declare function setAgentConfigHome(path: string | undefined): void;
+/**
+ * Resolve the agent runtime config home directory.
+ *
+ * Priority (high → low):
+ *   1. Programmatic override via {@link setAgentConfigHome}
+ *   2. `KODAX_HOME` env var
+ *   3. `~/.kodax` (hardcoded default)
+ */
+declare function getAgentConfigHome(): string;
+/**
+ * Resolve a sub-path under the agent config home.
+ *
+ * Equivalent to `path.join(getAgentConfigHome(), ...segments)` but
+ * shorter at every callsite (which is the entire point of the helper —
+ * 30 callsites of `path.join(os.homedir(), '.kodax', x, y)` collapse to
+ * 30 callsites of `getAgentConfigPath(x, y)`).
+ */
+declare function getAgentConfigPath(...segments: string[]): string;
+/**
+ * v0.7.42 — Namespaced data directory for third-party apps embedding the
+ * KodaX SDK (e.g. `KodaX Space` desktop client, IDE extensions).
+ *
+ * Returns `${getAgentConfigHome()}/apps/<appId>/` and creates the directory
+ * if missing. Provides a coordination point so multiple SDK consumers can
+ * share `~/.kodax/` without colliding on path conventions.
+ *
+ * Constraints:
+ *   - `appId` must match `^[a-z][a-z0-9-]{1,31}$` (lowercase kebab, 2–32 chars,
+ *     no dots, no slashes, no underscores) — keeps the directory name safe
+ *     across all filesystems and prevents `../` traversal.
+ *   - Reserved prefixes (`kodax`, `kodax-*`) are rejected to leave room
+ *     for first-party feature directories that may collide later.
+ *
+ * The convention is intentionally light — no central registry, no manifest.
+ * Apps owning their data dir means SDK upgrades cannot trample on third-party
+ * state. Apps are responsible for migration/cleanup within their own subtree.
+ */
+declare function getAppDataDir(appId: string): string;
+
 /**
  * History cleanup middleware — CAP-002
  *
@@ -1262,5 +1471,5 @@ declare function validateAndFixToolHistory(messages: KodaXMessage[]): KodaXMessa
  */
 declare function cleanupIncompleteToolCalls(messages: KodaXMessage[]): KodaXMessage[];
 
-export { cleanupIncompleteToolCalls as $, DEFAULT_SYSTEM_CAP as D, Runner as G, KODAX_API_MIN_INTERVAL as K, PROMISE_PATTERN as P, _resetPresetDispatchers as Y, buildSystemPrompt as Z, _resetAdmittedAgentBindings as _, countTokens as a0, createInMemorySession as a1, createInvariantSessionForAgent as a2, detectInstructionsInjection as a3, estimateTokens as a4, extractAssistantTextFromMessage as a5, getAdmittedAgentBindings as a6, registerPresetDispatcher as a7, runAdmissionAudit as a8, setAdmittedAgentBindings as a9, validateAndFixToolHistory as aa, DefaultSummaryCompaction as h, InvariantSession as m, KODAX_DEFAULT_TIMEOUT as n, KODAX_HARD_TIMEOUT as o, KODAX_MAX_INCOMPLETE_RETRIES as p, KODAX_MAX_MAXTOKENS_RETRIES as q, KODAX_MAX_RETRIES as r, KODAX_MAX_TOKENS as s, KODAX_RETRY_BASE_DELAY as t, KODAX_STAGGER_DELAY as u };
-export type { AdmissionAuditOptions as A, RunEvent as B, CompactionContext as C, RunOptions as E, RunResult as F, RunnerEvent as H, InMemorySessionOptions as I, SessionDispatchResult as J, SessionEntry as L, ManifestPatch as M, SessionExtension as N, ObserveCtx as O, QualityInvariant as Q, ReadonlyMutationTracker as R, Session as S, SessionForkOptions as T, SystemCap as U, TerminalCtx as V, ToolCapability as W, ToolPermission as X, AdmissionCtx as a, AdmissionVerdict as b, AdmittedHandle as c, AgentManifest as d, CompactionEntry as e, CompactionEntryPayload as f, CompactionPolicy as g, DefaultSummaryCompactionOptions as i, Deliverable as j, InvariantId as k, InvariantResult as l, MessageEntry as v, PolicyCompactionResult as w, PresetDispatcher as x, PresetTracingContext as y, ReadonlyRecorder as z };
+export { _resetAdmittedAgentBindings as $, DEFAULT_SYSTEM_CAP as D, Runner as G, KODAX_API_MIN_INTERVAL as K, PROMISE_PATTERN as P, _resetPresetDispatchers as a0, buildSystemPrompt as a1, cleanupIncompleteToolCalls as a2, countTokens as a3, createInMemorySession as a4, createInvariantSessionForAgent as a5, detectInstructionsInjection as a6, estimateTokens as a7, extractAssistantTextFromMessage as a8, getAdmittedAgentBindings as a9, getAgentConfigHome as aa, getAgentConfigPath as ab, getAppDataDir as ac, registerPresetDispatcher as ad, runAdmissionAudit as ae, setAdmittedAgentBindings as af, setAgentConfigHome as ag, validateAndFixToolHistory as ah, DefaultSummaryCompaction as h, InvariantSession as m, KODAX_DEFAULT_TIMEOUT as n, KODAX_HARD_TIMEOUT as o, KODAX_MAX_INCOMPLETE_RETRIES as p, KODAX_MAX_MAXTOKENS_RETRIES as q, KODAX_MAX_RETRIES as r, KODAX_MAX_TOKENS as s, KODAX_RETRY_BASE_DELAY as t, KODAX_STAGGER_DELAY as u };
+export type { AdmissionAuditOptions as A, RunEvent as B, CompactionContext as C, RunOptions as E, RunResult as F, RunnerEvent as H, InMemorySessionOptions as I, SessionDispatchResult as J, SessionEntry as L, ManifestPatch as M, SessionExtension as N, ObserveCtx as O, QualityInvariant as Q, ReadonlyMutationTracker as R, Session as S, SessionForkOptions as T, StopHookContext as U, StopHookFn as V, StopHookResult as W, SystemCap as X, TerminalCtx as Y, ToolCapability as Z, ToolPermission as _, AdmissionCtx as a, AdmissionVerdict as b, AdmittedHandle as c, AgentManifest as d, CompactionEntry as e, CompactionEntryPayload as f, CompactionPolicy as g, DefaultSummaryCompactionOptions as i, Deliverable as j, InvariantId as k, InvariantResult as l, MessageEntry as v, PolicyCompactionResult as w, PresetDispatcher as x, PresetTracingContext as y, ReadonlyRecorder as z };

package/dist/types-chunks/{instance-discovery.d-DZhp77vb.d.ts → instance-discovery.d-BsKnIwpg.d.ts}

@@ -1,255 +1,4 @@
-import { o as KodaXMessage, _ as KodaXToolDefinition, G as KodaXReasoningMode, W as KodaXThinkingBlock, J as KodaXRedactedThinkingBlock } from './capability.d-BxNgd1-c.js';
-
-/**
- * @kodax-ai/agent Types
- *
- * 通用 Agent 类型定义
- */
-
-type KodaXJsonPrimitive = string | number | boolean | null;
-type KodaXJsonValue = KodaXJsonPrimitive | KodaXJsonValue[] | {
-    [key: string]: KodaXJsonValue;
-};
-/**
- * Session error metadata - 会话错误元数据
- * Used for error recovery and session cleanup - 用于错误恢复和会话清理
- */
-interface SessionErrorMetadata {
-    /** Last error message - 最后的错误消息 */
-    lastError?: string;
-    /** Last error timestamp - 最后错误时间戳 */
-    lastErrorTime?: number;
-    /** Consecutive error count - 连续错误计数 */
-    consecutiveErrors: number;
-}
-interface KodaXExtensionSessionRecord {
-    id: string;
-    extensionId: string;
-    type: string;
-    ts: number;
-    data?: KodaXJsonValue;
-    dedupeKey?: string;
-}
-type KodaXExtensionSessionState = Record<string, Record<string, KodaXJsonValue>>;
-interface KodaXSessionEntryBase {
-    id: string;
-    parentId: string | null;
-    timestamp: string;
-}
-interface KodaXSessionMessageEntry extends KodaXSessionEntryBase {
-    type: 'message';
-    message: KodaXMessage;
-}
-interface KodaXSessionCompactionEntry extends KodaXSessionEntryBase {
-    type: 'compaction';
-    summary: string;
-    firstKeptEntryId?: string;
-    tokensBefore?: number;
-    tokensAfter?: number;
-    artifactLedgerId?: string;
-    reason?: string;
-    details?: KodaXJsonValue;
-    memorySeed?: KodaXCompactMemorySeed;
-    /**
-     * FEATURE_072: post-compact ledger summary + file-content messages that
-     * are inlined after the compaction summary at slicer time
-     * (`getSessionMessagesFromLineage`). Stored here so they leave the active
-     * path automatically when a new compaction entry is appended.
-     *
-     * NOTE: attachments are emitted by the slicer, NOT by `getContextMessagesForEntry`
-     * — preserving the latter's 1-to-1 contract that `entryMatchesContextMessage`
-     * and FEATURE_073's future slicing both depend on.
-     */
-    postCompactAttachments?: readonly KodaXMessage[];
-}
-interface KodaXSessionBranchSummaryEntry extends KodaXSessionEntryBase {
-    type: 'branch_summary';
-    summary: string;
-    fromId?: string;
-    details?: KodaXJsonValue;
-}
-interface KodaXSessionLabelEntry extends KodaXSessionEntryBase {
-    type: 'label';
-    targetId: string;
-    label?: string;
-}
-interface KodaXSessionArchiveMarkerEntry extends KodaXSessionEntryBase {
-    type: 'archive_marker';
-    /** Links to the corresponding batch in the .archive.jsonl sidecar file */
-    archiveBatchId: string;
-    /** Number of entries that were archived in this batch */
-    archivedEntryCount: number;
-    /** Brief summary of the archived content */
-    summary: string;
-}
-type KodaXSessionEntry = KodaXSessionMessageEntry | KodaXSessionCompactionEntry | KodaXSessionBranchSummaryEntry | KodaXSessionLabelEntry | KodaXSessionArchiveMarkerEntry;
-interface KodaXSessionArtifactLedgerEntry {
-    id: string;
-    kind: 'file_read' | 'file_modified' | 'file_created' | 'file_deleted' | 'path_scope' | 'search_scope' | 'command_scope' | 'check_result' | 'decision' | 'image_input' | 'tombstone';
-    sourceTool?: string;
-    action?: string;
-    target: string;
-    displayTarget?: string;
-    summary?: string;
-    sessionEntryId?: string;
-    timestamp: string;
-    metadata?: Record<string, KodaXJsonValue>;
-}
-interface KodaXCompactMemoryProgress {
-    completed: string[];
-    inProgress: string[];
-    blockers: string[];
-}
-interface KodaXCompactMemorySeed {
-    objective?: string;
-    constraints: string[];
-    progress: KodaXCompactMemoryProgress;
-    keyDecisions: string[];
-    nextSteps: string[];
-    keyContext: string[];
-    importantTargets: string[];
-    tombstones: string[];
-}
-interface KodaXSessionLineage {
-    version: 2;
-    activeEntryId: string | null;
-    entries: KodaXSessionEntry[];
-}
-interface KodaXSessionNavigationOptions {
-    summarizeCurrentBranch?: boolean;
-}
-interface KodaXSessionTreeNode {
-    entry: Exclude<KodaXSessionEntry, KodaXSessionLabelEntry>;
-    children: KodaXSessionTreeNode[];
-    label?: string;
-    active: boolean;
-}
-type KodaXSessionScope = 'user' | 'managed-task-worker';
-type KodaXSessionUiHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint';
-interface KodaXSessionUiHistoryItem {
-    type: KodaXSessionUiHistoryItemType;
-    text: string;
-    icon?: string;
-    compactText?: string;
-}
-type KodaXSessionWorkspaceKind = 'detected' | 'managed';
-interface KodaXSessionRuntimeInfo {
-    canonicalRepoRoot?: string;
-    workspaceRoot?: string;
-    executionCwd?: string;
-    branch?: string;
-    workspaceKind?: KodaXSessionWorkspaceKind;
-}
-interface KodaXSessionData {
-    messages: KodaXMessage[];
-    title: string;
-    gitRoot: string;
-    runtimeInfo?: KodaXSessionRuntimeInfo;
-    scope?: KodaXSessionScope;
-    uiHistory?: KodaXSessionUiHistoryItem[];
-    errorMetadata?: SessionErrorMetadata;
-    extensionState?: KodaXExtensionSessionState;
-    extensionRecords?: KodaXExtensionSessionRecord[];
-    lineage?: KodaXSessionLineage;
-    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
-}
-interface KodaXSessionMeta {
-    _type: 'meta';
-    title: string;
-    id: string;
-    gitRoot: string;
-    runtimeInfo?: KodaXSessionRuntimeInfo;
-    createdAt: string;
-    scope?: KodaXSessionScope;
-    uiHistory?: KodaXSessionUiHistoryItem[];
-    extensionState?: KodaXExtensionSessionState;
-    extensionRecordCount?: number;
-    artifactLedgerCount?: number;
-    lineageVersion?: 2;
-    activeEntryId?: string | null;
-    lineageEntryCount?: number;
-    activeMessageCount?: number;
-    /** Error metadata for recovery - 错误元数据用于恢复 */
-    errorMetadata?: SessionErrorMetadata;
-}
-/**
- * Extension-scoped persistence entry.
- *
- * Each entry belongs to a namespace (extensionId) and carries
- * a string key, a JSON-safe value, and an opaque version tag
- * used for optimistic concurrency control.
- */
-interface KodaXExtensionStoreEntry {
-    key: string;
-    value: KodaXJsonValue;
-    version: string;
-    updatedAt: number;
-}
-/**
- * Extension persistence store interface (FEATURE_034 manual persistence).
- *
- * Implementations provide a durable key-value store scoped to a single
- * extension identity.  The store is independent of session lifecycle —
- * data survives across sessions and restarts.
- */
-interface KodaXExtensionStore {
-    /**
-     * Read a single key.
-     * Returns `undefined` when the key does not exist.
-     */
-    get(key: string): Promise<KodaXExtensionStoreEntry | undefined>;
-    /**
-     * Write a key-value pair.
-     *
-     * When `expectedVersion` is provided the write only succeeds when the
-     * stored entry's version still matches (optimistic concurrency).
-     * Returns the new entry on success, or `false` on version mismatch.
-     */
-    put(key: string, value: KodaXJsonValue, options?: {
-        expectedVersion?: string;
-    }): Promise<KodaXExtensionStoreEntry | false>;
-    /**
-     * Remove a key.
-     * Returns `true` when the key existed and was removed.
-     */
-    delete(key: string): Promise<boolean>;
-    /**
-     * List all keys (optionally filtered by prefix).
-     */
-    list(options?: {
-        prefix?: string;
-    }): Promise<string[]>;
-    /**
-     * Clear all keys (optionally filtered by prefix).
-     * Returns the number of entries removed.
-     */
-    clear(options?: {
-        prefix?: string;
-    }): Promise<number>;
-}
-interface KodaXSessionStorage {
-    save(id: string, data: KodaXSessionData): Promise<void>;
-    load(id: string): Promise<KodaXSessionData | null>;
-    getLineage?(id: string): Promise<KodaXSessionLineage | null>;
-    setActiveEntry?(id: string, selector: string, options?: KodaXSessionNavigationOptions): Promise<KodaXSessionData | null>;
-    setLabel?(id: string, selector: string, label?: string): Promise<KodaXSessionData | null>;
-    rewind?(id: string, selector?: string): Promise<KodaXSessionData | null>;
-    fork?(id: string, selector?: string, options?: {
-        sessionId?: string;
-        title?: string;
-    }): Promise<{
-        sessionId: string;
-        data: KodaXSessionData;
-    } | null>;
-    list?(gitRoot?: string): Promise<Array<{
-        id: string;
-        title: string;
-        msgCount: number;
-        runtimeInfo?: KodaXSessionRuntimeInfo;
-    }>>;
-    delete?(id: string): Promise<void>;
-    deleteAll?(gitRoot?: string): Promise<void>;
-}
+import { X as KodaXToolDefinition, m as KodaXMessage, D as KodaXReasoningMode, Z as KodaXToolResultContentItem, T as KodaXThinkingBlock, G as KodaXRedactedThinkingBlock } from './types.d-B1uGoVTE.js';
 
 /**
  * Layer A Primitive: Agent / Handoff / Guardrail / AgentReasoningProfile
@@ -508,12 +257,29 @@ interface FanoutSpanData {
     readonly winnerChildId?: string;
     readonly cancelledChildIds?: readonly string[];
 }
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook observability.
+ *
+ * Emitted when the Runner's `RunOptions.stopHook` is invoked or fails.
+ * `outcome` records what the hook returned (or `'error'` for thrown
+ * exceptions — fail-open path), `reanimateCount` is the running count
+ * after this invocation. `reason` carries the abort/reanimate text
+ * when relevant, truncated by consumers as needed.
+ */
+interface StopHookSpanData {
+    readonly kind: 'stop-hook';
+    readonly outcome: 'accept' | 'reanimate' | 'abort' | 'budget-exhausted' | 'error';
+    readonly reanimateCount: number;
+    readonly reanimateBudget: number;
+    readonly reason?: string;
+    readonly error?: string;
+}
 /**
  * Discriminated union of all span payload shapes. Additional variants may
  * be added in future features — consumers should check `kind` before
  * reading specific fields.
  */
-type SpanData = AgentSpanData | GenerationSpanData | ToolCallSpanData | HandoffSpanData | CompactionSpanData | GuardrailSpanData | EvidenceSpanData | FanoutSpanData;
+type SpanData = AgentSpanData | GenerationSpanData | ToolCallSpanData | HandoffSpanData | CompactionSpanData | GuardrailSpanData | EvidenceSpanData | FanoutSpanData | StopHookSpanData;
 
 /**
  * Span — a single timed unit of work inside a Trace.
@@ -644,11 +410,18 @@ interface RunnerToolContext {
     readonly toolCallId?: string;
 }
 /**
- * Value returned by `RunnableTool.execute`. The `content` string is what the
- * LLM sees in the next turn as `tool_result`.
+ * Value returned by `RunnableTool.execute`. The `content` is what the LLM
+ * sees in the next turn as `tool_result`:
+ *
+ *   - `string` — plain text (the default for most tools).
+ *   - `readonly KodaXToolResultContentItem[]` — an array of typed items
+ *     (text + image), used by multimodal tools like `read` on an image
+ *     path. Provider serializers lower each item to the wire format
+ *     (Anthropic accepts inline; OpenAI-compat downgrades image to text
+ *     placeholder).
  */
 interface RunnerToolResult {
-    readonly content: string;
+    readonly content: string | readonly KodaXToolResultContentItem[];
     readonly isError?: boolean;
     readonly metadata?: Record<string, unknown>;
 }
@@ -1213,5 +986,5 @@ interface DiscoveryOptions {
  */
 declare function discoverInstances(options?: DiscoveryOptions): DiscoveredInstance[];
 
-export { MAX_TOOL_LOOP_ITERATIONS as R, buildAssistantMessageFromLlmResult as af, buildToolResultMessage as ag, collectGuardrails as ah, createAgent as ai, createHandoff as aj, createStateWriter as ak, discoverInstances as al, executeRunnerToolCall as am, isRunnableTool as an, isRunnerLlmResult as ao, registerChildTask as ap, requestTaskStop as aq, runInputGuardrails as ar, runOutputGuardrails as as, runToolAfterGuardrails as at, runToolBeforeGuardrails as au, GuardrailBlockedError as g, GuardrailEscalateError as i };
-export type { RunnerToolCall as $, Agent as A, KodaXSessionMessageEntry as B, ChildTaskRegistry as C, DiscoveredInstance as D, KodaXSessionMeta as E, KodaXSessionNavigationOptions as F, Guardrail as G, Handoff as H, InputGuardrail as I, KodaXSessionRuntimeInfo as J, KodaXCompactMemoryProgress as K, KodaXSessionScope as L, KodaXSessionStorage as M, KodaXSessionTreeNode as N, KodaXSessionUiHistoryItem as O, KodaXSessionUiHistoryItemType as P, KodaXSessionWorkspaceKind as Q, OutputGuardrail as S, PersistedSessionState as T, ReasoningDepth as U, RecentlyModifiedFile as V, RequestTaskStopOptions as W, RequestTaskStopResult as X, RunnableTool as Y, RunnerLlmResult as Z, RunnerLlmReturn as _, AgentMessage as a, RunnerToolContext as a0, RunnerToolObserver as a1, RunnerToolResult as a2, SessionErrorMetadata as a3, SessionMeta as a4, SessionStateSnapshot as a5, Span as a6, SpanData as a7, SpanError as a8, StateWriter as a9, StateWriterFs as aa, StateWriterOptions as ab, TaskAbortRegistry as ac, ToolBeforeOutcome as ad, ToolGuardrail as ae, AgentMiddlewareDeclaration as b, AgentReasoningProfile as c, AgentTool as d, CurrentTodoSummary as e, DiscoveryOptions as f, GuardrailContext as h, GuardrailVerdict as j, InstanceDiscoveryFs as k, KodaXCompactMemorySeed as l, KodaXExtensionSessionRecord as m, KodaXExtensionSessionState as n, KodaXExtensionStore as o, KodaXExtensionStoreEntry as p, KodaXJsonValue as q, KodaXSessionArchiveMarkerEntry as r, KodaXSessionArtifactLedgerEntry as s, KodaXSessionBranchSummaryEntry as t, KodaXSessionCompactionEntry as u, KodaXSessionData as v, KodaXSessionEntry as w, KodaXSessionEntryBase as x, KodaXSessionLabelEntry as y, KodaXSessionLineage as z };
+export { requestTaskStop as $, buildAssistantMessageFromLlmResult as K, buildToolResultMessage as L, MAX_TOOL_LOOP_ITERATIONS as M, collectGuardrails as N, createAgent as Q, createHandoff as U, createStateWriter as V, discoverInstances as W, executeRunnerToolCall as X, isRunnableTool as Y, isRunnerLlmResult as Z, registerChildTask as _, runInputGuardrails as a0, runOutputGuardrails as a1, runToolAfterGuardrails as a2, runToolBeforeGuardrails as a3, GuardrailBlockedError as g, GuardrailEscalateError as i };
+export type { Agent as A, StateWriterFs as B, ChildTaskRegistry as C, DiscoveredInstance as D, StateWriterOptions as E, ToolBeforeOutcome as F, Guardrail as G, Handoff as H, InputGuardrail as I, ToolGuardrail as J, OutputGuardrail as O, PersistedSessionState as P, ReasoningDepth as R, SessionMeta as S, TaskAbortRegistry as T, AgentMessage as a, AgentMiddlewareDeclaration as b, AgentReasoningProfile as c, AgentTool as d, CurrentTodoSummary as e, DiscoveryOptions as f, GuardrailContext as h, GuardrailVerdict as j, InstanceDiscoveryFs as k, RecentlyModifiedFile as l, RequestTaskStopOptions as m, RequestTaskStopResult as n, RunnableTool as o, RunnerLlmResult as p, RunnerLlmReturn as q, RunnerToolCall as r, RunnerToolContext as s, RunnerToolObserver as t, RunnerToolResult as u, SessionStateSnapshot as v, Span as w, SpanData as x, SpanError as y, StateWriter as z };

package/dist/types-chunks/{resolver.d-BwD6TKz7.d.ts → resolver.d-DX9au4NJ.d.ts}

@@ -1,6 +1,6 @@
-import { G as KodaXReasoningMode, X as KodaXThinkingBudgetMap, Y as KodaXThinkingDepth, t as KodaXProviderConfig, F as KodaXReasoningCapability, I as KodaXReasoningRequest, T as KodaXTaskType, H as KodaXReasoningOverride, _ as KodaXToolDefinition, o as KodaXMessage, B as KodaXProviderStreamOptions, N as KodaXStreamResult, s as KodaXProviderCapabilityProfile, j as KodaXCustomProviderConfig } from './capability.d-BxNgd1-c.js';
+import { D as KodaXReasoningMode, U as KodaXThinkingBudgetMap, V as KodaXThinkingDepth, r as KodaXProviderConfig, C as KodaXReasoningCapability, F as KodaXReasoningRequest, Q as KodaXTaskType, E as KodaXReasoningOverride, X as KodaXToolDefinition, m as KodaXMessage, z as KodaXProviderStreamOptions, J as KodaXStreamResult, q as KodaXProviderCapabilityProfile, h as KodaXCustomProviderConfig } from './types.d-B1uGoVTE.js';
 import Anthropic from '@anthropic-ai/sdk';
-import { K as KodaXBaseProvider } from './cost-tracker.d-C4dMlQuV.js';
+import { K as KodaXBaseProvider } from './cost-tracker.d-B6vMoLLF.js';
 import OpenAI from 'openai';
 
 /**
@@ -189,6 +189,7 @@ declare function isProviderName(name: string): name is ProviderName;
  * Supports both OpenAI and Anthropic protocol families.
  */
 
+declare function validateCustomProviderConfig(custom: KodaXCustomProviderConfig): void;
 declare function createCustomProvider(custom: KodaXCustomProviderConfig): KodaXBaseProvider;
 
 /**
@@ -258,5 +259,5 @@ declare function isKnownProvider(name: string): boolean;
  */
 declare function getAvailableProviderNames(): string[];
 
-export { getProviderList as A, getProviderModel as B, getProviderModels as C, getReasoningCapability as D, getRuntimeModelProvider as E, getRuntimeModelProviderNames as F, isCustomProviderName as G, isKnownProvider as H, isProviderConfigured as I, isProviderName as J, KODAX_DEFAULT_PROVIDER as K, isReasoningEnabled as L, isRuntimeModelProviderName as M, loadReasoningOverride as N, mapDepthToOpenAIReasoningEffort as O, normalizeReasoningRequest as Q, reasoningCapabilityToOverride as R, reasoningOverrideToCapability as S, registerCustomProviders as T, registerModelProvider as U, resolveProvider as V, resolveThinkingBudget as W, saveReasoningOverride as X, KODAX_DEFAULT_THINKING_BUDGETS as a, KODAX_PROVIDERS as b, KODAX_PROVIDER_SNAPSHOTS as c, KODAX_REASONING_MODE_SEQUENCE as d, KODAX_REASONING_SAFETY_RESERVE as e, KodaXAnthropicCompatProvider as f, KodaXError as g, KodaXNetworkError as h, KodaXOpenAICompatProvider as i, KodaXProviderError as j, KodaXRateLimitError as k, KodaXToolCallIdError as l, buildReasoningOverrideKey as m, clampThinkingBudget as n, clearReasoningOverride as o, clearRuntimeModelProviders as p, createCustomProvider as q, getAvailableProviderNames as r, getCustomProvider as s, getCustomProviderList as t, getCustomProviderModels as u, getCustomProviderNames as v, getDefaultThinkingDepthForMode as w, getProvider as x, getProviderConfiguredCapabilityProfile as y, getProviderConfiguredReasoningCapability as z };
+export { getProviderList as A, getProviderModel as B, getProviderModels as C, getReasoningCapability as D, getRuntimeModelProvider as E, getRuntimeModelProviderNames as F, isCustomProviderName as G, isKnownProvider as H, isProviderConfigured as I, isProviderName as J, KODAX_DEFAULT_PROVIDER as K, isReasoningEnabled as L, isRuntimeModelProviderName as M, loadReasoningOverride as N, mapDepthToOpenAIReasoningEffort as O, normalizeReasoningRequest as Q, reasoningCapabilityToOverride as R, reasoningOverrideToCapability as S, registerCustomProviders as T, registerModelProvider as U, resolveProvider as V, resolveThinkingBudget as W, saveReasoningOverride as X, validateCustomProviderConfig as Y, KODAX_DEFAULT_THINKING_BUDGETS as a, KODAX_PROVIDERS as b, KODAX_PROVIDER_SNAPSHOTS as c, KODAX_REASONING_MODE_SEQUENCE as d, KODAX_REASONING_SAFETY_RESERVE as e, KodaXAnthropicCompatProvider as f, KodaXError as g, KodaXNetworkError as h, KodaXOpenAICompatProvider as i, KodaXProviderError as j, KodaXRateLimitError as k, KodaXToolCallIdError as l, buildReasoningOverrideKey as m, clampThinkingBudget as n, clearReasoningOverride as o, clearRuntimeModelProviders as p, createCustomProvider as q, getAvailableProviderNames as r, getCustomProvider as s, getCustomProviderList as t, getCustomProviderModels as u, getCustomProviderNames as v, getDefaultThinkingDepthForMode as w, getProvider as x, getProviderConfiguredCapabilityProfile as y, getProviderConfiguredReasoningCapability as z };
 export type { ProviderName as P };