@kodax-ai/kodax 0.7.41 → 0.7.43

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

@@ -1,255 +1,5 @@
-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';
+import { a as KodaXCompactMemorySeed, h as KodaXSessionArtifactLedgerEntry } from './types.d-mM8vqvhT.js';
 
 /**
  * Layer A Primitive: Agent / Handoff / Guardrail / AgentReasoningProfile
@@ -369,6 +119,17 @@ interface Agent<TContext = unknown> {
     readonly handoffs?: readonly Handoff[];
     readonly reasoning?: AgentReasoningProfile;
     readonly guardrails?: readonly Guardrail[];
+    /**
+     * FEATURE_191 — one-sentence human-readable summary surfaced to
+     * other agents that may dispatch this one (e.g., via the
+     * `dispatch_child_task(subagent_type=<name>)` Worker SP block). The
+     * field propagates from `AgentContent.description` when the agent is
+     * built via the construction substrate; built-in / SDK-created
+     * agents may set it directly. Optional for backward compatibility
+     * with the FEATURE_089 minimal-agent shape and pre-FEATURE_191
+     * built-ins.
+     */
+    readonly description?: string;
     /** Reserved for structured-output agents; not consumed in v0.7.23. */
     readonly outputSchema?: unknown;
     readonly model?: string;
@@ -508,12 +269,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.
@@ -552,6 +330,41 @@ interface Span {
     setError(err: SpanError | Error): void;
     end(): void;
 }
+interface SpanImplOptions {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
+    readonly name: string;
+    readonly data: SpanData;
+    readonly startedAt?: number;
+    readonly now?: () => number;
+    readonly nextSpanId?: () => string;
+    readonly onChildCreated?: (span: Span) => void;
+    readonly onSpanEnd?: (span: Span) => void;
+}
+declare class SpanImpl implements Span {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
+    readonly name: string;
+    readonly data: SpanData;
+    readonly startedAt: number;
+    private _endedAt?;
+    private _error?;
+    private readonly _children;
+    private readonly now;
+    private readonly nextSpanId;
+    private readonly onChildCreated?;
+    private readonly onSpanEnd?;
+    private _ended;
+    constructor(opts: SpanImplOptions);
+    get endedAt(): number | undefined;
+    get error(): SpanError | undefined;
+    get children(): readonly Span[];
+    addChild(name: string, data: SpanData): Span;
+    setError(err: SpanError | Error): void;
+    end(): void;
+}
 
 /**
  * Runner Tool Loop — FEATURE_084 Shard 1 (v0.7.26).
@@ -644,11 +457,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>;
 }
@@ -1050,6 +870,15 @@ interface SessionStateSnapshot {
      * working on: <X>" without owning the todo store.
      */
     readonly currentTodoSummary?: CurrentTodoSummary;
+    /**
+     * v0.7.43 (FEATURE_173 Part B follow-up) — REPL session id
+     * (e.g. `YYYYMMDD_HHMMSS`). Lets `listRunningSessions()` correlate
+     * a sibling instance with its `.jsonl` file. Mutable: starts
+     * undefined during bootstrap, set after `createInteractiveContext`,
+     * re-published on `/new`. Older writers omit this; readers MUST
+     * treat as optional.
+     */
+    readonly sessionId?: string;
 }
 interface RecentlyModifiedFile {
     readonly path: string;
@@ -1213,5 +1042,86 @@ 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 };
+/**
+ * ../../index.js Compaction Types
+ */
+
+interface CompactionConfig {
+    /** Whether automatic compaction is enabled. */
+    enabled: boolean;
+    /** Trigger compaction when context usage exceeds this percentage of the window. */
+    triggerPercent: number;
+    /**
+     * @deprecated V2 compaction no longer uses this option.
+     *
+     * The system now combines protected recent context, lightweight pruning, and
+     * rolling summaries automatically.
+     */
+    keepRecentPercent?: number;
+    /** Percentage of the most recent context that is never compacted or pruned. Defaults to 20. */
+    protectionPercent?: number;
+    /**
+     * Percentage of the context window used as the chunk size for each rolling
+     * summary pass. Defaults to 10.
+     */
+    rollingSummaryPercent?: number;
+    /** Prune oversized tool results when they exceed roughly this many tokens. Defaults to 500. */
+    pruningThresholdTokens?: number;
+    /**
+     * Gap ratio for prune fast-return. After pruning, if remaining tokens still exceed
+     * triggerTokens * pruningGapRatio, the system continues to the summarization path
+     * instead of returning early. Defaults to 0.8.
+     */
+    pruningGapRatio?: number;
+    /** Optional override for the provider context window. */
+    contextWindow?: number;
+}
+interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+interface CompactionAnchor {
+    summary: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    entriesRemoved: number;
+    reason: string;
+    artifactLedgerId?: string;
+    details?: CompactionDetails;
+    memorySeed?: KodaXCompactMemorySeed;
+}
+interface CompactionUpdate {
+    anchor?: CompactionAnchor;
+    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
+    memorySeed?: KodaXCompactMemorySeed;
+    /**
+     * FEATURE_072: ledger-summary + file-content messages produced by
+     * `buildPostCompactAttachments` + `buildFileContentMessages`. Agent.ts
+     * passes these separately from the kept-tail messages so REPL-side
+     * `applySessionCompaction` can store them natively on the CompactionEntry
+     * rather than inlining them as loose `[Post-compact: ...]` system messages
+     * in lineage. Agent.ts keeps inlining them into its local flat `messages`
+     * via `injectPostCompactAttachments` (P4 belt-and-suspenders); the lineage
+     * is the persistence source of truth.
+     */
+    postCompactAttachments?: readonly KodaXMessage[];
+}
+interface CompactionResult {
+    compacted: boolean;
+    messages: KodaXMessage[];
+    summary?: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    entriesRemoved: number;
+    details?: CompactionDetails;
+    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
+    anchor?: CompactionAnchor;
+    memorySeed?: KodaXCompactMemorySeed;
+}
+interface FileOperations {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+
+export { MAX_TOOL_LOOP_ITERATIONS as M, SpanImpl as X, buildAssistantMessageFromLlmResult as a5, buildToolResultMessage as a6, collectGuardrails as a7, createAgent as a8, createHandoff as a9, createStateWriter as aa, discoverInstances as ab, executeRunnerToolCall as ac, isRunnableTool as ad, isRunnerLlmResult as ae, registerChildTask as af, requestTaskStop as ag, runInputGuardrails as ah, runOutputGuardrails as ai, runToolAfterGuardrails as aj, runToolBeforeGuardrails as ak, GuardrailBlockedError as p, GuardrailEscalateError as r };
+export type { StateWriterOptions as $, Agent as A, RunnerLlmResult as B, ChildTaskRegistry as C, DiscoveredInstance as D, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, InputGuardrail as I, RunnerLlmReturn as J, RunnerToolCall as K, RunnerToolContext as L, RunnerToolObserver as N, OutputGuardrail as O, PersistedSessionState as P, RunnerToolResult as Q, ReasoningDepth as R, SessionMeta as S, SessionStateSnapshot as T, Span as U, SpanData as V, SpanError as W, SpanImplOptions as Y, StateWriter as Z, StateWriterFs as _, AgentMessage as a, StopHookSpanData as a0, TaskAbortRegistry as a1, ToolBeforeOutcome as a2, ToolCallSpanData as a3, ToolGuardrail as a4, AgentMiddlewareDeclaration as b, AgentReasoningProfile as c, AgentSpanData as d, AgentTool as e, CompactionAnchor as f, CompactionConfig as g, CompactionDetails as h, CompactionResult as i, CompactionSpanData as j, CompactionUpdate as k, CurrentTodoSummary as l, DiscoveryOptions as m, FileOperations as n, Guardrail as o, GuardrailContext as q, GuardrailSpanData as s, GuardrailVerdict as t, HandoffSpanData as u, InstanceDiscoveryFs as v, RecentlyModifiedFile as w, RequestTaskStopOptions as x, RequestTaskStopResult as y, RunnableTool as z };