@keyou007/agent-bot 0.1.0

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@keyou007/agent-bot",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Using Codex in Lark/Feishu feels just like using native Codex.",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keyou/agent-bot.git"
+  },
+  "homepage": "https://github.com/keyou/agent-bot#readme",
+  "bugs": {
+    "url": "https://github.com/keyou/agent-bot/issues"
+  },
+  "keywords": [
+    "agent",
+    "codex",
+    "acp",
+    "feishu",
+    "lark",
+    "cli"
+  ],
+  "bin": {
+    "agent-bot": "dist/cli.js"
+  },
+  "files": [
+    ".env.example",
+    "CHANGELOG.md",
+    "config.example.yaml",
+    "dist/",
+    "docs/technical-reference.md",
+    "docs/technical-reference.zh.md",
+    "npm-shrinkwrap.json",
+    "README.zh.md",
+    "SECURITY.md",
+    "skills/agent-bot/",
+    "src/",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "start": "node dist/supervisor.js",
+    "start:once": "node dist/index.js",
+    "cli": "node dist/cli.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "verify": "npm run typecheck && npm test",
+    "prepack": "npm run build && node scripts/check-package.mjs",
+    "prepublishOnly": "npm run verify",
+    "package:check": "npm run prepack",
+    "package:smoke": "node scripts/smoke-package.mjs"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.2.1",
+    "@larksuiteoapi/node-sdk": "1.56.1",
+    "@resvg/resvg-js": "2.6.2",
+    "better-sqlite3": "12.11.1",
+    "dotenv": "17.4.2",
+    "pino": "10.3.1",
+    "qrcode-terminal": "0.12.0",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
+    "@types/node": "22.18.11",
+    "@types/qrcode-terminal": "0.12.2",
+    "eslint": "10.6.0",
+    "prettier": "3.9.5",
+    "tsx": "4.23.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "overrides": {
+    "axios": "1.18.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@11.12.1"
+}

package/skills/agent-bot/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: agent-bot
+description: Initialize Agent Bot, detect and work safely inside its runtime, and manage the local service and its Codex or ACP sessions through the agent-bot CLI. Use when an agent needs to adapt its behavior while running under Agent Bot, or when a user asks to initialize, inspect, start, safely restart, immediately restart, or stop Agent Bot; open its console UI; list, inspect, stop, rename, or send a prompt to tasks; check a scheduled restart; or troubleshoot the bot without manually killing worker processes.
+---
+
+# Agent Bot
+
+Use the `agent-bot` command as the supported control surface for Agent Bot. Prefer its structured status and control operations over direct process manipulation or database edits.
+
+## Detect the Agent Bot runtime
+
+Agent Bot injects `AGENT_BOT=1` into every Codex and ACP agent process it starts. Test for the exact value `1`:
+
+```powershell
+if ($env:AGENT_BOT -eq "1") { "running in Agent Bot" }
+```
+
+```sh
+if [ "${AGENT_BOT:-}" = "1" ]; then echo "running in Agent Bot"; fi
+```
+
+```js
+const runningInAgentBot = process.env.AGENT_BOT === "1";
+```
+
+```python
+import os
+
+running_in_agent_bot = os.environ.get("AGENT_BOT") == "1"
+```
+
+Treat this environment marker as authoritative. Do not infer Agent Bot execution merely because the CLI is installed, `~/.agent-bot` exists, or an Agent Bot process is running elsewhere. Configured agent environment variables cannot override the marker. Child processes normally inherit it, so the marker identifies the Agent Bot-started process tree unless a child explicitly replaces its environment.
+
+## Behave safely inside Agent Bot
+
+When `AGENT_BOT=1`:
+
+- Do not kill Agent Bot, its supervisor, or agent workers directly. For code changes that must be loaded by the running service, finish verification first and schedule a safe restart; never use an immediate restart from an active hosted task unless the user explicitly accepts interruption.
+- Keep repository contents limited to source and examples. Read user configuration and runtime state from the root selected by `AGENT_BOT_HOME`, defaulting to `~/.agent-bot`.
+
+## Initialize after installation
+
+Run initialization once after installing or linking the CLI:
+
+```powershell
+agent-bot init
+```
+
+Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `logs/` from the bundled examples. If Feishu credentials are absent, it starts Feishu one-click app registration, prints an authorization URL and QR code, waits for the user to approve the request, and stores the returned app ID and secret in `.env`. It then audits the app's currently published tenant permissions, event subscriptions, and callbacks. Core and optional missing items produce separate incremental-configuration URLs so optional approval cannot block core setup.
+
+When running `init` on the user's behalf, relay every exact authorization or incremental-configuration URL and let the user complete it in their own browser. The command waits only for core message receipt and delivery capabilities. Optional capabilities such as group creation, group-title synchronization, reactions, images, and card actions do not block initialization; relay the final affected-feature warnings when they remain unavailable. Neither URL contains the app secret, and the secret itself is never printed.
+
+Existing complete Feishu credentials are preserved but still audited and repaired when needed. Use `agent-bot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agent-bot init --reconfigure-feishu` only when the user explicitly wants to replace existing credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agent-bot init --json` when structured final output helps.
+
+## Start with inspection
+
+Verify the CLI and current service state before changing anything:
+
+```powershell
+agent-bot --help
+agent-bot server status
+agent-bot task list
+```
+
+Add `--json` to status and list commands when machine-readable output helps. If `agent-bot` is unavailable, report that the CLI is not installed or linked instead of guessing process state.
+
+By default Agent Bot stores user-owned configuration and runtime state in `~/.agent-bot`: config at `~/.agent-bot/config.yaml`, environment variables at `~/.agent-bot/.env`, SQLite state at `~/.agent-bot/data/agent-bot.sqlite`, logs at `~/.agent-bot/logs/agent-bot.log`, and inbound image cache next to the SQLite database. `AGENT_BOT_HOME` changes this root. Use `--config <path>` only when controlling a non-default configuration.
+
+## Manage the service
+
+Use these commands:
+
+```powershell
+agent-bot server start
+agent-bot server status
+agent-bot server restart --reason "reason for restart"
+agent-bot server stop
+```
+
+Treat `server restart` as the normal restart path. It schedules a safe restart and waits for active tasks, pending final-message delivery, and a quiet inbound-message window. The first safe-restart status card is delayed by three seconds so the active task's final response can usually be delivered first; this presentation delay does not postpone scheduler polling.
+
+Use `agent-bot server restart --immediate` only when the user explicitly requests an immediate restart or accepts interruption. Never use `taskkill`, `Stop-Process`, or equivalent commands for routine Agent Bot restart management.
+
+`agent-bot console` opens the console UI only when the service is stopped. Do not use `--force` while the service is live unless the user explicitly accepts concurrent state access.
+
+## Manage tasks
+
+List tasks before resolving a numeric reference because task numbers follow the current list order:
+
+```powershell
+agent-bot task list
+agent-bot task chat <number-or-task-id> [--json]
+agent-bot task status <number-or-task-id>
+agent-bot task stop <number-or-task-id>
+agent-bot task title <number-or-task-id> <new-title>
+agent-bot task prompt <number-or-task-id> <prompt>
+```
+
+Task IDs may be supplied in full or as an unambiguous prefix. Use `task stop` to ask the running worker to send the Codex Interrupt signal; leave child-process lifecycle management to Codex.
+
+Use `task chat <number-or-task-id>` to read the Feishu chat ID associated with a task from local routing state. Plain output is only the chat ID for scripting. Add `--json` to include the stable task ID, complete context key, and the thread ID for a topic-bound task. This read-only command does not require the Agent Bot server to be running.
+
+Use `task prompt` to send input to a specific task without changing any chat's current task. The bot first posts the Prompt text to the task's existing Feishu chat, thread, or private-chat route, then submits it to the task. If posting fails, the task is not started or steered. The thinking card and final response continue to the same route; the command line only reports whether the Prompt was accepted.
+
+Use `/queue <prompt>` in Feishu to persist a separate follow-up Prompt instead of steering the active turn. Queued Prompts run in FIFO order after the current turn completes and survive Agent Bot restarts. `/nosteer <prompt>` is an equivalent compatibility spelling.
+
+For a long-running objective in the active Feishu task, use `/goal <objective>`. Use `/goal` to inspect it, `/goal pause` or `/goal resume` to control automatic continuation, `/goal edit <objective>` to revise it, and `/goal clear` to remove it. Stopping a Goal turn through Agent Bot also pauses the Goal before sending Interrupt so it does not immediately continue.
+
+Use `/newgroup [title]` in Feishu to create a private group named `[agent] [project directory] <title>`, invite the command sender, and immediately create and bind a new task in that group. The new task inherits the source chat's current task project directory, model, reasoning effort, and permission mode without interrupting or switching the source task. When the source chat has no current task, use the selected agent and its runtime defaults. An explicit title becomes both the group suffix and the task title. When the title is omitted, use task title `新任务` and group name `[agent] [project directory] 新任务 (mm-dd)`; an explicit title never gets a date suffix. Every new group gets a deterministic scheme-C Identicon avatar: Latin project names display their first word, Chinese names display up to their first four characters, and the normalized full project path hashes into the palette and symmetric node pattern. Projectless groups use the title as the stable seed. Replace the user's home-directory prefix with `~`. The bracketed project-directory value is limited to 15 characters. Longer paths keep the final two directories when they fit, otherwise keep the final directory, truncating the tail only when the final directory itself is overlong. Use `\` on Windows and `/` on macOS/Linux. Do not automatically send a Sessions or Status card to the new group. A later `/new --dir <cwd>` or `/new --nodir` in the group may explicitly replace the inherited project shape.
+
+Group names created by `/newgroup` and `/forkgroup` are capped at 60 displayed characters. When the generated name would exceed that limit, truncate only the title portion in the Feishu group name; preserve the underlying Agent Bot task title.
+
+Use `/forkgroup [title]` in Feishu to fork the current position into a newly created private group. In a Feishu thread, use the thread's original anchor turn when the thread has no bound task or its bound task has not completed a turn of its own. Once the bound thread task has completed a turn, use its latest locally persisted completed turn; exclude any newer active turn without interrupting it. Resolve this source before generic thread initialization so an unbound thread does not create an intermediate task. Outside a thread, fork the current Codex task's latest available completed turn. Agent Bot invites the command sender and binds the fork as the new group's current task, but does not automatically send a Sessions or Status card there. An explicit title is used directly. Without an explicit title, both the forked task and group name use the same persistent `source title（分支 N）` sequence as `/fork`. `/forkgroup` does not add a date suffix.
+
+Use `/new [title] --nodir` to force a new Codex Projectless task even when the current task belongs to a project. `--nodir` and `--dir <cwd>` are mutually exclusive; omitting both preserves the normal project-shape inheritance behavior.
+
+Every task in the Feishu `/sessions` card has a `New` action. It inherits the source task's project directory, model, reasoning effort, and permission mode, creates a new task, and switches the current chat to it without stopping or forking the source task.
+
+Use `/fork [number-or-task-id]` in Feishu to branch from the current or specified Codex task and switch to the new branch. If the source task is running, Agent Bot forks from its latest completed turn and leaves the active turn running; it rejects only when the task has no completed turn yet.
+
+Status cards include a `Refresh` action that reads the latest task state and updates the same card in place without switching tasks or sending another card.
+
+Use `/model` in Feishu to show an interactive Card 2.0 model selector for the current task. Each non-current model has a blue link-style `Switch` action. After selecting a model, the same card advances to that model's reasoning-mode selector; the selector lists only mode names, has a `Back` action, and applies a selected mode from the next request. `/thinking` opens the reasoning selector directly. `/model <name>` and `/thinking <level>` remain available for direct text-based selection.
+
+Keep action labels placed to the right of card content or at the bottom of a card in English. Buttons above the main card content, such as activity-history navigation, may remain in Chinese.
+
+Messages whose trimmed text starts with `/` are always parsed as Agent Bot commands. Unknown slash commands are reported to the user with a `/help` hint and must never fall through to the model, including slash-prefixed messages that also contain images.
+
+When a group body has a current task, renaming the Feishu group to `[agent-name] new title` also renames that current task if the prefix matches the task's configured agent. Malformed names, agent mismatches, empty groups, and thread-specific tasks are ignored.
+
+Use `--context <key>` or `--status <status>` to narrow `task list`. Use `--config <path>` before the command when controlling a non-default Agent Bot configuration.
+
+## Apply code changes safely
+
+After changing Agent Bot code, run the relevant tests, typecheck, and build. If a running service must pick up the result, schedule:
+
+```powershell
+agent-bot server restart --reason "brief description of the completed change"
+```
+
+Do not replace the worker immediately while a task is active. A later incoming task must not cancel the pending safe restart; allow the scheduler to wait until the service becomes safely idle again.

package/skills/agent-bot/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Bot"
+  short_description: "Manage Agent Bot services, sessions, and tasks safely"
+  default_prompt: "Use $agent-bot to inspect and safely manage the local Agent Bot service."

package/src/acp/AcpJsonRpcConnection.ts

@@ -0,0 +1,212 @@
+import { EventEmitter } from "node:events";
+import readline from "node:readline";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Logger } from "pino";
+import {
+  isJsonRpcNotification,
+  isJsonRpcRequest,
+  isJsonRpcResponse,
+  type JsonRpcMessage,
+  type JsonRpcResponse,
+  type JsonValue,
+} from "./acpTypes.js";
+
+type ClientMethodHandler = (params: JsonValue | undefined) => Promise<JsonValue>;
+
+interface PendingRequest {
+  resolve: (value: JsonValue) => void;
+  reject: (error: Error) => void;
+  method: string;
+}
+
+export interface AcpJsonRpcConnectionEvents {
+  notification: [method: string, params: JsonValue | undefined];
+  request: [method: string, params: JsonValue | undefined];
+  close: [];
+}
+
+export class AcpJsonRpcConnection extends EventEmitter {
+  private nextId = 1;
+  private readonly pending = new Map<string | number, PendingRequest>();
+  private readonly handlers = new Map<string, ClientMethodHandler>();
+  private closed = false;
+
+  constructor(
+    private readonly process: ChildProcessWithoutNullStreams,
+    private readonly logger: Logger,
+  ) {
+    super();
+    this.bindOutput();
+  }
+
+  on<K extends keyof AcpJsonRpcConnectionEvents>(
+    eventName: K,
+    listener: (...args: AcpJsonRpcConnectionEvents[K]) => void,
+  ): this {
+    return super.on(eventName, listener);
+  }
+
+  registerHandler(method: string, handler: ClientMethodHandler): void {
+    this.handlers.set(method, handler);
+  }
+
+  async request<T = JsonValue>(
+    method: string,
+    params?: JsonValue,
+    timeoutMs = 0,
+  ): Promise<T> {
+    if (this.closed) {
+      throw new Error(`Cannot send ACP request after connection closed: ${method}`);
+    }
+
+    const id = this.nextId++;
+    const responsePromise = new Promise<JsonValue>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, method });
+    });
+
+    this.write({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    });
+
+    if (timeoutMs <= 0) {
+      return (await responsePromise) as T;
+    }
+
+    return (await Promise.race([
+      responsePromise,
+      new Promise<JsonValue>((_resolve, reject) => {
+        setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`ACP request timed out: ${method}`));
+        }, timeoutMs);
+      }),
+    ])) as T;
+  }
+
+  notify(method: string, params?: JsonValue): void {
+    if (this.closed) {
+      return;
+    }
+
+    this.write({
+      jsonrpc: "2.0",
+      method,
+      params,
+    });
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const pending of this.pending.values()) {
+      pending.reject(new Error("ACP connection closed."));
+    }
+    this.pending.clear();
+    this.emit("close");
+  }
+
+  private bindOutput(): void {
+    const reader = readline.createInterface({
+      input: this.process.stdout,
+      crlfDelay: Infinity,
+    });
+
+    reader.on("line", (line) => {
+      if (!line.trim()) {
+        return;
+      }
+
+      this.handleLine(line);
+    });
+
+    this.process.once("close", () => this.close());
+  }
+
+  private handleLine(line: string): void {
+    let message: JsonRpcMessage;
+    try {
+      message = JSON.parse(line) as JsonRpcMessage;
+    } catch (error) {
+      this.logger.warn({ line, error }, "Ignoring non-JSON ACP stdout line.");
+      return;
+    }
+
+    if (isJsonRpcResponse(message)) {
+      this.handleResponse(message);
+      return;
+    }
+
+    if (isJsonRpcRequest(message)) {
+      void this.handleRequest(message.id, message.method, message.params);
+      return;
+    }
+
+    if (isJsonRpcNotification(message)) {
+      this.emit("notification", message.method, message.params);
+      return;
+    }
+
+    this.logger.warn({ message }, "Ignoring unknown ACP message shape.");
+  }
+
+  private handleResponse(message: JsonRpcResponse): void {
+    const pending = this.pending.get(message.id);
+    if (!pending) {
+      this.logger.warn({ message }, "Received ACP response for unknown request.");
+      return;
+    }
+
+    this.pending.delete(message.id);
+    if ("error" in message) {
+      pending.reject(new Error(`${pending.method} failed: ${message.error.message}`));
+      return;
+    }
+
+    pending.resolve(message.result);
+  }
+
+  private async handleRequest(
+    id: string | number,
+    method: string,
+    params: JsonValue | undefined,
+  ): Promise<void> {
+    this.emit("request", method, params);
+    const handler = this.handlers.get(method);
+    if (!handler) {
+      this.write({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32601,
+          message: `Client method is not implemented by Agent Bot: ${method}`,
+        },
+      });
+      return;
+    }
+
+    try {
+      const result = await handler(params);
+      this.write({
+        jsonrpc: "2.0",
+        id,
+        result,
+      });
+    } catch (error) {
+      this.write({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32000,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  }
+
+  private write(message: JsonRpcMessage): void {
+    const serialized = JSON.stringify(message);
+    this.process.stdin.write(`${serialized}\n`, "utf8");
+  }
+}

package/src/acp/AcpProcessManager.ts

@@ -0,0 +1,87 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import readline from "node:readline";
+import type { Logger } from "pino";
+import type { AgentConfig } from "../config/schema.js";
+import { AcpJsonRpcConnection } from "./AcpJsonRpcConnection.js";
+import { agentBotEnvironment } from "../runtime/agentEnvironment.js";
+import { spawnStdioCommand } from "../utils/spawnCommand.js";
+
+export interface ManagedAcpProcess {
+  processKey: string;
+  child: ChildProcessWithoutNullStreams;
+  connection: AcpJsonRpcConnection;
+  stop: () => void;
+}
+
+export class AcpProcessManager {
+  private readonly processes = new Map<string, ManagedAcpProcess>();
+
+  constructor(private readonly logger: Logger) {}
+
+  start(processKey: string, agentName: string, agent: AgentConfig): ManagedAcpProcess {
+    if (this.processes.has(processKey)) {
+      throw new Error(`ACP process already exists: ${processKey}`);
+    }
+
+    const child = spawnStdioCommand(agent.command, agent.args, agentBotEnvironment(process.env, agent.env));
+
+    const childLogger = this.logger.child({ processKey, agentName });
+    const connection = new AcpJsonRpcConnection(child, childLogger);
+    const managed: ManagedAcpProcess = {
+      processKey,
+      child,
+      connection,
+      stop: () => this.stop(processKey),
+    };
+
+    this.processes.set(processKey, managed);
+    this.bindLifecycle(managed, childLogger);
+
+    childLogger.info({ command: agent.command, args: agent.args }, "Started ACP agent process.");
+    return managed;
+  }
+
+  get(processKey: string): ManagedAcpProcess | undefined {
+    return this.processes.get(processKey);
+  }
+
+  stop(processKey: string): void {
+    const managed = this.processes.get(processKey);
+    if (!managed) {
+      return;
+    }
+
+    this.processes.delete(processKey);
+    managed.connection.close();
+
+    if (!managed.child.killed) {
+      managed.child.kill();
+    }
+  }
+
+  stopAll(): void {
+    for (const processKey of this.processes.keys()) {
+      this.stop(processKey);
+    }
+  }
+
+  private bindLifecycle(managed: ManagedAcpProcess, logger: Logger): void {
+    const stderr = readline.createInterface({
+      input: managed.child.stderr,
+      crlfDelay: Infinity,
+    });
+
+    stderr.on("line", (line) => {
+      logger.debug({ stderr: line }, "ACP agent stderr.");
+    });
+
+    managed.child.once("error", (error) => {
+      logger.error({ error }, "ACP agent process error.");
+    });
+
+    managed.child.once("exit", (code, signal) => {
+      this.processes.delete(managed.processKey);
+      logger.info({ code, signal }, "ACP agent process exited.");
+    });
+  }
+}