@oharness/engine 0.10.0 → 0.11.0

package/dist/agent/agent.js

@@ -1,5 +1,7 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { GOAL_MAX_TURNS, GOAL_TOOL, MAX_GOAL_NUDGES, activeGoal, goalNudge, goalPromptSection, goalTool } from "./goal.js";
-import { COMPUTER_KEY, computerOn, computerPromptSection, isComputerTool } from "../computer/mode.js";
+import { COMPUTER_ENABLE_TOOL, COMPUTER_KEY, computerOn, computerPromptSection, isComputerTool } from "../computer/mode.js";
 import { randomUUID } from "node:crypto";
 import { errorMessage } from "../core/errors.js";
 import { estimateMessagesTokens, estimateStringTokens, estimateToolsTokens } from "../core/tokens.js";
@@ -28,6 +30,7 @@ import { createSkillTool } from "../tools/builtin/skill.js";
 import { createMcpResourceTools } from "../tools/builtin/mcp-resource.js";
 import { HookRegistry } from "./hooks.js";
 import { buildSystemPrompt } from "./prompt.js";
+import { AcpSignInRequired, AcpUnavailable, runAcpTurn } from "../acp/runner.js";
 import { ASK_USER_TOOL } from "../tools/questions.js";
 import { SubagentRegistry } from "./subagent.js";
 function withoutSignal(opts) {
@@ -643,6 +646,8 @@ export class Agent {
         // background tasks: it has none of its own.
         const childTools = definition.tools ? this.tools.filtered(definition.tools) : this.tools.clone();
         childTools.unregister(ASK_USER_TOOL);
+        // Nor may it switch the screen on for itself; see the COMPUTER_KEY rule above.
+        childTools.unregister(COMPUTER_ENABLE_TOOL);
         childTools.unregister(TASK_OUTPUT_TOOL);
         childTools.unregister(TASK_STOP_TOOL);
         childTools.unregister(TASK_MESSAGE_TOOL);
@@ -689,6 +694,8 @@ export class Agent {
      * the task say what the subagent is doing now.
      */
     async runChild(child, input, signal, report) {
+        if (child.definition.runtime?.kind === "acp")
+            return this.runExternalChild(child, input, signal, report);
         let text = "";
         let turns = 0;
         let usage = emptyUsage();
@@ -723,6 +730,279 @@ export class Agent {
         });
         return { text, turns, usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens } };
     }
+    /**
+     * One run of a subagent whose loop is an external agent's (ACP).
+     *
+     * The child session is still kept, as the record of the task: the prompt
+     * and the agent's answer go into it, so a background task's transcript and
+     * a follow-up after a restart read the same as any other subagent's. The
+     * agent itself starts fresh each run, so what came before rides in the
+     * prompt.
+     */
+    async runExternalChild(child, input, signal, report) {
+        const runtime = child.definition.runtime;
+        const session = child.agent.session;
+        const earlier = session.messages
+            .map((message) => `${message.role === "user" ? "Asked" : "You answered"}: ${messageText(message).trim()}`)
+            .filter((line) => !line.endsWith(": "));
+        const prompt = earlier.length
+            ? `Earlier in this task:\n\n${earlier.join("\n\n")}\n\nNow: ${input}`
+            : input;
+        // The agent's own session from the last run, when it ran in this folder:
+        // a follow-up resumes it, so the agent keeps what it learned, and only
+        // the new message is sent. Another folder (a replaced worktree) is not
+        // the same session, whatever its id.
+        const last = [...session.messages].reverse().find((message) => message.role === "assistant");
+        const previous = last?.meta?.["acpSession"];
+        const resume = typeof previous?.id === "string" && previous.cwd === session.cwd
+            ? { sessionId: previous.id, prompt: input }
+            : undefined;
+        const servers = await this.forwardedMcpServers();
+        await session.addMessage({ role: "user", content: [{ type: "text", text: input }], meta: { timestamp: Date.now() } });
+        report?.turn();
+        let text;
+        let acpSession;
+        try {
+            const result = await runAcpTurn({
+                runtime,
+                cwd: session.cwd,
+                prompt,
+                ...(resume ? { resume } : {}),
+                ...(servers.length ? { mcpServers: servers } : {}),
+                // Its file reads and writes through the same policy as ours: in the
+                // project (or its worktree), and nowhere it was not allowed to go.
+                fs: child.agent.externalFs(),
+                ...(signal ? { signal } : {}),
+                askPermission: (title, toolInput, toolCallId) => child.agent.askForExternal(title, toolInput, toolCallId, signal),
+                onActivity: (title) => report?.activity(title),
+            });
+            text = result.text || (result.stopReason === "cancelled" ? "Stopped." : "The agent finished without saying anything.");
+            acpSession = { id: result.sessionId, cwd: session.cwd };
+        }
+        catch (err) {
+            // Said as the answer rather than thrown: "sign in to Claude Code" is
+            // what the parent has to pass on, not a crash to report.
+            if (err instanceof AcpSignInRequired || err instanceof AcpUnavailable)
+                text = err.message;
+            else
+                throw err;
+        }
+        await session.addMessage({
+            role: "assistant",
+            content: [{ type: "text", text }],
+            meta: { timestamp: Date.now(), ...(acpSession ? { acpSession } : {}) },
+        });
+        await this.hooks.run({
+            event: "SubagentStop",
+            sessionId: this.session.id,
+            agentId: `${this.agentId}/${child.definition.name}`,
+            cwd: this.session.cwd,
+        });
+        // No usage: the external agent bills its own account and reports none.
+        return { text, turns: 1, usage: { inputTokens: 0, outputTokens: 0 } };
+    }
+    /**
+     * File access for an external agent, through this agent's workspace policy:
+     * reads where ours may read, writes where ours may write, nowhere else.
+     */
+    externalFs() {
+        return {
+            read: async (file, line, limit) => {
+                const text = await readFile(this.resolvePath(file, "read"), "utf8");
+                if (line === undefined && limit === undefined)
+                    return text;
+                const lines = text.split("\n");
+                const start = Math.max(0, (line ?? 1) - 1);
+                return lines.slice(start, limit === undefined ? undefined : start + limit).join("\n");
+            },
+            write: async (file, content) => {
+                const target = this.resolvePath(file, "write");
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, content);
+            },
+        };
+    }
+    /**
+     * `@claude …`: a message addressed to an external agent by name.
+     *
+     * Only an agent with an ACP runtime answers to this, and only at the start
+     * of what was typed — or of the paragraph after a reference note, which the
+     * page puts above the prompt. The note stays with the message; the name
+     * does not.
+     */
+    directTarget(input) {
+        if (typeof input !== "string")
+            return undefined;
+        const match = /(^|\n\n)@([\w./-]+)[ \t]+(\S[\s\S]*)$/.exec(input);
+        if (!match)
+            return undefined;
+        const definition = this.subagents.get(match[2]);
+        if (definition?.runtime?.kind !== "acp")
+            return undefined;
+        const note = input.slice(0, match.index).trim();
+        return { definition, text: note ? `${note}\n\n${match[3]}` : match[3] };
+    }
+    /**
+     * A turn answered by an external agent instead of the model.
+     *
+     * What makes `@claude` worth having: the message goes straight to the
+     * user's own Claude Code, so it is paid for by their Claude account and
+     * nothing is spent on this harness's model in between. The agent's reply
+     * streams into the conversation as text, its tool calls as tool cards, its
+     * questions as the usual permission card; the exchange is kept as an
+     * ordinary user/assistant pair, and the agent's session id rides on the
+     * reply so the next `@claude` picks up where this one left off.
+     */
+    async *runDirect(target, raw, signal) {
+        const { definition, text } = target;
+        const runtime = definition.runtime;
+        const finishRun = this.opts.onRunStart?.();
+        let stopReason = "end_turn";
+        try {
+            await this.session.init();
+            await this.session.addMessage(userMessage(raw));
+            yield { type: "turn_start", turn: 1, model: definition.name };
+            const previous = [...this.session.messages]
+                .reverse()
+                .find((message) => message.role === "assistant" && message.meta?.["agent"] === definition.name)
+                ?.meta?.["acpSession"];
+            const resume = typeof previous?.id === "string" && previous.cwd === this.session.cwd
+                ? { sessionId: previous.id, prompt: text }
+                : undefined;
+            const events = channel();
+            const started = new Map();
+            let reply = "";
+            const servers = await this.forwardedMcpServers();
+            const turn = runAcpTurn({
+                runtime,
+                cwd: this.session.cwd,
+                prompt: text,
+                ...(resume ? { resume } : {}),
+                ...(servers.length ? { mcpServers: servers } : {}),
+                fs: this.externalFs(),
+                signal,
+                askPermission: (title, input, toolCallId) => this.askForExternal(title, input, toolCallId, signal, definition.name),
+                onActivity: (title) => {
+                    if (title === "Starting the agent…")
+                        events.push({ type: "notice", message: `Starting ${definition.name}…` });
+                },
+                onUpdate: (update) => {
+                    if (update.sessionUpdate === "agent_message_chunk" || update.sessionUpdate === "agent_thought_chunk") {
+                        const content = update.content;
+                        if (content?.type !== "text" || !content.text)
+                            return;
+                        if (update.sessionUpdate === "agent_thought_chunk")
+                            return events.push({ type: "thinking_delta", text: content.text });
+                        reply += content.text;
+                        events.push({ type: "text_delta", text: content.text });
+                    }
+                    else if (update.sessionUpdate === "tool_call") {
+                        const call = update;
+                        const id = `${definition.name}:${call.toolCallId}`;
+                        started.set(id, Date.now());
+                        events.push({
+                            type: "tool_start",
+                            toolCallId: id,
+                            toolName: call.kind || "tool",
+                            title: call.title || call.kind || "tool",
+                            input: call.rawInput ?? {},
+                        });
+                    }
+                    else if (update.sessionUpdate === "tool_call_update") {
+                        const call = update;
+                        const id = `${definition.name}:${call.toolCallId}`;
+                        if ((call.status !== "completed" && call.status !== "failed") || !started.has(id))
+                            return;
+                        const began = started.get(id);
+                        started.delete(id);
+                        events.push({
+                            type: "tool_end",
+                            toolCallId: id,
+                            toolName: call.kind || "tool",
+                            result: { content: [{ type: "text", text: call.status }], ...(call.status === "failed" ? { isError: true } : {}) },
+                            durationMs: Date.now() - began,
+                        });
+                    }
+                },
+            });
+            void turn.then(() => events.close(), () => events.close());
+            for await (const event of events.drain())
+                yield event;
+            let acpSession;
+            try {
+                const result = await turn;
+                acpSession = { id: result.sessionId, cwd: this.session.cwd };
+                if (result.stopReason === "cancelled" || signal.aborted)
+                    stopReason = "aborted";
+                if (!reply.trim())
+                    reply = result.text;
+            }
+            catch (err) {
+                if (err instanceof AcpSignInRequired || err instanceof AcpUnavailable) {
+                    reply = err.message;
+                    yield { type: "text_delta", text: err.message };
+                }
+                else if (signal.aborted) {
+                    stopReason = "aborted";
+                }
+                else {
+                    stopReason = "error";
+                    yield { type: "error", error: `${definition.name}: ${errorMessage(err)}`, fatal: false };
+                }
+            }
+            if (reply.trim()) {
+                const message = {
+                    role: "assistant",
+                    content: [{ type: "text", text: reply }],
+                    meta: { timestamp: Date.now(), agent: definition.name, ...(acpSession ? { acpSession } : {}) },
+                };
+                await this.session.addMessage(message);
+                yield { type: "assistant_message", message };
+            }
+        }
+        finally {
+            this.running = false;
+            await this.session.persist().catch(() => { });
+            finishRun?.();
+        }
+        yield { type: "done", stopReason, usage: this.session.usage, costUsd: this.session.costUsd, turns: 1 };
+    }
+    /**
+     * This conversation's MCP servers, in the shape ACP's `session/new` takes,
+     * so an external agent works with the same tools. HTTP ones are filtered
+     * out later for an agent that does not take them.
+     */
+    async forwardedMcpServers() {
+        const pairs = (values) => Object.entries(values ?? {}).map(([name, value]) => ({ name, value }));
+        const found = await this.opts.mcp?.forwardable().catch(() => []) ?? [];
+        return found.map(({ name, config, headers }) => config.type === "stdio"
+            ? { name, command: config.command, args: config.args ?? [], env: pairs(config.env) }
+            : { type: "http", name, url: config.url, headers: pairs({ ...config.headers, ...headers }) });
+    }
+    /**
+     * An external agent's own tool call, put to the person the way this
+     * harness's calls are — the same card, placed in the conversation that
+     * started the task and labelled with who is asking. Plan mode and a
+     * read-only workspace refuse; bypass allows, as it would for our own tools.
+     */
+    async askForExternal(title, input, toolCallId, signal, from) {
+        const mode = this.session.permissions.getMode();
+        if (this.opts.workspace?.mode === "read-only" || mode === "plan" || !this.opts.permissionPrompt)
+            return false;
+        if (mode === "bypassPermissions")
+            return true;
+        const request = {
+            toolName: "external",
+            input,
+            title,
+            ...this.interactionPlace(),
+            ...(from ? { from } : {}),
+            toolCallId,
+        };
+        const prompt = this.opts.permissionPrompt;
+        const ask = () => prompt(request, signal);
+        return signal ? untilAborted(signal, ask, false, false) : ask();
+    }
     /** What a subagent left in its worktree, when it left anything. */
     async worktreeNote(child) {
         if (!child.worktree)
@@ -767,6 +1047,12 @@ export class Agent {
             this.running = false;
             throw new Error("Agent host is closed");
         }
+        // Addressed to an external agent by name: its turn, not the model's.
+        const direct = this.directTarget(input);
+        if (direct) {
+            yield* this.runDirect(direct, input, signal);
+            return;
+        }
         // Fired once per session rather than per turn: hooks use it to seed
         // context or announce the session, which should not repeat every prompt.
         if (!this.sessionStarted) {
@@ -1301,6 +1587,9 @@ export class Agent {
         return this.tools
             .visible(this.opts.toolFilter)
             .filter((tool) => (goal || tool.name !== GOAL_TOOL) && (computer || !isComputerTool(tool.name)))
+            // Asking for the computer is for a conversation without it and with
+            // somebody there: a routine or a headless run has nobody to answer.
+            .filter((tool) => tool.name !== COMPUTER_ENABLE_TOOL || (!computer && Boolean(this.opts.permissionPrompt)))
             .filter((tool) => worktrees || tool.name !== WORKTREE_START_TOOL)
             .filter((tool) => background || ![TASK_OUTPUT_TOOL, TASK_STOP_TOOL, TASK_MESSAGE_TOOL].includes(tool.name));
     }
@@ -1778,4 +2067,36 @@ function touchesSkills(toolName, input) {
     // what is advertised, so re-scanning for those would be noise.
     return target.includes("skills") && target.endsWith("SKILL.md");
 }
+/**
+ * A queue a callback pushes into and a generator drains, for turning an
+ * external agent's callbacks into a stream of events as they happen.
+ */
+function channel() {
+    const items = [];
+    let wake;
+    let closed = false;
+    const poke = () => {
+        wake?.();
+        wake = undefined;
+    };
+    return {
+        push(item) {
+            items.push(item);
+            poke();
+        },
+        close() {
+            closed = true;
+            poke();
+        },
+        async *drain() {
+            for (;;) {
+                while (items.length)
+                    yield items.shift();
+                if (closed)
+                    return;
+                await new Promise((resolve) => (wake = resolve));
+            }
+        },
+    };
+}
 //# sourceMappingURL=agent.js.map