@trim21/personal-pi-extensions 0.1.690 → 0.1.692

package/src/lib/github-reads.ts

@@ -15,7 +15,7 @@ import { pipeline } from "node:stream/promises";
 
 import type { Octokit } from "octokit";
 
-import { createGithubApi, type GithubClientOptions } from "./github.js";
+import { type GithubApi } from "./github.js";
 
 /** `actions.listWorkflowRuns*` 的 `status` 取值（octokit 是字面量联合，工具参数是 string）。 */
 type WorkflowRunParams = NonNullable<
@@ -146,23 +146,6 @@ function limitOf(limit: number | undefined, fallback: number): number {
   return Math.min(Math.max(limit ?? fallback, 1), 100);
 }
 
-/** 响应体不是 2xx 时抛错（状态、URL 与 GitHub 的 message 都在里面）。 */
-async function ensureOk(response: Response): Promise<Response> {
-  if (response.ok) {
-    return response;
-  }
-  let detail: string | undefined;
-  try {
-    const body = await response.text();
-    detail = (JSON.parse(body) as { message?: string }).message ?? body.slice(0, 200);
-  } catch {
-    detail = undefined;
-  }
-  throw new Error(
-    `GitHub API error (HTTP ${response.status}) at ${response.url}${detail === undefined || detail === "" ? "" : `: ${detail}`}`,
-  );
-}
-
 function octokitRequest(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal };
 }
@@ -172,9 +155,7 @@ function asJson(value: unknown): unknown {
   return value;
 }
 
-export function createGithubReads(options: GithubClientOptions = {}): GithubReads {
-  const api = createGithubApi(options);
-
+export function createGithubReads(api: GithubApi): GithubReads {
   return {
     async issue(owner, repo, number, signal) {
       const { data } = await api.call((octokit) =>
@@ -373,11 +354,11 @@ export function createGithubReads(options: GithubClientOptions = {}): GithubRead
     },
 
     async downloadAssetTo(owner, repo, assetId, destPath, signal) {
+      // rawFetch 非 2xx 直接抛 GithubApiError；这里只需流式落盘
       const response = await api.rawFetch(
         `https://api.github.com/repos/${owner}/${repo}/releases/assets/${assetId}`,
         { headers: { accept: "application/octet-stream" }, ...(signal && { signal }) },
       );
-      await ensureOk(response);
       await streamToFile(response, destPath);
     },
 
@@ -388,7 +369,6 @@ export function createGithubReads(options: GithubClientOptions = {}): GithubRead
         `https://api.github.com/repos/${owner}/${repo}/${kind}${suffix}`,
         { ...(signal && { signal }) },
       );
-      await ensureOk(response);
       await streamToFile(response, destPath);
     },
   };

package/src/lib/github.ts

@@ -270,21 +270,41 @@ export function normalizeRestList(items: unknown, repo: string): SearchHit[] {
 }
 
 /**
- * Error thrown when the GitHub search API rejects the request. Carries the
- * original toolcall params so the model can see the exact input.
+ * GitHub 请求失败：octokit 调用与非 JSON 的原始下载共用这一个类型，调用方据此区分
+ * 「不存在」（`isNotFound`）与真失败，不用再各自去剥错误对象上的 status。
+ *
+ * `input` 是触发该请求的工具参数；带上它，模型才能在报错里看到自己给的输入。
  */
-class GithubSearchError extends Error {
-  readonly params: SearchParams;
+export class GithubApiError extends Error {
+  /** HTTP 状态；连响应都没拿到（网络错误）时为 undefined。 */
   readonly status: number | undefined;
-
-  constructor(message: string, params: SearchParams, status?: number) {
-    super(`${message} (input: ${JSON.stringify(params)})`);
-    this.name = "GithubSearchError";
-    this.params = params;
-    this.status = status;
+  readonly input: unknown;
+
+  constructor(
+    message: string,
+    options: { status?: number; input?: unknown; cause?: unknown } = {},
+  ) {
+    const inputText =
+      options.input === undefined ? "" : ` (input: ${JSON.stringify(options.input)})`;
+    super(
+      `${message}${inputText}`,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.name = "GithubApiError";
+    this.status = options.status;
+    this.input = options.input;
   }
 }
 
+/** 404：资源不存在或 token 没有访问权限——与网络/限流错误分开处理。 */
+export function isNotFound(error: unknown): boolean {
+  return error instanceof GithubApiError && error.status === 404;
+}
+
+const errorStatus = (error: unknown): number | undefined => (error as { status?: number }).status;
+const errorMessage = (error: unknown): string =>
+  (error as { message?: string }).message ?? String(error);
+
 function describeHttpError(status: number | undefined): string {
   if (status === 401) {
     return 'GitHub auth failed (401): token invalid or expired — run "gh auth login"';
@@ -298,12 +318,35 @@ function describeHttpError(status: number | undefined): string {
   return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
 }
 
+/** 非 2xx 的原始响应（二进制下载）转成错误：状态、URL 与 GitHub 的 message 一起给出。 */
+async function ensureOk(response: Response): Promise<Response> {
+  if (response.ok) {
+    return response;
+  }
+  let detail: string | undefined;
+  try {
+    const body = await response.text();
+    detail = (JSON.parse(body) as { message?: string }).message ?? body.slice(0, 200);
+  } catch {
+    detail = undefined;
+  }
+  throw new GithubApiError(
+    `GitHub API error (HTTP ${response.status}) at ${response.url}${detail === undefined || detail === "" ? "" : `: ${detail}`}`,
+    { status: response.status },
+  );
+}
+
 export interface GithubApi {
-  /** Run an octokit request; retries once with a fresh token on 401. */
-  call<T>(fn: (octokit: Octokit) => Promise<T>): Promise<T>;
+  /**
+   * Run an octokit request; retries once with a fresh token on 401. Failures
+   * are rethrown as `GithubApiError`; `input` (the toolcall params behind the
+   * request) is attached to that error when given.
+   */
+  call<T>(fn: (octokit: Octokit) => Promise<T>, input?: unknown): Promise<T>;
   /**
    * 用同一个 token 直接 fetch（二进制资产、源码归档这类要走原始响应体、不能经 octokit
-   * 的 JSON 解析的请求）。重定向自动跟随，401 同样丢缓存重试一次。
+   * 的 JSON 解析的请求）。重定向自动跟随，401 同样丢缓存重试一次；非 2xx 抛
+   * `GithubApiError`（状态、URL 与 GitHub 的 message 都在里面）。
    */
   rawFetch(url: string, init?: RequestInit): Promise<Response>;
 }
@@ -361,18 +404,26 @@ export function createGithubApi(options: GithubClientOptions = {}): GithubApi {
   }
 
   return {
-    async call(fn) {
+    async call(fn, input) {
       for (let attempt = 0; ; attempt += 1) {
         try {
           return await fn(await getClient());
         } catch (error) {
-          const status = (error as { status?: number }).status;
+          const status = errorStatus(error);
           if (status === 401 && attempt === 0 && client) {
             token = undefined;
             client = undefined;
             continue;
           }
-          throw error;
+          // 统一在这里成 GithubApiError：调用方（工具、诊断）拿到的是同一种错误形态，
+          // 不必各自去剥 status / message。
+          throw error instanceof GithubApiError
+            ? error
+            : new GithubApiError(`${describeHttpError(status)}: ${errorMessage(error)}`, {
+                status,
+                input,
+                cause: error,
+              });
         }
       }
     },
@@ -381,7 +432,7 @@ export function createGithubApi(options: GithubClientOptions = {}): GithubApi {
       for (let attempt = 0; ; attempt += 1) {
         const response = await rawFetchOnce(url, init);
         if (response.status !== 401 || attempt > 0) {
-          return response;
+          return ensureOk(response);
         }
         await response.body?.cancel();
       }
@@ -394,31 +445,22 @@ export interface GithubSearch {
 }
 
 /**
- * Create a search client backed by a cached octokit instance.
+ * Create a search client on top of a shared API accessor (见 `createGithubApi`)：
+ * 一个会话只应有一个 accessor，搜索 / checks / reads 共用同一份 octokit 与 token 缓存。
  */
-export function createGithubSearch(options: GithubClientOptions = {}): GithubSearch {
-  const api = createGithubApi(options);
-
+export function createGithubSearch(api: GithubApi): GithubSearch {
   return {
     async search(kind, params) {
       const limit = Math.min(Math.max(params.limit ?? 30, 1), 100);
-
-      try {
-        // `@me` 是 gh CLI 的简写，REST 搜索不认识：这里不展开，带关键词时它按字面量
-        // 进入查询串（无关键词的列表走 gh CLI，由 gh 自己展开）。
-        const q = buildSearchQuery(kind, { ...params, limit });
-        return await api.call(async (client) => {
-          const { data } = await client.rest.search.issuesAndPullRequests({
-            q,
-            per_page: limit,
-          });
-          return data.items.map((item) => normalize(parseWithSchema(searchItemSchema, item)));
+      // `@me` 是 gh CLI 的简写，REST 搜索不认识：这里不展开，它按字面量进入查询串。
+      const q = buildSearchQuery(kind, { ...params, limit });
+      return await api.call(async (client) => {
+        const { data } = await client.rest.search.issuesAndPullRequests({
+          q,
+          per_page: limit,
         });
-      } catch (error) {
-        const status = (error as { status?: number }).status;
-        const message = (error as { message?: string }).message ?? String(error);
-        throw new GithubSearchError(`${describeHttpError(status)}: ${message}`, params, status);
-      }
+        return data.items.map((item) => normalize(parseWithSchema(searchItemSchema, item)));
+      }, params);
     },
   };
 }
@@ -522,7 +564,7 @@ export interface GithubChecksClient {
 }
 
 /**
- * Create a client for PR CI checks, backed by a cached octokit instance.
+ * Create a client for PR CI checks on top of a shared API accessor.
  * Covers both check sources GitHub exposes for a commit — classic commit
  * statuses (Azure DevOps, Jenkins, ...) and check runs (GitHub Actions,
  * GitHub Apps) — so external CI is visible to the caller.
@@ -553,9 +595,7 @@ function toRunJob(job: ApiJob): RunJob {
   };
 }
 
-export function createGithubChecks(options: GithubClientOptions = {}): GithubChecksClient {
-  const api = createGithubApi(options);
-
+export function createGithubChecks(api: GithubApi): GithubChecksClient {
   return {
     async statuses(owner, repo, ref, signal) {
       const { data } = await api.call((octokit) =>

package/src/lib/model-call.ts

@@ -25,6 +25,8 @@ import {
   type UserMessage,
 } from "@earendil-works/pi-ai";
 
+import { withTimeoutSignal } from "./abort.js";
+
 /**
  * 模型注册表操作：扩展传 `ctx.modelRegistry`，测试传 mock。
  * 结构化类型（duck typing），只声明用到的两个方法。
@@ -58,12 +60,6 @@ export interface CompleteTextResult {
   usage: Usage;
 }
 
-/** 合并调用方 signal 与本地超时；调用方未传时仍然有超时兜底 */
-function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
-  const timeout = AbortSignal.timeout(ms);
-  return signal ? AbortSignal.any([signal, timeout]) : timeout;
-}
-
 /**
  * 用给定模型生成正文。`registry.complete` 抛出的错误原样向上抛（含
  * `AbortError`），取消与失败的区分由调用方决定。
@@ -79,7 +75,7 @@ export async function completeText(options: CompleteTextOptions): Promise<Comple
     },
     {
       maxTokens: options.maxTokens ?? options.model.maxTokens,
-      signal: withTimeout(options.signal, options.timeoutMs),
+      signal: withTimeoutSignal(options.signal, options.timeoutMs),
     },
   );
   const text = contentText(result.content).trim();

package/src/lib/tool-bus.ts

@@ -3,7 +3,9 @@
  * （按名执行，不必绕回模型）。
  *
  * - `register`：按配置过滤（被禁用时跳过并返回 false）后交给 `pi.registerTool`，
- *   并保留通过的定义供 `list` / `get` 查询。
+ *   并保留通过的定义供 `list` / `get` 查询。命中 codemode-only 且声明了
+ *   `structuredSchema` 的工具只保留在总线上、不交给 pi（标 `codemodeOnly: true`）；
+ *   命中但没有 schema 的工具照常注册，并在 `diagnostics` 里留一条说明。
  * - `executeTool`：先用工具自身的参数 schema 校验参数，再调用定义的 `execute`；
  *   参数校验失败与工具抛出的异常都归一化成错误结果返回，不向调用方抛异常。
  *
@@ -85,9 +87,10 @@ export interface ExecuteToolOptions {
   toolCallId?: string;
 }
 
-/** 注册后的定义：多出的 `structuredSchema` 供 codemode 渲染脚本侧返回类型。 */
+/** 注册后的定义：多出的 `structuredSchema` 供 codemode 渲染脚本侧返回类型，`codemodeOnly` 标出未交给 pi 的只读脚本工具。 */
 export type RegisteredToolDefinition = ToolDefinition<TSchema, unknown, unknown> & {
   structuredSchema?: TSchema;
+  codemodeOnly?: boolean;
 };
 
 export interface ToolBus {
@@ -99,6 +102,8 @@ export interface ToolBus {
   list(): readonly RegisteredToolDefinition[];
   /** 所有尝试注册过的工具名（含被禁用而跳过的），用于校验配置里的模式是否有效。 */
   declaredNames(): readonly string[];
+  /** 注册期发现的可诊断问题（去重），由调用方在能提示用户时上报。 */
+  diagnostics(): readonly string[];
   get(name: string): RegisteredToolDefinition | undefined;
   /** 按名执行一个已注册工具；任何失败都以 `isError` 结果返回，不抛异常。 */
   executeTool(
@@ -111,6 +116,8 @@ export interface ToolBus {
 export interface ToolBusOptions {
   /** 返回 true 表示该工具被禁用、不注册。 */
   isDisabled?: (name: string) => boolean;
+  /** 返回 true 表示该工具应只进 codemode（是否真的如此还要看它有没有声明 `structuredSchema`）。 */
+  isCodemodeOnly?: (name: string) => boolean;
 }
 
 function errorResult(text: string): ToolExecutionResult {
@@ -180,6 +187,7 @@ function checkStructuredResult(
 export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): ToolBus {
   const registered = new Map<string, RegisteredToolDefinition>();
   const declared = new Set<string>();
+  const diagnostics = new Set<string>();
   let callCounter = 0;
 
   return {
@@ -188,6 +196,22 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
       if (options.isDisabled?.(definition.name) === true) {
         return false;
       }
+      if (options.isCodemodeOnly?.(definition.name) === true) {
+        // schema 门控：进不了 codemode 的工具照常直接注册，只留一条可诊断的说明，
+        // 避免配置把工具从模型面前静默移除（见 openspec design.md）。
+        if ((definition as { structuredSchema?: unknown }).structuredSchema === undefined) {
+          diagnostics.add(
+            `personalExtensions.codemodeOnlyTools: tool "${definition.name}" declares no structuredSchema; it stays directly available.`,
+          );
+        } else {
+          const codemodeStored = {
+            ...(definition as unknown as RegisteredToolDefinition),
+            codemodeOnly: true,
+          };
+          registered.set(codemodeStored.name, codemodeStored);
+          return true;
+        }
+      }
       const stored = definition as unknown as RegisteredToolDefinition;
       pi.registerTool(stored);
       registered.set(stored.name, stored);
@@ -202,6 +226,10 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
       return [...declared];
     },
 
+    diagnostics() {
+      return [...diagnostics];
+    },
+
     get(name) {
       return registered.get(name);
     },

package/src/lib/tool-registration.ts

@@ -41,6 +41,8 @@ export interface ToolRegistration {
   onSessionStart(register: (bus: ToolBus, ctx: ExtensionContext) => void | Promise<void>): void;
   /** 哪些配置模式没命中过任何工具（在注册完成后调用）。 */
   unmatchedPatterns(): UnmatchedPattern[];
+  /** 注册期发现的可诊断问题（去重），与 unmatchedPatterns 一样在注册完成后上报。 */
+  diagnostics(): readonly string[];
 }
 
 /**
@@ -62,6 +64,7 @@ export function createToolRegistration(pi: ExtensionAPI, settingsPath?: string):
     // 每次注册都按当前模型重新判定：工具在 session_start 里注册，模型由下面
     // 的 handler 更新，二者在同一个会话内保持一致。
     isDisabled: (name) => resolveToolAvailability(config, model).isDisabled(name),
+    isCodemodeOnly: (name) => resolveToolAvailability(config, model).isCodemodeOnly(name),
   });
 
   pi.on("session_start", (_event, ctx) => {
@@ -79,5 +82,8 @@ export function createToolRegistration(pi: ExtensionAPI, settingsPath?: string):
     unmatchedPatterns() {
       return resolveToolAvailability(config, model).unmatchedPatterns(bus.declaredNames());
     },
+    diagnostics() {
+      return bus.diagnostics();
+    },
   };
 }

package/src/lib/tools-config.ts

@@ -7,7 +7,8 @@
  *     "fileIo": "claude-code",
  *     "fileIoByModel": [{ "models": ["glm-*"], "fileIo": "opencode" }],
  *     "disabledTools": ["talk-*", { "tools": ["web_*"], "models": ["gpt-*"] }],
- *     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }]
+ *     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }],
+ *     "codemodeOnlyTools": [{ "tools": ["read-github-*"], "models": ["glm-*"] }]
  *   }
  * }
  * ```
@@ -15,6 +16,9 @@
  * 工具名与模型名都用 minimatch 通配模式匹配；模型名同时试 `model.id` 与
  * `provider/model` 两种写法。带 `models` 的条目只在当前模型命中时才参与判定。
  * 非法字段/条目被忽略并产出警告，不影响其余配置生效。
+ *
+ * `codemodeOnlyTools` 只表示曝光方式：命中它的工具由总线决定是否按 codemode-only
+ * 注册（还要看工具有没有声明 `structuredSchema`，见 `tool-bus.ts`）。
  */
 
 import { readFileSync } from "node:fs";
@@ -25,6 +29,8 @@ import { minimatch } from "minimatch";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "./narrow.js";
+
 // ── schema ───────────────────────────────────────────────────────────────────
 
 const fileIoSchema = Type.Union([Type.Literal("claude-code"), Type.Literal("opencode")]);
@@ -43,7 +49,7 @@ const toolRuleSchema = Type.Object({
 
 export type FileIoToolset = "claude-code" | "opencode";
 
-export type ToolRuleField = "disabledTools" | "enabledTools";
+export type ToolRuleField = "disabledTools" | "enabledTools" | "codemodeOnlyTools";
 
 export interface FileIoByModelEntry {
   models: readonly string[];
@@ -63,6 +69,8 @@ export interface ToolsConfig {
   fileIoByModel: readonly FileIoByModelEntry[];
   disabledTools: readonly ToolPatternRule[];
   enabledTools: readonly ToolPatternRule[];
+  /** 命中且声明了 `structuredSchema` 的工具只进 codemode、不交给 pi。 */
+  codemodeOnlyTools: readonly ToolPatternRule[];
   /** 解析阶段发现的问题，由调用方在能提示用户时上报。 */
   warnings: readonly string[];
 }
@@ -80,6 +88,8 @@ export interface UnmatchedPattern {
 export interface ToolAvailability {
   /** 该工具名是否被禁用（命中 disabledTools 且未命中 enabledTools）。 */
   isDisabled(name: string): boolean;
+  /** 该工具名是否命中 codemodeOnlyTools（是否真的按 codemode-only 注册还要看它有没有结构化输出）。 */
+  isCodemodeOnly(name: string): boolean;
   /** 哪些模式没匹配到任何工具（含被规则禁用的工具）。 */
   unmatchedPatterns(declaredNames: readonly string[]): UnmatchedPattern[];
 }
@@ -88,10 +98,6 @@ export const DEFAULT_FILE_IO: FileIoToolset = "claude-code";
 
 // ── 读取与解析 ───────────────────────────────────────────────────────────────
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function parseFileIo(value: unknown, field: string, warnings: string[]): FileIoToolset | undefined {
   if (value === undefined) {
     return undefined;
@@ -167,6 +173,7 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
       fileIoByModel: [],
       disabledTools: [],
       enabledTools: [],
+      codemodeOnlyTools: [],
       warnings,
     };
   }
@@ -177,6 +184,7 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
       fileIoByModel: [],
       disabledTools: [],
       enabledTools: [],
+      codemodeOnlyTools: [],
       warnings,
     };
   }
@@ -186,6 +194,11 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
     fileIoByModel: parseFileIoByModel(section.fileIoByModel, `${source}.fileIoByModel`, warnings),
     disabledTools: parseToolRules(section.disabledTools, `${source}.disabledTools`, warnings),
     enabledTools: parseToolRules(section.enabledTools, `${source}.enabledTools`, warnings),
+    codemodeOnlyTools: parseToolRules(
+      section.codemodeOnlyTools,
+      `${source}.codemodeOnlyTools`,
+      warnings,
+    ),
     warnings,
   };
 }
@@ -260,9 +273,13 @@ export function resolveToolAvailability(
       return config.enabledTools.every((rule) => !ruleMatches(rule, name, model));
     },
 
+    isCodemodeOnly(name) {
+      return config.codemodeOnlyTools.some((rule) => ruleMatches(rule, name, model));
+    },
+
     unmatchedPatterns(declaredNames) {
       const unmatched: UnmatchedPattern[] = [];
-      for (const field of ["disabledTools", "enabledTools"] as const) {
+      for (const field of ["disabledTools", "enabledTools", "codemodeOnlyTools"] as const) {
         for (const rule of config[field]) {
           for (const pattern of rule.tools) {
             if (declaredNames.every((name) => !matchesPattern(pattern, name))) {

package/src/opencode/bash.ts

@@ -1,5 +1,4 @@
 import { readFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
@@ -12,53 +11,23 @@ import {
   formatElapsedSeconds,
   sandboxHintBlock,
 } from "../bwrap/runtime.js";
+import {
+  BASH_DEFAULT_TIMEOUT_MS,
+  BASH_MAX_TIMEOUT_MS,
+  bashStructuredSchema,
+  spilledOutput,
+} from "../lib/bash-tool.js";
 import { resolveWorkdir } from "../lib/path.js";
 import { createRequestPolicy } from "../lib/request-policy.js";
 import { defineStructuredTool, type ToolBus } from "../lib/tool-bus.js";
 import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 
-const DEFAULT_TIMEOUT_MS = 120_000;
-const MAX_TIMEOUT_MS = 7_200_000;
-
 /** 对齐上游 opencode 的截断提示文案（tools/BashTool/bash.ts）。 */
 const CAPTURE_TRUNCATED_NOTICE = "[output capture truncated at the in-memory safety limit]";
 
 /** Bash tool guidance, kept in markdown so it reads like documentation. */
 const BASH_PROMPT = readFileSync(fileURLToPath(new URL("bash.md", import.meta.url)), "utf8").trim();
 
-/**
- * `bash` 的结构化结果：只有退出码与完整输出——命令非零退出不是失败，所以载荷里没有成败
- * 标志，脚本直接读 `exitCode` 分支；超时/中止时 `exitCode` 为 `null`（原因在模型侧文本里）。
- */
-const bashStructuredSchema = Type.Object({
-  exitCode: Type.Union([Type.Number(), Type.Null()], {
-    description: "Exit code of the command; null when it was killed (timeout or abort)",
-  }),
-  output: Type.String({
-    description:
-      "Complete output of the command (stdout and stderr merged). Never truncated, never mixed with tool-added notices.",
-  }),
-});
-
-/**
- * 载荷里的输出：文本被截断时读回落盘的完整输出（读不到就退回那份截断文本），
- * 因此脚本拿到的永远是命令真正输出的内容。
- */
-async function fullOutput(
-  output: string,
-  truncation: TruncationResult,
-  spillPath: string | undefined,
-): Promise<string> {
-  if (spillPath === undefined || !truncation.truncated) {
-    return output;
-  }
-  try {
-    return await readFile(spillPath, "utf8");
-  } catch {
-    return output;
-  }
-}
-
 /** opencode 风格截断提示（成功、超时、中断路径共用）。 */
 function appendTruncationNotice(
   text: string,
@@ -127,9 +96,9 @@ export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapR
         { additionalProperties: false },
       ),
       async execute(id, params, signal, onUpdate, ctx) {
-        const timeout = params.timeout ?? DEFAULT_TIMEOUT_MS;
-        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_MS) {
-          throw new Error(`timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds`);
+        const timeout = params.timeout ?? BASH_DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > BASH_MAX_TIMEOUT_MS) {
+          throw new Error(`timeout must be between 1 and ${BASH_MAX_TIMEOUT_MS} milliseconds`);
         }
 
         const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
@@ -175,7 +144,7 @@ export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapR
                 ok: true as const,
                 value: {
                   exitCode: null,
-                  output: await fullOutput(
+                  output: await spilledOutput(
                     error.partial.output,
                     error.partial.truncation,
                     error.partial.fullOutputPath,
@@ -208,7 +177,7 @@ export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapR
             ok: true as const,
             value: {
               exitCode: result.exitCode,
-              output: await fullOutput(result.output, result.truncation, result.fullOutputPath),
+              output: await spilledOutput(result.output, result.truncation, result.fullOutputPath),
             },
           },
         };

package/src/opencode/glob.ts

@@ -21,7 +21,7 @@ import { Type } from "typebox";
 import type { ToolBus } from "../lib/tool-bus.js";
 import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { didYouMean } from "./files.js";
-import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
+import { normalizeRipgrepPath, RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
 
 /** Tool guidance, kept in markdown so it reads like documentation. */
 const GLOB_PROMPT = readFileSync(fileURLToPath(new URL("glob.md", import.meta.url)), "utf8").trim();
@@ -30,11 +30,6 @@ export function buildGlobArgs(pattern: string): string[] {
   return ["--no-config", "--files", `--glob=${pattern}`, "--glob=!**/.git/**", "."];
 }
 
-/** rg --files 输出的路径：去掉前导 `./`，分隔符统一成 `/`。 */
-function normalizeRipgrepPath(text: string): string {
-  return text.replace(/^(?:\.[\\/])+/u, "").replaceAll("\\", "/");
-}
-
 export function renderGlobOutput(files: readonly string[], truncated: boolean): string {
   if (files.length === 0) {
     return "No files found";

package/src/opencode/grep.ts

@@ -24,7 +24,7 @@ import { parseWithSchema } from "../lib/parse-with-schema.js";
 import type { ToolBus } from "../lib/tool-bus.js";
 import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { didYouMean } from "./files.js";
-import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
+import { normalizeRipgrepPath, RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
 
 /** Tool guidance, kept in markdown so it reads like documentation. */
 const GREP_PROMPT = readFileSync(fileURLToPath(new URL("grep.md", import.meta.url)), "utf8").trim();
@@ -51,11 +51,6 @@ export interface GrepMatch {
   text: string;
 }
 
-/** rg 输出的路径：去掉前导 `./`，分隔符统一成 `/`。 */
-function normalizeRipgrepPath(text: string): string {
-  return text.replace(/^(?:\.[\\/])+/u, "").replaceAll("\\", "/");
-}
-
 /** 行文本：去掉行尾换行，超长截断（不留半个 surrogate pair）。 */
 function normalizeLineText(text: string): string {
   const line = text.replace(/[\r\n]+$/u, "");

package/src/opencode/ripgrep.ts

@@ -12,6 +12,11 @@ import { spawn } from "node:child_process";
 /** 单次搜索最多返回的结果数（上游 limit = 100）。 */
 export const RIPGREP_RESULT_LIMIT = 100;
 
+/** rg 输出的路径：去掉前导 `./`，分隔符统一成 `/`。 */
+export function normalizeRipgrepPath(text: string): string {
+  return text.replace(/^(?:\.[\\/])+/u, "").replaceAll("\\", "/");
+}
+
 /** stderr 最多保留的字节数（上游 ERROR_BYTES）。 */
 const ERROR_BYTES = 8 * 1024;