@kiturone/kapibala 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,636 @@
+/**
+ * Canonical Message & Event Types for Kapibala
+ */
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | RedactedThinkingBlock;
+interface TextBlock {
+    type: 'text';
+    text: string;
+}
+interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultBlock {
+    type: 'tool_result';
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+    /** 单次工具调用总耗时，包含 tool hooks 与实际执行。 */
+    durationMs?: number;
+}
+interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+}
+interface RedactedThinkingBlock {
+    type: 'redacted_thinking';
+    data: string;
+}
+interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+interface CanonicalMessage {
+    role: MessageRole;
+    content: ContentBlock[];
+    timestamp?: number;
+}
+declare function isTextBlock(block: ContentBlock): block is TextBlock;
+declare function isToolUseBlock(block: ContentBlock): block is ToolUseBlock;
+declare function isToolResultBlock(block: ContentBlock): block is ToolResultBlock;
+declare function isThinkingBlock(block: ContentBlock): block is ThinkingBlock;
+interface TurnMetrics {
+    turn: number;
+    startTime: number;
+    endTime: number;
+    totalDurationMs: number;
+    ttftMs?: number;
+    modelDurationMs: number;
+    toolDurationMs: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    toolCallsCount: number;
+}
+interface RunMetrics {
+    startTime: number;
+    endTime: number;
+    totalDurationMs: number;
+    modelDurationMs: number;
+    toolDurationMs: number;
+    ttftMs?: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    turns: number;
+    toolCalls: number;
+    status: 'completed' | 'failed' | 'aborted';
+    /** 最近一次内部模型请求占用的上下文；不使用 run 累计 promptTokens。 */
+    contextUsage?: ContextUsage;
+}
+interface ContextUsage {
+    usedTokens?: number;
+    limitTokens: number;
+    percent?: number;
+    estimatedLimit: boolean;
+}
+type StepLogStage = 'model_request_start' | 'first_token' | 'model_stream_finish' | 'tool_execution_start' | 'tool_execution_finish' | 'turn_finish';
+interface StepLogEntry {
+    timestamp: number;
+    turn: number;
+    stage: StepLogStage;
+    message: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * AgentSession 面向宿主输出的统一进程内事件契约。
+ *
+ * 事件只描述 Agent 语义，不携带终端颜色、组件状态或具体 UI 类型，因此 CLI、TUI、
+ * GUI 和 SDK 可以消费同一条事件流。跨进程或网络传输需要由宿主转换为独立的 wire DTO，
+ * 不应直接把本类型当作长期兼容的网络协议。
+ */
+type SessionEvent = {
+    type: 'turn_start';
+    turn: number;
+} | {
+    type: 'step_log';
+    log: StepLogEntry;
+} | {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'thinking_delta';
+    thinking: string;
+} | {
+    type: 'tool_start';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_finish';
+    id: string;
+    name: string;
+    result: string;
+    isError: boolean;
+    durationMs?: number;
+}
+/**
+ * 工具结果已完成 canonical 装配并写入历史。
+ * 消费方(SessionStore)据此落盘 —— 见设计文档 §4.4「tool:after 落一条 tool_result message」。
+ * 该事件在熔断/中断判定之前派发，保证任何终止路径下历史结构都合法(§4.3)。
+ */
+ | {
+    type: 'tool_messages';
+    messages: CanonicalMessage[];
+} | {
+    type: 'message_stop';
+    message: CanonicalMessage;
+    usage?: Usage;
+    ttftMs?: number;
+    durationMs?: number;
+} | {
+    type: 'turn_finish';
+    turn: number;
+    usage?: Usage;
+    metrics: TurnMetrics;
+} | {
+    type: 'run_finish';
+    metrics: RunMetrics;
+} | {
+    type: 'error';
+    error: Error;
+};
+type ModelEvent = {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'thinking_delta';
+    thinking: string;
+} | {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    argumentChunk: string;
+} | {
+    type: 'tool_call_finish';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    /** 参数 JSON 解析失败时置位，input 退化为 { _raw: '<原始字符串>' }，便于上游诊断而非静默吞错 */
+    parseError?: boolean;
+} | {
+    type: 'message_stop';
+    usage?: Usage;
+    ttftMs?: number;
+    durationMs?: number;
+};
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface ModelRequest {
+    systemPrompt?: string;
+    messages: CanonicalMessage[];
+    tools?: ToolDefinition[];
+    signal?: AbortSignal;
+    temperature?: number;
+    maxTokens?: number;
+}
+
+/**
+ * Error Taxonomy for Kapibala Agent Harness
+ */
+declare class KapibalaError extends Error {
+    constructor(message: string);
+}
+declare class ModelError extends KapibalaError {
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(message: string, options?: {
+        status?: number;
+        retryable?: boolean;
+    });
+}
+declare class TransportError extends KapibalaError {
+    readonly retryable: boolean;
+    constructor(message: string, retryable?: boolean);
+}
+declare class ToolError extends KapibalaError {
+    constructor(message: string);
+}
+declare class ToolNotFound extends KapibalaError {
+    readonly toolName: string;
+    readonly availableTools: string[];
+    constructor(toolName: string, availableTools?: string[]);
+}
+declare class AbortError extends KapibalaError {
+    constructor(message?: string);
+}
+declare class FatalError extends KapibalaError {
+    constructor(message: string);
+}
+declare class SessionBusyError extends KapibalaError {
+    constructor(operation: string);
+}
+
+interface SandboxConfig {
+    rootDir: string;
+    /**
+     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
+     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
+     */
+    allowSymlinks?: boolean;
+}
+declare class PathSandbox {
+    readonly rootDir: string;
+    readonly allowSymlinks: boolean;
+    private cachedRealRootDir?;
+    constructor(config: SandboxConfig);
+    /**
+     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
+     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
+     */
+    private get realRootDir();
+    /**
+     * 检查并解析安全路径
+     * 1. 解析相对路径为相对于 rootDir 的绝对路径
+     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
+     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
+     */
+    resolveSafePath(targetPath: string): string;
+    /**
+     * 把词法路径映射为物理路径。
+     *
+     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
+     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
+     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
+     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
+     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
+     */
+    private toPhysicalPath;
+}
+
+type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn';
+interface ToolMetadata {
+    source?: string;
+    dangerous?: boolean;
+    /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
+    permissions?: Capability[];
+}
+interface ToolContext {
+    rootDir: string;
+    signal?: AbortSignal;
+    logger?: (message: string) => void;
+}
+interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly metadata?: ToolMetadata;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>(tool: Tool<TInput, TOutput>): Tool<TInput, TOutput>;
+declare function toToolDefinition(tool: Tool): ToolDefinition;
+
+type ConflictPolicy = 'error' | 'prefer-builtin' | 'prefer-last';
+declare class ToolRegistry {
+    private readonly tools;
+    private readonly toolSources;
+    private readonly conflictPolicy;
+    constructor(options?: {
+        conflictPolicy?: ConflictPolicy;
+    });
+    register(tool: Tool, opts?: {
+        source?: string;
+    }): void;
+    registerSource(source: string, tools: Tool[]): void;
+    unregisterSource(source: string): void;
+    get(name: string): Tool | undefined;
+    resolve(name: string): Tool;
+    list(): Tool[];
+    definitions(): ToolDefinition[];
+}
+
+declare const readFileTool: Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string>;
+declare const writeFileTool: Tool<{
+    path: string;
+    content: string;
+}, string>;
+declare const editFileTool: Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string>;
+declare const globTool: Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string>;
+declare const grepTool: Tool<{
+    pattern: string;
+    path?: string;
+}, string>;
+declare const builtinTools: (Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string> | Tool<{
+    path: string;
+    content: string;
+}, string> | Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string> | Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string> | Tool<{
+    pattern: string;
+    path?: string;
+}, string>)[];
+
+type HookPoint = 'session:start' | 'session:end' | 'model:before' | 'model:after' | 'tool:before' | 'tool:after' | 'error';
+interface HookContext {
+    readonly signal?: AbortSignal;
+    readonly logger?: (msg: string) => void;
+}
+type ToolDecision = {
+    action: 'continue';
+} | {
+    action: 'skip';
+    result: string;
+    isError?: boolean;
+} | {
+    action: 'modify';
+    input: Record<string, unknown>;
+};
+interface HookHandlers {
+    'session:start'?: (ctx: HookContext) => void | Promise<void>;
+    'session:end'?: (ctx: HookContext) => void | Promise<void>;
+    'model:before'?: (ctx: HookContext, req: ModelRequest) => ModelRequest | Promise<ModelRequest>;
+    'model:after'?: (ctx: HookContext, res: {
+        message: CanonicalMessage;
+    }) => void | Promise<void>;
+    'tool:before'?: (ctx: HookContext, call: {
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }) => ToolDecision | Promise<ToolDecision>;
+    'tool:after'?: (ctx: HookContext, call: {
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }, result: {
+        output: string;
+        isError: boolean;
+    }) => void | Promise<void>;
+    error?: (ctx: HookContext, err: Error) => void | Promise<void>;
+}
+
+declare class HookRegistry {
+    private readonly hooks;
+    on<K extends HookPoint>(point: K, handler: NonNullable<HookHandlers[K]>): void;
+    get<K extends HookPoint>(point: K): Array<NonNullable<HookHandlers[K]>>;
+    emit<K extends 'session:start' | 'session:end' | 'model:after' | 'tool:after' | 'error'>(point: K, ctx: HookContext, ...args: any[]): Promise<void>;
+}
+
+interface PluginContext {
+    readonly tools: ToolRegistry;
+    readonly hooks: HookRegistry;
+    readonly rootDir: string;
+    readonly logger?: (msg: string) => void;
+}
+interface AgentPlugin {
+    readonly name: string;
+    readonly version?: string;
+    setup(ctx: PluginContext): void | Promise<void>;
+    teardown?(): void | Promise<void>;
+}
+
+interface ExecutorOptions {
+    tools: ToolRegistry;
+    hooks: HookRegistry;
+    rootDir: string;
+    signal?: AbortSignal;
+    logger?: (msg: string) => void;
+    /** 单次工具执行超时(毫秒)。异步挂起的工具超时后返回 isError 结果，避免永久卡死会话循环 */
+    toolTimeoutMs?: number;
+}
+declare class ToolExecutor {
+    private readonly tools;
+    private readonly hooks;
+    private readonly rootDir;
+    private readonly signal?;
+    private readonly logger?;
+    private readonly toolTimeoutMs;
+    constructor(options: ExecutorOptions);
+    runAll(calls: ToolUseBlock[]): Promise<ToolResultBlock[]>;
+    executeOne(call: ToolUseBlock): Promise<ToolResultBlock>;
+    /**
+     * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
+     * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
+     *
+     * 局限：同步 CPU 密集型实现会阻塞事件循环，timer 同样无法触发；
+     * 因此内置工具仍需避免执行用户可控的同步高复杂度计算。
+     */
+    private withTimeout;
+}
+
+type ModelRole = 'default' | 'planning' | 'execution' | 'summary' | 'fast';
+type ContextWindowValue = number | `${number}${'K' | 'k' | 'M' | 'm'}`;
+interface ResolvedContextWindow {
+    tokens: number;
+    /** true 表示模型未声明窗口，当前值来自 Kapibala 的默认估算。 */
+    estimated: boolean;
+}
+declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 1000000;
+/**
+ * 将模型上下文窗口统一解析为整数 Token 数。
+ *
+ * 配置允许直接填写整数，或使用十进制 K/M 简写；未填写时返回默认 1M，并标记为估算值。
+ */
+declare function resolveContextWindow(value?: ContextWindowValue): ResolvedContextWindow;
+interface ModelProfile {
+    id: string;
+    name: string;
+    provider: 'openai-compatible';
+    baseURL: string;
+    apiKeyEnv: string;
+    apiKey?: string;
+    modelName: string;
+    contextWindow?: ContextWindowValue;
+    supportsThinking?: boolean;
+}
+interface ModelRouter {
+    resolve(role?: ModelRole): ModelProvider;
+    getProfile(role?: ModelRole): ModelProfile;
+}
+declare class SimpleModelRouter implements ModelRouter {
+    private readonly providers;
+    private readonly profiles;
+    private defaultRole;
+    constructor(defaultProfile: ModelProfile, defaultProvider: ModelProvider);
+    setRole(role: ModelRole, profile: ModelProfile, provider: ModelProvider): void;
+    resolve(role?: ModelRole): ModelProvider;
+    getProfile(role?: ModelRole): ModelProfile;
+}
+
+interface ModelProvider {
+    readonly name: string;
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /** 把一批工具结果装配成符合本协议的 canonical 消息序列 */
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+}
+
+interface OpenAIProviderOptions {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    supportsThinking?: boolean;
+    /** 建立 HTTP 连接(收到响应头)的超时毫秒数；仅约束建连阶段，不限制流式读取总时长 */
+    connectTimeoutMs?: number;
+}
+declare class OpenAICompatibleProvider implements ModelProvider {
+    readonly name = "openai-compatible";
+    readonly baseURL: string;
+    readonly apiKey: string;
+    readonly modelName: string;
+    readonly supportsThinking: boolean;
+    readonly connectTimeoutMs: number;
+    constructor(options: OpenAIProviderOptions);
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+    private translateMessagesToWire;
+}
+
+declare class JSONLMessageStore implements MessageStore {
+    readonly filePath: string;
+    constructor(filePath: string);
+    append(message: CanonicalMessage): Promise<void>;
+    load(): Promise<CanonicalMessage[]>;
+    clear(): Promise<void>;
+    /**
+     * 历史自愈(设计文档 §4.4)：逐条扫描 assistant 的 tool_use，
+     * 若其后的 tool 消息未完整覆盖这些 tool_use，就地补一条 is_error 的 tool_result。
+     *
+     * 之所以做**全历史扫描**而非只看末条：崩溃可能发生在任意一轮工具执行中途，
+     * 悬挂的 tool_use 未必位于历史末尾(例如中断后用户又继续提了问)。
+     * 只看末条会漏掉夹在中间的悬挂，下一次请求仍会因上下文非法而 400。
+     */
+    private healDanglingToolCalls;
+}
+
+interface MessageStore {
+    append(message: CanonicalMessage): Promise<void>;
+    load(): Promise<CanonicalMessage[]>;
+    clear(): Promise<void>;
+}
+
+interface PromptAssemblerOptions {
+    tools?: ToolRegistry;
+    rootDir: string;
+    agentName?: string;
+    customInstructions?: string;
+}
+declare class PromptAssembler {
+    private readonly tools?;
+    private readonly rootDir;
+    private readonly agentName;
+    private readonly customInstructions?;
+    constructor(options: PromptAssemblerOptions);
+    assemble(): string;
+    private getL1Behavior;
+    private getL2Tools;
+    private getL3Environment;
+}
+
+interface AgentLoopOptions {
+    provider: ModelProvider;
+    executor: ToolExecutor;
+    tools: ToolRegistry;
+    hooks: HookRegistry;
+    systemPrompt?: string;
+    maxSteps?: number;
+    maxConsecutiveErrors?: number;
+    signal?: AbortSignal;
+}
+declare class AgentLoop {
+    private readonly provider;
+    private readonly executor;
+    private readonly tools;
+    private readonly hooks;
+    private readonly systemPrompt?;
+    private readonly maxSteps;
+    private readonly maxConsecutiveErrors;
+    private readonly signal?;
+    constructor(options: AgentLoopOptions);
+    run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
+}
+
+interface SessionConfig {
+    defaultProfile: ModelProfile;
+    defaultProvider: ModelProvider;
+    store?: MessageStore;
+    rootDir?: string;
+    systemPrompt?: string;
+    maxSteps?: number;
+    logger?: (msg: string) => void;
+}
+interface SessionStats {
+    totalTurns: number;
+    totalTokens: Usage;
+    activeModel: string;
+    loadedToolsCount: number;
+    lastMetrics?: TurnMetrics;
+    lastRunMetrics?: RunMetrics;
+    contextUsage: ContextUsage;
+}
+declare class AgentSession {
+    readonly rootDir: string;
+    readonly tools: ToolRegistry;
+    readonly hooks: HookRegistry;
+    private readonly router;
+    private readonly store?;
+    private readonly customSystemPrompt?;
+    private readonly maxSteps;
+    private readonly logger?;
+    private history;
+    private totalTurns;
+    private usageStats;
+    private lastMetrics?;
+    private lastRunMetrics?;
+    private initialized;
+    private destroyed;
+    private activeRun;
+    private readonly plugins;
+    constructor(config: SessionConfig);
+    init(): Promise<void>;
+    use(plugin: AgentPlugin): Promise<void>;
+    switchModel(profile: ModelProfile, role?: ModelRole, provider?: ModelProvider): void;
+    getActiveProfile(role?: ModelRole): ModelProfile;
+    getHistory(): CanonicalMessage[];
+    getStats(): SessionStats;
+    getLastMetrics(): TurnMetrics | undefined;
+    getLastRunMetrics(): RunMetrics | undefined;
+    reset(): Promise<void>;
+    /**
+     * 执行一次用户输入，并以宿主无关的语义事件流返回全过程。
+     *
+     * Core 不负责终端或图形界面渲染；CLI、TUI、GUI 与其它宿主应消费同一组
+     * {@link SessionEvent}，分别完成展示、交互和中止控制。
+     *
+     * @param userInput 用户本轮输入。
+     * @param options 可选的中止信号。
+     * @returns 文本、思考、工具、指标和错误等结构化事件的异步流。
+     * @throws {SessionBusyError} 当前会话已有正在执行的 run 时抛出。
+     */
+    run(userInput: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<SessionEvent>;
+    destroy(): Promise<void>;
+    private assertIdle;
+    /**
+     * 计算最近一次内部模型请求的上下文占用。
+     * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
+     */
+    private createContextUsage;
+    private persistAssistant;
+    private persistToolMessages;
+    private closeInterruptedToolCalls;
+    private findClosedToolMessages;
+}
+
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, type CanonicalMessage, type Capability, type ConflictPolicy, type ContentBlock, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type ExecutorOptions, FatalError, type HookContext, type HookHandlers, type HookPoint, HookRegistry, JSONLMessageStore, KapibalaError, type MessageRole, type MessageStore, ModelError, type ModelEvent, type ModelProfile, type ModelProvider, type ModelRequest, type ModelRole, type ModelRouter, OpenAICompatibleProvider, type OpenAIProviderOptions, PathSandbox, type PluginContext, PromptAssembler, type PromptAssemblerOptions, type RedactedThinkingBlock, type ResolvedContextWindow, type RunMetrics, type SandboxConfig, SessionBusyError, type SessionConfig, type SessionEvent, type SessionStats, SimpleModelRouter, type StepLogEntry, type StepLogStage, type TextBlock, type ThinkingBlock, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, ToolExecutor, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolResultBlock, type ToolUseBlock, TransportError, type TurnMetrics, type Usage, builtinTools, defineTool, editFileTool, globTool, grepTool, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, readFileTool, resolveContextWindow, toToolDefinition, writeFileTool };