@seqyuan/ennote 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,40 @@
 # Ennote
 
-AI-native bioinformatics agent workspace.
+本地优先、可审计的 Agent 运行时，核心能力是 **Agent Flow**。
+
+Ennote 把长任务编排成可恢复的 Agent Flow：Task 图、Role 绑定、预算、审批、
+checkpoint 和恢复状态都持久化在本地 SQLite 中。它不依赖账号或云端即可启动、
+计算和保存结果；生信是参考工作流，而不是平台承诺。
+
+## 核心特点
+
+### Agent Flow
+
+- 用 Task 图表达依赖、分支、收敛和只读 fan-out，而不是把复杂流程塞进一条提示词。
+- Agent Flow 是不可变版本；每次运行冻结 Role、Skill、模型和权限配置。
+- 每个 Task 是独立子 Run，带自己的预算、审批和输出契约。
+- Task 的 `writes` 声明只影响调度（reader/writer lane 与 disjoint writers），**不是沙箱隔离边界**。
+- 串行执行、checkpoint 续跑、取消与恢复都已落地，并经过真实 Provider 验证。
+- Graph 编辑器、版本校验、导入/导出共用同一套文件格式。
+
+### 可审计执行
+
+- append-only Run 事件、commit-before-publish、durable SQLite 历史。
+- 危险工具调用走审批；支持 standing grants 与冻结的策略快照。
+- 失败/中断 Run 可恢复，Session 可 rewind 和 branch，不覆盖已有历史。
+- 每个请求、Run、审批和 Artifact 都有稳定的本地标识，便于回溯“谁在什么时候做了什么”。
+
+### 本地优先
+
+- `ennoworker` 只监听 loopback，`ennogate` 负责认证、静态 UI 和进程监督。
+- 没有账号、Relay 或 Connect Token 也能完整使用 localhost/LAN Web。
+- 云端不可用只会影响远程访问，不会停止 Worker、取消 Run 或删除数据。
+- LAN 访问默认关闭；需要显式开启，并优先使用 TLS。
+
+### 可组合
+
+- 不可变 Role、Skills、MCP 工具、typed Artifact 和托管委托。
+- 生信示例（`skills/bio-workspace`）展示如何把本地数据、shell 工具和 Agent Flow 组合起来。
 
 ## 架构
 
@@ -9,9 +43,12 @@ AI-native bioinformatics agent workspace.
 ```
 Browser → ennogate (Go, :45131) → ennoworker (Go, :0, loopback)
            守门人                     劳动者
-           认证 / 代理 / 静态文件       SQLite / Agent / 工具 / Skill
+           认证 / 代理 / 静态文件      SQLite / Agent Flow / 审批 / 工具 / Skill
 ```
 
+Worker 是 Project、Session、Message、Run、Attention、审批、Role/模型配置、
+Workspace、Artifact 和委托状态的唯一权威。Web UI 只是同一套 Worker API 的客户端。
+
 ## 快速开始
 
 ```bash
@@ -32,7 +69,56 @@ ennote start
 - npm 包（`@seqyuan/ennote`）只包含 CLI 脚本和编译后的静态前端（约 12 MB）。
 - 首次 `ennote start` 时，CLI 会从本仓库（[seqyuan/ennote](https://github.com/seqyuan/ennote)）的 GitHub Release 按当前平台/架构下载 Go 二进制（ennogate + ennoworker），缓存到 `~/.ennote/bin/`，后续启动不再下载。
 - 支持平台：linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64。
-- 发布流程：打版本 tag（`vX.Y.Z`）后，[release workflow](.github/workflows/release.yml) 自动构建四平台二进制、上传到该 tag 对应的 GitHub Release，并发布 npm 包。
+- 发布流程：打版本 tag（`vX.Y.Z`）后，[release workflow](.github/workflows/release.yml) 运行测试、构建四平台二进制、验证 npm 版本已生效，最后创建 GitHub Release。
+
+### 审查 Agent Pack
+
+`ennote pack inspect` 调用正在运行的 Worker 做只读审查：不安装、不执行、不验证签名、不写磁盘。
+
+```bash
+ennote pack inspect ~/Downloads/cell-qc.enpack      # 归档
+ennote pack inspect ~/src/cell-qc                  # 目录包（需含 pack.yaml）
+ennote pack inspect ~/Downloads/cell-qc.enpack --json      # 原始 inspect 结果
+ennote pack inspect ~/Downloads/cell-qc.enpack --documents # 附带 flow/role/skill 正文
+```
+
+输出包含 `manifestDigest`（`pack.yaml` 原始字节）和 `packDigest`（排序后的 payload 行，排除顶层 `pack.sig`）、flow/role/skill 摘要、能力信封与 warnings。`format: flow` 与 `format: graph` 会如实标注，不会被悄悄降级。Worker 未启动时命令直接失败并提示 `ennote start`，不做离线降级。
+
+### 安装 / 列出 / 卸载 Agent Pack
+
+安装同样只通过 loopback Worker 落盘，CLI 自己不做解析或写盘。
+
+```bash
+ennote pack install ~/Downloads/cell-qc.enpack --dry-run   # 只出计划，不写任何文件
+ennote pack install ~/Downloads/cell-qc.enpack             # 正式安装（可传目录包）
+ennote pack install ~/src/cell-qc --as-flow qc-review=cell-qc-review
+ennote pack list                                          # 已安装 Pack 摘要
+ennote pack remove seqyuan/cell-qc-review                 # 卸载
+ennote pack remove seqyuan/cell-qc-review --force          # 覆盖本地编辑 / 共享 Role 的拒绝
+```
+
+安装支持三种形态：Role-only Pack（每个 Role 变成 Worker 全局 Role 并发布 revision）、`format: graph` Flow Pack（未发布 revision 的 Graph draft + 其私有 Role/Skill）、以及 `format: flow` Agent Flow Pack（未发布 revision 的完整 FlowDefinition draft + 其 flow-local Role/Skill；安装前用真实 `agentflow.Validator` 校验 check/fan-out/terminal/next，不会降级成 graph）。非空 `mcp`、非空 `requires` 仍会被明确拒绝并返回稳定错误码，不会降级安装。dry-run 恒返回计划（含 blockers），正式安装遇到 blocker/冲突返回 422。
+
+安装后的 source 默认不可运行：`format: graph` 需要发布 Graph revision；`format: flow` 需要 `POST /v1/flows/{id}/publish` 发布 revision，再由 Project GraphBinding 显式启用。安装器永远不会自动发布或自动启用。
+
+### 从 v0.1.x 升级
+
+v0.1.x 的旧数据库（`data/ennote.db`）不再被读取，但也不会被删除：升级后首次启动会把它（含 `-wal`/`-shm`）原子移动到 `data/legacy-v1/` 并打印一条 `archived legacy V1 database` 警告。迁移完成后再次启动不会改动该归档。需要找回旧数据时，从 `data/legacy-v1/` 手动复制即可。
+
+### 局域网访问
+
+默认只监听 `127.0.0.1`。需要从局域网打开时：
+
+```bash
+# 推荐：TLS 终止在 ennogate，cookie 带 Secure
+ENNOTE_HOSTNAME=0.0.0.0 ENNOTE_ALLOW_LAN=1 \
+ENNOTE_TLS_CERT=/path/cert.pem ENNOTE_TLS_KEY=/path/key.pem ennogate
+
+# 不推荐：显式接受明文风险（密码和 7 天 cookie 会明文过网）
+ENNOTE_HOSTNAME=0.0.0.0 ENNOTE_ALLOW_LAN=1 ENNOTE_ALLOW_INSECURE_LAN=1 ennogate
+```
+
+非 loopback 地址在缺少 `ENNOTE_ALLOW_LAN=1` 时会拒绝启动；缺少 TLS 且没有 `ENNOTE_ALLOW_INSECURE_LAN=1` 时同样拒绝启动。
 
 ## 目录
 
@@ -46,33 +132,40 @@ ennoworker/
     config/           配置与环境变量
     domain/           领域类型和状态机
     events/           Durable EventWriter + 订阅 Hub
+    graphrun/         Agent Flow 执行与恢复
     llm/              Provider 接口、OpenAI-compatible、fake
     runs/             Run Coordinator（并发、取消、恢复）
     skills/           Skill bundle 加载与 per-run 快照
-    store/            SQLite、迁移、Repository
-    tools/            7 个文件/Shell 工具 + registry
+    store/            SQLite、Repository
+    tools/            文件/Shell/审批工具 + registry
     workspace/        Path jail、bubblewrap 沙箱
-  migrations/         SQL 版本化迁移
-
+  sessionmigrations/  Session SQL 版本化迁移
+  catalogmigrations/  Catalog 投影迁移
+  usagemigrations/    Usage 投影迁移
 app/                  Next.js 前端（React + SSE 消费）
 contracts/            OpenAPI 3.1 契约
 skills/               内置 Skill bundle
-docs/                 设计与实施计划
 ```
 
-## Roadmap
+## 当前重点
 
-当前开发状态、优先级和明确延期范围以 [`docs/roadmap.md`](docs/roadmap.md) 为唯一来源。`docs/plans/` 中的旧优先级仅保留为设计与实施历史。
+- Agent Flow 的可观测性、恢复语义和实际采用，而不是继续扩张产品表面。
+- Run 的可审计性、审批体验和本地留痕。
+- 本地优先与沙箱边界（bwrap 网络隔离、SandboxNone 的凭据保护）。
+- 生信作为参考工作流维护，不承诺 Warm Kernel、Notebook 或 Publication 工作台。
 
 ## 开发
 
 ```bash
 make dev          # 启动 ennogate + ennoworker
-make test-go      # Go 测试（含 -race）
+make test-go      # Go 测试（go test ./...）
 make test         # JS 测试
-make lint         # ESLint
+make lint         # ESLint + design token guard
 make typecheck    # tsc --noEmit
 make build        # 构建静态前端和本机 Go 产物
+npm run test:e2e  # Playwright
 npm run release:prepare   # 构建四个平台的发布包并检查 tarball
-npm run smoke:installed  # 安装临时 tarball 并验证双进程生命周期
+npm run smoke:installed   # 安装临时 tarball 并验证双进程生命周期
 ```
+
+CI 会在 Go 测试矩阵里额外运行 `-race`。

package/bin/ennote.js

@@ -16,6 +16,8 @@ const DEFAULT_PORT = "45131";
 const DEFAULT_HOSTNAME = "127.0.0.1";
 const START_TIMEOUT_MS = 45_000;
 const STOP_TIMEOUT_MS = 15_000;
+const PACK_INSPECT_TIMEOUT_MS = 15_000;
+const PACK_REQUEST_TIMEOUT_MS = 15_000;
 const GITHUB_RELEASES_BASE = "https://github.com/seqyuan/ennote/releases/download";
 
 function platformSuffix(platform = os.platform(), arch = os.arch()) {
@@ -54,6 +56,18 @@ function statePaths(home) {
   };
 }
 
+// workerStatePath is the owner-only handshake file ennoworker writes and
+// ennogate supervises (see internal/runtimeinfo.WorkerState).
+function workerStatePath(home) {
+  return path.join(home, "runtime", "worker-state.json");
+}
+
+function usageError(message) {
+  const error = new Error(message);
+  error.exitCode = 2;
+  return error;
+}
+
 function validateRuntime(paths) {
   for (const [name, file] of [["ennogate", paths.gate], ["ennoworker", paths.worker]]) {
     if (!fs.existsSync(file)) throw new Error(`Missing ${name} binary: ${file}`);
@@ -302,6 +316,9 @@ async function startService(options) {
       ENNOTE_HOME: home,
       ENNOTE_STATIC_DIR: runtime.staticDir,
       ENNOTE_WORKER_PATH: runtime.worker,
+      ...(fs.existsSync(path.join(packageDir, "skills"))
+        ? { ENNOTE_BUILTIN_SKILLS_DIR: path.join(packageDir, "skills") }
+        : {}),
       PORT: String(port),
       ENNOTE_HOSTNAME: hostname,
     },
@@ -362,6 +379,373 @@ async function serviceStatus(home) {
   return { running: healthy, healthy, pid: state.pid, url: state.url, port: state.port };
 }
 
+function isLoopbackHostname(hostname) {
+  const name = String(hostname ?? "").replace(/^\[|\]$/g, "").toLowerCase();
+  if (name === "localhost" || name === "::1") return true;
+  const match = name.match(/^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return Boolean(match) && match.slice(1).every(part => Number(part) <= 255);
+}
+
+// loadWorkerEndpoint reads the Worker handshake written by ennoworker and
+// refuses anything that is not a live loopback http Worker: ennote pack inspect
+// talks to the real Worker instead of re-implementing pack parsing in Node.
+function loadWorkerEndpoint(home) {
+  const file = workerStatePath(home);
+  if (!fs.existsSync(file)) {
+    throw new Error(`Ennote Worker is not running (${file} is missing). Start it with: ennote start`);
+  }
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`Ennote Worker state ${file} is unreadable. Restart it with: ennote restart`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(String(state?.url ?? ""));
+  } catch {
+    throw new Error(`Ennote Worker state ${file} has an invalid url: ${state?.url ?? ""}`);
+  }
+  if (parsed.protocol !== "http:") {
+    throw new Error(`refusing Worker url ${state.url}: expected http:`);
+  }
+  if (!isLoopbackHostname(parsed.hostname)) {
+    throw new Error(`refusing non-loopback Worker url ${state.url}`);
+  }
+  if (!isPidAlive(state.pid)) {
+    throw new Error(`Ennote Worker pid ${state.pid} is not running. Start it with: ennote start`);
+  }
+  if (typeof state.bootstrapToken !== "string" || state.bootstrapToken === "") {
+    throw new Error(`Ennote Worker state ${file} has no bootstrap token. Restart it with: ennote restart`);
+  }
+  return { url: parsed.origin, token: state.bootstrapToken, pid: state.pid, instanceId: state.instanceId };
+}
+
+function postJSON(url, body, headers, timeoutMs) {
+  return httpRequest("POST", url, body, headers, timeoutMs);
+}
+
+// httpRequest is the one place the CLI talks to the Worker. GET/DELETE carry no
+// body; POST serializes it. The Worker url is already pinned to loopback http by
+// loadWorkerEndpoint, so no transport negotiation happens here.
+function httpRequest(method, url, body, headers, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined || body === null ? null : Buffer.from(JSON.stringify(body), "utf8");
+    const request = http.request(url, {
+      method,
+      headers: payload
+        ? { "Content-Type": "application/json", "Content-Length": payload.length, ...headers }
+        : headers,
+    }, (response) => {
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve({
+        statusCode: response.statusCode ?? 0,
+        body: Buffer.concat(chunks).toString("utf8"),
+      }));
+    });
+    request.once("error", reject);
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`Worker request timed out after ${timeoutMs / 1000}s`));
+    });
+    request.end(payload ?? undefined);
+  });
+}
+
+// decodeWorkerResponse unwraps the Worker error envelope and the data envelope.
+// A 204 (pack remove) has no data and yields null.
+function decodeWorkerResponse(response, action) {
+  if (response.statusCode < 200 || response.statusCode >= 300) {
+    let message = `Worker returned HTTP ${response.statusCode}`;
+    let code;
+    try {
+      const parsed = JSON.parse(response.body);
+      code = parsed?.error?.code;
+      if (parsed?.error?.message) message = parsed.error.message;
+    } catch {
+      // A non-JSON error body keeps the status-only message.
+    }
+    const error = new Error(code ? `${message} (${code})` : message);
+    error.code = code;
+    error.statusCode = response.statusCode;
+    throw error;
+  }
+  if (response.statusCode === 204 || response.body.trim() === "") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(response.body);
+  } catch {
+    throw new Error(`Worker returned an unreadable ${action} response`);
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.data == null) {
+    throw new Error(`Worker returned an unexpected ${action} response`);
+  }
+  return parsed.data;
+}
+
+// requestJSON performs one authenticated Worker call. Every pack command except
+// install is GET/DELETE; install reuses postJSON so its body and headers stay in
+// one place.
+async function requestJSON(endpoint, method, pathname, options = {}) {
+  if (method === "POST") {
+    const response = await postJSON(
+      `${endpoint.url}${pathname}`,
+      options.body,
+      { Authorization: `Bearer ${endpoint.token}` },
+      options.timeoutMs ?? PACK_REQUEST_TIMEOUT_MS,
+    );
+    return decodeWorkerResponse(response, options.action ?? "pack");
+  }
+  const response = await httpRequest(
+    method,
+    `${endpoint.url}${pathname}`,
+    undefined,
+    { Authorization: `Bearer ${endpoint.token}` },
+    options.timeoutMs ?? PACK_REQUEST_TIMEOUT_MS,
+  );
+  return decodeWorkerResponse(response, options.action ?? "pack");
+}
+
+async function requestPackInspect(endpoint, target, options = {}) {
+  const body = {
+    source: { kind: "path", path: target },
+    includeDocuments: Boolean(options.documents),
+  };
+  if (options.expectedDigest) body.expectedDigest = options.expectedDigest;
+  const response = await postJSON(
+    `${endpoint.url}/v1/packs/inspect`,
+    body,
+    { Authorization: `Bearer ${endpoint.token}` },
+    options.timeoutMs ?? PACK_INSPECT_TIMEOUT_MS,
+  );
+  return decodeWorkerResponse(response, "inspect");
+}
+
+function formatPackSummary(data) {
+  const pack = data.pack ?? {};
+  const container = data.container ?? {};
+  const signature = data.signature ?? {};
+  const lines = [];
+  lines.push(`${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"})`);
+  if (pack.description) lines.push(pack.description);
+  lines.push(`Source:   ${data.source?.path ?? "?"} (${container.kind ?? "?"}, ${container.bytes ?? 0} bytes)`);
+  lines.push(signature.present
+    ? `Signature: ${signature.algorithm} at ${signature.path} — UNVERIFIED (inspect never verifies signatures)`
+    : "Signature: Unsigned");
+  lines.push(`Manifest: ${data.manifestDigest ?? "?"}`);
+  lines.push(`Pack:     ${data.packDigest ?? "?"}`);
+
+  const flows = data.flows ?? [];
+  lines.push(`Flows (${flows.length})`);
+  for (const flow of flows) {
+    lines.push(`  - ${flow.id} [${flow.format}] ${flow.taskCount} task(s), ${flow.checkTasks} check, ${flow.fanOutTasks} fan-out, ${flow.maxTotalTokens} tokens`);
+  }
+  const roles = data.roles ?? [];
+  lines.push(`Roles (${roles.length})`);
+  for (const role of roles) {
+    lines.push(`  - ${role.handle} (${role.scope}) ${role.authority}, tools: ${(role.allowedTools ?? []).join(", ") || "none"}`);
+  }
+  const skills = data.skills ?? [];
+  lines.push(`Skills (${skills.length})`);
+  for (const skill of skills) {
+    lines.push(`  - ${skill.kind === "external" ? skill.ref : skill.id} (${skill.kind})`);
+  }
+  // External MCP profile refs are reported but never resolved: the summary says
+  // so explicitly so a reviewer does not read the line as an installed profile.
+  const mcp = data.mcp ?? [];
+  if (mcp.length > 0) {
+    lines.push(`MCP (${mcp.length})`);
+    for (const profile of mcp) {
+      lines.push(`  - ${profile.ref} (external ref, not resolved or executed)`);
+    }
+  }
+  const envelope = data.capabilityEnvelope ?? {};
+  lines.push(`Checks:   ${(envelope.checkCommands ?? []).join(", ") || "none"}`);
+  lines.push(`Writes:   ${(envelope.writes ?? []).join(", ") || "none"}`);
+  lines.push(`Files:    ${data.filesTotal ?? 0}${data.filesTruncated ? " (truncated)" : ""}`);
+
+  const warnings = data.warnings ?? [];
+  lines.push(`Warnings (${warnings.length})`);
+  for (const warning of warnings) lines.push(`  - ${warning.code} (${warning.severity}): ${warning.message}`);
+  return lines.join("\n");
+}
+
+async function packCommand(home, positionals, values) {
+  const action = positionals[1];
+  const target = positionals[2];
+  if (action === "inspect") {
+    if (!target) {
+      throw usageError("Usage: ennote pack inspect <file|dir> [--json] [--documents]");
+    }
+    const endpoint = loadWorkerEndpoint(home);
+    const data = await requestPackInspect(endpoint, path.resolve(target), {
+      documents: values.documents,
+    });
+    if (values.json) console.log(JSON.stringify(data));
+    else console.log(formatPackSummary(data));
+    return;
+  }
+  if (action === "install") {
+    if (!target) {
+      throw usageError("Usage: ennote pack install <file|dir> [--dry-run] [--json] [--as-flow old=new] [--as-role old=new]");
+    }
+    // Renames are validated before the Worker is contacted, so a typo is a
+    // usage error instead of a refused install.
+    const renames = {
+      flows: parsePackRenames(values["as-flow"], "--as-flow"),
+      roles: parsePackRenames(values["as-role"], "--as-role"),
+    };
+    const endpoint = loadWorkerEndpoint(home);
+    const plan = await requestPackInstall(endpoint, path.resolve(target), {
+      dryRun: Boolean(values["dry-run"]),
+      renames,
+    });
+    if (values.json) console.log(JSON.stringify(plan));
+    else console.log(formatPackInstallPlan(plan, { dryRun: Boolean(values["dry-run"]) }));
+    return;
+  }
+  if (action === "list") {
+    const endpoint = loadWorkerEndpoint(home);
+    const summaries = await requestJSON(endpoint, "GET", "/v1/packs", { action: "pack list" });
+    if (values.json) console.log(JSON.stringify(summaries ?? []));
+    else console.log(formatPackList(summaries ?? []));
+    return;
+  }
+  if (action === "remove") {
+    if (!target) {
+      throw usageError("Usage: ennote pack remove <publisher>/<name> [--force] [--json]");
+    }
+    const packId = parsePackID(target);
+    const endpoint = loadWorkerEndpoint(home);
+    const [publisher, name] = packId.split("/");
+    const query = values.force ? "?force=1" : "";
+    const pathname = `/v1/packs/${encodeURIComponent(publisher)}/${encodeURIComponent(name)}${query}`;
+    // A 204 carries no body; the CLI still reports the same shape as --json so
+    // scripts do not have to special-case the empty response.
+    const data = (await requestJSON(endpoint, "DELETE", pathname, { action: "pack remove" })) ?? {
+      packId,
+      removed: true,
+    };
+    if (values.json) console.log(JSON.stringify(data));
+    else console.log(`Removed ${data.packId ?? packId}${values.force ? " (forced)" : ""}`);
+    return;
+  }
+  throw usageError(
+    `Unknown pack command: ${action ?? ""}\nUsage: ennote pack <inspect|install|list|remove> ...`,
+  );
+}
+
+// parsePackRenames turns repeated --as-flow/--as-role old=new flags into the
+// renames object. A rename only changes the installed store id.
+function parsePackRenames(entries, flag) {
+  const renames = {};
+  for (const entry of entries ?? []) {
+    const text = String(entry);
+    const separator = text.indexOf("=");
+    if (separator <= 0 || separator === text.length - 1) {
+      throw usageError(`${flag} expects old=new, got ${text}`);
+    }
+    const from = text.slice(0, separator).trim();
+    const to = text.slice(separator + 1).trim();
+    if (from === "" || to === "") throw usageError(`${flag} expects old=new, got ${text}`);
+    if (Object.prototype.hasOwnProperty.call(renames, from) && renames[from] !== to) {
+      throw usageError(`${flag} maps ${from} twice (${renames[from]} and ${to})`);
+    }
+    renames[from] = to;
+  }
+  return renames;
+}
+
+// parsePackID validates <publisher>/<name> before it goes on the wire: a bad id
+// is a usage error, not a Worker 400/404.
+function parsePackID(value) {
+  const segments = String(value).split("/");
+  if (segments.length !== 2 || segments.some(segment => segment === "" || segment === "." || segment === "..")) {
+    throw usageError(`pack id must be <publisher>/<name>, got ${value}`);
+  }
+  return segments.join("/");
+}
+
+async function requestPackInstall(endpoint, target, options = {}) {
+  const body = { source: { kind: "path", path: target }, dryRun: Boolean(options.dryRun) };
+  const renames = options.renames ?? {};
+  const encoded = {};
+  if (Object.keys(renames.flows ?? {}).length > 0) encoded.flows = renames.flows;
+  if (Object.keys(renames.roles ?? {}).length > 0) encoded.roles = renames.roles;
+  if (Object.keys(encoded).length > 0) body.renames = encoded;
+  return requestJSON(endpoint, "POST", "/v1/packs/install", { body, action: "pack install" });
+}
+
+function formatPackActionCounts(actions) {
+  const counts = new Map();
+  for (const action of actions) {
+    counts.set(action.action, (counts.get(action.action) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, count]) => `${count} ${name}`)
+    .join(", ");
+}
+
+function formatPackInstallPlan(plan, options = {}) {
+  const pack = plan?.pack ?? {};
+  const lines = [];
+  const headline = plan?.reinstall === "noop"
+    ? "Already installed"
+    : options.dryRun ? "Dry run (nothing written)" : "Installed";
+  lines.push(`${headline}: ${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"})`);
+  lines.push(`Manifest: ${plan?.manifestDigest ?? "?"}`);
+  lines.push(`Pack:     ${plan?.packDigest ?? "?"}`);
+
+  const actions = plan?.actions ?? [];
+  lines.push(`Actions (${actions.length}): ${formatPackActionCounts(actions) || "none"}`);
+  for (const action of actions) {
+    const scope = action.scope ? ` (${action.scope})` : "";
+    lines.push(`  - ${action.action} ${action.kind} ${action.storeId}${scope}`);
+  }
+
+  const state = plan?.state;
+  if (state) {
+    lines.push(`State:    ${state.installState ?? "?"}; flows ${state.flows?.length ?? 0}, roles ${state.roles?.length ?? 0}, skills ${state.skills?.length ?? 0}`);
+    const drafts = (state.flows ?? []).filter(flow => !flow.publishedRevision);
+    if (drafts.length > 0) {
+      lines.push(`Disabled: ${drafts.map(flow => flow.storeId).join(", ")} (draft Graph, no published revision — publish it to enable runs)`);
+    }
+    if (state.source?.path) lines.push(`Source:   ${state.source.path}`);
+    const external = state.externalRefs ?? {};
+    const externalSkills = external.skills ?? [];
+    const externalMcp = external.mcp ?? [];
+    if (externalSkills.length > 0 || externalMcp.length > 0) {
+      lines.push(`Recorded (not installed): skills ${externalSkills.join(", ") || "none"}; mcp ${externalMcp.join(", ") || "none"}`);
+    }
+  } else if (options.dryRun) {
+    lines.push("State:    not written (dry run)");
+  }
+
+  const blockers = plan?.blockers ?? [];
+  lines.push(`Blockers (${blockers.length})`);
+  for (const blocker of blockers) {
+    lines.push(`  - ${blocker.code} (${blocker.severity ?? "error"}): ${blocker.message}`);
+  }
+  const warnings = plan?.warnings ?? [];
+  lines.push(`Warnings (${warnings.length})`);
+  for (const warning of warnings) {
+    lines.push(`  - ${warning.code} (${warning.severity ?? "warning"}): ${warning.message}`);
+  }
+  return lines.join("\n");
+}
+
+function formatPackList(summaries) {
+  if (summaries.length === 0) return "No Agent Packs installed.";
+  const lines = [`Installed Agent Packs (${summaries.length})`];
+  for (const summary of summaries) {
+    const pack = summary.pack ?? {};
+    lines.push(`  - ${pack.name ?? "(unnamed pack)"} (${pack.id ?? "?"}@${pack.version ?? "?"}) ${summary.installState ?? "?"}`);
+    lines.push(`    flows ${summary.flowCount ?? 0}, roles ${summary.roleCount ?? 0}, skills ${summary.skillCount ?? 0}; installed ${summary.installedAt ?? "?"}`);
+  }
+  return lines.join("\n");
+}
+
 async function setPassword(home, reset) {
   const authFile = statePaths(home).auth;
   ensureDirectory(path.dirname(authFile));
@@ -397,11 +781,20 @@ Commands:
   logs            Show recent service logs
   passwd          Set the local password
   passwd --reset  Remove the local password and require setup
+  pack inspect    Inspect an Agent Pack (.enpack or directory) without installing
+  pack install    Install an Agent Pack from a .enpack file or directory
+  pack list       List installed Agent Packs
+  pack remove     Uninstall an Agent Pack (<publisher>/<name>)
 
 Options:
   --port, -p      Browser-facing port (default ${DEFAULT_PORT})
   --hostname, -H  Bind address (default ${DEFAULT_HOSTNAME})
-  --json          Machine-readable output
+  --json          Machine-readable output (prints the Worker data payload)
+  --documents     pack inspect: include flow, role, and skill source text
+  --dry-run       pack install: plan only and write nothing
+  --as-flow       pack install: old=new rename of an installed Graph id
+  --as-role       pack install: old=new rename of an installed Role handle
+  --force         pack remove: override local edits and shared global Roles
   --version, -v   Show version
   --help, -h      Show this help`);
 }
@@ -415,6 +808,11 @@ async function main(argv = process.argv.slice(2)) {
       port: { type: "string", short: "p", default: DEFAULT_PORT },
       hostname: { type: "string", short: "H", default: DEFAULT_HOSTNAME },
       json: { type: "boolean", default: false },
+      documents: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      "as-flow": { type: "string", multiple: true },
+      "as-role": { type: "string", multiple: true },
+      force: { type: "boolean", default: false },
       reset: { type: "boolean", default: false },
       version: { type: "boolean", short: "v", default: false },
       help: { type: "boolean", short: "h", default: false },
@@ -451,6 +849,11 @@ async function main(argv = process.argv.slice(2)) {
     case "passwd":
       result = await setPassword(home, values.reset);
       break;
+    case "pack":
+      // Every pack command talks to the running Worker instead of re-implementing
+      // manifest parsing, installation, or store writes in Node.
+      await packCommand(home, positionals, values);
+      return;
     default:
       throw new Error(`Unknown command: ${command}`);
   }
@@ -466,6 +869,7 @@ module.exports = {
   runtimeBinDir,
   runtimePaths,
   statePaths,
+  workerStatePath,
   serviceURL,
   validateRuntime,
   healthCheck,
@@ -478,12 +882,23 @@ module.exports = {
   stopService,
   serviceStatus,
   setPassword,
+  isLoopbackHostname,
+  loadWorkerEndpoint,
+  requestPackInspect,
+  formatPackSummary,
+  requestJSON,
+  requestPackInstall,
+  parsePackRenames,
+  parsePackID,
+  formatPackInstallPlan,
+  formatPackList,
+  packCommand,
   main,
 };
 
 if (require.main === module) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
   });
 }