@armadra/agent 0.0.0-stage → 0.3.0

package/dist/agent/session-tools.js

@@ -0,0 +1,277 @@
+/**
+ * 会话侧的工具装配（设计 §5.1、§6.3）：tool-runner 的注入项。[B2]
+ *
+ * 一次工具调用的门禁顺序（§6.3）：schema 校验（tool-runner）→ 命令式 Hook PreToolUse（deny / block
+ * 一票否决；updatedInput 替换输入；allow / ask 作为 hookDecision 交给管线）→ 权限管线（B3，注入）→
+ * ask 时走审批链（宿主 broker → UI broker → 无人值守 deny；超时 deny）→ 执行 → PostToolUse
+ * （additionalContext 追加到结果末尾；block 把结果改为错误）。
+ *
+ * （W3-B9a-2）ask 时请求带 `context{depth, readFiles}` 与执行前预览 `preview`（只读、有上限，
+ * 见 permissions/preview.ts）；预览出错或为空则缺省，不影响审批。`permission_request` 事件同样带
+ * `preview`，RPC 客户端可直接显示。
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_APPROVAL_TIMEOUT_MS } from "../permissions/broker.js";
+import { previewAction } from "../permissions/preview.js";
+import { runSingleToolCall } from "./tool-runner.js";
+/** 外层是这个工具时，嵌套调用的 Hook 输入带 `viaCodemode: true`。 */
+const CODEMODE_TOOL_NAME = "codemode";
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => (block.type === "text" ? block.text : "")).join("");
+}
+/** 审批链：依次问每个 broker，第一个给出决定的为准；全部弃权 → deny。 */
+export async function requestApproval(core, request, signal) {
+    const timeoutMs = core.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    const event = {
+        type: "permission_request",
+        requestId: request.requestId,
+        toolName: request.toolName,
+        input: request.input,
+        reason: request.reason,
+        timeoutMs,
+    };
+    if (request.hookReason !== undefined)
+        event.hookReason = request.hookReason;
+    if (request.preview !== undefined)
+        event.preview = request.preview;
+    core.emit(event);
+    void core.runHook("Notification", {
+        notification: { kind: "approval", message: `approval requested for ${request.toolName}` },
+    });
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let decision = "deny";
+    try {
+        for (const broker of core.options.brokers ?? []) {
+            if (controller.signal.aborted)
+                break;
+            const answer = await Promise.race([
+                broker.ask(request, controller.signal).catch(() => undefined),
+                new Promise((resolve) => controller.signal.addEventListener("abort", () => resolve(undefined), { once: true })),
+            ]);
+            if (answer !== undefined) {
+                decision = answer;
+                break;
+            }
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+    }
+    if (signal.aborted)
+        decision = "deny"; // run 被中断：即使 broker 已放行也不执行
+    core.emit({ type: "permission_resolved", requestId: request.requestId, decision });
+    return decision;
+}
+/** 嵌套调用时 Hook 输入的两个字段（设计 §5.5）；模型直接发起的调用不带。 */
+function nestedFields(parent) {
+    if (parent === undefined)
+        return {};
+    return parent.viaCodemode
+        ? { viaCodemode: true, parentToolCallId: parent.toolCallId }
+        : { parentToolCallId: parent.toolCallId };
+}
+/** 审批请求的执行前预览；出错或没有可显示的内容时 undefined（预览永不阻塞审批）。 */
+function safePreview(core, request) {
+    try {
+        const preview = previewAction(request, { cwd: core.cwd });
+        return preview.lines.length > 0 ? preview : undefined;
+    }
+    catch (err) {
+        core.log("warn", `approval preview failed: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+export async function gateToolCall(core, call, ctx) {
+    const tool = ctx.tool;
+    if (tool === undefined)
+        return { block: true, reason: `Tool ${call.name} not found` };
+    let input = call.arguments;
+    let replaced = false;
+    let hookDecision;
+    let hookReason;
+    if (core.options.hooks?.has("PreToolUse", call.name) === true) {
+        const outcome = await core.runHook("PreToolUse", { toolCallId: call.id, toolName: call.name, toolInput: input, ...nestedFields(ctx.parent) }, ctx.signal);
+        if (outcome !== undefined) {
+            if (outcome.stop)
+                core.requestStop(outcome.reason);
+            if (outcome.decision === "deny" || outcome.decision === "block") {
+                return { block: true, reason: outcome.reason ?? `Blocked by PreToolUse hook` };
+            }
+            if (outcome.hasUpdatedInput) {
+                input = outcome.updatedInput;
+                replaced = true;
+            }
+            if (outcome.decision === "allow" || outcome.decision === "ask") {
+                hookDecision = outcome.decision;
+                hookReason = outcome.reason;
+            }
+        }
+    }
+    const permission = core.options.permission;
+    let decision = hookDecision === "ask" ? "ask" : "allow";
+    let approvalReason = "hook";
+    let denyMessage;
+    if (permission !== undefined) {
+        const checkInput = {
+            toolName: call.name,
+            permission: tool.permission,
+            input,
+            unattended: core.options.unattended === true,
+        };
+        if (hookDecision !== undefined)
+            checkInput.hookDecision = hookDecision;
+        if (hookReason !== undefined)
+            checkInput.hookReason = hookReason;
+        const verdict = permission.check(checkInput);
+        decision = verdict.decision;
+        approvalReason = verdict.approvalReason ?? "mode";
+        denyMessage = verdict.message;
+    }
+    else if (decision === "ask" && core.options.unattended === true) {
+        decision = "deny";
+    }
+    if (decision === "deny") {
+        return { block: true, reason: denyMessage ?? `Permission denied for ${call.name}` };
+    }
+    if (decision === "ask") {
+        const request = {
+            requestId: randomUUID(),
+            toolName: call.name,
+            input,
+            reason: approvalReason,
+            context: { depth: core.depth, readFiles: core.readFiles },
+        };
+        if (hookReason !== undefined)
+            request.hookReason = hookReason;
+        const preview = safePreview(core, request);
+        if (preview !== undefined)
+            request.preview = preview;
+        const answer = await requestApproval(core, request, ctx.signal);
+        if (answer === "deny")
+            return { block: true, reason: `The user denied ${call.name}` };
+        if (answer === "allow_session")
+            permission?.rememberForSession(call.name, input);
+    }
+    return replaced ? { input } : {};
+}
+export async function afterToolCall(core, call, result, parent) {
+    if (core.options.hooks?.has("PostToolUse", call.name) !== true)
+        return result;
+    const outcome = await core.runHook("PostToolUse", {
+        toolCallId: call.id,
+        toolName: call.name,
+        toolInput: call.arguments,
+        toolResult: { content: textOf(result.content), isError: result.isError === true },
+        ...nestedFields(parent),
+    });
+    if (outcome === undefined)
+        return result;
+    if (outcome.stop)
+        core.requestStop(outcome.reason);
+    let next = result;
+    const extras = [];
+    if (outcome.decision === "block" || outcome.decision === "deny") {
+        next = { ...next, isError: true };
+        extras.push(outcome.reason ?? "Blocked by PostToolUse hook");
+    }
+    if (outcome.additionalContext !== undefined && outcome.additionalContext !== "") {
+        extras.push(outcome.additionalContext);
+    }
+    if (extras.length === 0)
+        return next;
+    const suffix = `\n\n${extras.join("\n\n")}`;
+    const content = typeof next.content === "string"
+        ? next.content + suffix
+        : [...next.content, { type: "text", text: suffix.trimStart() }];
+    return { ...next, content };
+}
+export function createToolContext(core, runner, call, signal, onUpdate) {
+    const model = core.model();
+    let nested = 0;
+    const ctx = {
+        toolCallId: call.id,
+        cwd: core.cwd,
+        sessionId: core.manager.id,
+        signal,
+        depth: core.depth,
+        model: { provider: model.provider, id: model.id },
+        thinkingLevel: core.thinkingLevel(),
+        onUpdate,
+        readFiles: core.readFiles,
+        markRead: (path) => {
+            core.readFiles.add(path);
+        },
+        tools: {
+            executeTool: (name, input, options) => {
+                nested++;
+                const nestedCall = {
+                    type: "toolCall",
+                    id: `${call.id}_n${nested}`,
+                    name,
+                    arguments: typeof input === "object" && input !== null && !Array.isArray(input)
+                        ? input
+                        : {},
+                };
+                const assistant = core.agent.messages.findLast((message) => message.role === "assistant");
+                if (assistant === undefined || assistant.role !== "assistant") {
+                    return Promise.resolve({ content: "no active assistant message", isError: true });
+                }
+                const nestedSignal = options?.signal === undefined ? signal : AbortSignal.any([signal, options.signal]);
+                return runSingleToolCall(nestedCall, assistant, runner, nestedSignal, {
+                    parent: { toolCallId: call.id, viaCodemode: call.name === CODEMODE_TOOL_NAME },
+                    emit: async (event) => core.emit(event),
+                });
+            },
+        },
+        session: {
+            appendCustom: (customType, data) => {
+                core.appendEntry({ type: "custom", customType, data });
+            },
+            lastCustom: (customType) => {
+                const branch = core.manager.branch();
+                for (let i = branch.length - 1; i >= 0; i--) {
+                    const entry = branch[i];
+                    if (entry?.type === "custom" && entry.customType === customType)
+                        return entry.data;
+                }
+                return undefined;
+            },
+        },
+        log: (level, message) => core.log(level, message),
+    };
+    const file = core.manager.file();
+    const outputDir = core.outputDir();
+    const extra = {};
+    if (file !== undefined)
+        extra.sessionFile = file;
+    if (outputDir !== undefined)
+        extra.outputDir = outputDir;
+    if (core.depth === 0 && core.options.subagents !== false) {
+        extra.spawnSubagent = (request) => core.spawnSubagent(request);
+    }
+    return Object.assign(ctx, extra);
+}
+export function createToolRunnerOptions(core) {
+    const runner = {
+        getTool: (name) => core.activeTool(name),
+        getNestedTool: (name) => core.tool(name),
+        beforeToolCall: (call, ctx) => gateToolCall(core, call, ctx),
+        afterToolCall: (call, result, ctx) => afterToolCall(core, call, result, ctx?.parent),
+        createToolContext: (call, signal, onUpdate) => createToolContext(core, runner, call, signal, onUpdate),
+        get outputDir() {
+            return core.outputDir();
+        },
+    };
+    if (core.options.maxToolResultChars !== undefined) {
+        runner.maxToolResultChars = core.options.maxToolResultChars;
+    }
+    if (core.options.abortGraceMs !== undefined)
+        runner.abortGraceMs = core.options.abortGraceMs;
+    return runner;
+}

package/dist/agent/session.d.ts

@@ -0,0 +1,117 @@
+/**
+ * AgentSessionImpl（设计 §4.2–§4.3、§9、§11.1 第 16 步、§13.1）。[B2]
+ *
+ * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文消息、队列、run）+ 压缩 / 重试 / Hook 调度。
+ * - 每条 message_end 落盘为条目；Agent 的上下文 = 活动分支的投影（压缩 / context_edit 后重建）。
+ * - 首次模型请求前把系统提示 + 工具表作为首条 `system` 消息落盘并 `flush()`（此时才创建文件）；
+ *   之后节或工具表变化落 system 补丁。
+ * - `prompt()`：运行中且无 streamingBehavior → `AmaError{code:"busy"}`；否则展开（expandPrompt）→
+ *   UserPromptSubmit Hook → 阈值压缩检查 → 会话周期（session-run.ts）；周期结束后 resolve。
+ * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
+ * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
+ */
+import type { Model, ModelThinkingLevel } from "../ai/types.js";
+import type { HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { SessionManager } from "../session/manager.js";
+import type { AgentMessage, BranchSummaryEntry, SessionEntry, SessionEntryInput } from "../session/types.js";
+import type { SubagentRequest, SubagentResult, ToolDefinition } from "../tools/types.js";
+import { Agent } from "./agent.js";
+import type { StreamFn } from "./loop.js";
+import type { AgentSessionOptions, SessionCore } from "./session-core.js";
+import { SessionCacheController } from "./session-cache.js";
+import type { SystemPromptInput } from "./system-prompt.js";
+import type { AgentSession, CompactionResult, EnqueueOptions, PromptDisposition, PromptOptions, SessionEvent, SessionState, SessionStats } from "./types.js";
+export type { AgentSessionOptions } from "./session-core.js";
+export declare class AgentSessionImpl implements AgentSession, SessionCore {
+    readonly options: AgentSessionOptions;
+    readonly manager: SessionManager;
+    readonly agent: Agent;
+    readonly cwd: string;
+    readonly depth: number;
+    readonly readFiles: Set<string>;
+    readonly stream: StreamFn;
+    readonly cache: SessionCacheController;
+    private currentModel;
+    private currentThinking;
+    private readonly allTools;
+    private activeNames;
+    private readonly listeners;
+    private readonly compaction;
+    private retrySettings;
+    private cycle;
+    private retrying;
+    private stopReason;
+    private stopFlag;
+    private turns;
+    private systemInput;
+    private readonly subagentPool;
+    private disposed;
+    /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
+    private readonly queuedMessages;
+    constructor(options: AgentSessionOptions);
+    model(): Model;
+    thinkingLevel(): ModelThinkingLevel;
+    outputDir(): string | undefined;
+    resolveApiKey(): Promise<string | undefined>;
+    emit(event: SessionEvent): void;
+    appendEntry(input: SessionEntryInput): SessionEntry;
+    reloadMessages(): void;
+    activeTool(name: string): ToolDefinition | undefined;
+    tool(name: string): ToolDefinition | undefined;
+    activeToolNames(): string[];
+    runHook(event: HookEvent, payload: HookEventPayload, signal?: AbortSignal): Promise<HookOutcome | undefined>;
+    requestStop(reason: string | undefined): void;
+    log(level: "debug" | "info" | "warn" | "error", message: string): void;
+    private onAgentEvent;
+    private emitQueue;
+    private syncSystem;
+    private assertUsable;
+    private startCycle;
+    private runDeps;
+    prompt(text: string, options?: PromptOptions): Promise<PromptDisposition>;
+    private enqueue;
+    private enqueueOrRun;
+    steer(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
+    followUp(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
+    abort(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    clearQueue(): {
+        steering: string[];
+        followUp: string[];
+    };
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    /** 手动压缩；运行中 → busy。 */
+    compact(instructions?: string): Promise<CompactionResult>;
+    fork(entryId: string): Promise<AgentSessionImpl>;
+    /**
+     * `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。
+     */
+    navigate(targetId: string | null, options?: {
+        summarize?: boolean;
+        instructions?: string;
+    }): Promise<BranchSummaryEntry | undefined>;
+    setModel(ref: string): Promise<void>;
+    setThinkingLevel(level: ModelThinkingLevel): void;
+    setPermissionMode(mode: PermissionMode): void;
+    setActiveTools(names: string[]): void;
+    /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
+    addTool(tool: ToolDefinition, active?: boolean): void;
+    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
+    updateSystem(patch: Partial<Omit<SystemPromptInput, "tools" | "cwd">>): void;
+    setAutoCompaction(enabled: boolean): void;
+    setAutoRetry(enabled: boolean): void;
+    getTools(): readonly ToolDefinition[];
+    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
+    announceStart(reason: "startup" | "resume" | "new" | "fork"): void;
+    get state(): SessionState;
+    get messages(): readonly AgentMessage[];
+    get entries(): readonly SessionEntry[];
+    /** run 被 Hook 的 continue:false 结束时的说明。 */
+    get stopHookReason(): string | undefined;
+    getLastAssistantText(): string | null;
+    getStats(): SessionStats;
+    dispose(): Promise<void>;
+    childBase(): Pick<AgentSessionOptions, "model" | "thinkingLevel" | "activeTools" | "system">;
+    spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
+}