@fitlab-ai/agent-infra 0.11.8 → 0.11.9

package/templates/.agents/README.en.md

@@ -261,59 +261,11 @@ When you disable a built-in client, reconciliation stops maintaining its seed co
 ### Relation to other config fields
 
 - `sandbox.tools.ids` lists non-client tools such as `agent-infra` and custom tools; custom definitions belong in `sandbox.tools.definitions`. Built-in client installation belongs in `agentClients[].installInSandbox`.
-- `agentClients` is independent from `customTUIs` (see below). Custom TUI command files are preserved even when their directory is under a disabled built-in client's path prefix.
-
-## Custom TUI Configuration
-
-Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
-
-| Field | Required | Meaning |
-|-------|----------|---------|
-| `name` | Yes | Display name shown in reports and next-step guidance, for example `<your-tui-name>`. |
-| `dir` | Yes | Command directory relative to the project root, for example `.<your-tui>/commands`. The path must stay inside the project root. |
-| `invoke` | Yes | User-facing command template used in next-step guidance. |
-
-Supported `invoke` placeholders:
-
-| Placeholder | Replaced with | Example |
-|-------------|---------------|---------|
-| `${skillName}` | The skill command name, such as `review-code` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
-| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/your-project:review-code` |
-
-Non-namespaced custom TUI:
-
-```json
-{
-  "customTUIs": [
-    {
-      "name": "<your-tui-name>",
-      "dir": ".<your-tui>/commands",
-      "invoke": "<your-cli> ${skillName}"
-    }
-  ]
-}
-```
-
-Namespaced custom TUI:
-
-```json
-{
-  "project": "your-project",
-  "customTUIs": [
-    {
-      "name": "<your-tui-name>",
-      "dir": ".<your-tui>/commands",
-      "invoke": "/${projectName}:${skillName}"
-    }
-  ]
-}
-```
-
-`customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
+- Custom tool next-step commands are configured with `sandbox.tools.definitions.<id>.invoke`. See [Custom Tool Invocations](https://github.com/fitlab-ai/agent-infra/blob/main/docs/en/custom-tool-invocations.md) for the full example.
 
 ## Sandbox Custom Tools
 
-`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under an ID key in `sandbox.tools.definitions` in `.agents/.airc.json`. Built-in Agent Clients are installed according to `agentClients[].installInSandbox`; `agent-infra` remains a non-client entry in `sandbox.tools.ids` and only provides the in-sandbox `ai` / `agent-infra` CLI.
+To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under an ID key in `sandbox.tools.definitions` in `.agents/.airc.json`. Built-in Agent Clients are installed according to `agentClients[].installInSandbox`; `agent-infra` remains a non-client entry in `sandbox.tools.ids` and only provides the in-sandbox `ai` / `agent-infra` CLI.
 
 ### Required fields
 

package/templates/.agents/README.zh-CN.md

@@ -259,59 +259,11 @@ TraeCode CLI 以 `.agents/skills/` 作为 Skill 的唯一权威源。agent-infra
 ### 与其他配置字段的关系
 
 - `sandbox.tools.ids` 只列出 `agent-infra` 和自定义工具等非客户端工具；自定义定义放在 `sandbox.tools.definitions`。内建客户端的安装状态由 `agentClients[].installInSandbox` 表达。
-- `agentClients` 与 `customTUIs`（见下）相互独立。即使自定义 TUI 目录落在已取消的内建客户端路径前缀下，其命令文件也会被保留。
-
-## 自定义 TUI 配置
-
-当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
-
-| 字段 | 必填 | 含义 |
-|------|------|------|
-| `name` | 是 | 报告和下一步提示中展示的工具名称，例如 `<your-tui-name>`。 |
-| `dir` | 是 | 相对项目根目录的命令目录，例如 `.<your-tui>/commands`。路径必须位于项目根目录内。 |
-| `invoke` | 是 | 面向用户展示的命令模板，用于生成下一步提示。 |
-
-`invoke` 支持的占位符：
-
-| 占位符 | 替换为 | 示例 |
-|--------|--------|------|
-| `${skillName}` | skill 命令名，例如 `review-code` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
-| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/your-project:review-code` |
-
-不带命名空间的自定义 TUI：
-
-```json
-{
-  "customTUIs": [
-    {
-      "name": "<your-tui-name>",
-      "dir": ".<your-tui>/commands",
-      "invoke": "<your-cli> ${skillName}"
-    }
-  ]
-}
-```
-
-带命名空间的自定义 TUI：
-
-```json
-{
-  "project": "your-project",
-  "customTUIs": [
-    {
-      "name": "<your-tui-name>",
-      "dir": ".<your-tui>/commands",
-      "invoke": "/${projectName}:${skillName}"
-    }
-  ]
-}
-```
-
-`customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
+- 自定义工具的下一步命令通过 `sandbox.tools.definitions.<id>.invoke` 配置。完整示例见 [自定义工具调用说明](https://github.com/fitlab-ai/agent-infra/blob/main/docs/zh-CN/custom-tool-invocations.md)。
 
 ## 沙箱自定义工具（Sandbox Custom Tools）
 
-`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.tools.definitions` 中按工具 ID 声明。内建 Agent Client 按 `agentClients[].installInSandbox` 安装；`agent-infra` 仍是 `sandbox.tools.ids` 中的非客户端条目，只提供沙箱内的 `ai` / `agent-infra` CLI。
+自定义沙箱工具通过 `.agents/.airc.json` 的 `sandbox.tools.definitions` 按工具 ID 声明。需要把非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像，或 live-mount 它的凭证目录时，可在对应定义中配置。内建 Agent Client 按 `agentClients[].installInSandbox` 安装；`agent-infra` 仍是 `sandbox.tools.ids` 中的非客户端条目，只提供沙箱内的 `ai` / `agent-infra` CLI。
 
 ### 必填字段
 

package/templates/.agents/rules/next-step-output.en.md

@@ -33,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 
 - Pass the next skill name for the already-selected scenario. Include `--task-ref` only when that command needs a task reference.
 - Include `--version` only for a versioned release command. It must start with a digit and satisfy `semver.valid(raw) === raw`; never pass an action, complete command, shell fragment, whitespace, or a `v` / `V` / `=` prefix.
-- The helper lists only built-in clients enabled in `.agents/.airc.json` `agentClients`, followed by valid `customTUIs` in configuration order.
+- The helper lists enabled built-in clients, followed by selected sandbox custom tools with a valid `invoke` field in `sandbox.tools.ids` order.
 - Insert non-empty stdout verbatim at `{next-step-commands}` below the current "Next steps" heading. When stdout is empty, omit the client command block while still rendering reminders, warnings, and `Completed at`.
 - If the helper writes stderr or exits non-zero, use the current skill's error path and stop; never fall back to a hard-coded client table.
 - A complex skill selects one scenario first and invokes the helper once for that scenario; it must not pre-render every branch.

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -33,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 
 - 静态传入当前已选场景的下一 skill 名；只有命令需要任务引用时才传 `--task-ref`。
 - 只有版本化发布命令需要版本时才传 `--version`；值必须是以数字开头且 `semver.valid(raw) === raw` 的规范 SemVer。不得传 action、完整命令、shell 片段、空白或 `v` / `V` / `=` 前缀。
-- helper 只展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并在其后按配置顺序追加合法的 `customTUIs`。
+- helper 展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并按 `sandbox.tools.ids` 顺序追加具有有效 `invoke` 的已选自定义沙箱工具。
 - 将非空 stdout 原样放入当前“下一步”标题后的 `{next-step-commands}`；stdout 为空时省略整个客户端命令块，但继续输出提醒、告警和 `Completed at`。
 - helper 写 stderr 或返回非零时，按当前 skill 的错误路径报告并停止；禁止回退到硬编码客户端表。
 - 复杂 skill 先选定唯一场景，再只为该场景调用一次 helper，不得提前渲染所有分支。

package/templates/.agents/scripts/lib/agent-infra-package.js

@@ -1,7 +1,6 @@
 import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
 const PACKAGE_NAME = "@fitlab-ai/agent-infra";
 const COMMAND_NAMES = ["ai", "agent-infra"];
@@ -82,7 +81,6 @@ function rootsForCommand(commandPath, platform) {
 function resolveAgentInfraPackage(options = {}) {
   const env = options.env || process.env;
   const platform = options.platform || process.platform;
-  const startPath = options.startPath || fileURLToPath(import.meta.url);
   const attempts = [];
   const tryRoot = (candidate, source) => {
     const inspected = inspectPackageRoot(candidate, source);
@@ -95,11 +93,6 @@ function resolveAgentInfraPackage(options = {}) {
     if (explicit) return { ...explicit, attempts };
   }
 
-  for (const candidate of packageRootsAbove(startPath)) {
-    const self = tryRoot(candidate, "current installation");
-    if (self) return { ...self, attempts };
-  }
-
   for (const command of COMMAND_NAMES) {
     const commandPaths = lookupCommand(command, platform);
     if (commandPaths.length === 0) {

package/templates/.agents/skills/commit/SKILL.en.md

@@ -96,7 +96,7 @@ Present the verification summary per `.agents/rules/validation-output.md`; do no
 
 ## 6. Render the next step
 
-Before rendering the next step, read `.agents/rules/next-step-output.md` and call the unified helper exactly once based on the latest task and PR state. A failed push keeps the task active and reports only diagnostics; a final commit routes to `create-pr` or `complete-task` according to `prFlow`.
+Before rendering the next step, read `.agents/rules/next-step-output.md` and call the unified helper exactly once based on the latest task and PR state. A failed push keeps the task active and reports only diagnostics. When a verified PR is already bound, route to `watch-pr`; without a bound PR, route to `create-pr` or `complete-task` according to `prFlow`.
 
 ## Notes
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -96,7 +96,7 @@ agent-infra-internal task-verify {task-id} commit.completed --format text
 
 ## 6. 输出下一步
 
-渲染下一步前先读取 `.agents/rules/next-step-output.md`，并根据最新 task/PR 状态只调用一次统一 helper。push 失败时保持任务 active，只输出诊断；最终提交则按 `prFlow` 选择 `create-pr` 或 `complete-task`。
+渲染下一步前先读取 `.agents/rules/next-step-output.md`，并根据最新 task/PR 状态只调用一次统一 helper。push 失败时保持任务 active，只输出诊断；已有 verified 绑定 PR 时路由到 `watch-pr`；没有绑定 PR 时，按 `prFlow` 选择 `create-pr` 或 `complete-task`。
 
 ## 注意事项
 

package/templates/.agents/skills/create-pr/reference/pr-body-template.en.md

@@ -57,7 +57,7 @@ Milestone rule:
 
 - Extract `platform_issue_identity` from task.md when this work belongs to an active task
 - If `platform_issue_identity` exists, complete the prerequisite code-hosting platform detection steps first, then query the Issue via `.agents/rules/issue-pr-commands.md`
-- Before calling the PR creation command, check whether the current branch already has a PR. If it does, report the PR URL and state, then stop without repeating metadata sync or summary publication
+- Before calling `platform-pr create`, check whether the current branch already has a PR. If the task is bound to the unique PR, the core reuses that bound identity and continues metadata sync, change reporting, and summary publication. If an existing PR is unbound, verify and bind its identity before continuing; an ordinary create request without a bound PR identity may create a new PR
 - Use HEREDOC to pass the PR body
 - Replace `{$IssueNumber}` in the template when present
 - End the PR body with `Generated with AI assistance`

package/templates/.agents/skills/create-pr/reference/pr-body-template.zh-CN.md

@@ -57,7 +57,7 @@ Milestone 规则：
 
 - 当前工作属于 active task 时，从 task.md 提取 `platform_issue_identity`
 - 如果存在 `platform_issue_identity`，先完成代码托管平台检测，再通过 `.agents/rules/issue-pr-commands.md` 查询 Issue
-- 调用 PR 创建命令前，先检查当前分支是否已有 PR；若已有，报告 PR URL 和状态后停止，不重复执行元数据同步或 summary 发布
+- 调用 `platform-pr create` 前检查当前分支是否已有 PR；任务已绑定到唯一 PR 时，core 复用该绑定身份并继续完成元数据同步、变更报告和摘要发布；发现已有 PR 但任务尚未绑定时，先核验并绑定其身份再继续；未绑定 PR 身份的普通创建请求可能会创建新的 PR
 - 使用 HEREDOC 传入 PR 正文
 - 模板中存在 `{$IssueNumber}` 时进行替换
 - PR 正文以 `Generated with AI assistance` 结尾

package/templates/.agents/skills/review-code/SKILL.en.md

@@ -175,7 +175,7 @@ manual-validation counts do not influence branch selection; they are displayed o
 
 > Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
 
-render the selected next-step commands through the shared helper. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+Render only the selected scenario's commands returned by the shared helper. The helper builds custom tool commands from `sandbox.tools.ids` and `sandbox.tools.definitions`; do not reread configuration or manually append commands.
 
 ## Completion Checklist
 

package/templates/.agents/skills/review-code/SKILL.zh-CN.md

@@ -171,7 +171,7 @@ manual-validation 的数量不参与分支选择，只作为人工校验计数
 
 > 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
-向用户通过统一 helper 渲染已选场景的下一步命令。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+向用户只展示统一 helper 返回的已选场景命令。自定义工具命令由 helper 按 `sandbox.tools.ids` 和 `sandbox.tools.definitions` 生成；不得再次读取配置或手工追加命令。
 
 ## 完成检查清单
 

package/templates/.agents/skills/review-code/reference/output-templates.en.md

@@ -41,10 +41,10 @@ If the summary cannot be parsed safely, set `{last-readable-review-result}` to "
 
 Do not route by review round. Read `prFlow` / verified `pr_delivery_fact`; when a PR exists, call `agent-infra-internal platform-checks inspect {task-id}`. Select exactly one mutually exclusive exit:
 
-- No PR: use Branch A3 (complete) when `prFlow=disabled`; otherwise use Branch A1 (create PR).
-- Existing PR with PR head != `R`: Branch A1 (create or update the PR).
-- PR head = `R` with `pending|failed|cancelled` checks or temporarily unavailable platform state: Branch A2 (watch); never show completion.
-- PR head = `R` with `passed|no-required` checks: Branch A3 (complete).
+- No PR: use Branch A4 (complete) when `prFlow=disabled`; otherwise use Branch A1 (create PR).
+- Existing PR with PR head != `R`: Branch A2 (update the existing PR).
+- PR head = `R` with `pending|failed|cancelled` checks or temporarily unavailable platform state: Branch A3 (watch); never show completion.
+- PR head = `R` with `passed|no-required` checks: Branch A4 (complete).
 
 Common Branch A summary:
 
@@ -63,7 +63,16 @@ Next step - create a Pull Request:
 {next-step-commands}
 ```
 
-#### Branch A2: Watch All Checks
+#### Branch A2: Update an Existing Pull Request
+
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit --task-ref {task-ref}`. `commit` delivers the current commit; when there is no new commit, it uses push-only delivery to update the bound PR. The commit skill routes a bound PR to `watch-pr` afterward.
+
+```text
+Next step - update the existing Pull Request:
+{next-step-commands}
+```
+
+#### Branch A3: Watch All Checks
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}`.
 
@@ -72,7 +81,7 @@ Next step - watch PR checks:
 {next-step-commands}
 ```
 
-#### Branch A3: Complete and Archive
+#### Branch A4: Complete and Archive
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
 

package/templates/.agents/skills/review-code/reference/output-templates.zh-CN.md

@@ -41,10 +41,10 @@
 
 通过后不得按轮次路由。读取任务的 `prFlow` / verified `pr_delivery_fact`；存在 PR 时调用 `agent-infra-internal platform-checks inspect {task-id}`。只选择以下一个互斥出口：
 
-- 无 PR：`prFlow=disabled` 用场景 A3（完成）；PR flow 开启时用场景 A1（创建 PR）。
-- 已有 PR 但 PR head != `R`：场景 A1（创建或更新 PR）。
-- PR head = `R`，checks 为 `pending|failed|cancelled` 或平台暂不可用：场景 A2（监控），不得输出完成命令。
-- PR head = `R`，checks 为 `passed|no-required`：场景 A3（完成）。
+- 无 PR：`prFlow=disabled` 用场景 A4（完成）；PR flow 开启时用场景 A1（创建 PR）。
+- 已有 PR 但 PR head != `R`：场景 A2（更新已有 PR）。
+- PR head = `R`，checks 为 `pending|failed|cancelled` 或平台暂不可用：场景 A3（监控），不得输出完成命令。
+- PR head = `R`，checks 为 `passed|no-required`：场景 A4（完成）。
 
 场景 A 的共同摘要：
 
@@ -64,7 +64,16 @@
 {next-step-commands}
 ```
 
-#### 场景 A2：监控全部 checks
+#### 场景 A2：更新已有 Pull Request
+
+使用 `agent-infra-internal agent-client next-steps --skill commit --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。`commit` 会交付当前提交；没有新提交时执行 push-only，将更新推送到已绑定的 PR。完成后按 commit 技能的绑定 PR 路由进入 `watch-pr`。
+
+```text
+下一步 - 更新已有 Pull Request：
+{next-step-commands}
+```
+
+#### 场景 A3：监控全部 checks
 
 使用 `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 
@@ -73,7 +82,7 @@
 {next-step-commands}
 ```
 
-#### 场景 A3：完成并归档
+#### 场景 A4：完成并归档
 
 使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 

package/templates/.agents/skills/update-agent-infra/SKILL.en.md

@@ -51,7 +51,7 @@ The script outputs JSON to stdout. Parse and record the report.
 - `managed.conflicts`: guarded managed files with unknown origin, two-sided changes, or ownership that cannot be proven during a platform switch; list each target, reason, and three-way hash
 - `managed.removed`: deleted managed files (including old paths removed during template migrations)
 - `managed.skippedPlatform`: managed / merged entries skipped because they belong to a different platform
-- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (customTUI command files under the same path prefix are preserved)
+- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false`
 - `merged.pending`: list of merged files for AI to process
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
 - `registryAdded`: newly added file registry entries

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -43,7 +43,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 - `managed.conflicts`：来源未知、双边修改或平台切换时无法证明官方所有权的 guarded managed 冲突；必须逐项展示 target、reason 与三方哈希
 - `managed.removed`：被删除的 managed 文件（包括模板迁移时移除的旧路径）
 - `managed.skippedPlatform`：因归属其他平台而被跳过的 managed / merged 条目
-- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目（落在同一路径前缀下的 customTUI 命令文件会被保留）
+- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目
 - `merged.pending`：需要 AI 处理的 merged 文件列表
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
 - `registryAdded`：新增的文件注册条目