pi-ultracode 0.10.3 → 0.10.4

package/README.md

@@ -57,18 +57,18 @@ Pi decides whether a workflow is useful. Small tasks can still use the normal si
 
 Useful commands:
 
-| Command | Action |
-| --- | --- |
-| `/ultracode` | Enable `auto` from off; disable any active mode |
-| `/ultracode auto` | Let the parent choose depth using the task and context |
-| `/ultracode focused` | Use fixed depth for bounded work with direct local verification |
-| `/ultracode standard` | Use fixed depth for independent dimensions or competing hypotheses, with targeted verification |
-| `/ultracode deep` | Use fixed depth for interacting constraints or critical invariants, with independent evidence and counterexample checks |
-| `/ultracode off` | Disable it without changing the parent effort |
-| `/ultracode status` | Show the configured mode and its applicability / verification requirements |
-| `/workflows` or `F6` | Open the workflow browser |
-| `/workflows <runId>` | Open a specific run |
-| `/workflows abort` | Abort active runs |
+| Command               | Action                                                                                                                  |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `/ultracode`          | Enable `auto` from off; disable any active mode                                                                         |
+| `/ultracode auto`     | Let the parent choose depth using the task and context                                                                  |
+| `/ultracode focused`  | Use fixed depth for bounded work with direct local verification                                                         |
+| `/ultracode standard` | Use fixed depth for independent dimensions or competing hypotheses, with targeted verification                          |
+| `/ultracode deep`     | Use fixed depth for interacting constraints or critical invariants, with independent evidence and counterexample checks |
+| `/ultracode off`      | Disable it without changing the parent effort                                                                           |
+| `/ultracode status`   | Show the configured mode and its applicability / verification requirements                                              |
+| `/workflows` or `F6`  | Open the workflow browser                                                                                               |
+| `/workflows <runId>`  | Open a specific run                                                                                                     |
+| `/workflows abort`    | Abort active runs                                                                                                       |
 
 Press `Esc` to cancel a running workflow. In Pi's fullscreen TUI, use `Ctrl+PageUp`, `Ctrl+PageDown`, and `Ctrl+End` inside workflow details.
 
@@ -76,12 +76,12 @@ Press `Esc` to cancel a running workflow. In Pi's fullscreen TUI, use `Ctrl+Page
 
 Depth defines **what must be investigated and verified**, not model effort or a quota of agents and rounds:
 
-| Depth | Applicable conditions | Required verification |
-|---|---|---|
-| **Focused** | Bounded work with a known approach and locally verifiable results; e.g. a specified validation rule | Directly check the changed behavior or key claim, usually in the parent loop. No broad investigation or adversarial panel by default; verification is not skipped. |
-| **Standard** | Multiple independent dimensions or unresolved hypotheses can materially change the answer; e.g. a fault with several plausible causes | Investigate those dimensions or compare causes, then target disputed or weakly evidenced claims. Known multi-step work alone is not enough to require standard. |
-| **Deep** | Tightly interacting hard constraints or critical invariants need independent evidence and counterexamples; e.g. cancellation racing a durable commit | Trace interactions, test boundary/failure cases, and challenge key claims with a distinct test, reproduction, proof, or source. A second agent is neither necessary nor sufficient. |
-| **Auto** | Choose the smallest depth sufficient for the current task | Apply the selected depth's evidence requirements; escalate only when material new evidence or unresolved conflicts justify it. |
+| Depth        | Applicable conditions                                                                                                                                | Required verification                                                                                                                                                               |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Focused**  | Bounded work with a known approach and locally verifiable results; e.g. a specified validation rule                                                  | Directly check the changed behavior or key claim, usually in the parent loop. No broad investigation or adversarial panel by default; verification is not skipped.                  |
+| **Standard** | Multiple independent dimensions or unresolved hypotheses can materially change the answer; e.g. a fault with several plausible causes                | Investigate those dimensions or compare causes, then target disputed or weakly evidenced claims. Known multi-step work alone is not enough to require standard.                     |
+| **Deep**     | Tightly interacting hard constraints or critical invariants need independent evidence and counterexamples; e.g. cancellation racing a durable commit | Trace interactions, test boundary/failure cases, and challenge key claims with a distinct test, reproduction, proof, or source. A second agent is neither necessary nor sufficient. |
+| **Auto**     | Choose the smallest depth sufficient for the current task                                                                                            | Apply the selected depth's evidence requirements; escalate only when material new evidence or unresolved conflicts justify it.                                                      |
 
 Risk determines **which claims need verification**. Security, concurrency, data loss, file count, or a request for review alone never mandates `deep`; missing information does not prove hidden complexity. Deep does not automatically mean a workflow, more agents, or repeated rounds. Explicit `focused` / `standard` / `deep` modes remain fixed: if insufficient, report the uncertainty and recommend a deeper mode rather than silently exceeding the boundary.
 
@@ -105,15 +105,15 @@ Before each parent run, the extension supplies a local Pi capability snapshot: t
 
 The snapshot describes local registered capabilities, not a live provider probe, and may become stale during a run. Runtime clamping remains a safety net for explicit requests or stale metadata. Standalone SDK use of `createWorkflowTool()` without the extension does not inject this section; the host must supply capability context to enable informed automatic suffix selection. Neither the snapshot nor its absence rewrites explicit user effort choices or no-suffix defaults.
 
-| Suffix | Criteria and exclusions | Example |
-|---|---|---|
-| `:off` | Fully specified mechanical work; no locating changes, interpreting meaning, or hidden-impact reasoning | Fix a typo at an exact location using a supplied replacement |
-| `:minimal` | One clear local judgment; no cross-file tracing or multi-step implementation | Explain a short self-contained expression |
-| `:low` | Small implementation or question with a known approach and straightforward checks; not an unknown-root-cause fault | Add a specified validation rule and its test |
-| `:medium` | Bounded multi-step work coordinating known constraints; not interacting unresolved hypotheses | Wire a configuration option through loading, usage, and tests |
-| `:high` | Test competing hypotheses, trace cross-module effects, or reason about critical correctness constraints; security/architecture keywords alone do not qualify | Diagnose cross-module state desynchronization by comparing plausible causes |
-| `:xhigh` | Interacting hard problems requiring comparison of approaches and validation of cross-module invariants; file count or vague complexity claims do not qualify | Investigate an intermittent lifecycle, cache, and cancellation interaction |
-| `:max` | Exceptionally difficult synthesis requiring rigorous argument and adversarial validation, or concrete evidence of insufficient lower-effort reasoning; risk keywords alone do not qualify | Prove and repair system-wide concurrency, memory-safety, and low-level invariants |
+| Suffix     | Criteria and exclusions                                                                                                                                                                   | Example                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `:off`     | Fully specified mechanical work; no locating changes, interpreting meaning, or hidden-impact reasoning                                                                                    | Fix a typo at an exact location using a supplied replacement                      |
+| `:minimal` | One clear local judgment; no cross-file tracing or multi-step implementation                                                                                                              | Explain a short self-contained expression                                         |
+| `:low`     | Small implementation or question with a known approach and straightforward checks; not an unknown-root-cause fault                                                                        | Add a specified validation rule and its test                                      |
+| `:medium`  | Bounded multi-step work coordinating known constraints; not interacting unresolved hypotheses                                                                                             | Wire a configuration option through loading, usage, and tests                     |
+| `:high`    | Test competing hypotheses, trace cross-module effects, or reason about critical correctness constraints; security/architecture keywords alone do not qualify                              | Diagnose cross-module state desynchronization by comparing plausible causes       |
+| `:xhigh`   | Interacting hard problems requiring comparison of approaches and validation of cross-module invariants; file count or vague complexity claims do not qualify                              | Investigate an intermittent lifecycle, cache, and cancellation interaction        |
+| `:max`     | Exceptionally difficult synthesis requiring rigorous argument and adversarial validation, or concrete evidence of insufficient lower-effort reasoning; risk keywords alone do not qualify | Prove and repair system-wide concurrency, memory-safety, and low-level invariants |
 
 Implementation, review, input length, file count, risk keywords, and depth mode are not sufficient reasons for high effort. Missing information does not automatically imply `medium/high`; do not invent complexity. For `high/xhigh/max`, briefly identify the concrete reasoning difficulty. The highest supported effort requires neither a failed lower-level attempt nor an available intermediate level. Risk determines what needs verification, not a uniform high effort for every child.
 
@@ -145,14 +145,14 @@ export const meta = {
 };
 
 const findings = await parallel([
-  () => agent(
-    "Review the current branch for correctness and lifecycle bugs.",
-    { label: "correctness review" },
-  ),
-  () => agent(
-    "Review the current branch for missing or weak regression tests.",
-    { label: "test review" },
-  ),
+  () =>
+    agent("Review the current branch for correctness and lifecycle bugs.", {
+      label: "correctness review",
+    }),
+  () =>
+    agent("Review the current branch for missing or weak regression tests.", {
+      label: "test review",
+    }),
 ]);
 
 return findings.filter(Boolean);
@@ -210,13 +210,63 @@ Token and cost data are reported for observability, not enforced as a budget. Wo
 
 ## Development
 
+Development uses Node.js 24.21.0 (`.node-version`) and Vite+ 1.0.0. The
+`packageManager` field pins npm 11.19.0 and selects the installer used by
+`vp install`, `vp add`, and `vp remove`.
+
+With the global Vite+ CLI installed:
+
 ```bash
-npm ci
-npm run typecheck
-npm test
-npm pack --dry-run
+vp install --frozen-lockfile --ignore-scripts
+vp run check
+vp run typecheck
+vp run test
+vp pm pack -- --dry-run
 ```
 
+Without the global CLI, run `npm ci --ignore-scripts`, then `npm run check`,
+`npm run typecheck`, and `npm test`. These scripts use the pinned local `vp`;
+release CI follows this path and preserves npm trusted publishing and version gates.
+
+`vp test` invokes the built-in test runner once; use `vp test watch` for watch mode.
+`vp run test` executes this package's `test` script, which uses `vp test run` for a
+single run. `vp dev` starts Vite's development server; this source-distributed
+extension has no web development server or `dev` task.
+
+### Static checks
+
+`vp check` and `vp run check` run the same complete formatting, lint, and type
+checks. The `check` script calls `vp check` without bypass flags or path filters,
+and release CI uses this same script. Lint warnings remain visible for review.
+Use `vp fmt <files>` to format changed files.
+
+`vp run typecheck` runs only TypeScript (`vp exec tsc --noEmit`) against
+`tsconfig.json`. It is a focused development command; the complete `check` task
+remains the CI gate.
+
+Saved JavaScript workflows in `examples/` run in the workflow sandbox. The example
+uses a JSDoc type-only import from `pi-ultracode/workflow` to load the ambient
+workflow declarations in both the checkout and an installed package, without
+adding a runtime import or a checkout-only alias.
+
+Tests retain isolated fork workers, automatic mock restoration, and the previous
+runner's unlimited default test timeout.
+
+### Package validation
+
+The published package intentionally contains `extensions/`, `src/`, `types/`,
+examples, and documentation. Pi loads the TypeScript entry directly, and
+`src/workflow/script-executor.ts` locates its sibling `script-worker.mjs`.
+`npm pack --dry-run` checks the actual publication contents; an extracted tarball
+should also resolve `/// <reference types="pi-ultracode/workflow" />` from a
+consumer TypeScript project.
+
+`vp pack` is a tsdown bundle builder, not a replacement for `npm pack` here. An
+optional smoke check such as
+`vp pack --no-config src/depth.ts --out-dir /tmp/pi-ultracode-pack-smoke --no-dts`
+only tests the bundler. It does not validate the extension's release artifact.
+There is intentionally no generated `dist/`, build step, or rewritten export map.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -57,21 +57,21 @@ Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通
 
 常用命令：
 
-| 命令 | 作用 |
-| --- | --- |
-| `/ultracode` | 关闭时开启 `auto`；任一模式已开启时关闭 |
-| `/ultracode auto` | 始终由父代理结合任务和上下文选择深度 |
-| `/ultracode focused` | 固定处理方法已知、范围明确且能局部直接验证的工作 |
-| `/ultracode standard` | 固定调查独立维度或竞争假设，并做针对性验证 |
-| `/ultracode deep` | 固定检查相互作用的约束或关键不变量，要求独立证据和反例检验 |
-| `/ultracode off` | 关闭且不改变父代理 effort |
-| `/ultracode status` | 查看配置模式及其适用条件、验证要求 |
-| `/ultracode default on` | 全局默认开启，并立即开启当前会话；已开启时保留当前深度 |
-| `/ultracode default off` | 取消默认开启 |
-| `/ultracode default` | 查看全局启动默认值 |
-| `/workflows` 或 `F6` | 打开工作流浏览器 |
-| `/workflows <runId>` | 打开指定运行 |
-| `/workflows abort` | 中止活动运行 |
+| 命令                     | 作用                                                       |
+| ------------------------ | ---------------------------------------------------------- |
+| `/ultracode`             | 关闭时开启 `auto`；任一模式已开启时关闭                    |
+| `/ultracode auto`        | 始终由父代理结合任务和上下文选择深度                       |
+| `/ultracode focused`     | 固定处理方法已知、范围明确且能局部直接验证的工作           |
+| `/ultracode standard`    | 固定调查独立维度或竞争假设，并做针对性验证                 |
+| `/ultracode deep`        | 固定检查相互作用的约束或关键不变量，要求独立证据和反例检验 |
+| `/ultracode off`         | 关闭且不改变父代理 effort                                  |
+| `/ultracode status`      | 查看配置模式及其适用条件、验证要求                         |
+| `/ultracode default on`  | 全局默认开启，并立即开启当前会话；已开启时保留当前深度     |
+| `/ultracode default off` | 取消默认开启                                               |
+| `/ultracode default`     | 查看全局启动默认值                                         |
+| `/workflows` 或 `F6`     | 打开工作流浏览器                                           |
+| `/workflows <runId>`     | 打开指定运行                                               |
+| `/workflows abort`       | 中止活动运行                                               |
 
 `/ultracode default on` 保存全局启动默认值，并立即将关闭的当前会话切换为 `auto`；当前已开启时保留所选深度。`/ultracode default off` 只取消默认开启，不关闭当前会话；关闭当前会话请用 `/ultracode off`。这些操作均不改变 effort。设置保存在 `~/.pi/agent/ultracode.json`（遵循 `PI_CODING_AGENT_DIR`），跨项目和重启生效；未设置时默认关闭。启动时，只有当前分支没有保存 Ultracode 模式才应用默认值，已有的 `off` 或深度选择在 reload、resume、fork 后继续保留。显式 `pi --ultracode` 仍可启用 `auto`。
 
@@ -81,12 +81,12 @@ Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通
 
 深度决定**要调查和验证什么**，不是模型 effort，也不是代理数量或调查轮数配额：
 
-| 深度 | 适用条件 | 验证要求 |
-|---|---|---|
-| **Focused** | 范围明确、方法已知、结果可局部验证；例如添加指定校验规则 | 直接检查修改行为或关键结论，通常使用父代理循环。默认不做广泛调查或对抗评审，但不能省略验证。 |
-| **Standard** | 多个独立维度或未解决的竞争假设会实质影响答案；例如故障存在多个合理根因 | 调查相关维度或比较根因，再针对冲突、证据薄弱的结论验证。仅仅步骤多且方法已知，不足以要求 standard。 |
-| **Deep** | 紧密相互作用的硬约束或关键不变量，需要独立证据与反例检验；例如取消与持久提交发生竞争 | 追踪相互影响，检查边界及失败路径，用不同测试、复现、证明或来源挑战关键结论。第二个代理既非必要条件，也不保证证据独立。 |
-| **Auto** | 选择足以处理当前任务的最小深度 | 遵守所选深度的证据要求；仅在实质新证据或未解决冲突要求时升级。 |
+| 深度         | 适用条件                                                                             | 验证要求                                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| **Focused**  | 范围明确、方法已知、结果可局部验证；例如添加指定校验规则                             | 直接检查修改行为或关键结论，通常使用父代理循环。默认不做广泛调查或对抗评审，但不能省略验证。                           |
+| **Standard** | 多个独立维度或未解决的竞争假设会实质影响答案；例如故障存在多个合理根因               | 调查相关维度或比较根因，再针对冲突、证据薄弱的结论验证。仅仅步骤多且方法已知，不足以要求 standard。                    |
+| **Deep**     | 紧密相互作用的硬约束或关键不变量，需要独立证据与反例检验；例如取消与持久提交发生竞争 | 追踪相互影响，检查边界及失败路径，用不同测试、复现、证明或来源挑战关键结论。第二个代理既非必要条件，也不保证证据独立。 |
+| **Auto**     | 选择足以处理当前任务的最小深度                                                       | 遵守所选深度的证据要求；仅在实质新证据或未解决冲突要求时升级。                                                         |
 
 风险决定**哪些结论需要验证**。安全、并发、数据丢失等关键词、文件数量或“做一次 review”本身不能自动触发 `deep`；信息不足也不证明存在隐藏复杂度。Deep 不自动意味着必须使用工作流、增加代理或反复调查。显式 `focused` / `standard` / `deep` 保持固定：若不足以确认结论，应说明不确定性并建议更深模式，不能悄悄越界。
 
@@ -108,15 +108,15 @@ Ultracode 不会修改父会话的 effort；以下父代理选择作为默认和
 
 快照来自本地注册信息，不会在线探测提供商，且运行期间可能过时；执行端仍用 clamp 保护显式请求或过时信息。SDK 单独使用 `createWorkflowTool()` 而不加载扩展时，不会注入此区块，宿主需自行提供能力上下文才能让父代理据此自动选择后缀。快照存在与否，都不会改写用户显式选择的 effort 或无后缀默认行为。
 
-| 后缀 | 适用条件与排除条件 | 例子 |
-|---|---|---|
-| `:off` | 完全指定的机械操作；不涉及寻找修改位置、判断含义或隐藏影响 | 在指定位置按给定内容修正错字 |
-| `:minimal` | 单一范围内的一次明确局部判断；不涉及跨文件追踪或多步骤实现 | 解释一个自包含短表达式 |
-| `:low` | 目标清楚、方法已知、验证直接的小实现或问题；不包含根因未知的故障 | 给已有函数添加指定校验规则及测试 |
-| `:medium` | 协调多个已知约束的有界多步骤实现或调查；不包含相互影响的未解决假设 | 在既有架构中贯通配置加载、使用和测试 |
-| `:high` | 检验多个合理假设、追踪跨模块影响，或推理关键正确性约束；不能只凭安全或架构关键词升级 | 比较竞争根因，诊断跨模块状态不同步 |
-| `:xhigh` | 多个困难问题相互作用，需要比较方案、验证跨模块不变量；文件多或笼统声称复杂不够 | 排查生命周期、缓存、取消相互影响的偶发故障 |
-| `:max` | 极难的综合推理，需要严密论证及反例检验，或已有低档推理不足的具体证据；风险关键词本身不够 | 证明并修复涉及并发、内存安全和底层语义的全系统不变量 |
+| 后缀       | 适用条件与排除条件                                                                       | 例子                                                 |
+| ---------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `:off`     | 完全指定的机械操作；不涉及寻找修改位置、判断含义或隐藏影响                               | 在指定位置按给定内容修正错字                         |
+| `:minimal` | 单一范围内的一次明确局部判断；不涉及跨文件追踪或多步骤实现                               | 解释一个自包含短表达式                               |
+| `:low`     | 目标清楚、方法已知、验证直接的小实现或问题；不包含根因未知的故障                         | 给已有函数添加指定校验规则及测试                     |
+| `:medium`  | 协调多个已知约束的有界多步骤实现或调查；不包含相互影响的未解决假设                       | 在既有架构中贯通配置加载、使用和测试                 |
+| `:high`    | 检验多个合理假设、追踪跨模块影响，或推理关键正确性约束；不能只凭安全或架构关键词升级     | 比较竞争根因，诊断跨模块状态不同步                   |
+| `:xhigh`   | 多个困难问题相互作用，需要比较方案、验证跨模块不变量；文件多或笼统声称复杂不够           | 排查生命周期、缓存、取消相互影响的偶发故障           |
+| `:max`     | 极难的综合推理，需要严密论证及反例检验，或已有低档推理不足的具体证据；风险关键词本身不够 | 证明并修复涉及并发、内存安全和底层语义的全系统不变量 |
 
 写代码、审查、文本长度、文件数量、风险关键词及 depth 模式都不能单独决定高档；信息不足不自动意味着 `medium/high`，也不能臆造复杂度。选择 `high/xhigh/max` 时须简述具体推理难点。最高档不要求先经历低档失败，也不要求模型支持中间档。风险决定需要验证什么，不等于所有参与代理都要高 effort。
 
@@ -148,14 +148,14 @@ export const meta = {
 };
 
 const findings = await parallel([
-  () => agent(
-    "Review the current branch for correctness and lifecycle bugs.",
-    { label: "correctness review" },
-  ),
-  () => agent(
-    "Review the current branch for missing or weak regression tests.",
-    { label: "test review" },
-  ),
+  () =>
+    agent("Review the current branch for correctness and lifecycle bugs.", {
+      label: "correctness review",
+    }),
+  () =>
+    agent("Review the current branch for missing or weak regression tests.", {
+      label: "test review",
+    }),
 ]);
 
 return findings.filter(Boolean);
@@ -213,13 +213,56 @@ Token 和成本只用于可观测性，不作为执行预算。Worker 与 VM 限
 
 ## 开发
 
+开发使用 Node.js 24.21.0（`.node-version`）和 Vite+ 1.0.0。
+`packageManager` 固定 npm 11.19.0，并决定 `vp install`、`vp add`、`vp remove`
+使用的包管理器。
+
+已安装全局 Vite+ CLI 时：
+
 ```bash
-npm ci
-npm run typecheck
-npm test
-npm pack --dry-run
+vp install --frozen-lockfile --ignore-scripts
+vp run check
+vp run typecheck
+vp run test
+vp pm pack -- --dry-run
 ```
 
+也可以先运行 `npm ci --ignore-scripts`，再运行 `npm run check`、
+`npm run typecheck` 和 `npm test`。这些脚本使用固定版本的本地 `vp`；
+发布 CI 使用此方式，并保留 npm 可信发布与版本校验。
+
+`vp test` 调用内置测试运行器并执行一次；使用 `vp test watch` 监听文件变化。
+`vp run test` 执行本项目的 `test` 脚本，通过 `vp test run` 单次运行测试。
+`vp dev` 启动 Vite 开发服务器；本项目按源码发布扩展，未配置网页开发服务器或 `dev` 任务。
+
+### 静态检查
+
+`vp check` 和 `vp run check` 执行相同的完整格式、lint 和类型检查。
+`check` 脚本直接调用 `vp check`，不添加跳过参数或路径过滤；发布 CI 使用同一脚本。
+Lint 警告保持可见，供后续审查。使用 `vp fmt <files>` 格式化修改的文件。
+
+`vp run typecheck` 仅通过 `vp exec tsc --noEmit` 检查 `tsconfig.json` 中的 TypeScript。
+此命令用于开发时的定向检查，CI 仍执行完整 `check` 任务。
+
+`examples/` 中的 JavaScript 工作流在工作流沙箱中运行。示例使用 JSDoc 类型导入引用
+`pi-ultracode/workflow`，在源码目录和已安装包中加载全局工作流声明，保持运行时零导入，
+无需添加源码目录专用别名。
+
+测试保留隔离的 fork worker、自动恢复 mock，以及原测试运行器默认无超时限制的行为。
+
+### 发布包验证
+
+发布包保留 `extensions/`、`src/`、`types/`、示例和文档。Pi 直接加载 TypeScript
+入口，`src/workflow/script-executor.ts` 按相邻路径定位 `script-worker.mjs`。
+`npm pack --dry-run` 检查实际发布内容；还应解压 tarball，在消费方 TypeScript
+项目中验证 `/// <reference types="pi-ultracode/workflow" />` 的类型解析。
+
+`vp pack` 使用 tsdown 生成 bundle，与本项目的 `npm pack` 发布流程用途不同。
+可选冒烟命令
+`vp pack --no-config src/depth.ts --out-dir /tmp/pi-ultracode-pack-smoke --no-dts`
+仅验证打包器，扩展发布产物仍需上述检查。项目保持源码布局，无需生成 `dist/`、
+增加构建步骤或改写导出映射。
+
 ## 许可证
 
 MIT

package/examples/workflows/loop-until-dry-bugs.workflow.js

@@ -1,4 +1,4 @@
-/// <reference types="pi-ultracode/workflow" />
+/** @import {} from "pi-ultracode/workflow" */
 //
 // Example saved workflow. Copy to `.pi/ultracode/workflows/` and run it with
 // the `workflow` tool's `name` parameter, or call `workflow('loop-until-dry-bugs')`
@@ -9,76 +9,100 @@
 // confirms each fresh bug with three distinct lenses.
 
 export const meta = {
-  name: 'loop-until-dry-bugs',
-  description: 'Find bugs until the well runs dry, verifying each with three lenses',
-  phases: [{ title: 'Find' }, { title: 'Verify' }],
-}
+  name: "loop-until-dry-bugs",
+  description: "Find bugs until the well runs dry, verifying each with three lenses",
+  phases: [{ title: "Find" }, { title: "Verify" }],
+};
 
 const FINDERS = [
-  'Find correctness bugs by reading the changed files closely.',
-  'Find bugs by tracing data flow across module boundaries.',
-  'Find bugs by hunting error-handling and edge-case gaps.',
-]
+  "Find correctness bugs by reading the changed files closely.",
+  "Find bugs by tracing data flow across module boundaries.",
+  "Find bugs by hunting error-handling and edge-case gaps.",
+];
 
 const BUGS = {
-  type: 'object',
+  type: "object",
   properties: {
     bugs: {
-      type: 'array',
+      type: "array",
       items: {
-        type: 'object',
-        properties: { file: { type: 'string' }, line: { type: 'number' }, desc: { type: 'string' } },
-        required: ['file', 'desc'],
+        type: "object",
+        properties: {
+          file: { type: "string" },
+          line: { type: "number" },
+          desc: { type: "string" },
+        },
+        required: ["file", "desc"],
       },
     },
   },
-  required: ['bugs'],
-}
+  required: ["bugs"],
+};
 
 const VERDICT = {
-  type: 'object',
-  properties: { real: { type: 'boolean' }, why: { type: 'string' } },
-  required: ['real'],
-}
+  type: "object",
+  properties: { real: { type: "boolean" }, why: { type: "string" } },
+  required: ["real"],
+};
 
-const seen = new Set()
-const confirmed = []
-let dry = 0
-let roundsRun = 0
-const MAX_ROUNDS = 2
+const seen = new Set();
+const confirmed = [];
+let dry = 0;
+let roundsRun = 0;
+const MAX_ROUNDS = 2;
 
 while (dry < 2 && roundsRun < MAX_ROUNDS) {
-  roundsRun++
+  roundsRun++;
   const rounds = await parallel(
-    FINDERS.map((prompt, i) => () => agent(prompt, { label: 'find ' + i, phase: 'Find', schema: BUGS })),
-  )
-  const found = rounds.filter(Boolean).flatMap((r) => r.bugs ?? [])
-  const fresh = found.filter((b) => !seen.has(b.file + ':' + b.desc))
+    FINDERS.map(
+      (prompt, i) => () => agent(prompt, { label: "find " + i, phase: "Find", schema: BUGS }),
+    ),
+  );
+  const found = rounds.filter(Boolean).flatMap((r) => r.bugs ?? []);
+  const fresh = found.filter((b) => !seen.has(b.file + ":" + b.desc));
   if (fresh.length === 0) {
-    dry++
-    continue
+    dry++;
+    continue;
   }
-  dry = 0
-  for (const b of fresh) seen.add(b.file + ':' + b.desc)
+  dry = 0;
+  for (const b of fresh) seen.add(b.file + ":" + b.desc);
 
   const judged = await parallel(
     fresh.map((b) => async () => {
       const votes = await parallel(
-        ['correctness', 'security', 'does-it-reproduce'].map((lens) => () =>
-          agent('Judge via the ' + lens + ' lens — is this real? "' + b.desc + '" (' + b.file + '). Default to real:false if unsure.',
-            { label: 'verify ' + lens, phase: 'Verify', agentType: 'code-reviewer', schema: VERDICT }),
+        ["correctness", "security", "does-it-reproduce"].map(
+          (lens) => () =>
+            agent(
+              "Judge via the " +
+                lens +
+                ' lens — is this real? "' +
+                b.desc +
+                '" (' +
+                b.file +
+                "). Default to real:false if unsure.",
+              {
+                label: "verify " + lens,
+                phase: "Verify",
+                agentType: "code-reviewer",
+                schema: VERDICT,
+              },
+            ),
         ),
-      )
-      return { bug: b, real: votes.filter(Boolean).filter((v) => v.real).length >= 2 }
+      );
+      return { bug: b, real: votes.filter(Boolean).filter((v) => v.real).length >= 2 };
     }),
-  )
-  confirmed.push(...judged.filter((j) => j.real).map((j) => j.bug))
+  );
+  confirmed.push(...judged.filter((j) => j.real).map((j) => j.bug));
 }
 
-const complete = dry >= 2
-const truncated = !complete
+const complete = dry >= 2;
+const truncated = !complete;
 if (truncated) {
-  log('Stopped after MAX_ROUNDS=' + MAX_ROUNDS + ' before reaching two consecutive dry rounds; returning truncated results.')
+  log(
+    "Stopped after MAX_ROUNDS=" +
+      MAX_ROUNDS +
+      " before reaching two consecutive dry rounds; returning truncated results.",
+  );
 }
 
-return { confirmed, totalSeen: seen.size, roundsRun, complete, truncated }
+return { confirmed, totalSeen: seen.size, roundsRun, complete, truncated };

package/extensions/ultracode.ts

@@ -5,7 +5,8 @@
  * workflow orchestration, and the `/ultracode` / `/workflows` commands.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Effect } from "effect";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createWorkflowTool, type WorkflowToolDeps } from "../src/workflow/tool.ts";
 import { UltracodeMode, type ThinkingPreferenceStore } from "../src/mode.ts";
 import { registerCommands } from "../src/commands.ts";
@@ -62,54 +63,73 @@ export default function extension(pi: ExtensionAPI, extraDeps: UltracodeExtensio
     if (event.toolName === workflowTool.name && !mode.isEnforcing()) {
       return {
         block: true,
-        reason: "The workflow tool is disabled. Run /ultracode or select an Ultracode depth before using it.",
+        reason:
+          "The workflow tool is disabled. Run /ultracode or select an Ultracode depth before using it.",
       };
     }
   });
 
-  pi.on("session_start", async (_event, ctx) => {
-    // Restore persisted mode state across reload / resume / fork.
-    let hasSavedMode = true;
-    try {
-      // Mode entries are branch-local; discarded future branches must not win.
-      hasSavedMode = mode.restore(pi, ctx.sessionManager.getBranch() as any);
-    } catch {
-      // Do not apply a startup default when branch restoration failed.
-    }
-    if (!mode.isEnabled() && pi.getFlag?.("ultracode") === true) {
-      mode.enable(pi, "auto");
-    } else if (!hasSavedMode && !mode.isEnabled()) {
-      try {
-        if (preferences.getDefaultEnabled()) mode.enable(pi, "auto");
-      } catch (error) {
-        ctx.ui.notify(`Failed to read Ultracode default: ${String(error)}`, "warning");
+  const attempt = <A>(thunk: () => A) => Effect.try({ try: thunk, catch: (error) => error });
+  const updateStatus = (ctx: ExtensionContext) =>
+    attempt(() => {
+      mode.syncWorkflowTool(pi);
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(
+          "ultracode",
+          mode.isEnabled()
+            ? mode.statusLine((text, color) => ctx.ui.theme.fg(color, text))
+            : undefined,
+        );
       }
-    }
-    // Registration makes tools discoverable; activation follows the chosen mode.
-    mode.syncWorkflowTool(pi);
-    if (ctx.hasUI) {
-      ctx.ui.setStatus(
-        "ultracode",
-        mode.isEnabled() ? mode.statusLine((label) => ctx.ui.theme.fg("accent", label)) : undefined,
-      );
-    }
-  });
+    });
 
-  pi.on("session_tree", async (_event, ctx) => {
-    if (mode.isSuspended()) return;
-    mode.restore(pi, ctx.sessionManager.getBranch() as any);
-    if (ctx.hasUI) {
-      ctx.ui.setStatus(
-        "ultracode",
-        mode.isEnabled() ? mode.statusLine((label) => ctx.ui.theme.fg("accent", label)) : undefined,
-      );
-    }
-  });
+  pi.on("session_start", (_event, ctx) =>
+    Effect.runPromise(
+      // Mode entries are branch-local; restoration failure suppresses startup defaults.
+      attempt(() => mode.restore(pi, ctx.sessionManager.getBranch() as any)).pipe(
+        Effect.catch(() => Effect.succeed(true)),
+        Effect.flatMap((hasSavedMode) =>
+          attempt(() => pi.getFlag?.("ultracode") === true).pipe(
+            Effect.flatMap((flagEnabled) => {
+              if (!mode.isEnabled() && flagEnabled) return attempt(() => mode.enable(pi, "auto"));
+              if (hasSavedMode || mode.isEnabled()) return Effect.void;
+              return attempt(() => {
+                if (preferences.getDefaultEnabled()) mode.enable(pi, "auto");
+              }).pipe(
+                Effect.catch((error) =>
+                  attempt(() => {
+                    ctx.ui.notify(`Failed to read Ultracode default: ${String(error)}`, "warning");
+                  }),
+                ),
+              );
+            }),
+          ),
+        ),
+        Effect.andThen(updateStatus(ctx)),
+      ),
+    ),
+  );
 
-  pi.on("session_shutdown", async () => {
-    // The persisted configured mode remains active for reload/resume/fork replacements.
-    mode.suspend(pi);
-  });
+  pi.on("session_tree", (_event, ctx) =>
+    Effect.runPromise(
+      Effect.suspend(() =>
+        mode.isSuspended()
+          ? Effect.void
+          : attempt(() => mode.restore(pi, ctx.sessionManager.getBranch() as any)).pipe(
+              Effect.andThen(updateStatus(ctx)),
+            ),
+      ),
+    ),
+  );
+
+  pi.on("session_shutdown", () =>
+    Effect.runPromise(
+      attempt(() => {
+        // Persisted configuration survives reload/resume/fork replacements.
+        mode.suspend(pi);
+      }),
+    ),
+  );
 
   pi.on("before_agent_start", (event, ctx) => {
     // Reconcile tool availability and update our prompt section on every turn,