@armadra/agent 0.0.0-stage → 0.2.1

package/docs/session-format.md

@@ -0,0 +1,119 @@
+# 会话文件格式（JSONL 条目树）
+
+会话是一个只追加的 JSONL 文件：首行是头，其后每行一个条目（以及可选的 `leaf` 行）。条目经 `parentId` 连成树，「当前分支」是从根到叶子的一条路径；发给模型的上下文由当前分支**投影**得到。类型定义在 `src/session/types.ts`（经 `@armadra/agent` 导出），格式版本 `SESSION_FORMAT_VERSION = 1`。设计依据见 [design.md](design.md) §8、§9。
+
+## 位置与文件
+
+- 目录：`--session-dir` > profile `sessionDir` > `<数据目录>/sessions`（数据目录缺省 `~/.local/share/ama`，`AMA_DATA_DIR` 可改）。
+- 文件：`<sessions>/<编码 cwd>/<ISO 时间>_<uuid>.jsonl`。编码 cwd = 去掉开头的分隔符，`/`、`\`、`:` 换成 `-`；ISO 时间里的 `:` 与 `.` 也换成 `-`。文件名里的 uuid 就是会话 id。
+- 延迟落盘：新会话先在内存里，首次模型请求前才建文件、写头与已缓存的条目；之前退出不留文件。
+- 只追加：每条记录一行 JSON + LF，以 O_APPEND 写入。打开时若末行是半行（写入中途崩溃），截掉半行再继续；中间行损坏 → 拒绝打开（`session_corrupt`，退出码 5），不猜测、不重写文件。
+- 单写者锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在时视为陈旧锁并接管。
+- `ama sessions prune [--older-than <天>]`（缺省 30 天）把文件移到 `<sessions>/.trash/`，文件名前缀删除时间；trash 里超过 7 天的再清理。
+
+## 头
+
+```json
+{
+  "type": "session",
+  "version": 1,
+  "id": "0b7f…",
+  "timestamp": "2026-10-02T08:00:00.000Z",
+  "cwd": "/home/me/proj",
+  "agent": { "name": "ama", "version": "0.1.0" },
+  "parentSession": "/…/上一个会话.jsonl"
+}
+```
+
+`parentSession` 只在 fork 与 `task` 子会话里出现，指向来源文件。读取时 `version` 不是 1 → 拒绝并提示升级 ama；缺头、头损坏、条目缺 `id` 或 `type`、出现第二个头 → 拒绝。
+
+## 条目
+
+全部条目都有 `id`、`parentId`（根条目为 `null`）、`timestamp`（ISO 8601）。
+
+| `type`                  | 字段                                                                                                 | 进上下文                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- |
+| `message`               | `message`：`system` / `user` / `assistant` / `toolResult` 四种 LLM 消息                              | 是                           |
+| `compaction`            | `summary`、`firstKeptEntryId`、`tokensBefore`、`usage?`、`details?`（`readFiles` / `modifiedFiles`） | 是，作为摘要消息             |
+| `branch_summary`        | `fromId`、`summary`、`usage?`、`details?`                                                            | 是，作为分支摘要消息         |
+| `context_edit`          | `targetId`、`replacement: string \| null`、`reason: prune \| abort \| retry \| overflow \| manual`   | 改写目标条目                 |
+| `model_change`          | `provider`、`modelId`                                                                                | 否（决定续会话时的模型）     |
+| `thinking_level_change` | `thinkingLevel`                                                                                      | 否（决定续会话时的思考级别） |
+| `custom`                | `customType`、`data`                                                                                 | 否                           |
+| `custom_message`        | `customType`、`content`（字符串或内容块）、`display`、`details?`                                     | 是，作为 custom 消息         |
+| `label`                 | `targetId`、`label?`（缺省 = 清除标签）                                                              | 否                           |
+| `session_info`          | `name?`                                                                                              | 否                           |
+| `usage`                 | `kind`、`provider`、`model`（不含 provider 的模型 id）、`usage`                                      | 否                           |
+
+### 消息
+
+- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → hooks → cwd → host`）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装全量。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
+- `user`：`content`、`origin?`（缺省 = 普通用户输入；`steer` / `followUp` 是运行中插话与排队，`host` 是宿主 `sendUser` 注入，其它字符串原样记录）。
+- `assistant`：`content`（文本 / 思考 / 工具调用块）、`api`、`provider`、`model`、`usage`、`stopReason`，以及可选的 `responseId`、`thinkingLevel`、`providerThinkingLevel`、`rawStopReason`、`errorMessage`。`usage` 是 `{ input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost?, cacheReported? }`：`input` 不含缓存部分，`cost` 是 `{ input, output, cacheRead, cacheWrite, total }`（美元，模型无价格时缺省），`cacheReported` 表示原始响应里出现过缓存字段。
+- `toolResult`：对应工具调用的结果（`toolCallId`、`toolName`、`content`、`isError`、`details?`）。
+
+### `usage` 条目
+
+不进上下文的请求用量，计入 `/session` 费用与 RPC 统计，投影时跳过。第一期只有 `kind: "cache_warm"`（缓存保温请求，见 [providers.md](providers.md)「缓存」）：
+
+```json
+{
+  "type": "usage",
+  "kind": "cache_warm",
+  "provider": "anthropic",
+  "model": "<model-id>",
+  "usage": {
+    "input": 1,
+    "output": 1,
+    "cacheRead": 12000,
+    "cacheWrite": 0,
+    "totalTokens": 12002,
+    "cost": { "input": 0, "output": 0, "cacheRead": 0.0036, "cacheWrite": 0, "total": 0.0036 }
+  },
+  "id": "…",
+  "parentId": "…",
+  "timestamp": "…"
+}
+```
+
+### `leaf` 行
+
+`/tree` 在同一文件里换叶子时追加一行 `{"type":"leaf","id":<条目 id 或 null>,"timestamp":…}`。它**不是条目**：没有 `parentId`，`get_entries` 与树不返回它，fork 不复制它。打开文件时，最后一条 `leaf` 行若在最后一条条目之后，就用它的 `id` 作叶子（`null` = 回到根之前的空分支）；之后又追加了条目则作废。
+
+`usage` 条目与 `leaf` 行都是 v1 的可选行，格式版本不升。
+
+## 投影
+
+当前分支 → 上下文消息（`src/session/projection.ts`）：
+
+1. **压缩**：分支上若有 `compaction`，取最新一条。上下文 = 该 compaction（作为摘要消息）+ `firstKeptEntryId` 到它之间的非 system 条目 + 它之后的全部条目。compaction 之前的 system 消息依次重放后折成一条完整的 system **检查点**放在最前（文件里不另存检查点）。
+2. **改写**：对分支上每个目标取最新一条 `context_edit`：`replacement` 为 `null` → 从上下文剔除；字符串 → 只换内容，保留角色与元数据（assistant 换成一个文本块，摘要类换 `summary`，system 不改）。用途：档一裁剪旧工具结果（`prune`）、中断（`abort`）、失败重试的尝试（`retry`）、溢出恢复（`overflow`）、手动（`manual`）。
+3. **映射**：`message` → 原消息；`custom_message` → `{ role: "custom", customType, content, display, details? }`；`compaction` → `{ role: "compactionSummary", summary, tokensBefore }`；`branch_summary` → `{ role: "branchSummary", summary, fromId }`；其余类型（含 `usage` 与未知类型）不进上下文。
+4. **模型与思考级别**：分支上最近的 `model_change` / `thinking_level_change`，续会话时据此恢复。
+
+发给模型前，`convertToLlm` 把三种扩展角色（custom、compactionSummary、branchSummary）转成 user 消息。
+
+## 分支与 fork
+
+- `/tree`：同一文件换叶子（落 `leaf` 行）；从旧位置再发消息就形成新分支。离开的分支可以写 `branch_summary` 带进新分支。
+- fork（`--fork <id>`、`/fork`、RPC `fork`）：把根 → 指定条目的分支复制到新文件，头的 `parentSession` 指回原文件；不复制 `leaf` 行。
+- `task` 子会话：独立文件，头带 `parentSession`，首条条目是 `custom{customType:"ama.task"}`。
+
+## custom 类型
+
+`custom` 不进上下文，`custom_message` 进上下文。ama 自己使用的 `customType`：
+
+| `customType`         | 条目类型         | 内容                                                                                | 写入时机                                                |
+| -------------------- | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `ama.todo`           | `custom`         | `data: { items: { id, text, status: pending \| in_progress \| done }[] }`，整表快照 | `todo` 工具 `set`；`get` 取分支上最近一条               |
+| `ama.task`           | `custom`         | `data: { parentToolCallId, description, parentSession? }`                           | `task` 子会话的首条条目                                 |
+| `ama.codemode-store` | `custom`         | `data: { entries }`，`store()` 的完整快照                                           | codemode 脚本成功结束且写过 store；读取取分支上最近一条 |
+| `ama.aborted`        | `custom_message` | `content`：告诉模型上一条回复被用户中断；`display: false`                           | 用户中断运行                                            |
+| `ama.hook_context`   | `custom_message` | `content`：UserPromptSubmit Hook 的 `additionalContext`；`display: false`           | 随用户提示进上下文                                      |
+
+其它程序（宿主、SDK 工具经 `ToolContext.session.appendCustom`）可以写自己的 `customType`；建议加前缀避免冲突，`ama.` 前缀保留给 ama。
+
+## 读取方
+
+- `ama sessions list|show`、交互模式 `/resume`、RPC `get_entries{since}`（以 entry id 为游标返回 `{ entries, leafId }`）、`get_tree`。
+- 嵌入方可以直接读文件：按行解析，首行为头，跳过 `type: "leaf"` 的行后按 `parentId` 建树；遇到不认识的条目类型保留但不进上下文。

package/docs/tui.md

@@ -0,0 +1,168 @@
+# 终端界面
+
+交互模式的使用说明，以及终端组件库 `@armadra/agent/tui` 的 API。设计依据见 [design.md](design.md) §12。
+
+`ama` 在终端里直接运行（stdin / stdout 都是 TTY、`TERM` 不是 `dumb`、没有 `--no-tui`）时进入交互模式。界面只用**主屏**：对话历史滚进终端回滚，不切备用屏，所以在 tmux 里 `capture-pane` 能读到完整对话，退出后对话也留在屏幕上。
+
+## 布局
+
+```
+ama 0.1.0 · Enter 发送 · Esc 中断 · Ctrl+C 两次退出 · /help 命令    ← 启动画面
+› 读一下 README                                                    ← 用户消息
+思考 · 120 token                                                    ← 思考块（折叠）
+● read  README.md                                                   ← 工具调用
+  …前 3 行结果…
+回答正文（Markdown）
+↳ followUp  之后再提交                                               ← 排队消息
+⠋ 工作中 · Esc 中断 (12s)                                            ← 运行中
+──────────────────────────────────
+输入框
+──────────────────────────────────
+anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0.12 · rebill $0.11 · ctx 34% · mode:default · preset:default
+```
+
+- **用户消息**：`›` 开头；运行中插话标 `↳ steer`，排到本轮之后的标 `↳ followUp`，宿主（Armadra 画布）注入的标 `↳ host`。
+- **思考块**：`ui.showThinking` = `collapsed`（缺省，一行计数）/ `full`（全文）/ `hidden`。
+- **工具调用**：一行标题，圆点运行中为强调色、成功绿、失败红；折叠显示结果前 3 行，`edit` 显示 diff（前 12 行），`bash` 运行中滚动显示最后 8 行。`Ctrl+O` 展开 / 折叠全部。codemode 脚本里的内层调用挂在外层调用下面。
+- **提示**：压缩摘要卡、`↻ 重试 n/m`、`⛔ Hook 阻止`、宿主通知、审批被拒或超时的说明都进消息区。
+- **状态栏**：模型 · 思考级别 · `↑` 输入（含缓存读写）`↓` 输出 · 缓存 · 费用 · 重计费 · 上下文占用 · 排队数 · 权限模式 · codemode · 工具预设 · 宿主状态。终端太窄时依次丢弃宿主状态、预设、重计费、费用、缓存、token、思考级别、排队数、codemode，模型、上下文与权限模式最后丢。
+
+## 缓存与上下文
+
+状态栏各项：
+
+| 项              | 含义                                                                                                                |
+| --------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `cache 83%`     | **最近一次**请求的命中率（读缓存 /（输入 + 缓存读 + 缓存写））；会话累计在 `/session`                               |
+| `cache —`       | 端点还没报过缓存（`unknown`：还没有足够长的可比请求）                                                               |
+| `cache 未报告`  | 端点不报缓存（`silent`：连续 3 个可比请求读写都是 0，或 `compat.cacheReporting: "silent"`）；这类请求不进命中率分母 |
+| `♨`             | 保温计时中（工具长时间运行时按 TTL 重放前缀，`/cache warm` 可切换）                                                 |
+| `rebill $0.11`  | 本会话缓存未命中导致的重计费金额；模型没有价格时显示 token 数；为 0 不显示                                          |
+| `ctx 72%`       | 上下文占用，≥ 70% 黄色、≥ 90% 红色；`ctx ?` 表示模型没有窗口信息                                                    |
+| `codemode:only` | codemode 生效（`on` / `only`）；运行时 Node 的权限模型不隔离网络（Node 22 / 24）时追加红色 `net!`                   |
+
+消息区（line 模式写 stderr，前缀 `ama: `）只在两种情况下提示一行，`cache.missNotices: false` 可关：
+
+- 一次未命中重计费 ≥ 20k token 或 ≥ $0.10：`缓存未命中（空闲 7 分钟后）：重计费 38.2k token（约 $0.11）`。原因有空闲超时、子任务运行、切换模型、系统提示 / 工具表变化、服务端淘汰；更小的未命中只进统计。
+- 上下文占用跨过 70% / 90%（各一次）：`上下文已用 72%，约剩 9 回合（按最近 5 回合均值）`；回合数估不出时给余量 token。
+- line 模式在 `AMA_LOG=info` 时另写保温成功：`缓存保温已刷新（读 12k token，$0.001）`。
+
+`/session` 在会话信息之后有「缓存」段，`/cache` 只显示这一段：
+
+```
+缓存
+  输入      3.4k = 缓存读 2.2k（65%）+ 未缓存 1.2k
+  报告状态  reported
+  命中率    最近 84% · 会话 65%
+  未命中    0 次
+  保温      streaming · 已停止：模型目录没有缓存 TTL
+  上下文    1%，余量 ≈ 127k token ≈ 2443 回合
+```
+
+未命中行按原因分列（`3 次，重计费 61k token ≈ $0.18（空闲超时 2 · 前缀变化 1）`）；保温行在计时中显示 `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05`，停止时给原因；有 task 子会话时另有「子任务」行。
+
+- `/cache warm off|streaming|idle`：本会话内切换保温（不写配置；`idle` 在空闲时也保温，适合贵模型）。
+- `/cache fingerprint`：最近一次真实请求的前缀指纹——system 与工具表各一个 16 位哈希加模型名。两次之间哈希变了，就是宿主或 Hook 中途改了系统提示 / 工具表。
+
+取舍：状态栏显示最近一次命中率（会话累计放 `/session`）；`cache.missNotices` 缺省开（门槛下很少触发）；`Meter` 组件不进缺省状态栏。命中率、未命中与保温的判定规则见 [providers.md](providers.md)「缓存」。
+
+`ama models cache-probe <provider/model>` 用一个固定前缀相隔几秒发两次最小请求，判定端点 `reported` / `silent` / `inconclusive` 并给出配置建议（会计费：先打印预估，非交互环境需 `--yes`）。
+
+## 按键
+
+| 按键                 | 作用                                                               |
+| -------------------- | ------------------------------------------------------------------ |
+| Enter                | 发送；运行中 = steer（插到当前轮）                                 |
+| Alt+Enter            | 运行中排到本轮之后（followUp）；空闲时等同 Enter                   |
+| Shift+Enter / Ctrl+J | 换行                                                               |
+| Esc                  | 中断：排队的消息回填到输入框，然后停止当前运行；补全打开时先关补全 |
+| Alt+↑                | 取回最后一条排队消息                                               |
+| Shift+Tab            | 循环权限模式 plan → default → auto-edit → full-auto                |
+| Ctrl+O               | 展开 / 折叠工具输出                                                |
+| Ctrl+L / Ctrl+T      | 选择模型 / 思考级别                                                |
+| Ctrl+C               | 清空输入；输入为空时 1.5 秒内再按一次退出（退出码 130）            |
+| Ctrl+D               | 输入为空时退出                                                     |
+| Tab                  | 补全                                                               |
+| ↑ / ↓                | 单行时浏览历史（`<数据目录>/history`，500 条）                     |
+
+按键可在 `~/.config/ama/keybindings.json` 覆盖，键是动作 id（`app.interrupt`、`app.message.followUp`、`tui.editor.newLine` ……），值是按键或按键数组，空数组表示禁用。
+
+## 命令
+
+`/help` 列出全部命令。交互模式另有：
+
+- `/tree`：列出会话里的全部用户消息（分叉处缩进，`●` 是当前分支）；选中一条后回到它之前，原文回填输入框，修改后发送就形成新分支。
+- `/fork`（无参数）：同样选一条用户消息，从它之前复制出新会话。
+- `/model`、`/resume`、`/permission`、`/thinking` 不带参数时打开选择器；`/permissions` 显示权限判定顺序与已加载规则。
+- `/session`、`/cache`：会话用量与缓存统计（见下文「缓存与上下文」）。
+
+## 补全
+
+- 首行行首输入 `/`：命令、提示模板（`/<名字>`）、Skill（`/skill:<名字>`）。
+- `@`（行首或空格之后）：当前目录下的文件与目录（尊重 `.gitignore`），含 `*` `?` `[` `{` 时按 glob 匹配相对路径。
+
+## 审批
+
+工具调用需要确认时，底部弹出对话框：bash 显示完整命令，write 显示路径与行数，edit 显示每处修改的 −/+ 摘要；子 Agent 发起的请求标 `[task]`。`y` 允许、`n` / Esc 拒绝、`a` 本会话内同类不再询问、`v` 查看完整输入。10 分钟不作答按拒绝处理（`AMA_APPROVAL_TIMEOUT_MS` 可改）。
+
+输入摘要之后是**执行前预览**：这一步会碰到什么。
+
+- bash：识别每段命令（含 `sh -c`、`eval`、`xargs`、`find -exec` 里嵌套的命令）中的 `rm` / `rmdir` / `unlink`、`mv`、`git clean`、`git checkout -- <路径>`、`git reset --hard` 与 `>` / `>>` 重定向目标，列出路径是否存在、大小、目录里的文件数；通配符与变量不展开，原样显示并提示实际范围可能更大。
+- write：目标是否存在、现有行数与大小 → 新内容；覆盖本会话没读过的文件标黄。
+- edit：对原文干跑一遍，列出每处 −n/+m 行与总变化；匹配不到或不唯一时提前说明。
+
+预览按严重度着色（危险红、警告黄、其余暗色），只读、有上限：每个目录最多计 2000 项，整次预览 200 ms 预算，超出只给提示、不降低严重度；超过 2 MiB 的文件只报大小。预览失败不影响审批。line 模式在问句之前逐行打印同样的预览；RPC 客户端从 `permission_request.preview` 拿到它（[rpc.md](rpc.md)「审批」）。
+
+## 启动画面
+
+`ui.quietStartup` / `--quiet-startup`：`normal` 显示标题、模型、目录与信任状态、已加载的上下文文件 / Skill / 提示模板 / Hook；`header` 只有标题行（profile 缺省）；`silent` 不显示。`--resume` 不带 id、模型没有 key、会话目录不存在、项目资源需要信任时，界面启动前会先出现一个小的选择 / 输入提示，答完收成一行留在屏幕上。
+
+## 在 tmux / Armadra 终端节点里
+
+- 括号粘贴：启动时开启；粘贴的多行内容整体进入输入框（超过 10 行或 1 000 字符折叠为 `[paste #N +M lines]`），粘贴后紧跟的回车直接发送，适合由外部程序写入。
+- 不查询终端能力、不开鼠标与 Kitty 键盘协议，避免回包混进输入；tmux ≥ 3.4 透传同步输出，旧版本也能正常显示。
+- 窗口尺寸变化时整屏重画最后一屏，回滚里的历史不受影响。
+- 自动降级：非 TTY、`TERM=dumb`、`--no-tui` 或终端初始化失败时使用行式界面，命令与审批问答相同。
+
+## 组件库（`@armadra/agent/tui`）
+
+交互模式用的终端组件单独导出，零依赖，宿主或其它 Node 程序可以直接用来画主屏界面。
+
+```ts
+import { TUI, ProcessTerminal, Text, Editor, createTheme } from "@armadra/agent/tui";
+
+const tui = new TUI(new ProcessTerminal());
+const theme = createTheme("dark");
+const log = new Text("");
+const editor = new Editor({
+  theme,
+  requestRender: () => tui.requestRender(),
+  onSubmit: (text) => {
+    log.setText(`you said: ${text}`);
+    tui.requestRender();
+  },
+});
+tui.addChild(log);
+tui.addChild(editor);
+tui.setFocus(editor);
+tui.start();
+```
+
+| 导出                                                                        | 作用                                                                                                                                 |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `Component`、`Focusable`、`CURSOR_MARKER`                                   | 组件契约：`render(width)` 返回各行（每行可见宽 ≤ width）、`handleInput?(data)`、`invalidate()`；获焦组件在光标处输出 `CURSOR_MARKER` |
+| `TUI`                                                                       | 根容器与差分渲染（主屏、同步输出）：`addChild`、`start` / `stop`、`requestRender`、`setFocus`、`addInputListener`、`showOverlay`     |
+| `ProcessTerminal`、`MemoryTerminal`、`VirtualScreen`                        | 真实终端（raw 模式、括号粘贴）；内存终端与 VT 屏幕（测试、帧黄金）                                                                   |
+| `Container`、`Text`、`TruncatedText`、`Markdown`、`Box`、`Spacer`、`Loader` | 基础组件                                                                                                                             |
+| `Editor`、`EditorBuffer`、`PasteStore`                                      | 多行编辑器（历史、补全接口 `AutocompleteProvider`、粘贴折叠）                                                                        |
+| `SelectList`                                                                | 可过滤的选择列表                                                                                                                     |
+| `KeyValue`、`Meter`                                                         | 两列对齐的键值表；进度条                                                                                                             |
+| `compositeOverlays`、`OverlayOptions`                                       | 覆盖层合成（居中 / 底部锚定）                                                                                                        |
+| `createTheme`、`plainTheme`、`detectCapabilities`、`Theme`                  | 主题与颜色能力探测（`NO_COLOR`、16 / 256 / truecolor）；11 个语义色                                                                  |
+| `Keybindings`、`DEFAULT_KEYBINDINGS`、`loadKeybindingsFile`                 | 动作 id → 按键，`keybindings.json` 覆盖                                                                                              |
+| `parseKey`、`matchesKey`、`StdinBuffer`                                     | 键序列解析与 Esc 超时切分（`AMA_TUI_ESC_TIMEOUT`）                                                                                   |
+| `visibleWidth`、`truncateToWidth`、`wrapTextWithAnsi`、`sliceByColumn` 等   | 带 ANSI 与宽字符的宽度计算与截断                                                                                                     |
+
+## 测试
+
+`src/modes/interactive/interactive-mode.test.ts` 用 `MemoryTerminal`（80x24、40x24）+ fake 供应商跑一次完整的读文件 run，把启动、输入、工具运行中、结束、`Ctrl+O` 展开、退出各帧写进 `test/fixtures/tui/run-*.txt`。改界面后用 `AMA_UPDATE_GOLDEN=1 pnpm vitest run src/modes/interactive` 更新并审阅差异。

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@armadra/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "可独立使用、可嵌入 Armadra 的编码 / 协调 Agent",
+  "type": "module",
+  "keywords": [
+    "coding-agent",
+    "agent",
+    "ai",
+    "llm",
+    "cli",
+    "tui",
+    "anthropic",
+    "openai",
+    "claude",
+    "deepseek",
+    "codemode",
+    "prompt-cache",
+    "sdk",
+    "armadra"
+  ],
+  "homepage": "https://github.com/Owlbay/armadra-agent#readme",
+  "bugs": {
+    "url": "https://github.com/Owlbay/armadra-agent/issues"
+  },
+  "author": "YoVinchen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Owlbay/armadra-agent.git"
+  },
+  "bin": {
+    "ama": "dist/cli/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    },
+    "./bundle": "./dist/bundle/ama.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs/rpc.md",
+    "docs/host-api.md",
+    "docs/hooks.md",
+    "docs/providers.md",
+    "docs/codemode.md",
+    "docs/tui.md",
+    "docs/session-format.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/cli/main.js",
+    "./dist/codemode/sandbox-entry.js",
+    "./dist/bundle/*.cjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "pnpm build:lib && pnpm build:bundle",
+    "build:lib": "tsc -p tsconfig.build.json",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "AMA_E2E=1 vitest run test/e2e",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
+    "check:deps": "node scripts/check-no-deps.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "bench:presets": "node scripts/bench-presets.mjs",
+    "bench:cache": "node scripts/cache-experiment.mjs",
+    "ci": "pnpm typecheck && pnpm fmt:check && pnpm check:deps && pnpm release:check && pnpm test && pnpm build && node dist/bundle/ama.cjs --version"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "esbuild": "^0.28.2",
+    "prettier": "^3.9.9",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "packageManager": "pnpm@11.18.0"
+}