@epoch-agent/cli 0.1.0

package/LICENSE

@@ -0,0 +1,219 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+--------------------------------------------------------------------------------
+
+epoch-agent
+Copyright 2024-2026 bowen
+
+Portions of this software are derived from the Gemini CLI
+(https://github.com/google-gemini/gemini-cli), Copyright 2025 Google LLC,
+licensed under the Apache License, Version 2.0. Those files have been modified;
+each one retains its original copyright notice and SPDX-License-Identifier
+header. See the NOTICE file in the project source repository for the complete
+list of derived files.
+
+This software also quotes, with attribution, two lines of prose from OpenAI
+Codex (https://github.com/openai/codex), Copyright 2025 OpenAI, licensed under
+the Apache License, Version 2.0. No source file is a derived work of Codex.
+See the NOTICE file for details.

package/README.md

@@ -0,0 +1,199 @@
+# @epoch-agent/cli
+
+CLI 入口。装了它才有 `epoch` 这个可执行文件。
+
+- ✅ **做**：commander 参数解析、TUI 启动、审批与信任的终端交互、输出格式化、
+  退出码、更新检查、shell 补全
+- ❌ **不做**：装配（在 [runtime](../runtime)）、领域逻辑（在 [core](../core)）、
+  渲染细节（在 [tui](../tui)）
+- **依赖**：[protocol](../protocol) + [infra](../infra) + [core](../core) +
+  [runtime](../runtime) + [server](../server) + [tui](../tui) +
+  `commander` + `@inquirer/prompts` + `ink` + `react`
+
+**命令的完整清单（含全局选项和每个子命令）在
+[docs/CLI.md](../../docs/CLI.md)**，这里不重复一遍——两处抄同一份清单必然漂。
+
+```bash
+epoch model              # 首次使用：交互式选 provider + 模型，key 写进 ~/.epoch/.env
+epoch doctor             # 装不上 / 跑不起来时第一个跑这个
+```
+
+没有 `epoch setup`，也没有 `epoch config init`——初始化就走 `epoch model`。
+
+## 文件
+
+| 文件 / 目录                   | 职责                                                                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`                    | commander 装配，每个子命令挂在这里                                                                                    |
+| `commands/run.ts`             | `epoch [query]`：判断走 TUI / 单次问答 / 长驻模式 / 读 stdin                                                          |
+| `commands/run-once.ts`        | 单次问答的输出（三种 `--output-format`）+ 收尾（后台任务摘要、退出码）                                                |
+| `commands/run-stream.ts`      | `text` 档两条流（模型正文 / 工具实时输出）在同一块屏幕上怎么交错：`createStreamWriter`                                |
+| `commands/run-flags.ts`       | 全局选项的解析（纯函数）：会话续接三态、格式、限额、审批器路径                                                        |
+| `commands/run-overrides.ts`   | **分流之前**那一步：所有带值 flag 的落地与校验都挂在 `applyRunFlags` 这一个入口（见下）                               |
+| `commands/sessions.ts`        | `epoch sessions`，同时是**会话续接的唯一实现处**：`-c` / `-r` 与 `sessions resume` 共用它的 id 解析                   |
+| `headless/`                   | 程序驱动那条路（方案 28）：见下面「headless 协议」                                                                    |
+| `commands/schedule.ts`        | `epoch schedule` 的命令注册（薄壳）                                                                                   |
+| `schedule/`                   | 定时任务那一族的实现：`add` / `view` / `run` / `manage` / `doctor`，`labels.ts` 是**码 → 文案的唯一出口**（见下）     |
+| `commands/*.ts`               | `config` / `mcp` / `model` / `status` / `sessions` / `trust` / `agents` / `plugin` / `upgrade` / `web` / `completion` |
+| `commands/web-open.ts`        | 跨平台打开浏览器（`start` / `open` / `xdg-open`）                                                                     |
+| `tui-entry.ts`                | TUI 启动：建 runtime、接 `AgentSession`、`renderApp()`                                                                |
+| `approval.ts`                 | 非 TUI 场景的终端审批交互                                                                                             |
+| `trust-prompt.ts`             | 工作区信任的首次询问                                                                                                  |
+| `import-prompt.ts`            | 指令文件引用项目**之外**的文件时的逐个询问（方案 33）                                                                 |
+| `files/`                      | `config.yaml` / `.env` 的读写（保留注释与格式）；以及 `epoch config schema` 写出的 `.epoch/schemas/*.json`            |
+| `errors.ts` / `exit-codes.ts` | 错误 → 人话 + 稳定退出码（CI 靠它判断）。别的包抛的「预期内失败」按 `err.name` 查一张表，不打 stack                   |
+| `update-check.ts`             | 后台查新版本，detached 子进程，不拖慢启动                                                                             |
+| `installation.ts`             | 判断安装方式（npm / pnpm / 本地），`epoch upgrade` 靠它给出正确命令                                                   |
+| `clipboard.ts`                | 读剪贴板里的**图片**（TUI 的 Ctrl+V）。放在 cli 是因为 tui 不该 spawn 子进程                                          |
+| `statusline.ts`               | 自定义状态栏：跑用户配的命令，第一行给 TUI（超时 2s / 截 60 字 / 失败保留旧值）。放 cli 同上：要 spawn                |
+| `worktree.ts`                 | `--worktree` 的 git 那一侧：建 worktree + 新分支、收尾时**有改动就不删**                                              |
+| `paths.ts` / `version.ts`     | CLI 侧的路径与版本号；`--version` 那三行也在 `version.ts`，**第一行必须是裸版本号**                                   |
+
+## 带值的 flag 在**分流之前**落地，其中九个走环境变量
+
+「分流」= `commands/run.ts` 里那句「没有 prompt 就起 TUI」。所有带值 flag 的落地
+与校验都排在它**前面**，入口只有一个：`commands/run-overrides.ts` 的
+`applyRunFlags`。**加新 flag 时挂进那一个函数。**
+
+这条规矩是修出来的（前因见
+[方案 28 验收记录第七章](../../docs/verify/VERIFY_RECORD-28-headless-protocol.md)）：`--provider` 的值校验原来住在 `runOnce`
+里、排在分流后面，而打错一个带值的 flag 必然让位置参数为空 —— 于是
+`epoch -p "跑一下测试"` 这类手滑永远走不到校验，一律表现为**静默进 TUI**，
+一个字都不说。
+
+九个走环境变量的（其余全局选项是解析成 `BuildRuntimeOptions` 的字段传下去的）：
+
+| 选项               | 环境变量               | 值                                   |
+| ------------------ | ---------------------- | ------------------------------------ |
+| `--settings`       | `EPOCH_SETTINGS`       | 绝对路径                             |
+| `--add-dir`        | `EPOCH_ADD_DIR`        | 绝对路径，按 `path.delimiter` 连起来 |
+| `--agent`          | `EPOCH_AGENT`          | 角色名原样                           |
+| `-m/--model`       | `EPOCH_MODEL`          | 模型 id                              |
+| `--fallback-model` | `EPOCH_FALLBACK_MODEL` | 模型 id                              |
+| `-p/--provider`    | `EPOCH_PROVIDER`       | 收窄过的 provider 名                 |
+| `--base-url`       | `EPOCH_BASE_URL`       | http(s) 地址                         |
+| `--permission`     | `EPOCH_PERMISSION`     | 收窄过的权限级别                     |
+| `-c` / `-r`        | `EPOCH_RESUME`         | 选中的会话 id                        |
+
+因为无参进 TUI 那条路**不经过 `runOnce`**——TUI 起的是另一个进程，选项对象过不去，
+只有环境变量带得过去。路径一律转**绝对**：子进程的 cwd 不保证一样。
+
+前八个在 action 一开头就落进 env，`launchTui` 那边 `{ ...process.env }` 白拿；
+只有 `EPOCH_RESUME` 要显式塞，因为它是**算出来的**（`-c` 要查库、`-r` 不带值
+要弹选择器）。加新 flag 时按这条分。
+
+取值是**开放集合**的那三个（`-m` / `--fallback-model` / `--base-url`）没有可选值
+清单可以对，所以判**字形**：模型 id 得是 ASCII 可见字符，base URL 得能被
+`new URL()` 解析且是 http(s)。卡得松是刻意的 —— 误伤一个合法模型名的代价是
+「那个模型压根用不了」，比放过一句话严重得多。
+
+反面例子是 `--worktree`：它**没有**对应的 `EPOCH_*`，因为它不是「传下去的一个设置」，
+而是父进程先 `chdir` 到新建的 worktree，子进程照常继承 cwd —— 落成环境变量的话
+父子两边都会各建一个。它的时序也是硬的：建 + `chdir` 必须排在 `--add-dir` 落地和
+`-c` 查会话**之后**，那两件事都以「用户敲命令的那个目录」为准，chdir 之后项目根就
+变成 worktree 了，它们会一起错，而且错得很安静（`-c` 查不到任何会话，于是默默开新的）。
+
+也因此 `launchTui()` 现在 **await 到子进程退出**才返回（以前是发射后不管，靠继承的
+stdio 让父进程自然活着）：worktree 的收尾得等 TUI 真的退出，否则会在用户还在里面
+打字的时候问他「要不要删这个 worktree」。
+
+`-c` / `-r` 还多一条：**选哪一段在父进程里就定完**（含 `-r` 不带 id 时的选择器）。
+ink 一接管 stdin，inquirer 就抢不回来 —— 和信任闸门必须排在 `renderApp` 之前是
+同一个约束。
+
+三处的「坏输入」都**报错退出**，不静默当没给：
+
+- `--settings` 文件不存在 / 不是合法 JSON → 静默降级的表现是「规则一条都没生效」，
+  在 CI 里正好等于「审批全部走默认」，是最不该悄悄发生的那种失败。
+  JSON 坏了这一半由 core 抛 `SettingsFileError`（错误里带行号）
+- `--add-dir` 指的目录不存在 / 不是目录 → 静默失效等于 agent 的地盘和用户想的不一样，
+  而这件事只在它拒绝读某个文件时才露头。「白给」（已经在工作区里了）不算错，
+  由运行时报一条诊断
+- `--agent` 名字不认识 → 由 **runtime** 抛 `AgentRoleError`（可用角色都在消息里）。
+  故意不在 CLI 侧先查一遍：三层角色表只有 `buildRuntime()` 合并得出来，
+  在这儿再发现一遍等于养第二份逻辑，而两份迟早会给出不同答案
+
+这三个错误加上 `ManagedPolicyError` 共用 `errors.ts` 里那张 `name → 退出码` 表，
+一律只打一行 message（有 hint 再一行）、**不打 stack**：那段 stack 指向别人包里的
+一行 throw，对着它排查纯属浪费。
+
+分层语义（谁压过谁、哪几层过信任闸门）见 [docs/SETTINGS.md](../../docs/SETTINGS.md)。
+
+## 单次问答的两条流
+
+流式模式下 stdout 与 stderr 各有分工，`createStreamWriter` 是唯一的出口：
+
+| 流       | 内容                                                     |
+| -------- | -------------------------------------------------------- |
+| `stdout` | **只有模型的回答**——`epoch "…" > a.txt` 必须是纯回答     |
+| `stderr` | 工具执行期间的实时输出（每行 `│ ` 前缀）、诊断、用量汇总 |
+
+两条流必须由同一个东西管：它们在终端里落到**同一块屏幕**上，各写各的就会互相插队。
+正文停在半行上时先补一个换行再插工具输出，否则 `pnpm build` 的几百行会怼在模型半
+句话后面。两种机器格式（`json` / `stream-json`）下这个 writer 一个字节都不写——
+它们的契约是 **stdout 只有协议内容**。
+
+实时输出**不进** `json` 的载荷：它的最终版本本来就在工具结果里，塞进去是重复的。
+`stream-json` 下它是协议的一部分（`tool-output-delta` 帧），所以也不再往 stderr
+抄一份带 `│ ` 前缀的。
+
+## headless 协议
+
+对外的完整说明在 **[docs/HEADLESS.md](../../docs/HEADLESS.md)**（含「什么时候该直接
+用库而不是走协议」）。线上的形状在
+[protocol/src/headless-wire.ts](../protocol/src/headless-wire.ts) —— 本目录只做编解码。
+
+| 文件                   | 职责                                                                      |
+| ---------------------- | ------------------------------------------------------------------------- |
+| `headless/emit.ts`     | 事件 → stdout 的一行 JSON。`seq` 编号、审批中继、artifact 的 base64 摘除  |
+| `headless/read.ts`     | stdin 的一行 → 入站事件 + **给人看的**错误信息（坏行跳过不杀进程）        |
+| `headless/outcome.ts`  | 收尾语义：报什么 `reason`、退什么码。单次问答与长驻模式**共用这一份**     |
+| `headless/driver.ts`   | 长驻模式的状态机：排队、审批往返、`abort` / `close`、宿主没了怎么收摊     |
+| `headless/session.ts`  | 长驻模式的装配（`interactive: true`、不问信任、不接交互式审批）           |
+| `headless/approver.ts` | `--permission-prompt-tool` 的子进程桥：喂 JSON、收裁决、答不出来一律拒绝  |
+| `headless/tasks.ts`    | 单次问答收尾时的后台任务摘要（措辞复用 core 的 `describeBackgroundTask`） |
+
+三条不许改回去的规矩，每一条都在对应文件的头注释里写了理由：
+
+1. **stdout 只有协议内容。** 混一行中文，`epoch "…" --json | jq` 当场碎
+2. **`seq` 的编号规则和 [server 的 hub](../server/src/hub.ts) 逐条一致** ——
+   `fixtures/wire/*.json` 那几份录像因此能同时当两边的夹具
+3. **宿主没了不等于用户拒绝。** 不许逐个 `respond('deny')`，要放弃就
+   `abandonApprovals()` + `abort()`（同 [runtime/src/serialize.ts](../runtime/src/serialize.ts)）
+
+## 定时任务的文案走**穷举的表**，不走模板字符串
+
+[`schedule/labels.ts`](src/schedule/labels.ts) 把每个码映射到一个 catalog key，
+写成 `Record<ScheduleIssueCode, string>` 而不是 ``t(`schedule.issue.${code}`)``。
+两条理由缺一不可：
+
+1. **少一条当场编译不过。** 模板字符串那种写法漏掉的表现是用户看到一行
+   `schedule.issue.xxx` 的 key 路径 —— 而那要等到有人真撞上那条校验才被发现。
+2. **catalog 的「死 key」检查扫的是字面量**（根 `__tests__/i18n-catalog.test.ts`）。
+   key 拼在模板里的话，那几十条文案会被判成死 key，然后下一个人照着报告删掉它们。
+
+`core` / `runtime` 那两层**一个中文都没有**：它们给的是 `ScheduleIssueCode`、
+`ScheduleRunStatus` 这种码和技术细节，人话全在这一层。判据同
+`SettingWriteRefused.reason` 那条「是码不是句子」。
+
+## Web UI 的产物不在这个包里
+
+`epoch web` 托管的前端产物随 [server](../server) 一起发（`<server 包>/dist/web`），
+本包**不再**拷一份——2026-08-14 之前它在 `cli/dist/web`，搬家的理由见
+[server/scripts/copy-web-assets.mjs](../server/scripts/copy-web-assets.mjs) 的头注释
+（一句话：嵌入宿主依赖的是 server，产物留在 cli 里等于它们拿不到界面）。
+
+所以本包的 `build` 就是一句 `tsup`，`epoch web` 也不再自己去探产物目录——
+不传 `webRoot`，由 `createWebServer()` 定位自带的那份。
+
+## 开发
+
+```bash
+pnpm epoch:dev --version        # tsx 直跑源码，不用 build
+pnpm epoch:dev doctor
+```
+
+> ⚠️ **`pnpm epoch:dev` 只有本包是源码。** [tui](../tui) / [runtime](../runtime) /
+> [core](../core) / [server](../server) 都是按 package.json 的 `exports` 从各自
+> **`dist/`** 解析的（没有 tsconfig paths 映射）。改了那些包不 `pnpm build` 就来测，
+> 测的是上一次的产物——而且 typecheck 也读 dist 的 `.d.ts`，两边一起骗你。

package/dist/chunk-3SCZQI5W.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// src/files/env-file.ts
+import { readFileSync } from "fs";
+import {
+  getSecretStore,
+  parseEnvText,
+  setEnvVarText,
+  writeEnvFile
+} from "@epoch-agent/infra";
+async function writeProviderKey(name, value, fallbackEnvPath) {
+  const store = getSecretStore();
+  if (!store) {
+    writeEnvFile(fallbackEnvPath, setEnvVarText(readOrEmpty(fallbackEnvPath), name, value));
+    return { backend: "plaintext", encrypted: false, detail: `\u660E\u6587\u5199\u5165 ${fallbackEnvPath}` };
+  }
+  await store.set(name, value);
+  return { backend: store.backend, encrypted: store.encrypted, detail: store.detail };
+}
+async function exportSecretsToEnv(store, envFilePath, names) {
+  let text = readOrEmpty(envFilePath);
+  const written = [];
+  for (const name of names) {
+    const value = await store.get(name);
+    if (!value) continue;
+    text = setEnvVarText(text, name, value);
+    written.push(name);
+  }
+  if (written.length > 0) writeEnvFile(envFilePath, text);
+  return written;
+}
+function readOrEmpty(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export {
+  parseEnvText,
+  setEnvVarText,
+  writeEnvFile,
+  writeProviderKey,
+  exportSecretsToEnv
+};

package/dist/env-file-JUOFDESY.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  exportSecretsToEnv,
+  parseEnvText,
+  setEnvVarText,
+  writeEnvFile,
+  writeProviderKey
+} from "./chunk-3SCZQI5W.js";
+export {
+  exportSecretsToEnv,
+  parseEnvText,
+  setEnvVarText as setEnvVar,
+  writeEnvFile,
+  writeProviderKey
+};

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * epoch-agent CLI 入口。
+ *
+ * ✅ 做：命令解析（commander）+ 终端输出 + 交互式审批
+ * ❌ 不做：模块装配（@epoch-agent/runtime）、领域逻辑（@epoch-agent/core）、
+ *        渲染（@epoch-agent/tui）
+ *
+ * 这个文件只负责组装 program 然后 parse，每个命令的实现在 commands/ 下。
+ * 原来是一个 356 行的文件，命令定义、配置读写、凭据探测、模型发现交互全混在
+ * 一起，还手抄了 4 份 provider 清单。
+ */
+/**
+ * `--help` / `--version` 只是打一段文本就退出，为它 spawn 一个 detached 子进程
+ * 纯属浪费。补全脚本会高频调 `epoch --help`，那更不该每次都起进程。
+ */
+declare function isMetaInvocation(argv: readonly string[]): boolean;
+
+export { isMetaInvocation };