@keyou007/agent-bot 0.1.0

package/dist/utils/executeShellCommand.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+export function executeShellCommand(command, cwd, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const prepared = prepareShellCommand(command, options.platform ?? process.platform);
+    return new Promise((resolve, reject) => {
+        const child = spawn(prepared.command, prepared.args, {
+            cwd,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const output = new BoundedOutput(maxOutputBytes);
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => output.append("stdout", chunk));
+        child.stderr.on("data", (chunk) => output.append("stderr", chunk));
+        child.once("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.once("close", (exitCode) => {
+            clearTimeout(timeout);
+            resolve({
+                ...output.result(),
+                exitCode,
+                timedOut,
+            });
+        });
+    });
+}
+function prepareShellCommand(command, platform) {
+    if (platform !== "win32")
+        return { command: "/bin/sh", args: ["-lc", command] };
+    const script = `$ProgressPreference = 'SilentlyContinue'; [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new(); ${command}`;
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    return {
+        command: "powershell.exe",
+        args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-OutputFormat", "Text", "-EncodedCommand", encoded],
+    };
+}
+class BoundedOutput {
+    maxBytes;
+    stdout = [];
+    stderr = [];
+    retainedBytes = 0;
+    truncated = false;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    append(stream, chunk) {
+        const remaining = Math.max(0, this.maxBytes - this.retainedBytes);
+        if (remaining === 0) {
+            this.truncated = true;
+            return;
+        }
+        const retained = chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
+        this[stream].push(retained);
+        this.retainedBytes += retained.length;
+        if (retained.length < chunk.length)
+            this.truncated = true;
+    }
+    result() {
+        return {
+            stdout: Buffer.concat(this.stdout).toString("utf8"),
+            stderr: Buffer.concat(this.stderr).toString("utf8"),
+            outputTruncated: this.truncated,
+        };
+    }
+}
+//# sourceMappingURL=executeShellCommand.js.map

package/dist/utils/executeShellCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executeShellCommand.js","sourceRoot":"","sources":["../../src/utils/executeShellCommand.ts"],"names":[],"mappings":"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"}

package/dist/utils/id.js

@@ -0,0 +1,5 @@
+import { randomUUID } from "node:crypto";
+export function createId(prefix) {
+    return `${prefix}_${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAO,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC"}

package/dist/utils/markdown.js

@@ -0,0 +1,29 @@
+export function truncateText(text, maxLength = 8000) {
+    if (text.length <= maxLength)
+        return text;
+    if (maxLength <= 0)
+        return "";
+    if (maxLength <= 3)
+        return ".".repeat(maxLength);
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+export function truncateMiddle(text, maxLength = 8000, marker = "\n...\n") {
+    if (text.length <= maxLength)
+        return text;
+    if (maxLength <= 0)
+        return "";
+    if (maxLength <= marker.length)
+        return ".".repeat(maxLength);
+    const retainedLength = maxLength - marker.length;
+    const headLength = Math.ceil(retainedLength / 2);
+    const tailLength = Math.floor(retainedLength / 2);
+    return `${text.slice(0, headLength)}${marker}${text.slice(text.length - tailLength)}`;
+}
+export function codeBlock(text, language = "") {
+    const fenceSafe = text.replaceAll("```", "`\u200b``");
+    return `\`\`\`${language}\n${fenceSafe}\n\`\`\``;
+}
+export function asInlineCode(text) {
+    return `\`${text.replaceAll("`", "'")}\``;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/utils/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/utils/markdown.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,SAAS,GAAG,IAAI;IACzD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,SAAS,GAAG,IAAI,EAAE,MAAM,GAAG,SAAS;IAC/E,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7D,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IAClD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,QAAQ,GAAG,EAAE;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACtD,OAAO,SAAS,QAAQ,KAAK,SAAS,UAAU,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;AAC5C,CAAC"}

package/dist/utils/spawnCommand.js

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+export function prepareCommand(command, args, platform = process.platform, comspec = process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe") {
+    if (platform !== "win32")
+        return { command, args };
+    const commandLine = [command, ...args].map(quoteCmdToken).join(" ");
+    return { command: comspec, args: ["/d", "/s", "/c", commandLine] };
+}
+export function spawnStdioCommand(command, args, env) {
+    const prepared = prepareCommand(command, args);
+    return spawn(prepared.command, prepared.args, {
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+}
+function quoteCmdToken(value) {
+    if (value.length > 0 && !/[\s"&|<>^()%!]/.test(value))
+        return value;
+    return `"${value.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=spawnCommand.js.map

package/dist/utils/spawnCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawnCommand.js","sourceRoot":"","sources":["../../src/utils/spawnCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAuC,MAAM,oBAAoB,CAAC;AAOhF,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAc,EACd,QAAQ,GAAoB,OAAO,CAAC,QAAQ,EAC5C,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS;IAEjE,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACnD,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,IAAc,EACd,GAAsB;IAEtB,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE;QAC5C,GAAG;QACH,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC/B,WAAW,EAAE,IAAI;KAClB,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpE,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AAC5C,CAAC"}

package/dist/utils/taskTitle.js

@@ -0,0 +1,10 @@
+const MAX_TASK_TITLE_LENGTH = 120;
+export function normalizeTaskTitle(value) {
+    const normalized = value?.replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return undefined;
+    return normalized.length <= MAX_TASK_TITLE_LENGTH
+        ? normalized
+        : `${normalized.slice(0, MAX_TASK_TITLE_LENGTH - 3)}...`;
+}
+//# sourceMappingURL=taskTitle.js.map

package/dist/utils/taskTitle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskTitle.js","sourceRoot":"","sources":["../../src/utils/taskTitle.ts"],"names":[],"mappings":"AAAA,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,UAAU,kBAAkB,CAAC,KAAgC;IACjE,MAAM,UAAU,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAClC,OAAO,UAAU,CAAC,MAAM,IAAI,qBAAqB;QAC/C,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC;AAC7D,CAAC"}

package/docs/technical-reference.md

@@ -0,0 +1,294 @@
+# Agent Bot Technical Reference
+
+English | [简体中文](technical-reference.zh.md)
+
+This document covers deployment, configuration, runtime behavior, persistence, and integration details. For installation and everyday commands, start with the [README](../README.md).
+
+## Runtime Architecture
+
+Agent Bot is a Node.js 22+ ESM TypeScript application built around these components:
+
+- The supervisor owns the long-running service and restarts the worker.
+- The worker starts the configured Codex and ACP runtimes, Feishu transport, Console transport, local control server, and SQLite store.
+- Feishu events and Console input are normalized into the same task controller.
+- Presentation components maintain one progress card per turn and send the final Markdown response separately.
+- Codex agents use Codex App Server over stdio; other configured agents use ACP.
+
+Relevant source areas:
+
+| Area                | Responsibility                                                            |
+| ------------------- | ------------------------------------------------------------------------- |
+| `src/config/`       | YAML loading, environment expansion, validation, and path resolution      |
+| `src/cli/`          | Initialization, app registration, app auditing, and service/task commands |
+| `src/feishu/`       | Feishu WebSocket events, API calls, cards, images, and context keys       |
+| `src/runtime/`      | Shared runtime abstraction                                                |
+| `src/codex/`        | Codex App Server protocol integration                                     |
+| `src/acp/`          | ACP process and JSON-RPC integration                                      |
+| `src/proxy/`        | Tasks, turns, steering, queues, forks, and command execution              |
+| `src/presentation/` | Turn-state reduction and outbound routing                                 |
+| `src/state/`        | SQLite schema, migrations, routing, and delivery state                    |
+| `src/supervision/`  | Safe restart and restart notifications                                    |
+
+## User Data And Path Resolution
+
+The default user-data root is `~/.agent-bot`. `AGENT_BOT_HOME` replaces that root.
+
+| Default path                         | Contents                           |
+| ------------------------------------ | ---------------------------------- |
+| `~/.agent-bot/config.yaml`           | Main YAML configuration            |
+| `~/.agent-bot/.env`                  | Feishu credentials                 |
+| `~/.agent-bot/data/agent-bot.sqlite` | Persistent task and delivery state |
+| `~/.agent-bot/data/inbound-images/`  | Cached incoming images             |
+| `~/.agent-bot/logs/agent-bot.log`    | Structured runtime logs            |
+
+Configuration path precedence:
+
+1. CLI `--config <path>`
+2. `AGENT_BOT_CONFIG`
+3. `~/.agent-bot/config.yaml`
+
+The default `.env` is always loaded from the Agent Bot home. YAML values in the form `${NAME}` are expanded from the process environment after `.env` loading.
+
+Relative `storage.sqlitePath` and `logging.path` values resolve against the directory containing the loaded configuration file. `defaults.cwd` resolves against the process startup directory.
+
+## Initialization
+
+`agent-bot init` copies the packaged `config.example.yaml` and `.env.example` when their target files do not exist, creates the data and log directories, and restricts `.env` permissions where the platform supports POSIX modes.
+
+Credential behavior:
+
+- Environment values take precedence over values in `~/.agent-bot/.env`.
+- Both `FEISHU_APP_ID` and `FEISHU_APP_SECRET` are required.
+- Complete credentials are preserved unless `--reconfigure-feishu` is used.
+- An incomplete credential pair is rejected instead of being silently replaced.
+- Newly registered credentials are written atomically to `.env`.
+
+When credentials are absent, initialization uses Feishu one-click registration and reports its verification URL as text and a QR code. After registration, or when complete credentials already exist, it audits the currently published app version.
+
+Missing app configuration is handled in two stages:
+
+1. Core configuration is requested and polled until it becomes available.
+2. Remaining optional configuration is requested without blocking initialization.
+
+The generated authorization links do not contain the app secret.
+
+## Feishu App Requirements
+
+Core configuration required for basic messaging:
+
+- Bot capability
+- Persistent-connection event delivery
+- `im.message.receive_v1`
+- Tenant permissions for group @ messages and private messages
+- `im:message:send_as_bot` or a broader equivalent
+- `application:application:self_manage` so initialization can inspect the published version
+
+Optional configuration:
+
+| Configuration                         | Enabled behavior             |
+| ------------------------------------- | ---------------------------- |
+| `im:chat:create`                      | `/newgroup` and `/forkgroup` |
+| `im:chat:read`                        | Reading group metadata       |
+| `im.chat.updated_v1`                  | Group-title synchronization  |
+| `im:message.reactions:write_only`     | Processing-status reactions  |
+| Message-read and resource permissions | Incoming and outgoing images |
+| Image and chat permissions            | Generated group avatars      |
+| `card.action.trigger`                 | Interactive card actions     |
+
+Optional authorization failures are returned in the final initialization result with the affected feature names. Rerunning `agent-bot init` repeats the audit.
+
+## Configuration Model
+
+The complete example is [config.example.yaml](../config.example.yaml). The main sections are:
+
+```yaml
+feishu:
+  transport: "auto"
+  appId: "${FEISHU_APP_ID}"
+  appSecret: "${FEISHU_APP_SECRET}"
+  useConsoleWhenMissingCredentials: true
+
+console:
+  enabled: true
+
+agents:
+  codex:
+    kind: "codex"
+    title: "Codex"
+    command: "codex"
+    args: ["app-server", "--enable", "goals", "--listen", "stdio://"]
+    env: {}
+
+defaults:
+  agent: "codex"
+  cwd: "."
+
+storage:
+  sqlitePath: "./data/agent-bot.sqlite"
+
+logging:
+  level: "info"
+  path: "./logs/agent-bot.log"
+```
+
+`feishu.transport` accepts:
+
+- `auto`: use the SDK when credentials exist; otherwise follow `useConsoleWhenMissingCredentials`
+- `sdk`: require Feishu credentials and start the WebSocket client
+- `console`: disable Feishu transport
+
+At least one agent must be configured. `defaults.agent` must name a configured agent.
+
+## Agent Runtimes
+
+An agent with `kind: "codex"` uses Codex App Server. Agent Bot passes project directory, model, reasoning effort, permission mode, text input, and local images through the App Server protocol.
+
+An agent with `kind: "acp"`, or without a `kind`, is started as an ACP process. Agent-specific `env` values are added to its environment.
+
+Every agent process receives:
+
+```text
+AGENT_BOT=1
+```
+
+The bundled skill uses this variable to detect that it is running inside Agent Bot.
+
+## Chat Routing
+
+The message route determines the current task:
+
+- A private chat body is isolated by its Feishu chat ID.
+- A group timeline is isolated by its Feishu chat ID.
+- A message with a thread ID is isolated as its own thread context.
+- Console input uses a separate local context.
+
+Commands, card callbacks, progress cards, and final responses stay on the originating route.
+
+Starting a Feishu thread from a mapped user message, progress card, or final response forks from the associated completed Codex turn. If no reliable completed source turn exists, the operation fails instead of selecting an arbitrary point.
+
+`/forkgroup` has thread-aware source selection. An unbound thread, or a bound thread task with no completed turn of its own, forks directly from the thread's original anchor turn without creating an intermediate thread task. Once the thread task has completed a turn, `/forkgroup` uses its latest locally persisted completed turn. A newer active turn does not block the command and is excluded from the fork point.
+
+## Turn And Message Behavior
+
+- Plain text creates a task when the route has no current task.
+- Text received during an active Codex turn is sent through steering.
+- A steering race at turn completion becomes the next queued request.
+- `/nosteer` always creates a persistent FIFO queue item.
+- Queue card actions can cancel individual pending items.
+- Unknown slash commands are rejected and never forwarded as Prompts.
+
+Each turn owns one progress card. Normal updates are throttled to one every two seconds; critical updates have a 500 ms minimum gap. On completion, Agent Bot updates the progress card to a terminal state before sending a separate final Markdown message.
+
+After message deduplication, Agent Bot attempts an `OnIt` reaction. It replaces that reaction with `DONE`, `ERROR`, or `CrossMark` when the turn succeeds, fails, or is canceled. Reaction failures do not block task execution.
+
+Incoming rich-text images are downloaded into the inbound image cache and passed to Codex as `localImage` inputs. An image-only message uses the default Prompt `请分析这张图片。`. An ACP runtime that cannot accept image input returns an explicit error.
+
+## Tasks, Projects, And External Codex Work
+
+`/sessions` reads Codex tasks through `thread/list` and can discover tasks created by Codex Desktop, CLI, Agent Bot, or another App Server client under the same `CODEX_HOME`.
+
+Agent Bot keeps a local routing key for Feishu cards and delivery state, but presents the Codex task ID to users. It does not resume, steer, stop, or fork externally running Codex work without an explicit user action.
+
+Project behavior:
+
+- `/new --dir <path>` creates a project task.
+- `/new --nodir` creates a Projectless task.
+- `/new` inherits the current task's project or Projectless shape.
+- A first Projectless task is created under `~/Documents/Codex/<date>/<task-name>`.
+- An existing task's working directory is immutable.
+
+Forks use the latest available completed turn and do not interrupt an active source turn.
+
+## Persistence And Recovery
+
+SQLite stores:
+
+- Current and previous tasks for each route
+- Local and Codex task/thread identifiers
+- Model, reasoning effort, and permission mode
+- Queued Prompts
+- Progress snapshots and message bindings
+- Final-message delivery records
+
+On startup, Agent Bot reconciles persisted active work with Codex through `thread/read`. It also reconciles when turn identifiers change, terminal notifications arrive, or control requests fail.
+
+The final-delivery ledger prevents duplicate successful replies. App Server requests use finite timeouts so a stalled request cannot permanently occupy a message route.
+
+## Supervisor And Restart
+
+`agent-bot server start` starts a detached supervisor. The supervisor restarts the worker after unexpected exits and applies exponential backoff from one to 30 seconds after repeated crashes.
+
+A safe restart waits for:
+
+1. Active tasks to finish
+2. Final responses to be delivered
+3. A 15-second quiet inbound-message window
+
+New messages reset the quiet timer. `--immediate` and `--force` skip these checks. Exit code `75` identifies an intentional worker restart.
+
+The first safe-restart status card is delayed by three seconds so a task's final response can usually arrive first. Status changes during that window are coalesced into the initial card. The delay does not block scheduler polling, and shutdown flushes any pending card immediately.
+
+The local control server implements task mutations and service restart requests. Read-only task queries access SQLite directly.
+
+## Permission Modes
+
+- `auto`: Codex runs with `approvalPolicy=never` and `danger-full-access`.
+- `confirm`: approval requests are presented through card actions for one-time approval, session approval, denial, or task cancellation.
+
+Model, reasoning effort, permission mode, and project shape are inherited where applicable when creating or forking tasks.
+
+## Managed System Skill
+
+The packaged Agent Bot skill can be installed into the shared agent skill directory:
+
+```powershell
+agent-bot skills install
+agent-bot skills status
+agent-bot skills uninstall
+```
+
+The default target is `~/.agents/skills`. `AGENT_BOT_SKILLS_DIR` or `--target` selects another root. Installation is a managed copy; uninstall does not remove an unrelated same-named directory.
+
+## npm Package And Releases
+
+The public package is `@keyou007/agent-bot`; its executable remains `agent-bot`. The package uses a `files` allowlist so runtime code, templates, the managed skill, source code, and user-facing documentation are published without tests or internal design plans.
+
+`npm-shrinkwrap.json` is published with the CLI to keep transitive runtime dependencies reproducible. Direct runtime and development dependencies are also pinned to exact versions.
+
+Package lifecycle:
+
+- `prepublishOnly` runs type checking and the full test suite.
+- `prepack` builds a clean `dist/` and validates the tarball manifest.
+- `npm run package:smoke` packs the project, installs the tarball into a temporary directory, runs the CLI, and performs Console-only initialization.
+
+The first public release requires an npm account that owns the `@keyou007` scope:
+
+```powershell
+npm login
+npm ci
+npm run verify
+npm run package:smoke
+npm publish --access public
+```
+
+After the first release, configure an npm Trusted Publisher for:
+
+- GitHub owner: `keyou`
+- Repository: `agent-bot`
+- Workflow: `publish.yml`
+- Allowed action: `npm publish`
+
+The publish workflow is triggered by a GitHub Release whose tag exactly matches `v<package version>`. It uses GitHub OIDC instead of a long-lived npm token and publishes from a GitHub-hosted Node.js 24 runner.
+
+## Development And Source Installation
+
+```powershell
+npm ci
+npm run dev
+npm run typecheck
+npm test
+npm run build
+npm link
+```
+
+`npm link` registers the checkout's `agent-bot` executable globally. Without it, built CLI commands can be invoked through `npm run cli --`. `npm run dev` runs one foreground worker, while `npm start` runs the supervisor in the current terminal.