@kiturone/kapibala 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -19,6 +19,10 @@ interface ToolResultBlock {
     isError?: boolean;
     /** 单次工具调用总耗时，包含 tool hooks 与实际执行。 */
     durationMs?: number;
+    /** 稳定错误类别；旧历史中的该字段可缺省。 */
+    errorCode?: string;
+    /** 不代表自动重试，只描述调用方应如何处理该错误。 */
+    retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
 }
 interface ThinkingBlock {
     type: 'thinking';
@@ -112,6 +116,12 @@ type SessionEvent = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+} | {
+    type: 'tool_progress';
+    id: string;
+    name: string;
+    elapsedMs: number;
+    outputBytes: number;
 } | {
     type: 'tool_finish';
     id: string;
@@ -191,7 +201,14 @@ interface ModelRequest {
  * Error Taxonomy for Kapibala Agent Harness
  */
 declare class KapibalaError extends Error {
-    constructor(message: string);
+    readonly code: string;
+    readonly retryPolicy: 'never' | 'immediate' | 'backoff' | 'after_user_action';
+    readonly safeMessage: string;
+    constructor(message: string, options?: {
+        code?: string;
+        retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
+        safeMessage?: string;
+    });
 }
 declare class ModelError extends KapibalaError {
     readonly status?: number;
@@ -223,6 +240,248 @@ declare class SessionBusyError extends KapibalaError {
     constructor(operation: string);
 }
 
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+type LogChannel = 'operation' | 'audit';
+type LogField = string | number | boolean | null;
+/** 单条可持久化的脱敏运行或审计事件。 */
+interface LogEvent {
+    schemaVersion: 1;
+    timestamp: string;
+    level: LogLevel;
+    channel: LogChannel;
+    event: string;
+    sessionId: string;
+    runId?: string;
+    operationId?: string;
+    toolUseId?: string;
+    fields: Record<string, LogField>;
+}
+/** 宿主提供的事件存储入口；审计 Sink 的写入完成代表已持久化。 */
+interface LogSink {
+    write(event: LogEvent): Promise<void>;
+}
+interface LogInput {
+    level: LogLevel;
+    event: string;
+    sessionId: string;
+    runId?: string;
+    operationId?: string;
+    toolUseId?: string;
+    fields?: Record<string, unknown>;
+}
+/** Core 与宿主共同使用的运行日志和审批审计入口。 */
+interface EventLogger {
+    record(event: LogInput): Promise<void>;
+    recordAudit(event: LogInput): Promise<void>;
+}
+/** 将任意来源的字段缩减为可写入日志的固定集合。 */
+declare function projectSafeFields(fields: Record<string, unknown>): Record<string, LogField>;
+/** 生成不依赖模型工具调用 ID 的内部关联标识。 */
+declare function createLogId(): string;
+/** 只暴露固定命令类别与参数数目，避免把自由文本写入审计。 */
+declare function commandAuditSummary(command: string): {
+    commandDigest: string;
+    commandPreview: string;
+    commandLength: number;
+    argumentCount: number;
+};
+/** 将批准范围绑定到最终命令、解释器、目录与执行选项。 */
+declare function executionFingerprint(input: {
+    command: string;
+    shell: string;
+    executable: string;
+    cwd: string;
+    environmentDigest: string;
+    timeoutMs: number;
+    outputLimitBytes: number;
+    targetDigest?: string;
+}): string;
+/** 统一筛选和脱敏日志；运行日志失败只报告安全诊断，审计失败仍向调用方传播。 */
+declare class StructuredLogger implements EventLogger {
+    private readonly operationSink;
+    private readonly auditSink;
+    private readonly debug;
+    private readonly onDiagnostic?;
+    constructor(options: {
+        operationSink: LogSink;
+        auditSink: LogSink;
+        debug?: boolean;
+        onDiagnostic?: (message: string) => void;
+    });
+    /** 普通日志写入失败不阻断业务，也不声称持久化成功；诊断不携带原始异常内容。 */
+    record(event: LogInput): Promise<void>;
+    /** 审计必须成功持久化；异常交由执行器拒绝启动工具或报告已执行操作的结果未知。 */
+    recordAudit(event: LogInput): Promise<void>;
+    private format;
+}
+
+interface FileLogSinkOptions {
+    directory: string;
+    prefix: 'operation' | 'audit';
+    maxBytes?: number;
+    retentionDays?: number;
+    sync?: boolean;
+}
+/** 将每条 JSONL 事件完整追加到本地文件，并按日期及文件大小轮转。 */
+declare class FileLogSink implements LogSink {
+    readonly directory: string;
+    readonly prefix: 'operation' | 'audit';
+    private readonly maxBytes;
+    private readonly retentionDays?;
+    private readonly sync;
+    constructor(options: FileLogSinkOptions);
+    write(event: LogEvent): Promise<void>;
+    /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
+    getUsageBytes(): number;
+    private chooseFile;
+    private cleanupExpired;
+    private isOwnedFile;
+}
+/** 构造 CLI 与默认 SDK 使用的用户级运行及审计 Sink。 */
+declare function createDefaultLogSinks(baseDirectory?: string): {
+    operationSink: FileLogSink;
+    auditSink: FileLogSink;
+};
+/** 启动时保守关闭上次进程未完成的审计事务，绝不将其当作未执行或自动重试。 */
+declare function recoverIncompleteAudit(directory: string): Promise<number>;
+
+interface InstructionSource {
+    path: string;
+    content: string;
+}
+interface InstructionSnapshot {
+    sources: readonly InstructionSource[];
+    totalBytes: number;
+}
+interface InstructionLoadOptions {
+    projectRoot: string;
+    cwd: string;
+    userFile?: string;
+}
+/** 按用户层和项目根至 cwd 的目录链读取指令，全部成功后才返回快照。 */
+declare function loadInstructions(options: InstructionLoadOptions): InstructionSnapshot;
+
+type ShellKind = 'bash' | 'wsl' | 'pwsh' | 'powershell';
+/** auto / 具名解释器，或用户显式提供的解释器可执行文件全路径。 */
+type ShellPreference = 'auto' | ShellKind | (string & {});
+interface ShellEnvironment {
+    kind: ShellKind;
+    executable: string;
+    executableDigest: string;
+    cwd: string;
+}
+interface ShellDetectOptions {
+    preference?: ShellPreference;
+    cwd: string;
+    platform?: NodeJS.Platform;
+    pathEnv?: string;
+}
+/**
+ * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
+ * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
+ */
+declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
+/**
+ * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
+ * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
+ * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
+ */
+declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
+
+/** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
+type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
+type PermissionAction = 'allow' | 'ask' | 'deny';
+interface ShellScope {
+    command: string;
+    interpreter: string;
+    executablePath?: string;
+    cwd: string;
+    executableDigest?: string;
+    scriptDigest?: string;
+    executionFingerprint?: string;
+}
+interface PermissionRule {
+    action: PermissionAction;
+    tool?: string;
+    capability?: Capability;
+    shell?: ShellScope;
+}
+interface PermissionRequest {
+    mode: SessionMode;
+    toolName: string;
+    capabilities: readonly Capability[];
+    dangerous?: boolean;
+    hardDenied?: boolean;
+    shell?: ShellScope;
+    rules?: readonly PermissionRule[];
+    cachedApproval?: boolean;
+    cachedDenial?: boolean;
+}
+interface PermissionDecision {
+    decision: PermissionAction;
+    source: 'hard_limit' | 'plan' | 'explicit_rule' | 'session_cache' | 'mode_default';
+    ruleIndex?: number;
+}
+/** 拒绝含糊的 Shell 前缀/通配符和结构不完整的规则。 */
+declare function validatePermissionRules(rules: readonly PermissionRule[]): void;
+/** 纯策略裁决；宿主硬限制和 Plan 始终先于任何规则或会话缓存。 */
+declare class PermissionPolicy {
+    decide(request: PermissionRequest): PermissionDecision;
+}
+/** 只向模型展示当前模式与整项拒绝规则允许请求的工具。 */
+declare function visibleTools(tools: readonly Tool[], mode: SessionMode, rules?: readonly PermissionRule[]): Tool[];
+
+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[];
+    /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
+    managesTimeout?: boolean;
+}
+interface ToolContext {
+    rootDir: string;
+    signal?: AbortSignal;
+    logger?: (message: string) => void;
+    /** 命令工具在真实进程创建后调用；审计失败时须先回收进程再报告结果未知。 */
+    onProcessSpawned?: () => Promise<void>;
+    onProgress?: (progress: {
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void;
+}
+interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly metadata?: ToolMetadata;
+    approvalScope?(input: TInput, rootDir: string): ShellScope;
+    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;
+
+interface RunCommandInput {
+    [key: string]: unknown;
+    command: string;
+    cwd?: string;
+    timeout_ms?: number;
+}
+interface CommandResult {
+    exitCode: number | null;
+    output: string;
+    outputTruncated: boolean;
+    outputFile?: string;
+    outputFileTruncated: boolean;
+    outputBytes: number;
+    shell: ShellEnvironment['kind'];
+}
+/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
+declare function cleanupCommandResults(rootDir: string, now?: number): void;
+/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
+declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
+
 interface SandboxConfig {
     rootDir: string;
     /**
@@ -260,27 +519,28 @@ declare class PathSandbox {
     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 {
+type ApprovalChoice = 'allow_once' | 'allow_session' | 'deny_once' | 'deny_session' | 'cancel';
+/** 宿主展示实际执行目标并取得人工选择；无通道视为非交互拒绝。 */
+interface ApprovalRequest {
+    toolName: string;
+    capabilities: readonly Capability[];
+    input: Record<string, unknown>;
     rootDir: string;
-    signal?: AbortSignal;
-    logger?: (message: string) => void;
+    shell?: ShellScope;
+    sessionAllowed: boolean;
 }
-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>;
+interface ApprovalChannel {
+    requestApproval(request: ApprovalRequest, signal?: AbortSignal): Promise<ApprovalChoice>;
+}
+/** 规范化 JSON 序列化：递归对对象键按字典序排序，保证相同的输入结构产生一致的字符串和 Hash。 */
+declare function stableJsonStringify(value: unknown): string;
+/** 只在当前 Session 内复用精确调用范围，不存储原始工具参数。 */
+declare class SessionApprovalCache {
+    private readonly choices;
+    key(request: ApprovalRequest): string;
+    get(request: ApprovalRequest): 'allow' | 'deny' | undefined;
+    set(request: ApprovalRequest, choice: 'allow' | 'deny'): void;
 }
-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 {
@@ -408,6 +668,13 @@ interface ExecutorOptions {
     logger?: (msg: string) => void;
     /** 单次工具执行超时(毫秒)。异步挂起的工具超时后返回 isError 结果，避免永久卡死会话循环 */
     toolTimeoutMs?: number;
+    eventLogger?: EventLogger;
+    sessionId?: string;
+    runId?: string;
+    mode?: SessionMode | (() => SessionMode);
+    permissionRules?: readonly PermissionRule[];
+    approvalChannel?: ApprovalChannel;
+    approvalCache?: SessionApprovalCache;
 }
 declare class ToolExecutor {
     private readonly tools;
@@ -416,9 +683,33 @@ declare class ToolExecutor {
     private readonly signal?;
     private readonly logger?;
     private readonly toolTimeoutMs;
+    private readonly eventLogger?;
+    private readonly sessionId?;
+    private readonly runId?;
+    private readonly mode;
+    private readonly permissionRules;
+    private readonly approvalChannel?;
+    private readonly approvalCache;
+    private readonly policy;
+    private readonly neverFailures;
+    private readonly cancellation;
     constructor(options: ExecutorOptions);
-    runAll(calls: ToolUseBlock[]): Promise<ToolResultBlock[]>;
-    executeOne(call: ToolUseBlock): Promise<ToolResultBlock>;
+    /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
+    cancel(): void;
+    runAll(calls: ToolUseBlock[], onProgress?: (event: {
+        id: string;
+        name: string;
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void): Promise<ToolResultBlock[]>;
+    /** 在最终参数上裁决并审计一次调用，所有拒绝和异常均闭合为工具结果。 */
+    executeOne(call: ToolUseBlock, onProgress?: (event: {
+        id: string;
+        name: string;
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void, forcedDeny?: boolean): Promise<ToolResultBlock>;
+    private executeResolved;
     /**
      * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
      * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
@@ -524,12 +815,16 @@ interface PromptAssemblerOptions {
     rootDir: string;
     agentName?: string;
     customInstructions?: string;
+    instructionSources?: readonly InstructionSource[];
+    visibleTools?: readonly Tool[];
 }
 declare class PromptAssembler {
     private readonly tools?;
     private readonly rootDir;
     private readonly agentName;
     private readonly customInstructions?;
+    private readonly instructionSources;
+    private readonly visibleTools?;
     constructor(options: PromptAssemblerOptions);
     assemble(): string;
     private getL1Behavior;
@@ -546,6 +841,11 @@ interface AgentLoopOptions {
     maxSteps?: number;
     maxConsecutiveErrors?: number;
     signal?: AbortSignal;
+    eventLogger?: EventLogger;
+    sessionId?: string;
+    runId?: string;
+    getMode?: () => SessionMode;
+    permissionRules?: readonly PermissionRule[];
 }
 declare class AgentLoop {
     private readonly provider;
@@ -556,6 +856,11 @@ declare class AgentLoop {
     private readonly maxSteps;
     private readonly maxConsecutiveErrors;
     private readonly signal?;
+    private readonly eventLogger?;
+    private readonly sessionId?;
+    private readonly runId?;
+    private readonly getMode;
+    private readonly permissionRules;
     constructor(options: AgentLoopOptions);
     run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
 }
@@ -568,6 +873,17 @@ interface SessionConfig {
     systemPrompt?: string;
     maxSteps?: number;
     logger?: (msg: string) => void;
+    eventLogger?: EventLogger;
+    loggingDirectory?: string;
+    mode?: SessionMode;
+    permissionRules?: readonly PermissionRule[];
+    approvalChannel?: ApprovalChannel;
+    projectRoot?: string;
+    cwd?: string;
+    userInstructionsPath?: string;
+    auditRecoveryDirectory?: string;
+    /** 接收普通运行日志失败的脱敏诊断；诊断失败也不得中断问答或替代审计。 */
+    onDiagnostic?: (message: string) => void;
 }
 interface SessionStats {
     totalTurns: number;
@@ -587,6 +903,17 @@ declare class AgentSession {
     private readonly customSystemPrompt?;
     private readonly maxSteps;
     private readonly logger?;
+    private readonly eventLogger;
+    private readonly sessionId;
+    private mode;
+    private readonly permissionRules;
+    private readonly approvalChannel?;
+    private readonly approvalCache;
+    private readonly projectRoot;
+    private readonly cwd;
+    private readonly userInstructionsPath?;
+    private instructionSnapshot?;
+    private readonly auditRecoveryDirectory?;
     private history;
     private totalTurns;
     private usageStats;
@@ -601,6 +928,11 @@ declare class AgentSession {
     use(plugin: AgentPlugin): Promise<void>;
     switchModel(profile: ModelProfile, role?: ModelRole, provider?: ModelProvider): void;
     getActiveProfile(role?: ModelRole): ModelProfile;
+    /** 只在空闲时切换本次会话模式；宿主负责 FullAccess 的显式选择交互。 */
+    switchMode(mode: SessionMode): void;
+    getMode(): SessionMode;
+    /** 返回最近一次成功装载的来源路径，不暴露指令正文。 */
+    getInstructionSources(): string[];
     getHistory(): CanonicalMessage[];
     getStats(): SessionStats;
     getLastMetrics(): TurnMetrics | undefined;
@@ -633,4 +965,4 @@ declare class AgentSession {
     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 };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, FileLogSink, type FileLogSinkOptions, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type MessageRole, type MessageStore, ModelError, type ModelEvent, type ModelProfile, type ModelProvider, type ModelRequest, type ModelRole, type ModelRouter, OpenAICompatibleProvider, type OpenAIProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginContext, PromptAssembler, type PromptAssemblerOptions, type RedactedThinkingBlock, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionMode, type SessionStats, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type StepLogEntry, type StepLogStage, StructuredLogger, 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, classifyBashOutput, cleanupCommandResults, commandAuditSummary, createDefaultLogSinks, createLogId, createRunCommandTool, defineTool, detectShell, editFileTool, executionFingerprint, globTool, grepTool, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, loadInstructions, projectSafeFields, readFileTool, recoverIncompleteAudit, resolveContextWindow, stableJsonStringify, toToolDefinition, validatePermissionRules, visibleTools, writeFileTool };