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

package/dist/crew-tools.js

@@ -0,0 +1,115 @@
+export const crewToolNames = new Set([
+    "agent_spawn",
+    "agent_send",
+    "agent_wait",
+    "agent_close",
+]);
+const text = (value) => typeof value === "string" ? value.trim() : "";
+const failure = (message) => ({
+    content: [{ type: "text", text: message }],
+    isError: true,
+});
+export function crewServedTools(ops, options) {
+    const guard = (handler) => async (input, { signal }) => {
+        try {
+            return await handler(input, signal);
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    };
+    return [
+        {
+            name: "agent_spawn",
+            description: `开一个子 agent 在后台做一件独立的事（比如整理一段时间的日程、把一类备忘归纳成总结）。它有自己的会话（用户在 App 里能看到、能直接和它聊）、自己的记忆和自己的 Center 权限：默认只读，writeScopes 可以给它写权限（只能是你自己有的：${options.writeScopes.join(", ") || "无"}）。它做完后报告会自动送回给你；需要在这一轮里拿到结果就用 agent_wait。task 要写清楚：要做什么、范围、结果要什么格式。子 agent 不能再开子 agent。`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "简短的名字（用户会看到），如「下周日程总结」",
+                    },
+                    task: { type: "string", description: "交给它的任务，写完整" },
+                    writeScopes: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: '给它的写权限，如 ["memo:write"]；省略为只读',
+                    },
+                },
+                required: ["name", "task"],
+            },
+            handler: guard((input, signal) => {
+                const name = text(input.name);
+                const task = text(input.task);
+                if (!name || !task)
+                    throw new Error("name 和 task 都要写。");
+                return ops.spawn({
+                    name,
+                    task,
+                    writeScopes: Array.isArray(input.writeScopes)
+                        ? input.writeScopes.map(String)
+                        : null,
+                }, signal);
+            }),
+        },
+        {
+            name: "agent_send",
+            description: "给你开的一个子 agent 再发一条消息（补充要求、追问）。它正忙时会被拒绝：先 agent_wait 等它报告。",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent: { type: "string", description: "子 agent 的名字或 id" },
+                    message: { type: "string" },
+                },
+                required: ["agent", "message"],
+            },
+            handler: guard((input, signal) => {
+                const agent = text(input.agent);
+                const message = text(input.message);
+                if (!agent || !message)
+                    throw new Error("agent 和 message 都要写。");
+                return ops.send({ agent, message }, signal);
+            }),
+        },
+        {
+            name: "agent_wait",
+            description: "等子 agent 的报告（默认等任何一个，最多 timeoutSeconds 秒，默认 120）。返回已经到的报告；没等到就说明谁还在做。不等的话报告做完也会自动送回给你。",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agents: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "只等这些子 agent（名字或 id）；省略为任何一个",
+                    },
+                    timeoutSeconds: { type: "number", description: "最多等多久，≤ 600" },
+                },
+            },
+            handler: guard((input, signal) => ops.wait({
+                agents: Array.isArray(input.agents)
+                    ? input.agents.map(String)
+                    : null,
+                timeoutSeconds: Math.min(600, Math.max(0, typeof input.timeoutSeconds === "number"
+                    ? input.timeoutSeconds
+                    : 120)),
+            }, signal)),
+        },
+        {
+            name: "agent_close",
+            description: "结束一个子 agent（它的会话和记录会保留，用户还能翻看；再给它发消息会重新打开）。",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent: { type: "string", description: "子 agent 的名字或 id" },
+                },
+                required: ["agent"],
+            },
+            handler: guard((input, signal) => {
+                const agent = text(input.agent);
+                if (!agent)
+                    throw new Error("agent 要写。");
+                return ops.close({ agent }, signal);
+            }),
+        },
+    ];
+}

package/dist/driver.js

@@ -0,0 +1,87 @@
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted || ms <= 0)
+        return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", done);
+        resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+});
+const clip = (text, max) => {
+    const chars = Array.from(text);
+    return chars.length > max ? `${chars.slice(0, max).join("")}…` : text;
+};
+/**
+ * Plays a fixed script that echoes the user's message: a thought, one tool call, the text
+ * in small deltas, a record card pointing at the user's own message, done. Deterministic,
+ * so a resumed turn continues exactly where Center left off.
+ */
+export class EchoDriver {
+    name = "echo";
+    stepMs;
+    chunk;
+    constructor(options = {}) {
+        this.stepMs = options.stepMs ?? 60;
+        this.chunk = options.chunkChars ?? 6;
+    }
+    script(input) {
+        const text = input.message.text;
+        const chars = Array.from(text);
+        const callId = `echo-${input.turn.id}`;
+        const reply = `你说：${text}`;
+        const replyChars = Array.from(reply);
+        const deltas = [];
+        for (let i = 0; i < replyChars.length; i += this.chunk)
+            deltas.push({
+                type: "textDelta",
+                text: replyChars.slice(i, i + this.chunk).join(""),
+            });
+        return [
+            {
+                type: "thinking",
+                text: `收到「${clip(text, 40)}」。我是回声 agent，把它原样说回去。`,
+            },
+            {
+                type: "toolStarted",
+                id: callId,
+                name: "echo",
+                title: "复述消息",
+                detail: `${chars.length} 个字`,
+                input: { text },
+            },
+            {
+                type: "toolEnded",
+                id: callId,
+                resultSummary: `复述了 ${chars.length} 个字`,
+            },
+            ...deltas,
+            {
+                type: "card",
+                card: {
+                    type: "record",
+                    record: {
+                        uri: `agent:message/${input.message.id}`,
+                        preview: {
+                            title: clip(text, 80),
+                            summary: "你刚发的消息",
+                            symbol: "text.bubble",
+                            date: input.message.at,
+                        },
+                    },
+                },
+            },
+            { type: "done" },
+        ];
+    }
+    async run(input, sink, signal) {
+        const events = this.script(input);
+        for (const event of events.slice(input.appended)) {
+            await sleep(this.stepMs, signal);
+            if (signal.aborted)
+                return;
+            sink.emit(event);
+        }
+    }
+}

package/dist/host.js

@@ -0,0 +1,435 @@
+/**
+ * The host loop: register → listen on `events?hostId=` → claim → run each turn through a
+ * Driver, appending its events in ~100 ms batches. Reconnects with backoff when the
+ * stream drops (or goes silent past the heartbeat), re-claims on every (re)connect and on
+ * a slow poll, and resumes turns it was running before a restart. Says host.heartbeat
+ * every 20 s so Center keeps its agents online. A driver may add agents (sub-agents) and
+ * open turns itself (turn.open): they run through the same loop.
+ */
+import { CoreError } from "./core-client.js";
+const maxBatch = 500;
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+});
+const jitter = (ms) => Math.round(ms * (0.8 + Math.random() * 0.4));
+/** A rejection that retrying cannot fix: the turn was stopped, taken or removed. */
+const final = (error) => error instanceof CoreError && [403, 404, 409].includes(error.status);
+/** Collects one turn's events and appends them in order, one request at a time. */
+class Batcher {
+    queue = [];
+    timer = null;
+    chain = Promise.resolve();
+    seq;
+    rejected = null;
+    /** A batch was given up on; later ones must not land out of order. */
+    abandoned = false;
+    host;
+    turnId;
+    active;
+    constructor(host, turnId, appended, active) {
+        this.host = host;
+        this.turnId = turnId;
+        this.active = active;
+        this.seq = appended + 1;
+    }
+    push(event) {
+        this.queue.push(event);
+        if (event.type === "done" || event.type === "failed")
+            this.flush();
+        else
+            this.timer ??= setTimeout(() => {
+                this.flush();
+            }, this.host.batchMs);
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        while (this.queue.length) {
+            const batch = this.queue.splice(0, maxBatch);
+            const seq = this.seq;
+            this.seq += batch.length;
+            this.chain = this.chain.then(() => this.send(batch, seq));
+        }
+        return this.chain;
+    }
+    async send(batch, seq) {
+        let delay = this.host.backoffInitial;
+        for (;;) {
+            if (this.rejected || this.abandoned || this.active.stop.signal.aborted)
+                return;
+            try {
+                await this.host.client.append(this.turnId, batch, seq);
+                return;
+            }
+            catch (error) {
+                if (final(error)) {
+                    this.rejected = error;
+                    this.host.log(`turn ${this.turnId}: append rejected (${error.message}); stopping it`);
+                    this.active.stop.abort();
+                    return;
+                }
+                // Network or server error: retry the same batch at the same seq (idempotent).
+                // When shutting down, give up: a resume replays from Center's event count.
+                if (this.host.signal.aborted) {
+                    this.abandoned = true;
+                    return;
+                }
+                this.host.log(`turn ${this.turnId}: append failed (${error.message}); retrying`);
+                await sleep(jitter(delay));
+                delay = Math.min(this.host.backoffMax, delay * 2);
+            }
+        }
+    }
+    async close() {
+        if (this.active.stop.signal.aborted) {
+            if (this.timer)
+                clearTimeout(this.timer);
+            this.queue = [];
+        }
+        else
+            this.flush();
+        await this.chain;
+    }
+}
+export class AgentHost {
+    client;
+    driver;
+    batchMs;
+    backoffInitial;
+    backoffMax;
+    log;
+    hostId = null;
+    agents = [];
+    /** SSE connections opened so far. */
+    connections = 0;
+    options;
+    lifetime = new AbortController();
+    active = new Map();
+    /** Turns this process already finished, so a racing claim response never reruns one. */
+    ended = new Set();
+    claiming = null;
+    claimAgain = false;
+    loops = [];
+    constructor(options) {
+        this.options = options;
+        this.client = options.client;
+        this.driver = options.driver;
+        this.batchMs = options.batchMs ?? 100;
+        this.backoffInitial = options.backoff?.initialMs ?? 500;
+        this.backoffMax = options.backoff?.maxMs ?? 30_000;
+        this.log =
+            options.log ??
+                ((message) => console.error(`${new Date().toISOString()} agent-host: ${message}`));
+    }
+    get signal() {
+        return this.lifetime.signal;
+    }
+    /** Turns being answered now. */
+    get running() {
+        return [...this.active.keys()];
+    }
+    /** Register (retrying until Center answers), then run the loops in the background. */
+    async start() {
+        let delay = this.backoffInitial;
+        for (;;) {
+            try {
+                const registered = await this.client.register(this.options.name);
+                this.hostId = registered.hostId;
+                this.agents = registered.agents.filter((a) => a.hostId === registered.hostId);
+                break;
+            }
+            catch (error) {
+                if (error instanceof CoreError && [401, 403].includes(error.status))
+                    throw error;
+                this.log(`register failed (${error.message}); retrying`);
+                await sleep(jitter(delay), this.signal);
+                if (this.signal.aborted)
+                    return;
+                delay = Math.min(this.backoffMax, delay * 2);
+            }
+        }
+        const registered = this.agents;
+        if (this.options.agents?.length) {
+            this.agents = await this.ensureAgents();
+            // Sub-agents of these agents (made by the driver, not host.json) stay this host's.
+            const ids = new Set(this.agents.map((a) => a.id));
+            for (const a of registered)
+                if (a.parentAgentId && ids.has(a.parentAgentId) && !ids.has(a.id))
+                    this.agents.push(a);
+        }
+        else if (!this.agents.length)
+            this.agents = [
+                await this.client.upsertAgent({
+                    name: this.options.agentName ?? "回声",
+                    role: "把你说的话原样说回来（echo host）",
+                    hostId: this.hostId,
+                    runtime: this.driver.name,
+                    status: "idle",
+                }),
+            ];
+        await this.driver.start?.({
+            client: this.client,
+            hostId: this.hostId,
+            agents: this.agents,
+            log: this.log,
+            addAgent: (agent) => this.addAgent(agent),
+            openTurn: (input) => this.openTurn(input),
+        });
+        this.log(`registered as ${this.hostId}; agents: ${this.agents.map((a) => a.name).join(", ")}`);
+        this.loops = [this.listen(), this.poll(), this.beat()];
+        // Resume what this host was running before a restart, and pick up queued turns.
+        this.claimSoon();
+    }
+    /** Stop listening; running turns flush what they have and stay running for a resume. */
+    async stop() {
+        if (this.lifetime.signal.aborted)
+            return;
+        this.lifetime.abort();
+        for (const turn of this.active.values())
+            turn.shutdown = true;
+        await Promise.allSettled([
+            ...this.loops,
+            ...[...this.active.values()].map((t) => t.settled),
+            this.claiming,
+        ]);
+        await this.driver.stop?.().catch((error) => {
+            this.log(`driver stop failed (${error.message})`);
+        });
+        await Promise.allSettled(this.agents.map((a) => this.client.upsertAgent({ id: a.id, status: "offline" })));
+    }
+    /** Match host.json agents to the registered ones; create or update the rest. */
+    async ensureAgents() {
+        const result = [];
+        for (const spec of this.options.agents ?? []) {
+            const found = this.agents.find((a) => spec.id && a.id === spec.id) ??
+                this.agents.find((a) => !spec.id && a.name === spec.name);
+            const wanted = {
+                name: spec.name,
+                ...(spec.role !== undefined ? { role: spec.role } : {}),
+                runtime: spec.runtime ?? this.driver.name,
+                ...(spec.model !== undefined ? { model: spec.model } : {}),
+            };
+            const stale = !found ||
+                found.name !== wanted.name ||
+                found.runtime !== wanted.runtime ||
+                (wanted.role !== undefined && found.role !== wanted.role) ||
+                (wanted.model !== undefined && found.model !== wanted.model);
+            result.push(stale
+                ? await this.client.upsertAgent({
+                    ...(found ? { id: found.id } : spec.id ? { id: spec.id } : {}),
+                    ...wanted,
+                    hostId: this.hostId,
+                    ...(found ? {} : { status: "idle" }),
+                })
+                : found);
+        }
+        return result;
+    }
+    async listen() {
+        const hostId = this.hostId;
+        const staleMs = this.options.staleMs ?? 45_000;
+        let delay = this.backoffInitial;
+        while (!this.signal.aborted) {
+            const connection = new AbortController();
+            const abort = () => connection.abort();
+            this.signal.addEventListener("abort", abort, { once: true });
+            let watchdog = setTimeout(abort, staleMs);
+            try {
+                this.connections++;
+                for await (const frame of this.client.events(hostId, connection.signal)) {
+                    clearTimeout(watchdog);
+                    watchdog = setTimeout(() => {
+                        this.log("events stream went silent; reconnecting");
+                        abort();
+                    }, staleMs);
+                    if (frame.type === "ready") {
+                        delay = this.backoffInitial;
+                        // Anything queued while we were away.
+                        this.claimSoon();
+                    }
+                    else if (frame.type === "turn")
+                        this.onTurn(frame.turn);
+                }
+                if (!this.signal.aborted)
+                    this.log("events stream ended; reconnecting");
+            }
+            catch (error) {
+                if (this.signal.aborted)
+                    break;
+                if (!connection.signal.aborted)
+                    this.log(`events stream failed (${error.message}); reconnecting`);
+            }
+            finally {
+                clearTimeout(watchdog);
+                this.signal.removeEventListener("abort", abort);
+                connection.abort();
+            }
+            await sleep(jitter(delay), this.signal);
+            delay = Math.min(this.backoffMax, delay * 2);
+        }
+    }
+    async poll() {
+        const every = this.options.pollMs ?? 30_000;
+        while (!this.signal.aborted) {
+            await sleep(every, this.signal);
+            if (!this.signal.aborted)
+                this.claimSoon();
+        }
+    }
+    async beat() {
+        if (!this.client.heartbeat)
+            return;
+        const every = this.options.heartbeatMs ?? 20_000;
+        let failing = false;
+        while (!this.signal.aborted) {
+            await sleep(every, this.signal);
+            if (this.signal.aborted)
+                return;
+            try {
+                const { online } = await this.client.heartbeat();
+                if (online)
+                    this.log(`heartbeat: ${online} agent(s) back online`);
+                failing = false;
+            }
+            catch (error) {
+                // An older Center has no heartbeat: say so once, keep the loop (it may update).
+                if (!failing)
+                    this.log(`heartbeat failed (${error.message})`);
+                failing = true;
+            }
+        }
+    }
+    /** Run (and claim turns of) one more agent, e.g. a sub-agent the driver created. */
+    addAgent(agent) {
+        const index = this.agents.findIndex((a) => a.id === agent.id);
+        if (index >= 0)
+            this.agents[index] = agent;
+        else
+            this.agents.push(agent);
+    }
+    /**
+     * Start a turn this host originates (turn.open) and answer it like a claimed one.
+     * Resolves once Center stored it; the answer runs in the background.
+     */
+    async openTurn(input) {
+        if (!this.client.openTurn)
+            throw new Error("this Center client cannot open turns");
+        const item = await this.client.openTurn(input);
+        if (!this.signal.aborted &&
+            !this.active.has(item.turn.id) &&
+            !this.ended.has(item.turn.id))
+            this.runTurn(item);
+        return item;
+    }
+    onTurn(turn) {
+        if (turn.state === "queued")
+            this.claimSoon();
+        else if (turn.state !== "running") {
+            const active = this.active.get(turn.id);
+            if (active && !active.stop.signal.aborted) {
+                this.log(`turn ${turn.id} ${turn.state}; aborting`);
+                active.stop.abort();
+            }
+        }
+    }
+    /** Claim now; calls while a claim is in flight fold into one more round. */
+    claimSoon() {
+        if (this.signal.aborted)
+            return;
+        if (this.claiming) {
+            this.claimAgain = true;
+            return;
+        }
+        this.claiming = (async () => {
+            do {
+                this.claimAgain = false;
+                try {
+                    await this.claimOnce();
+                }
+                catch (error) {
+                    this.log(`claim failed (${error.message})`);
+                }
+            } while (this.claimAgain && !this.signal.aborted);
+        })().finally(() => {
+            this.claiming = null;
+        });
+    }
+    async claimOnce() {
+        const items = await this.client.claim({
+            limit: this.options.claimLimit ?? 4,
+            resume: true,
+            agentIds: this.agents.map((a) => a.id),
+        });
+        for (const item of items)
+            if (!this.active.has(item.turn.id) && !this.ended.has(item.turn.id))
+                this.runTurn(item);
+    }
+    runTurn(item) {
+        const turnId = item.turn.id;
+        const appended = item.turn.eventCount;
+        const active = {
+            stop: new AbortController(),
+            shutdown: false,
+            settled: Promise.resolve(),
+        };
+        this.active.set(turnId, active);
+        this.log(appended
+            ? `turn ${turnId}: resuming after ${appended} events`
+            : `turn ${turnId}: answering`);
+        const batcher = new Batcher(this, turnId, appended, active);
+        // The driver sees one signal: owner stop or host shutdown.
+        const signal = AbortSignal.any([active.stop.signal, this.signal]);
+        let terminal = false;
+        const sink = {
+            emit: (event) => {
+                if (terminal || active.stop.signal.aborted)
+                    return;
+                if (event.type === "done" || event.type === "failed")
+                    terminal = true;
+                batcher.push(event);
+            },
+            flushed: () => batcher.flush(),
+        };
+        active.settled = (async () => {
+            try {
+                await this.driver.run({ ...item, appended }, sink, signal);
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    sink.emit({
+                        type: "failed",
+                        reason: error.message || "The driver failed",
+                    });
+            }
+            await batcher.close();
+            if (!terminal &&
+                !batcher.rejected &&
+                !active.stop.signal.aborted &&
+                !this.signal.aborted)
+                await this.client.finish(turnId, "done").catch((error) => {
+                    this.log(`turn ${turnId}: finish failed (${error.message})`);
+                });
+        })()
+            .catch((error) => this.log(`turn ${turnId}: ${error.message}`))
+            .finally(() => {
+            this.active.delete(turnId);
+            if (!active.shutdown) {
+                this.ended.add(turnId);
+                if (this.ended.size > 1000)
+                    this.ended.delete(this.ended.values().next().value);
+                this.log(`turn ${turnId}: ${active.stop.signal.aborted ? "stopped" : "finished"}`);
+                // The agent is free again: its next queued turn (no push announces that).
+                this.claimSoon();
+            }
+        });
+    }
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { CenterApi, CenterTools, deniedReason, recordCards, } from "./center-tools.js";
+export { loadHostConfig, parseHostConfig, } from "./config.js";
+export { CoreError, HttpCoreClient, parseSse, } from "./core-client.js";
+export { configPath, loadCredentials, saveCredentials, TokenSource, } from "./credentials.js";
+export { EchoDriver, } from "./driver.js";
+export { AgentHost } from "./host.js";
+export { deviceLogin, normalizeServer } from "./login.js";
+export { MemorySync } from "./memory.js";
+export { OarDriver } from "./oar-driver.js";
+export { bareToolName, coreToolTitle, toolTitle } from "./tool-titles.js";