@rien7/agent-center-host 0.0.0-stage → 0.1.0

package/dist/oar-driver.js

@@ -0,0 +1,1245 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * OarDriver: answers turns with a real agent run by an oar runtime (Claude Code by
+ * default, pi, …). One oar session per agent, opened on demand (resumed from the agent's
+ * `resumeSessionId`), closed after `idleMinutes` without turns.
+ *
+ * - Tokens: each agent's tools use the agent's own Center token: host.json's
+ *   `agents[].token` when given, else one the host gets from Center (agent.issue_token,
+ *   kept in agent-tokens.json; agent-tokens.ts).
+ * - Tools: a host-served MCP server per agent (`serveMcpTools`, loopback HTTP + random
+ *   bearer) with the Center tools (center-tools.ts), proxied to core with the agent's own
+ *   token. The context's domains (the page or record the user is looking at) are added as
+ *   direct tools with full schemas for the rest of the session when the runtime takes MCP
+ *   tool-list changes (pi: full, claude: additions); otherwise they are inlined in the
+ *   turn's prefix.
+ * - Memory: `<workdir>/agents/<id>/memory/` (memory.ts) is the session's cwd subtree; the
+ *   runtime's own file tools edit it.
+ * - Records: every raw oar record is appended to
+ *   `<workdir>/records/<agentId>/<sessionId>-<opened>.jsonl`.
+ * - Sub-agents (crew-tools.ts): a main agent's agent_spawn makes a core agent with
+ *   parentAgentId (this host's, restricted token, own workdir and memory) whose session
+ *   oar's crew (`@botiverse/oar/agents`) opens. Its turns are core turns like any other:
+ *   the parent's task and follow-ups are turn.open turns in the child's conversation, the
+ *   user can chat with it directly. Each report of a turn the parent started goes back
+ *   to the parent: into a pending agent_wait, else as a turn.open turn in the parent's
+ *   conversation, with a card that opens the child's conversation. Children don't spawn.
+ * - A turn a host restart interrupted is run again once, with 「上一轮被打断，请继续」.
+ *
+ * Turn ↔ oar turn: a delivery that lands `prompted` owns the next oar turn; `steered`
+ * takes over the running one (the earlier core turn finishes as it stands); `queued`
+ * waits for the next one. Events of the root agent go to the current owner.
+ */
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentTokens, defaultAgentScopes } from "./agent-tokens.js";
+import { CenterApi, CenterTools, centerInstructions, centerServedTools, compactSchema, contextDomains, recordCards, } from "./center-tools.js";
+import { CoreError } from "./core-client.js";
+import { crewServedTools } from "./crew-tools.js";
+import { MemorySync } from "./memory.js";
+import { interruptedText, systemPrompt, turnText } from "./prompt.js";
+import { bareToolName, coreToolTitle, inputDetail, toolTitle, } from "./tool-titles.js";
+/** Runtime tools an agent never gets (no shell; Claude Code's web and sub-agent tools). */
+const defaultDisallowed = {
+    pi: ["bash"],
+    claude: [
+        "Bash",
+        "BashOutput",
+        "KillShell",
+        "WebFetch",
+        "WebSearch",
+        "Task",
+        "NotebookEdit",
+    ],
+};
+/** Sub-agents running at once (all parents together). */
+const maxRunningChildren = 4;
+/** Sub-agents one parent may have open. */
+const maxChildren = 8;
+/**
+ * Merges consecutive text deltas for up to `holdMs` (oar's `coalesceText` held pi's text
+ * until the message ended, so streaming is merged here instead).
+ */
+function textSink(sink, holdMs = 100) {
+    let text = "";
+    let timer = null;
+    const flush = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        if (text)
+            sink.emit({ type: "textDelta", text });
+        text = "";
+    };
+    return {
+        emit(event) {
+            if (event.type === "textDelta") {
+                text += event.text;
+                timer ??= setTimeout(flush, holdMs);
+                return;
+            }
+            flush();
+            sink.emit(event);
+        },
+    };
+}
+const clip = (text, max) => {
+    const chars = Array.from(text);
+    return chars.length > max ? `${chars.slice(0, max).join("")}…` : text;
+};
+const parse = (input) => {
+    if (!input)
+        return null;
+    try {
+        const value = JSON.parse(input);
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+const conversationUri = (id) => `agent:conversation/${id}`;
+/** The conversation a host-opened turn came from (its context), or null for the user's. */
+const fromConversation = (context) => {
+    const uri = context
+        ?.kind?.uri;
+    return typeof uri === "string" && uri.startsWith("agent:conversation/")
+        ? uri.slice("agent:conversation/".length)
+        : null;
+};
+class AgentRun {
+    agent;
+    spec;
+    dir;
+    runtimeId;
+    model;
+    tools;
+    memory;
+    /** Write scopes of its token (what a child may get at most). */
+    scopes;
+    parent;
+    live = null;
+    opening = null;
+    idle = null;
+    /** Prompt state of the current (or next) session. */
+    direct = new Set();
+    inlined = new Set();
+    /** MEMORY.md as the session last saw it. */
+    memorySeen = null;
+    /** driver.run calls in progress. */
+    busy = 0;
+    // A child:
+    /** Its crew id while its session is open. */
+    crewId = null;
+    /** Owners of the turn its session is being opened for. */
+    pending = [];
+    /** The owner of the oar turn that ended last (its report follows). */
+    lastEnded = null;
+    /** Its conversation with its parent. */
+    conversationId = null;
+    // A parent:
+    children = new Map();
+    /** Reports not delivered yet. */
+    inbox = [];
+    waiters = new Set();
+    constructor(agent, spec, driver, client, token, parent = null) {
+        this.agent = agent;
+        this.spec = spec;
+        this.parent = parent;
+        this.scopes = token.scopes;
+        this.dir = join(driver.config.workdir, "agents", agent.id);
+        this.runtimeId = spec.runtime ?? driver.config.runtime;
+        this.model = spec.model ?? driver.config.model;
+        this.tools = new CenterTools({
+            api: new CenterApi(driver.server, token.token, { fetch: driver.fetcher }),
+            timeZone: driver.config.timeZone,
+            now: driver.now,
+        });
+        this.memory = new MemorySync({
+            client,
+            agentId: agent.id,
+            agentName: agent.name,
+            agentDir: this.dir,
+            log: (m) => driver.log(`${agent.name}: ${m}`),
+        });
+    }
+    /** A child by name or id. */
+    child(ref) {
+        const all = [...this.children.values()];
+        return (this.children.get(ref) ??
+            all.findLast((c) => c.agent.name === ref) ??
+            all.findLast((c) => c.agent.name.includes(ref)) ??
+            null);
+    }
+}
+/** Scopes a token must never carry (Center refuses them for agent tokens too). */
+const unsafeScopes = ["*", "agent:host", "core:admin", "core:*", "agent:*"];
+export class OarDriver {
+    name;
+    config;
+    server;
+    fetcher;
+    now;
+    log = () => { };
+    client = null;
+    context = null;
+    runs = new Map();
+    loadOar;
+    loadAgents;
+    loadRuntime;
+    oarModule = null;
+    runtimes = new Map();
+    tokenOption;
+    tokens = null;
+    crew = null;
+    /** Runtimes as the crew sees them: sessions get the child's prompt, tools and limits. */
+    crewRuntimes = new Map();
+    /** Children whose session is being opened, by cwd. */
+    spawning = new Map();
+    opened = new Map();
+    resumed = null;
+    constructor(options) {
+        this.config = options.config;
+        this.name = options.config.runtime;
+        this.server = options.server;
+        this.fetcher = options.fetch;
+        this.now = options.now ?? Date.now;
+        this.tokenOption = options.tokens;
+        this.loadOar = options.oar ?? (() => import("@botiverse/oar"));
+        this.loadAgents = options.agents ?? (() => import("@botiverse/oar/agents"));
+        this.loadRuntime =
+            options.runtime ??
+                (async (id) => {
+                    const module = (await import(__rewriteRelativeImportExtension(`@botiverse/oar/runtimes/${id}`)));
+                    const runtime = module[`${id}Runtime`];
+                    if (!runtime)
+                        throw new Error(`oar has no runtime ${id}`);
+                    return runtime;
+                });
+    }
+    oar() {
+        this.oarModule ??= this.loadOar();
+        return this.oarModule;
+    }
+    runtime(id) {
+        let runtime = this.runtimes.get(id);
+        if (!runtime) {
+            runtime = this.loadRuntime(id);
+            this.runtimes.set(id, runtime);
+        }
+        return runtime;
+    }
+    /** The agent's token: host.json's, else the saved one Center still takes, else a new one. */
+    async token(agent, spec, scopes) {
+        const own = spec.token;
+        if (own)
+            return { token: own, scopes: spec.scopes ?? [] };
+        if (!this.tokens)
+            throw new Error("no token store");
+        const { token, issued } = await this.tokens.get(agent.id, scopes, (t) => this.accepted(t));
+        if (issued)
+            this.log(`${agent.name}: got its own Center token`);
+        return { token, scopes };
+    }
+    /** Does Center still take this token (false only on 401)? */
+    async accepted(token) {
+        const response = await (this.fetcher ?? fetch)(`${this.server.replace(/\/+$/, "")}/v1/ops/core.principal.me`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: "{}",
+        });
+        await response.body?.cancel();
+        if (response.status === 401)
+            return false;
+        if (!response.ok)
+            throw new Error(`core.principal.me failed with ${response.status}`);
+        return true;
+    }
+    /** Make the agent's run: token, safety check, workdir, memory. */
+    async prepare(agent, spec, scopes, parent) {
+        const client = this.client;
+        const token = await this.token(agent, spec, scopes).catch((error) => {
+            throw new Error(`agent ${agent.name}: no Center token (${error.message}); put one in host.json (agents[].token) or update Center`);
+        });
+        const run = new AgentRun(agent, spec, this, client, token, parent);
+        // The agent's token must not be able to act as a host or an admin.
+        const me = await run.tools.api
+            .op("core.principal.me", {})
+            .catch((error) => {
+            throw new Error(`agent ${agent.name}: its token was rejected (${error.message})`);
+        });
+        const granted = me.principal?.scopes ?? me.scopes ?? [];
+        const unsafe = granted.filter((s) => unsafeScopes.includes(s));
+        if (unsafe.length)
+            throw new Error(`agent ${agent.name}: its token has ${unsafe.join(", ")}; give the agent a narrower token (e.g. *:read,agent:read,memo:write,reminder:write,calendar:write)`);
+        this.runs.set(agent.id, run);
+        if (parent)
+            parent.children.set(agent.id, run);
+        await mkdir(run.dir, { recursive: true });
+        await run.memory.start().catch((error) => {
+            this.log(`${agent.name}: memory sync failed (${error.message})`);
+        });
+        return run;
+    }
+    async start(context) {
+        this.client = context.client;
+        this.context = context;
+        this.log = context.log;
+        this.tokens =
+            this.tokenOption === undefined
+                ? new AgentTokens({ client: context.client, server: this.server })
+                : (this.tokenOption ??
+                    new AgentTokens({
+                        client: context.client,
+                        server: this.server,
+                        path: null,
+                    }));
+        if (this.config.piAgentDir)
+            process.env.OAR_PI_AGENT_DIR = this.config.piAgentDir;
+        process.env.PI_TELEMETRY ??= "0";
+        const children = [];
+        for (const agent of context.agents) {
+            const spec = this.config.agents.find((a) => a.id === agent.id) ??
+                this.config.agents.find((a) => !a.id && a.name === agent.name);
+            if (!spec) {
+                if (agent.parentAgentId)
+                    children.push(agent);
+                else
+                    this.log(`agent ${agent.name} is not in host.json; its turns will fail`);
+                continue;
+            }
+            await this.prepare(agent, spec, spec.scopes ?? defaultAgentScopes, null);
+        }
+        // Sub-agents from before a restart: their parent's settings, their saved token.
+        for (const agent of children) {
+            const parent = this.runs.get(agent.parentAgentId);
+            if (!parent || parent.parent)
+                continue;
+            const saved = await this.tokens.entry(agent.id);
+            await this.prepare(agent, this.childSpec(parent, agent.name), saved?.scopes ?? [], parent).catch((error) => this.log(`${agent.name}: ${error.message}`));
+        }
+        // Warm oar up so the first turn doesn't pay for the import.
+        this.oar().catch(() => { });
+    }
+    childSpec(parent, name) {
+        return {
+            name,
+            runtime: parent.runtimeId,
+            ...(parent.model ? { model: parent.model } : {}),
+            ...(parent.spec.disallowedTools
+                ? { disallowedTools: parent.spec.disallowedTools }
+                : {}),
+        };
+    }
+    async stop() {
+        await Promise.allSettled([...this.runs.values()].map(async (run) => {
+            await this.close(run);
+            await run.memory.stop();
+        }));
+        const crew = this.crew;
+        this.crew = null;
+        if (crew)
+            await (await crew.catch(() => null))?.close();
+    }
+    /** Turns already run again after a restart (`<workdir>/resumed-turns.json`). */
+    async resumedTurns() {
+        if (this.resumed)
+            return this.resumed;
+        let ids = [];
+        try {
+            ids = JSON.parse(await readFile(join(this.config.workdir, "resumed-turns.json"), "utf8"));
+        }
+        catch { }
+        this.resumed = new Set(Array.isArray(ids) ? ids.map(String) : []);
+        return this.resumed;
+    }
+    async markResumed(turnId) {
+        const ids = await this.resumedTurns();
+        ids.add(turnId);
+        const kept = [...ids].slice(-200);
+        await mkdir(this.config.workdir, { recursive: true });
+        await writeFile(join(this.config.workdir, "resumed-turns.json"), `${JSON.stringify(kept)}\n`);
+    }
+    async run(input, sink, signal) {
+        const run = this.runs.get(input.agent.id);
+        if (!run) {
+            sink.emit({
+                type: "failed",
+                reason: `这个 host 没有配置 agent「${input.agent.name}」（host.json agents）`,
+            });
+            return;
+        }
+        run.busy++;
+        try {
+            await this.answer(run, input, sink, signal);
+        }
+        finally {
+            run.busy--;
+            this.flushInbox(run);
+        }
+    }
+    async answer(run, input, sink, signal) {
+        let interrupted = false;
+        if (input.appended > 0) {
+            // oar can't replay half a reply: run the turn again once, saying so.
+            if ((await this.resumedTurns()).has(input.turn.id)) {
+                sink.emit({
+                    type: "failed",
+                    reason: "host 又重启了，这条回复中断了，请重新发送",
+                });
+                return;
+            }
+            await this.markResumed(input.turn.id).catch((error) => this.log(`resumed-turns.json: ${error.message}`));
+            interrupted = true;
+            this.log(`${run.agent.name}: turn ${input.turn.id} was interrupted; running it again`);
+        }
+        if (run.idle)
+            clearTimeout(run.idle);
+        run.idle = null;
+        if (run.parent)
+            run.conversationId ??= input.conversation.id;
+        const opened = this.opened.get(input.turn.id);
+        this.opened.delete(input.turn.id);
+        const owner = {
+            turnId: input.turn.id,
+            conversationId: input.conversation.id,
+            fromParent: run.parent ? fromConversation(input.message.context) : null,
+            sink: textSink(sink),
+            finished: false,
+            chain: Promise.resolve(),
+            resolve: () => { },
+        };
+        const ended = new Promise((resolve) => {
+            owner.resolve = resolve;
+        });
+        if (interrupted)
+            owner.sink.emit({
+                type: "textDelta",
+                text: "\n\n（host 重启了，接着说）\n\n",
+            });
+        for (const card of opened?.cards ?? [])
+            owner.sink.emit({ type: "card", card });
+        // A child without a session: the crew opens one with this turn as its task.
+        if (run.parent && !run.live) {
+            run.pending.push(owner);
+            const text = await this.prompt(run, null, input, opened, interrupted);
+            // Once the crew prompted the task, abort it like any oar turn.
+            const onAbort = () => run.live?.owners.includes(owner)
+                ? this.abortOwner(run, run.live, owner)
+                : this.finish(run.pending, owner, null);
+            signal.addEventListener("abort", onAbort, { once: true });
+            const refused = await this.spawnChild(run, text).catch((error) => error.message);
+            if (refused)
+                this.finish(run.pending, owner, {
+                    type: "failed",
+                    reason: `打开子 agent 失败：${refused}`,
+                });
+            await ended;
+            signal.removeEventListener("abort", onAbort);
+            run.memory.sync();
+            this.scheduleIdle(run);
+            return;
+        }
+        let live;
+        try {
+            live = await this.open(run);
+        }
+        catch (error) {
+            sink.emit({
+                type: "failed",
+                reason: `打开 ${run.runtimeId} 会话失败：${error.message}`,
+            });
+            return;
+        }
+        if (signal.aborted)
+            return;
+        const text = await this.prompt(run, live, input, opened, interrupted).catch((error) => {
+            this.log(`${run.agent.name}: prompt prefix failed (${error.message})`);
+            return input.message.text;
+        });
+        const onAbort = () => this.abortOwner(run, live, owner);
+        signal.addEventListener("abort", onAbort, { once: true });
+        live.owners.push(owner);
+        try {
+            const result = await live.session.deliver(text, {
+                when: "now",
+                inputId: input.turn.id,
+                origin: opened?.origin ?? { kind: "user" },
+            });
+            if (result.landed === "rejected") {
+                this.finish(live.owners, owner, {
+                    type: "failed",
+                    reason: `${run.runtimeId} 拒绝了这条消息：${result.reason}`,
+                });
+            }
+            else if (result.landed !== "queued") {
+                // prompted / steered: earlier owners hand the running oar turn over.
+                for (const earlier of live.owners.slice(0, live.owners.indexOf(owner)))
+                    this.finish(live.owners, earlier, { type: "done" });
+            }
+        }
+        catch (error) {
+            this.finish(live.owners, owner, {
+                type: "failed",
+                reason: error.message,
+            });
+        }
+        await ended;
+        signal.removeEventListener("abort", onAbort);
+        run.memory.sync();
+        this.scheduleIdle(run);
+    }
+    /** The user's text with time, context, memory and the context's domain tools. */
+    async prompt(run, live, input, opened, interrupted) {
+        const memory = await run.memory.index();
+        const memoryChanged = memory !== run.memorySeen;
+        run.memorySeen = memory;
+        const domains = contextDomains(input.message.context);
+        const visible = new Set((await run.tools.tools()).map((t) => t.name.split("_")[0]));
+        const wanted = domains.filter((d) => visible.has(d));
+        let inline = null;
+        const runtime = await this.runtime(run.runtimeId);
+        const canChange = live !== null &&
+            this.config.contextTools === "direct" &&
+            (runtime.mcpToolsListChanged === "full" ||
+                runtime.mcpToolsListChanged === "additions");
+        const fresh = wanted.filter((d) => !run.direct.has(d) && !run.inlined.has(d));
+        if (fresh.length) {
+            if (canChange && live) {
+                for (const d of fresh)
+                    run.direct.add(d);
+                live.served.setTools(await this.servedTools(run));
+            }
+            else {
+                for (const d of fresh)
+                    run.inlined.add(d);
+                inline = await run.tools.expandDomains(fresh);
+            }
+        }
+        const text = opened?.text ?? input.message.text;
+        return turnText(interrupted ? interruptedText(text) : text, {
+            timeZone: this.config.timeZone,
+            now: this.now(),
+            context: input.message.context,
+            memory: memoryChanged ? memory : null,
+            tools: inline,
+        });
+    }
+    /** The meta tools, the sub-agent tools and every direct tool of the session's expanded domains. */
+    async servedTools(run) {
+        const base = await centerServedTools(run.tools);
+        if (this.config.subagents && !run.parent)
+            base.push(...crewServedTools({
+                spawn: (input) => this.spawnTool(run, input),
+                send: (input) => this.sendTool(run, input),
+                wait: (input, signal) => this.waitTool(run, input, signal),
+                close: (input) => this.closeTool(run, input),
+            }, { writeScopes: run.scopes }));
+        if (!run.direct.size)
+            return base;
+        const taken = new Set(base.map((t) => t.name));
+        const own = await Promise.all([...run.direct].map((d) => run.tools.contextTools(d)));
+        const direct = own
+            .flatMap(({ shown }) => shown)
+            .filter((t) => !taken.has(t.name))
+            .map((t) => ({
+            name: t.name,
+            description: `${coreToolTitle(t.name, t.readOnly)}。${t.description}`,
+            inputSchema: compactSchema(t.inputSchema),
+            handler: (input, { signal }) => run.tools.call(t.name, input, signal),
+        }));
+        return [...base, ...direct];
+    }
+    /** What every session of the agent is opened with (cwd, prompt, tools, limits). */
+    async sessionOptions(run, served) {
+        const options = {
+            cwd: run.dir,
+            name: run.agent.name,
+            ...(run.model ? { model: run.model } : {}),
+            systemPrompt: systemPrompt({
+                name: run.agent.name,
+                role: run.agent.role ?? run.spec.role,
+                timeZone: this.config.timeZone,
+                catalog: await run.tools.domainCatalog(),
+                subagents: this.config.subagents && !run.parent,
+                parent: run.parent?.agent.name ?? null,
+            }),
+            mcpServers: [served.server],
+            disallowedTools: run.spec.disallowedTools ?? defaultDisallowed[run.runtimeId] ?? [],
+        };
+        return options;
+    }
+    async serve(run) {
+        const oar = await this.oar();
+        return oar.serveMcpTools({
+            name: "center",
+            tools: await this.servedTools(run),
+            instructions: centerInstructions,
+        });
+    }
+    async open(run) {
+        if (run.live)
+            return run.live;
+        run.opening ??= this.doOpen(run).finally(() => {
+            run.opening = null;
+        });
+        return run.opening;
+    }
+    async doOpen(run) {
+        const oar = await this.oar();
+        const runtime = await this.runtime(run.runtimeId);
+        const installation = await runtime.installation?.();
+        if (!installation || installation.kind !== "available")
+            throw new Error(`${run.runtimeId} is not installed here (${installation?.kind ?? "no installation probe"})`);
+        const served = await this.serve(run);
+        let session;
+        const previous = run.agent.resumeSessionId;
+        try {
+            const options = await this.sessionOptions(run, served);
+            session = previous
+                ? await runtime
+                    .session(installation, { ...options, resume: previous })
+                    .catch((error) => {
+                    if (error instanceof oar.SessionNotFoundError ||
+                        error instanceof oar.SessionUnavailableError) {
+                        this.log(`${run.agent.name}: can't resume ${previous} (${error.message}); starting a new session`);
+                        return runtime.session(installation, options);
+                    }
+                    throw error;
+                })
+                : await runtime.session(installation, options);
+        }
+        catch (error) {
+            await served.close();
+            throw error;
+        }
+        return this.attach(run, session, served, previous);
+    }
+    /** Follow a new session: records, events, the agent's resumeSessionId. */
+    attach(run, session, served, previous) {
+        const live = {
+            session,
+            served,
+            owners: run.pending.splice(0),
+            calls: new Map(),
+            unsubscribe: () => { },
+            records: null,
+            draining: false,
+        };
+        const recordsDir = join(this.config.workdir, "records", run.agent.id);
+        const recordsPath = join(recordsDir, `${session.id}-${new Date(this.now()).toISOString().replace(/[:.]/g, "-")}.jsonl`);
+        const pending = [];
+        mkdir(recordsDir, { recursive: true })
+            .then(() => {
+            if (run.live !== live)
+                return;
+            live.records = createWriteStream(recordsPath, { flags: "a" });
+            live.records.on("error", () => { });
+            for (const record of pending.splice(0))
+                live.records.write(`${JSON.stringify(record)}\n`);
+        })
+            .catch(() => { });
+        const offRaw = session.rawEvents((record) => {
+            if (live.records)
+                live.records.write(`${JSON.stringify(record)}\n`);
+            else
+                pending.push(record);
+        });
+        const offEvents = session.events((event) => this.onEvent(run, live, event));
+        live.unsubscribe = () => {
+            offRaw();
+            offEvents();
+        };
+        run.live = live;
+        this.log(`${run.agent.name}: ${session.id === previous ? "resumed" : "opened"} ${run.runtimeId} session ${session.id} (records ${recordsPath})`);
+        if (session.id !== previous && this.client) {
+            this.client
+                .upsertAgent({ id: run.agent.id, resumeSessionId: session.id })
+                .then((agent) => {
+                run.agent = agent;
+            })
+                .catch((error) => {
+                this.log(`${run.agent.name}: saving resumeSessionId failed (${error.message})`);
+            });
+        }
+        return live;
+    }
+    // ---- sub-agents ----
+    async subagents() {
+        this.crew ??= this.loadAgents().then((m) => {
+            const crew = m.createSubagents({
+                runtimes: { get: (id) => this.crewRuntimes.get(id) },
+                maxRunning: maxRunningChildren,
+                maxDepth: 1,
+                cwd: join(this.config.workdir, "agents"),
+            });
+            crew.onReport((report) => this.onReport(report));
+            return crew;
+        });
+        return this.crew;
+    }
+    /**
+     * The runtime as the crew sees it: its sessions get the child's prompt, tools and
+     * limits (the crew passes only cwd, model and env) and are followed from the start.
+     */
+    async crewRuntime(id) {
+        const known = this.crewRuntimes.get(id);
+        if (known)
+            return known;
+        const runtime = await this.runtime(id);
+        const wrapped = Object.create(runtime);
+        Object.defineProperty(wrapped, "session", {
+            value: async (installation, options) => {
+                const spawning = this.spawning.get(options.cwd ?? "");
+                if (!spawning)
+                    throw new Error(`no sub-agent is being opened in ${options.cwd}`);
+                const session = await runtime.session(installation, {
+                    ...options,
+                    ...spawning.options,
+                    env: { ...options.env, ...spawning.options.env },
+                });
+                this.attach(spawning.run, session, spawning.served, spawning.run.agent.resumeSessionId);
+                return session;
+            },
+        });
+        this.crewRuntimes.set(id, wrapped);
+        return wrapped;
+    }
+    /** Open a child's session through the crew with `task` as its first turn; a refusal's reason, or null. */
+    async spawnChild(run, task) {
+        const crew = await this.subagents();
+        await this.crewRuntime(run.runtimeId);
+        const served = await this.serve(run);
+        const options = await this.sessionOptions(run, served);
+        const spawn = async (resume) => {
+            this.spawning.set(run.dir, { run, options, served });
+            try {
+                return await crew.spawn({
+                    runtime: run.runtimeId,
+                    task,
+                    name: run.agent.id,
+                    cwd: run.dir,
+                    ...(run.model ? { model: run.model } : {}),
+                    ...(resume ? { resume } : {}),
+                });
+            }
+            finally {
+                this.spawning.delete(run.dir);
+            }
+        };
+        const previous = run.agent.resumeSessionId;
+        let result = await spawn(previous);
+        if (result.kind === "refused" &&
+            previous &&
+            result.code === "open_failed") {
+            this.log(`${run.agent.name}: can't resume ${previous} (${result.reason}); starting a new session`);
+            result = await spawn(null);
+        }
+        if (result.kind === "refused") {
+            if (run.live)
+                await this.close(run);
+            else
+                await served.close().catch(() => { });
+            return result.reason;
+        }
+        run.crewId = result.agent.id;
+        return null;
+    }
+    children(parent) {
+        return [...parent.children.values()];
+    }
+    childOf(parent, ref) {
+        const child = parent.child(ref);
+        if (!child)
+            throw new Error(`没有叫「${ref}」的子 agent。你开过的：${this.children(parent)
+                .map((c) => c.agent.name)
+                .join("、") || "无"}`);
+        return child;
+    }
+    /** Where a tool call of the parent comes from: its current turn's conversation. */
+    currentConversation(parent) {
+        return parent.live?.owners[0]?.conversationId ?? null;
+    }
+    async spawnTool(parent, input) {
+        const context = this.context;
+        const client = this.client;
+        if (!context?.openTurn || !context.addAgent || !client || !this.tokens)
+            throw new Error("这个 host 不能开子 agent（Center 太旧）。");
+        const open = this.children(parent).filter((c) => c.agent.status !== "offline");
+        if (open.length >= maxChildren)
+            throw new Error(`已经开了 ${open.length} 个子 agent；先用 agent_close 关掉做完的。`);
+        const asked = input.writeScopes ?? [];
+        const denied = asked.filter((s) => !parent.scopes.includes(s));
+        if (denied.length)
+            throw new Error(`不能给子 agent ${denied.join(", ")}：你自己只有 ${parent.scopes.join(", ") || "只读"}。`);
+        const name = clip(input.name, 40);
+        const agent = await client.upsertAgent({
+            name,
+            role: clip(`「${parent.agent.name}」的子 agent：${input.task}`, 280),
+            hostId: context.hostId,
+            runtime: parent.runtimeId,
+            model: parent.model ?? null,
+            parentAgentId: parent.agent.id,
+            status: "idle",
+        });
+        const child = await this.prepare(agent, this.childSpec(parent, name), asked, parent);
+        context.addAgent(agent);
+        const from = this.currentConversation(parent);
+        const id = randomUUID();
+        this.opened.set(id, {
+            text: input.task,
+            origin: { kind: "notification", source: parent.agent.name },
+            cards: [],
+        });
+        const item = await context.openTurn({
+            id,
+            agentId: agent.id,
+            title: name,
+            text: input.task,
+            context: from
+                ? {
+                    kind: { type: "entity", uri: conversationUri(from) },
+                    label: `「${parent.agent.name}」交给的任务`,
+                    symbol: "person.2",
+                }
+                : null,
+        });
+        child.conversationId = item.conversation.id;
+        const owner = parent.live?.owners[0];
+        if (owner)
+            this.emit(owner, {
+                type: "card",
+                card: this.childCard(child, item.conversation.id, "开始了", input.task),
+            });
+        return JSON.stringify({
+            agent: name,
+            id: agent.id,
+            started: true,
+            note: "它在后台做；做完后报告会自动送回给你，或者用 agent_wait 等。",
+        });
+    }
+    async sendTool(parent, input) {
+        const child = this.childOf(parent, input.agent);
+        const context = this.context;
+        if (!context?.openTurn)
+            throw new Error("这个 host 不能给子 agent 发消息。");
+        const from = this.currentConversation(parent);
+        const id = randomUUID();
+        this.opened.set(id, {
+            text: input.message,
+            origin: { kind: "notification", source: parent.agent.name },
+            cards: [],
+        });
+        try {
+            await context.openTurn({
+                id,
+                agentId: child.agent.id,
+                ...(child.conversationId
+                    ? { conversationId: child.conversationId }
+                    : {}),
+                title: child.agent.name,
+                text: input.message,
+                context: from
+                    ? {
+                        kind: { type: "entity", uri: conversationUri(from) },
+                        label: `「${parent.agent.name}」发来的消息`,
+                        symbol: "person.2",
+                    }
+                    : null,
+            });
+        }
+        catch (error) {
+            this.opened.delete(id);
+            if (error instanceof CoreError && error.status === 409)
+                throw new Error(`「${child.agent.name}」正在忙（在做上一件事或在和用户聊）；先 agent_wait 等它报告再发。`);
+            throw error;
+        }
+        return JSON.stringify({ agent: child.agent.name, sent: true });
+    }
+    async waitTool(parent, input, signal) {
+        const ids = input.agents
+            ? new Set(input.agents.map((ref) => this.childOf(parent, ref).agent.id))
+            : null;
+        const wanted = (d) => !ids || ids.has(d.child.agent.id);
+        let got = parent.inbox.filter(wanted);
+        parent.inbox = parent.inbox.filter((d) => !wanted(d));
+        if (!got.length && input.timeoutSeconds > 0) {
+            const delivery = await new Promise((resolve) => {
+                const waiter = {
+                    ids,
+                    resolve: (d) => done(d),
+                };
+                const timer = setTimeout(() => done(null), input.timeoutSeconds * 1000);
+                const onAbort = () => done(null);
+                function done(d) {
+                    clearTimeout(timer);
+                    parent.waiters.delete(waiter);
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(d);
+                }
+                parent.waiters.add(waiter);
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+            if (delivery)
+                got = [delivery];
+        }
+        const owner = parent.live?.owners[0];
+        for (const d of got)
+            if (owner)
+                this.emit(owner, {
+                    type: "card",
+                    card: this.reportCard(d),
+                });
+        const busy = this.children(parent)
+            .filter((c) => (!ids || ids.has(c.agent.id)) && c.busy > 0)
+            .map((c) => c.agent.name);
+        return JSON.stringify({
+            reports: got.map((d) => ({
+                agent: d.child.agent.name,
+                outcome: d.report.outcome.kind,
+                ...(d.report.outcome.kind === "failed"
+                    ? { reason: d.report.outcome.reason }
+                    : {}),
+                text: d.report.text,
+            })),
+            ...(busy.length ? { stillWorking: busy } : {}),
+        });
+    }
+    async closeTool(parent, input) {
+        const child = this.childOf(parent, input.agent);
+        await this.close(child);
+        parent.inbox = parent.inbox.filter((d) => d.child !== child);
+        if (this.client)
+            child.agent = await this.client
+                .upsertAgent({ id: child.agent.id, status: "offline" })
+                .catch(() => child.agent);
+        return JSON.stringify({ agent: child.agent.name, closed: true });
+    }
+    childCard(child, conversationId, verb, summary) {
+        return {
+            type: "record",
+            record: {
+                uri: conversationUri(conversationId),
+                preview: {
+                    title: `子 agent「${child.agent.name}」${verb}`,
+                    summary: clip(summary.trim(), 160) || null,
+                    symbol: "person.2",
+                },
+            },
+        };
+    }
+    reportCard(d) {
+        const outcome = d.report.outcome;
+        return this.childCard(d.child, d.conversationId, outcome.kind === "completed"
+            ? "完成了"
+            : outcome.kind === "aborted"
+                ? "停下了"
+                : "没做完", outcome.kind === "failed" && !d.report.text
+            ? outcome.reason
+            : d.report.text);
+    }
+    /** A child ended a turn: back to the parent, if the parent started it. */
+    onReport(report) {
+        const child = [...this.runs.values()].find((r) => r.crewId === report.id);
+        const owner = child?.lastEnded;
+        if (!child?.parent || !owner)
+            return;
+        child.lastEnded = null;
+        if (!owner.fromParent || report.outcome.kind === "aborted")
+            return;
+        const parent = child.parent;
+        const delivery = {
+            child,
+            report,
+            conversationId: owner.conversationId,
+            parentConversationId: owner.fromParent,
+        };
+        const waiter = [...parent.waiters].find((w) => !w.ids || w.ids.has(child.agent.id));
+        if (waiter) {
+            waiter.resolve(delivery);
+            return;
+        }
+        parent.inbox.push(delivery);
+        this.flushInbox(parent);
+    }
+    /** An idle parent gets its undelivered reports as a turn in the conversation they belong to. */
+    flushInbox(parent) {
+        if (!parent.inbox.length || parent.busy || parent.live?.owners.length)
+            return;
+        const context = this.context;
+        if (!context?.openTurn)
+            return;
+        const first = parent.inbox[0];
+        const batch = parent.inbox.filter((d) => d.parentConversationId === first.parentConversationId);
+        parent.inbox = parent.inbox.filter((d) => !batch.includes(d));
+        const id = randomUUID();
+        const names = [...new Set(batch.map((d) => d.child.agent.name))];
+        const stored = clip(batch
+            .map((d) => `子 agent「${d.child.agent.name}」的报告：\n${d.report.text || (d.report.outcome.kind === "failed" ? d.report.outcome.reason : "（没有文字）")}`)
+            .join("\n\n"), 19_000);
+        const instruction = "（这是你开的子 agent 交回的报告，不是用户说的话。用一两句话告诉用户结果；需要的话再整理或继续安排。）";
+        this.opened.set(id, {
+            text: `${stored}\n\n${instruction}`,
+            origin: {
+                kind: "notification",
+                source: `子 agent ${names.join("、")}`,
+            },
+            cards: batch.map((d) => this.reportCard(d)),
+        });
+        context
+            .openTurn({
+            id,
+            agentId: parent.agent.id,
+            ...(first.parentConversationId
+                ? { conversationId: first.parentConversationId }
+                : {}),
+            text: stored,
+            context: {
+                kind: { type: "entity", uri: conversationUri(first.conversationId) },
+                label: `子 agent「${names.join("、")}」的报告`,
+                symbol: "person.2",
+            },
+            // Not the owner's words: the app shows no bubble for it (the reply's card carries it).
+            origin: "notification",
+        })
+            .catch((error) => {
+            this.opened.delete(id);
+            // Busy (a user's turn got there first): after that turn.
+            if (error instanceof CoreError && error.status === 409)
+                parent.inbox.unshift(...batch);
+            else
+                this.log(`${parent.agent.name}: delivering a report failed (${error.message})`);
+        });
+    }
+    scheduleIdle(run) {
+        if (run.idle)
+            clearTimeout(run.idle);
+        run.idle = setTimeout(() => {
+            if (run.live && !run.live.owners.length) {
+                this.log(`${run.agent.name}: idle; closing the session`);
+                this.close(run);
+            }
+        }, this.config.idleMinutes * 60_000);
+        run.idle.unref?.();
+    }
+    async close(run) {
+        if (run.idle)
+            clearTimeout(run.idle);
+        run.idle = null;
+        const live = run.live;
+        if (!live)
+            return;
+        run.live = null;
+        run.direct = new Set();
+        run.inlined = new Set();
+        run.memorySeen = null;
+        for (const owner of [...live.owners])
+            this.finish(live.owners, owner, null);
+        live.unsubscribe();
+        const crewId = run.crewId;
+        run.crewId = null;
+        const child = crewId
+            ? (await this.crew?.catch(() => null))?.get(crewId)
+            : null;
+        if (child)
+            await child.close().catch(() => { });
+        else
+            await live.session.dispose().catch(() => { });
+        await live.served.close().catch(() => { });
+        await new Promise((resolve) => live.records ? live.records.end(resolve) : resolve());
+    }
+    /** Owner stopped (or host shutdown): abort its oar turn or withdraw its queued input. */
+    abortOwner(run, live, owner) {
+        if (owner.finished)
+            return;
+        const current = live.owners[0] === owner;
+        this.finish(live.owners, owner, null);
+        if (current) {
+            live.draining = true;
+            live.session.abort().catch((error) => {
+                live.draining = false;
+                this.log(`${run.agent.name}: abort failed (${error.message})`);
+            });
+        }
+        else
+            live.session.withdraw?.(owner.turnId).catch(() => { });
+    }
+    /**
+     * Emit in order behind the owner's chain: a write's record cards are looked up
+     * asynchronously and must land before the text that follows the tool.
+     */
+    emit(owner, event) {
+        owner.chain = owner.chain.then(() => owner.sink.emit(event));
+    }
+    /** End a core turn: emit its terminal event (after pending cards), drop it. */
+    finish(owners, owner, terminal) {
+        if (owner.finished)
+            return;
+        owner.finished = true;
+        const index = owners.indexOf(owner);
+        if (index >= 0)
+            owners.splice(index, 1);
+        owner.chain.then(() => {
+            if (terminal)
+                owner.sink.emit(terminal);
+            owner.resolve();
+        });
+    }
+    announce(owner, id, call) {
+        const bare = bareToolName(call.raw);
+        const input = parse(call.input);
+        let event;
+        if (bare === "tool_call" && typeof input?.name === "string") {
+            call.inner = input.name;
+            const inner = input.input;
+            event = {
+                type: "toolStarted",
+                id,
+                name: input.name,
+                title: coreToolTitle(input.name),
+                detail: inputDetail(inner),
+                input: inner ?? {},
+            };
+        }
+        else {
+            if (bare !== call.raw || bare.includes("_"))
+                call.inner = bare;
+            event = {
+                type: "toolStarted",
+                id,
+                name: bare,
+                title: bare === "tool_describe" && typeof input?.name === "string"
+                    ? `查看「${coreToolTitle(input.name)}」的参数`
+                    : toolTitle(call.raw, input),
+                detail: bare === "tool_describe" ? null : inputDetail(input ?? call.input),
+                input: input ?? (call.input ? { text: call.input } : {}),
+            };
+        }
+        call.announced = owner;
+        this.emit(owner, event);
+    }
+    onEvent(run, live, event) {
+        if (event.agentPath.length)
+            return; // the runtime's own sub-agents (Task is off)
+        if (event.kind === "exited") {
+            for (const owner of [...live.owners])
+                this.finish(live.owners, owner, {
+                    type: "failed",
+                    reason: `${run.runtimeId} 退出了${event.reason ? `：${event.reason}` : ""}`,
+                });
+            if (run.live === live)
+                this.close(run);
+            return;
+        }
+        // A child's report follows its turn_ended: whose turn it was.
+        if (event.kind === "turn_ended")
+            run.lastEnded = live.draining ? null : (live.owners[0] ?? null);
+        if (live.draining) {
+            if (event.kind === "turn_ended") {
+                live.draining = false;
+                live.calls.clear();
+            }
+            return;
+        }
+        const owner = live.owners[0];
+        if (!owner)
+            return;
+        switch (event.kind) {
+            case "text_delta":
+                if (event.text)
+                    this.emit(owner, { type: "textDelta", text: event.text });
+                return;
+            case "reasoning":
+                if (event.content.kind === "text" && event.content.text)
+                    this.emit(owner, { type: "thinking", text: event.content.text });
+                return;
+            case "tool_call_started": {
+                const call = {
+                    raw: event.tool,
+                    input: event.input,
+                    announced: null,
+                    inner: null,
+                };
+                live.calls.set(event.callId, call);
+                if (parse(event.input))
+                    this.announce(owner, event.callId, call);
+                return;
+            }
+            case "tool_call_input": {
+                const call = live.calls.get(event.callId);
+                if (!call)
+                    return;
+                call.input = event.input;
+                if (!call.announced)
+                    this.announce(owner, event.callId, call);
+                return;
+            }
+            case "tool_call_ended": {
+                const call = live.calls.get(event.callId) ?? {
+                    raw: "tool",
+                    input: undefined,
+                    announced: null,
+                    inner: null,
+                };
+                live.calls.delete(event.callId);
+                // Started under a turn that handed over: announce it again in this one.
+                if (call.announced !== owner)
+                    this.announce(owner, event.callId, call);
+                const text = (event.content ?? [])
+                    .map((part) => (part.type === "text" ? part.text : ""))
+                    .join("\n");
+                const failed = event.result === "failed";
+                this.emit(owner, {
+                    type: "toolEnded",
+                    id: event.callId,
+                    ...(failed ? { failed: true } : {}),
+                    resultSummary: text ? clip(text, 500) : null,
+                });
+                if (!failed && text.includes('"commandId"'))
+                    owner.chain = owner.chain
+                        .then(() => recordCards(run.tools.api, text))
+                        .then((cards) => {
+                        for (const card of cards)
+                            owner.sink.emit({ type: "card", card });
+                    })
+                        .catch((error) => this.log(`${run.agent.name}: record card lookup failed (${error.message})`));
+                return;
+            }
+            case "turn_ended": {
+                const outcome = event.outcome;
+                if (outcome.kind === "completed")
+                    this.finish(live.owners, owner, { type: "done" });
+                else if (outcome.kind === "aborted")
+                    this.finish(live.owners, owner, null);
+                else
+                    this.finish(live.owners, owner, {
+                        type: "failed",
+                        reason: outcome.reason || `${outcome.failure}`,
+                    });
+                live.calls.clear();
+                return;
+            }
+            case "control_rejected":
+                if (["prompt", "steer", "queue"].includes(event.action))
+                    this.finish(live.owners, owner, {
+                        type: "failed",
+                        reason: `${run.runtimeId}：${event.reason}`,
+                    });
+                return;
+        }
+    }
+}