@vicvic-im/agent-bot 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @vicvic-im/agent-bot
 
-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.
+Connect a local coding agent to [vicvic.im](https://vicvic.im) as an AI contact. Supports **Claude Code**, **Codex**, **OpenCode**, and **Pi** through the [Agent Client Protocol](https://agentclientprotocol.com) (ACP).
+
+This is the multi-agent successor to `@ccbot/cli`. It reuses the same vicvic.im bot WebSocket protocol, so the server needs no changes.
+
+## Requirements
+
+- Node.js >= 20
+- One of the supported agents installed and authenticated **on the same machine**:
+
+| Agent       | Command prerequisite                     |
+| ----------- | ---------------------------------------- |
+| Claude Code | `claude login` or `ANTHROPIC_AUTH_TOKEN` |
+| Codex       | `codex login`                            |
+| OpenCode    | OpenCode >= 1.19, provider configured    |
+| Pi          | Pi installed and authenticated           |
+
+ACP adapters are pinned in code:
+
+- `@agentclientprotocol/claude-agent-acp@0.100.0`
+- `@agentclientprotocol/codex-acp@2.5.0`
+- `opencode acp` (OpenCode >= 1.19)
+- `pi-acp@0.0.34` (third-party adapter)
+
+`npx` based adapters are downloaded on first run; pre-install them globally if your network is slow.
+
+Verified ACP capabilities (2026-11-05, local):
+
+| Agent       | resume | load | model option | usage cost | Notes                                                   |
+| ----------- | ------ | ---- | ------------ | ---------- | ------------------------------------------------------- |
+| Claude Code | ✅     | ✅   | ✅           | ✅         | ~13s cold start                                         |
+| Codex       | ✅     | ✅   | ✅           | ❌         | ~100s cold start                                        |
+| OpenCode    | ✅     | ✅   | ✅           | ✅         | set a working model; the free default may hit its limit |
+| Pi          | ❌     | ✅   | ✅           | ❌         | uses `session/load`; may include a context preamble     |
+
+## Install
+
+```bash
+npm i -g @vicvic-im/agent-bot
+```
+
+## Quick start
+
+1. Create an AI Bot in vicvic.im and copy its pairing token.
+2. In the project directory you want the agent to work in:
+
+```bash
+vbot start
+```
+
+3. The first run asks for the agent, work directory, timeout, server URL, and token, then writes `vbot.json`.
+4. Send a message to the bot from vicvic.im.
+
+With `pm2` installed, `vbot start` runs in the background. Without pm2, or with `--foreground`, it runs in the current terminal.
+
+## Commands
+
+```bash
+vbot start [--foreground] [-c <config>]
+vbot stop    [-c <config>]
+vbot restart [-c <config>]
+vbot status  [-c <config>]
+vbot logs    [-c <config>]
+vbot delete  [-c <config>]
+```
+
+Chat commands:
+
+| Command         | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `/new`          | Drop the ACP session and start a new conversation    |
+| `/stop`         | Cancel the current run and clear the queue           |
+| `/status`       | Show agent, session, cwd, queue, usage, capabilities |
+| `/agent [name]` | List or switch the agent backend                     |
+| `/model [name]` | Show or switch the model (if the agent exposes it)   |
+| `/cost`         | Show context usage and optional cost                 |
+| `/help`         | Show commands                                        |
+
+Unknown `/commands` are forwarded to the agent as prompts.
+
+## Configuration
+
+`vbot.json` in the current directory, or `~/.vbot/config.json` as a fallback:
+
+```json
+{
+  "provider": "vicvic",
+  "vicvic": {
+    "baseUrl": "https://api.vicvic.im",
+    "token": "ccbotpk_xxx"
+  },
+  "agent": {
+    "name": "codex",
+    "cwd": "/Users/me/project",
+    "model": null
+  },
+  "timeoutMs": 3600000,
+  "logPrompt": false
+}
+```
+
+- `agent.command` / `agent.args` are optional overrides. When omitted, the pinned command from the registry is used.
+- `agent.cwd` must be an absolute existing directory.
+- `VBOT_TOKEN` overrides `vicvic.token`, which is useful for CI or secret managers.
+- `logPrompt` defaults to `false`; prompts are not printed to logs.
+
+Session state is stored in `~/.vbot/state/<sha256(token)[:16]>.json`. State contains no message text and no token.
+
+## Security
+
+`vbot` runs the agent with **your local user permissions** and automatically approves every ACP permission request. There is no interactive approval mode. Only run it in a directory you trust, and review what the agent is allowed to access.
+
+The pairing token is a long-lived credential. Do not commit `vbot.json`; the file is written with mode `0600` but may still be copied by backup tools.
+
+## Differences from `@ccbot/cli`
+
+- Multi-agent through ACP instead of Claude-only SDK.
+- Session state is persisted; restarting `vbot` can resume the ACP session when the backend supports it.
+- `/cost` reports ACP `usage_update` values (`used` / `size` / optional `cost`), not Claude's dollar cost.
+- New config file (`vbot.json`) and pm2 process names (`vbot-*`); it does not read or migrate `ccbot.json`.
+- The App's onboarding still says `npm i -g @ccbot/cli`; this is a known gap for now.
+
+## Known limitations
+
+- No streaming/progress messages yet: only `Processing...` and the final reply.
+- Text only. Image and file messages are not supported by the vicvic.im bot conversation.
+- The server's offline notice still mentions `ccbot` (the server is unchanged in this phase).
+- Windows is not officially verified; the adapters and pm2 may need extra setup.
+- Chat CLI messages are English, matching the existing `@ccbot/cli` developer tooling; App UI i18n is unaffected.
+
+## Development
+
+```bash
+pnpm --filter @vicvic-im/agent-bot build
+pnpm --filter @vicvic-im/agent-bot test
+pnpm --filter @vicvic-im/agent-bot lint
+
+# probe ACP capabilities of all four backends
+pnpm --filter @vicvic-im/agent-bot exec tsx scripts/probe.ts
+```
+
+See `docs/prds/agent-bot-cli.md` for the full design.

package/dist/agents/acp.d.ts

@@ -0,0 +1,42 @@
+import type { AgentBackend, AgentCapabilities, AgentName, AgentRunRequest, AgentRunResult } from "./types.js";
+import type { AgentConfig } from "../config.js";
+export declare class AgentAbortError extends Error {
+    constructor();
+}
+export declare class AgentStartError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/** 通过 ACP stdio 驱动单个 coding agent 子进程。 */
+export declare class AcpAgent implements AgentBackend {
+    readonly name: AgentName;
+    private readonly config;
+    private child;
+    private connection;
+    private ctx;
+    private startPromise;
+    private session;
+    private configOptions;
+    private initCaps;
+    private turn;
+    private stderr;
+    private sawUsageCost;
+    private pendingModel;
+    constructor(name: AgentName, config: AgentConfig);
+    capabilities(): AgentCapabilities;
+    sessionId(): string | null;
+    resetSession(): void;
+    start(): Promise<void>;
+    private doStart;
+    private ensureSession;
+    run(request: AgentRunRequest): Promise<AgentRunResult>;
+    cancel(): Promise<void>;
+    setModel(model: string): Promise<boolean>;
+    close(): Promise<void>;
+    private handleUpdate;
+    private dispatchUpdate;
+    private applyContentChunk;
+    private applyToolUpdate;
+    private applyUsage;
+}
+//# sourceMappingURL=acp.d.ts.map

package/dist/agents/acp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../../src/agents/acp.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,cAAc,EAEf,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,qBAAa,eAAgB,SAAQ,KAAK;;CAKzC;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAWD,0CAA0C;AAC1C,qBAAa,QAAS,YAAW,YAAY;IAczC,QAAQ,CAAC,IAAI,EAAE,SAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,GAAG,CAAkC;IAC7C,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAuB;gBAGhC,IAAI,EAAE,SAAS,EACP,MAAM,EAAE,WAAW;IAGtC,YAAY,IAAI,iBAAiB;IASjC,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,YAAY,IAAI,IAAI;IAId,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YASd,OAAO;YA8EP,aAAa;IA+CrB,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAkEtD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IASvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,UAAU;CAWnB"}

package/dist/agents/registry.d.ts

@@ -0,0 +1,13 @@
+import type { AgentCommand, AgentName } from "./types.js";
+export interface AgentDefinition {
+    name: AgentName;
+    label: string;
+    command: AgentCommand;
+    /** 需要用户自行完成的认证前置。 */
+    authHint: string;
+}
+export declare const AGENTS: Record<AgentName, AgentDefinition>;
+export declare const AGENT_NAMES: AgentName[];
+export declare function isAgentName(value: string): value is AgentName;
+export declare function definitionOf(name: AgentName): AgentDefinition;
+//# sourceMappingURL=registry.d.ts.map

package/dist/agents/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,CAAC;IACtB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,eAAe,CAqCrD,CAAC;AAEF,eAAO,MAAM,WAAW,EAA0B,SAAS,EAAE,CAAC;AAE9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAE7D"}

package/dist/agents/types.d.ts

@@ -0,0 +1,72 @@
+export type AgentName = "claude" | "codex" | "opencode" | "pi";
+export interface AgentCommand {
+    command: string;
+    args: string[];
+}
+export interface Usage {
+    /** 当前上下文 token 数（ACP v1 usage_update.used）。 */
+    used: number;
+    /** 上下文窗口大小（ACP v1 usage_update.size）。 */
+    size: number;
+    /** 累计成本，单位由 agent 决定；不提供时为 null。 */
+    cost: {
+        amount: number;
+        currency: string;
+    } | null;
+}
+export declare const EMPTY_USAGE: Usage;
+export type AgentEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "thought";
+    text: string;
+} | {
+    type: "tool";
+    name: string;
+    status: string;
+} | {
+    type: "usage";
+    usage: Usage;
+};
+export interface AgentRunRequest {
+    prompt: string;
+    /** 已保存的 ACP session id；为空或后端不支持 resume 时新建。 */
+    sessionId?: string;
+    cwd: string;
+    model?: string | null;
+    signal: AbortSignal;
+    onEvent?: (event: AgentEvent) => void;
+}
+export interface AgentRunResult {
+    text: string;
+    sessionId: string;
+    usage: Usage;
+    /** true 表示本次是新会话（用于提示用户上下文已重置）。 */
+    newSession: boolean;
+}
+export interface AgentCapabilities {
+    resume: boolean;
+    load: boolean;
+    setConfigOption: boolean;
+    usageCost: boolean;
+}
+export interface AgentBackend {
+    readonly name: AgentName;
+    /** 启动子进程并完成 initialize；可重复调用（已启动则直接返回）。 */
+    start(): Promise<void>;
+    /** 运行一轮 prompt。内部负责 session 新建/恢复。 */
+    run(request: AgentRunRequest): Promise<AgentRunResult>;
+    /** 取消当前 prompt。 */
+    cancel(): Promise<void>;
+    /** 切换模型；返回 false 表示当前后端不支持。 */
+    setModel(model: string): Promise<boolean>;
+    /** 丢弃当前 ACP session；下一次 run 会新建会话。 */
+    resetSession(): void;
+    /** 关闭子进程并清理资源。 */
+    close(): Promise<void>;
+    capabilities(): AgentCapabilities;
+    /** 当前 ACP session id（可能为空）。 */
+    sessionId(): string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,IAAI,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD;AAED,eAAO,MAAM,WAAW,EAAE,KAAwC,CAAC;AAEnE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,2CAA2C;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,sCAAsC;IACtC,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACvD,mBAAmB;IACnB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,sCAAsC;IACtC,YAAY,IAAI,IAAI,CAAC;IACrB,kBAAkB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,YAAY,IAAI,iBAAiB,CAAC;IAClC,+BAA+B;IAC/B,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;CAC5B"}