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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RieN7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,336 @@
-# Temporary Holding Version
+# agent-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The process that runs agents for Agent Center. It connects out to Center with its own
+credential, claims queued turns, answers them through a **driver** and streams the reply
+back as `AgentChatTurnEvent`s.
+
+- **OarDriver** runs a real agent through [oar](https://github.com/botiverse/oar)
+  (`@botiverse/oar`, pinned to an exact version): **Claude Code** by default, **pi**
+  (bundled, in-process, any OpenAI/Anthropic-compatible provider) per agent.
+- **EchoDriver** plays a fixed script (`runtime: "echo"`), for testing the wire.
+- **Target: Node 24.** Published to npm as
+  [`@rien7/agent-center-host`](https://www.npmjs.com/package/@rien7/agent-center-host): compiled ESM
+  in `dist/` (`tsc -p tsconfig.build.json`), Node >= 24 (oar's own engine). In this repo
+  the sources are plain TypeScript that Bun and Node 24 run directly (type stripping, so
+  only erasable syntax and `.ts` imports; the build rewrites them to `.js`).
+- Server side: `domains/agent` (ops `agent.host.register`, `host.heartbeat`,
+  `turn.claim`, `turn.open`, `event.append`, `turn.finish`, `agent.upsert`,
+  `agent.issue_token`, `memory_file.*`; SSE `GET /v1/agent/events?hostId=`).
+
+## On a Mac (three steps)
+
+You need Node 24 or later, and Claude Code installed and logged in (`claude`, then
+`/login`; check with `claude auth status`).
+
+```sh
+# 1. Log in: prints a pairing code; approve it in the Agent Center app.
+npx @rien7/agent-center-host login --server https://agent-center.rien7.com
+
+# 2. Check: Center login, Claude Code found and logged in, workdir writable.
+npx @rien7/agent-center-host doctor
+
+# 3. Run (keep it open; Ctrl-C stops it, the agents show offline in the app).
+npx @rien7/agent-center-host run --name mac
+```
+
+Or install it once (`npm i -g @rien7/agent-center-host`) and run `agent-center-host …` (also
+installed as `agent-host`). From a checkout of this repo (after `bun install`), use
+`bun packages/agent-host/src/cli.ts …` instead.
+
+That's all: without a `host.json` agent list the host runs one agent, 「助手」, on Claude
+Code, and gets its Center token from Center by itself (read everything, write memos,
+reminders and calendar). The agent appears in the app's agent menu with a green dot while
+the host runs. Its memory is in `~/.agent-center/work/agents/<id>/memory/`.
+
+What `doctor` prints when all is well:
+
+```
+✓ login: https://agent-center.example as agent-host mac (agent:host)
+✓ runtime claude: /opt/homebrew/bin/claude 2.1.x
+✓ claude login: you@example.com, max, …
+✓ workdir: /Users/you/.agent-center/work
+· agent 助手: claude, token issued by Center (/Users/you/.agent-center/agent-tokens.json)
+· sub-agents: on
+```
+
+When Claude Code isn't found, install it (`npm i -g @anthropic-ai/claude-code`) or point
+`OAR_CLAUDE_BIN` at it; when it is logged out, run `claude` and `/login`. Logs go to
+stderr: each turn (`answering`, `finished`), each session (`opened claude session …
+(records …)`), the token (`助手: got its own Center token`).
+
+## Use
+
+```sh
+# 1. Log in (RFC 8628 device flow, scope agent:host). Approve the request in the app
+#    (or via core.oauth_request.approve) with the pairing code it prints.
+node packages/agent-host/bin/agent-host.js login --server https://agent-center.example
+#    → ~/.agent-center/host.json (0600; AGENT_CENTER_HOST_CONFIG overrides the path)
+
+# 2. Optional: agents in host.json, next to the login (see "host.json" below). Without
+#    any the host runs one agent, 助手. Each agent's token comes from Center
+#    (agent.issue_token) unless host.json gives one made by hand:
+#    bun run cli principal:create --name 助手 --kind agent \
+#      --scopes '*:read,agent:read,memo:write,reminder:write,calendar:write'
+
+# 3. Run. Agents in host.json are matched by id or name, created when missing.
+node packages/agent-host/bin/agent-host.js run --name mac-studio
+#    --runtime echo: the echo driver (creates an agent 回声 when there are no agents)
+```
+
+With Bun, replace `node` with `bun`; from npm, use `npx @rien7/agent-center-host` instead. Instead of logging in you can pass a static token,
+for example a service principal from `bun run cli principal:create --name mac-studio
+--kind service --scopes agent:host`:
+
+```sh
+AGENT_CENTER_TOKEN=ac_… node packages/agent-host/bin/agent-host.js run --name mac-studio --server http://127.0.0.1:8800
+```
+
+Then send a message as in `domains/agent/README.md` (`agent.turn.start`) or from the app.
+With the echo driver the reply is a thought, one `echo` tool call, your text streamed
+back as 「你说：…」, and a record card pointing at your own message.
+
+## host.json
+
+```jsonc
+{
+  "server": "https://…", "accessToken": "ac_…",   // the host's login (agent-host login)
+  "runtime": "claude",          // default runtime: claude | pi | … | echo
+  "model": "sonnet",            // default model; pi: "provider/model" from models.json
+  "workdir": "~/.agent-center/work",
+  "timeZone": "Asia/Shanghai",  // 「今天」 and the [时间] line; default: the machine's
+  "idleMinutes": 15,            // close an idle agent's oar session (resumed later)
+  "contextTools": "inline",     // default; or "direct", see Tools
+  "piAgentDir": "~/.agent-center/pi",   // pi's models.json / auth.json (OAR_PI_AGENT_DIR)
+  "subagents": true,            // main agents get agent_spawn / send / wait / close
+  "agents": [                   // default: [{ "name": "助手" }]
+    { "name": "助手", "role": "…", "runtime": "pi", "model": "airrouter/…",
+      "scopes": ["memo:write", "reminder:write"],  // write scopes of its issued token
+      "token": "ac_…" }         // optional, made by hand; or "tokenEnv": "AGENT_TOKEN_ASSISTANT"
+  ]
+}
+```
+
+On start the host checks every agent token with `core.principal.me` and refuses one
+that carries `*`, `agent:host`, `agent:*`, `core:*` or `core:admin`.
+
+**Models.** Claude Code uses its own login (`claude auth login`, or
+`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`). pi needs a provider: an env key
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) or a `models.json` provider in `piAgentDir`,
+e.g. an OpenAI-compatible gateway:
+
+```json
+{"providers":{"airrouter":{"baseUrl":"https://…/v1","api":"openai-completions","apiKey":"$AIRROUTER_KEY","models":[{"id":"…"}]}}}
+```
+
+For development without any key, `test/fixtures/mock-openai.ts` is a scripted
+OpenAI-compatible server (`bun packages/agent-host/test/fixtures/mock-openai.ts 18999`
+prints the `models.json` to use; model `mock/mock-1`).
+
+## Tools
+
+Core's `/mcp` has ~100 tools (~130 KB of schemas), too many to put in front of a model on
+every request. The host serves its own small MCP server per agent instead
+(oar `serveMcpTools`: loopback HTTP with a random bearer, attached to the session; chosen
+over stdio because the handlers run in the host, which holds the agent token, and both
+pi and Claude Code take HTTP MCP servers). The model sees:
+
+| tool | what |
+|---|---|
+| `tools_search({query?, domain?})` | tool names + one line each; `domain` lists a whole domain, `query` searches (中文 or English) |
+| `tool_describe({name})` | one tool's description and input schema |
+| `tool_call({name, input})` | run it: proxied to core `/mcp` with the agent's token |
+| `today_overview({date?})` | a day's events, reminders (plus overdue ones today) and visits |
+| `agent_search_query` | full-text search over past conversations (core's own tool) |
+
+plus the runtime's file tools for memory (pi `read/edit/write`; Claude Code
+`Read/Edit/Write/…`; shell, web and sub-agent tools are disallowed).
+
+- **Domain catalog.** The system prompt lists every domain the token can read, one line
+  each, built from `core.domain.list` and the tool list: `reminder 提醒：待办和提醒 —
+  item_list, item_create, …` (~400 tokens; long domains like ledger shrink to a count and
+  their common tools).
+- **The context's domains.** When a message carries a `context` (the 今天 page →
+  reminder, calendar, location; a record → its domain), each of those domains' list/get
+  and its one common write (`reminder_item_create`, `calendar_event_create`,
+  `memo_note_create`) are expanded once per session; the domain's other tools are named
+  and stay a `tool_describe` away. By default (`contextTools: "inline"`) their parameters
+  are inlined in that turn's prefix (今天: ~1.7k tokens, once). With `"direct"` they're
+  added as MCP tools with full schemas instead (~2.8k tokens on every request; pi takes
+  the tool-list change fully, Claude Code takes additions).
+- **Denylist.** Scopes are the real boundary; the host also keeps out sync/credential
+  plumbing (`core_sync_*`, `core_change_*`, `core_command_*`, …), `*_settings_update` and
+  every `agent_*` op but search and reads.
+- **Titles.** Steps are titled by the inner tool in Chinese (`tool-titles.ts`):
+  `tool_call(reminder_item_create)` shows as 「新建提醒」 with the input's title as detail.
+- **Record cards.** A write's result carries its `commandId`; the host reads
+  `core.command.get` + `core.entity.get` (agent token) and appends a `record` card per
+  changed entity (at most 3).
+
+## Memory and records
+
+- `<workdir>/agents/<agentId>/` is the session's cwd. `memory/MEMORY.md` (index) and
+  `memory/notes/*.md` are mirrored with Center (`agent.memory_file.*`): pulled at start
+  (Center wins), pushed after each turn and on file changes with `ifVersion` (a conflict
+  takes Center's copy). A new agent gets a template MEMORY.md. MEMORY.md (≤8k characters)
+  is put in front of a turn's message whenever it changed since the session last saw it.
+- Every turn's message starts with `[时间] <local time>` and, with a context,
+  `[上下文] 用户正在看「今天」页（…）`.
+- oar's raw records go to `<workdir>/records/<agentId>/<sessionId>-<opened>.jsonl`.
+- The oar session id is stored as the agent's `resumeSessionId`; after a restart or an
+  idle close the session is resumed (a fresh one when that fails). A turn that was
+  half-answered when the host died is run again once: the model gets
+  「上一轮被打断，请继续。…」 and the user's message, the reply goes on after what it already
+  had (「（host 重启了，接着说）」). A second restart in the same turn fails it (turn ids
+  run again are kept in `<workdir>/resumed-turns.json`).
+- Core runs one turn per agent at a time, so a second message waits for the first (the
+  driver also handles oar's steer/queue landings for when that changes).
+- **Inactive history.** When the session compacts (oar `compaction_ended`, completed),
+  the host calls `agent.history.mark_inactive` with `beforeTurnId` (the tool calls of every
+  earlier turn of the agent) and the calls the current turn made so far; the messages stay
+  (the summary keeps them). When oar drops an accepted input (`input_dropped`; oar 0.86
+  has no other rollback record), that turn fails and its user message, reply and tool calls
+  are marked inactive. The mark waits for the turn's queued events to reach Center.
+  `search.query` and `message.list` leave inactive records out unless `includeInactive`.
+
+`Ctrl-C` flushes queued events, marks the host's agents offline and leaves any running
+turn running. The next `run` resumes it.
+
+## Sub-agents
+
+A main agent can hand a self-contained job to a sub-agent (`subagents: true`, the
+default). Four host-served tools, on top of oar's crew (`@botiverse/oar/agents`):
+
+| tool | what |
+|---|---|
+| `agent_spawn({name, task, writeScopes?})` 「开子 agent」 | a new core agent: `parentAgentId` = the parent, this host, the parent's runtime and model; its own token (read-only, plus `writeScopes`, at most the parent's own write scopes); its own workdir and memory. The task is a `turn.open` turn in the child's new conversation (context 「「助手」交给的任务」), the child's session is opened by the crew with it. The parent's reply gets a card 「子 agent「…」开始了」 into that conversation. |
+| `agent_send({agent, message})` 「给子 agent 发消息」 | a follow-up as another `turn.open` turn in the child's conversation; refused while the child is busy |
+| `agent_wait({agents?, timeoutSeconds?})` 「等子 agent 的报告」 | the reports that came in (waits up to 120 s by default); each gets a card |
+| `agent_close({agent})` 「结束子 agent」 | closes its session; the agent and its conversation stay (status offline); a later message reopens it |
+
+- **Reports.** Every turn the parent started ends in a report (the child's reply, which
+  is already in the child's conversation). It goes to a waiting `agent_wait`, else to
+  the parent as a `turn.open` turn in the conversation the task came from: the stored
+  message is 「子 agent「…」的报告：…」 (context: the child's conversation; oar origin
+  `notification`), the reply starts with a card 「子 agent「…」完成了」 whose uri is
+  `agent:conversation/<child conversation>`; the app opens that conversation. While the
+  parent is busy, reports wait for its turn to end.
+- **Talking to a child.** It is in `agent.list` like any agent; the user's turns are
+  claimed and answered by the same host. Those turns don't report to the parent.
+- **Limits.** Children don't get the four tools (depth 2). At most 4 children run at
+  once, 8 open per parent. After a restart the host takes its children back
+  (`parentAgentId` one of its agents) with their saved tokens and resumes their sessions.
+
+## Presence
+
+The host says `host.heartbeat` every 20 s. Center marks a host's agents offline when its
+event stream closes (5 s grace) or after 60 s without any call, and online again on the
+next one; `Ctrl-C` marks them offline at once. The app shows the state in the agent menu
+and, for an offline agent, 「…现在离线，消息会排队，等它上线后回复」: turns stay queued and
+are answered when the host is back.
+
+## Tokens
+
+The host token carries `agent:host`. It can claim turns and write replies for every agent
+assigned to the host (and for unassigned ones), but it can't read the owner's data.
+**Per-agent tokens, the credentials an agent's tools use to call Center, must never
+carry `agent:host`.** An agent holding it could claim other agents' turns and write their
+replies. `agent:host` is an explicit scope: `agent:write`, `*:write` or `agent:*` don't
+grant it. Never hand the host's own token to a runtime or its tools either; it stays in
+the host process.
+
+**Issued agent tokens.** An agent without a token in host.json gets one from Center: the
+host calls `agent.agent.issue_token({agentId, scopes})` with its own credential. Center
+allows it only for agents assigned to the calling host, gives `*:read agent:read` plus
+the write scopes asked for, and refuses `*`, `agent:host`, anything implying
+`agent:write` and `core:*` beyond `core:read`. The agent keeps one principal (kind
+agent, `agent.tokenPrincipalId`); calling again replaces its scopes and revokes its
+earlier tokens. The host keeps the tokens in `agent-tokens.json` next to host.json
+(0600, per server) and asks for a new one when Center rejects the saved one or the
+scopes changed. Why a host op rather than giving the host `core:token`/`core:admin`:
+those reach every principal, while this op can only mint restricted tokens for the
+host's own agents, so a stolen host token still can't read the owner's data or act as
+the owner.
+
+## Server
+
+`deploy/agent-host.Dockerfile` (Node 24 + oar + Claude Code) and the opt-in
+`deploy/compose.agent-host.yaml` (next to `api`, MCP via `http://api:8800`, a volume for
+`/data`).
+
+## Shape
+
+```
+src/core-client.ts  CoreClient interface + HttpCoreClient (ops, SSE parsing, 401 → refresh)
+src/driver.ts       Driver interface (start, run(turn, sink, signal), stop) + EchoDriver
+src/oar-driver.ts   OarDriver: oar sessions per agent, event mapping, cards, resume, idle
+src/center-tools.ts the agent's Center tools (catalog, search, describe, call, overview)
+src/tool-titles.ts  Chinese step titles
+src/prompt.ts       system prompt + per-turn prefix
+src/memory.ts       memory files ↔ Center
+src/host.ts         AgentHost: register, listen, claim, batch, stop, reconnect, resume
+src/config.ts       host.json settings (runtime, model, workdir, agents)
+src/credentials.ts  host.json login, TokenSource (OAuth refresh)
+src/login.ts        device login
+src/crew-tools.ts   agent_spawn / agent_send / agent_wait / agent_close (sub-agents, in oar-driver.ts)
+src/agent-tokens.ts the agents' issued tokens (agent-tokens.json)
+src/cli.ts          agent-host login | run | doctor
+```
+
+- **Claiming.** The host claims (`resume: true`, only its own agents) on start, on every
+  stream `ready`, on each `turn` push with state `queued`, after each finished turn (an
+  agent's next queued turn isn't pushed again), and on a 30 s safety poll.
+- **Batching.** Events are appended every 100 ms, and immediately on `done`/`failed`, one
+  request at a time. Each batch's idempotency key is `ev-<turnId>-<seq>`, so a retry
+  after a network error is applied once.
+- **Stop.** A `turn` push with state `stopped` (or a 409/403 on append) aborts the
+  runtime and drops its queued events.
+- **Reconnect.** When the stream ends, errors, or goes 45 s without even a heartbeat, the
+  host reconnects with jittered exponential backoff (0.5 s up to 30 s) and re-claims.
+- **Resume.** A running turn claimed back after a restart carries `eventCount`. The
+  driver gets it as `appended`: EchoDriver is deterministic and skips that many events;
+  OarDriver can't replay and runs the turn again once (see Memory and records).
+- **Host-opened turns.** A driver may add agents (`addAgent`) and open turns
+  (`openTurn` → `turn.open`, already running and claimed by this host); they run
+  through the same batching as claimed ones.
+
+## Test
+
+```sh
+bun test packages/agent-host     # core in-process over real HTTP + the host loop;
+                                 # oar-driver.test.ts: pi + the mock model, end to end
+                                 # subagents.test.ts: issued tokens, memory notes,
+                                 #   sub-agents, presence, interrupted turns
+                                 # inactive.test.ts: compaction / dropped input →
+                                 #   inactive history (fake oar session)
+bun x tsc -p packages/agent-host # typecheck against Node types
+```
+
+## Publishing
+
+Releases go out from GitHub Actions (`.github/workflows/agent-host-publish.yml`) with npm
+trusted publishing (OIDC, no npm token):
+
+1. Bump `version` in `packages/agent-host/package.json`, commit and merge to `main`.
+2. Tag that commit and push the tag:
+
+   ```sh
+   git tag agent-host-v0.1.1 && git push origin agent-host-v0.1.1
+   ```
+
+The workflow checks that the tag is on `main` and matches the package version, runs the
+tests and typecheck, builds, smoke-tests the packed tarball and runs `npm publish
+--access public`.
+
+One-time setup (the package has to exist on npm before a trusted publisher can be
+added):
+
+```sh
+cd packages/agent-host
+npm login
+npm publish --access public   # prepublishOnly builds dist/ first
+```
+
+then on npmjs.com → @rien7/agent-center-host → Settings → Trusted publishing → GitHub Actions:
+owner `rien7`, repository `agent-center`, workflow `agent-host-publish.yml`, no
+environment, allowed action **npm publish**. The first CI publish must happen within
+2 days of adding it. `npm pack --dry-run` shows what ships: `dist/` and this README.

package/dist/agent-tokens.js

@@ -0,0 +1,105 @@
+/**
+ * The agents' own Center tokens, issued by Center to the host (`agent.agent.issue_token`)
+ * and kept next to the host's login in `agent-tokens.json` (0600, per server). An agent
+ * token is restricted: read-only by default plus the write scopes asked for, never
+ * `agent:host`, `agent:write` or core beyond read (Center refuses those).
+ *
+ * A token written by hand in host.json (`agents[].token` / `tokenEnv`) still wins.
+ */
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { configPath } from "./credentials.js";
+/** What a new agent may write by default (on top of *:read, agent:read). */
+export const defaultAgentScopes = [
+    "memo:write",
+    "reminder:write",
+    "calendar:write",
+];
+export const agentTokensPath = (env = process.env) => env.AGENT_CENTER_AGENT_TOKENS ??
+    join(dirname(configPath(env)), "agent-tokens.json");
+export class AgentTokens {
+    path;
+    server;
+    client;
+    file = null;
+    chain = Promise.resolve();
+    /** `path: null` keeps the tokens in memory only (tests, read-only setups). */
+    constructor(options) {
+        this.client = options.client;
+        this.server = options.server;
+        this.path = options.path === undefined ? agentTokensPath() : options.path;
+    }
+    async load() {
+        if (this.file)
+            return this.file;
+        let file = {};
+        if (this.path)
+            try {
+                file = JSON.parse(await readFile(this.path, "utf8"));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        this.file = file;
+        return file;
+    }
+    save() {
+        const path = this.path;
+        const file = this.file;
+        if (!path || !file)
+            return Promise.resolve();
+        this.chain = this.chain.then(async () => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            const tmp = `${path}.${process.pid}.tmp`;
+            await writeFile(tmp, `${JSON.stringify(file, null, 2)}\n`, {
+                mode: 0o600,
+            });
+            await chmod(tmp, 0o600);
+            await rename(tmp, path);
+        });
+        return this.chain;
+    }
+    /** What is saved for an agent (its token and the scopes asked for), if anything. */
+    async entry(agentId) {
+        return (await this.load())[this.server]?.[agentId] ?? null;
+    }
+    /** The saved token of an agent, if it has one with these scopes. */
+    async saved(agentId, scopes) {
+        const entry = (await this.load())[this.server]?.[agentId];
+        return entry && sameScopes(entry.scopes, scopes) ? entry.token : null;
+    }
+    /** Ask Center for a (new) token and keep it; earlier tokens of the agent are revoked. */
+    async issue(agentId, scopes) {
+        if (!this.client.issueToken)
+            throw new Error("this Center client cannot issue agent tokens");
+        const issued = await this.client.issueToken(agentId, scopes);
+        const file = await this.load();
+        file[this.server] ??= {};
+        file[this.server][agentId] = {
+            token: issued.token,
+            scopes,
+            principalId: issued.principalId,
+        };
+        await this.save();
+        return issued.token;
+    }
+    async forget(agentId) {
+        const file = await this.load();
+        if (file[this.server]?.[agentId]) {
+            delete file[this.server][agentId];
+            await this.save();
+        }
+    }
+    /**
+     * A working token for the agent: the saved one when `check` accepts it, else a newly
+     * issued one. `check` returns false when Center rejects the token (401).
+     */
+    async get(agentId, scopes, check) {
+        const saved = await this.saved(agentId, scopes);
+        if (saved && (await check(saved)))
+            return { token: saved, issued: false };
+        return { token: await this.issue(agentId, scopes), issued: true };
+    }
+}
+const sameScopes = (a, b) => a.length === b.length && [...a].sort().join() === [...b].sort().join();