@trim21/personal-pi-extensions 0.0.312 → 0.0.313

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.312",
+  "version": "0.0.313",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/spawn-agent-agents.ts

@@ -13,8 +13,9 @@
  *     - grep
  *     - find
  *     - ls
- *   model: claude-haiku-4-5     # optional
- *   thinkingLevel: high         # optional; applied as "model:high"
+ *   provider: openai           # optional; overrides the global default
+ *   model: claude-haiku-4-5     # optional; overrides the global default
+ *   thinkingLevel: high         # optional; overrides the global default
  *   ---
  *   System prompt for the agent goes here.
  *
@@ -22,22 +23,33 @@
  * (missing name/description, wrong field types) are skipped. If `tools` is
  * omitted, the subagent runs with the read-only default toolset from the
  * spawn-agent config (read/grep/find/ls) unless overridden there.
+ *
+ * Global defaults for provider/model/thinkingLevel come from
+ * `~/.pi/agent/spawn-agent.json` (see loadSpawnAgentConfig); frontmatter
+ * fields take precedence over them, which in turn take precedence over the
+ * top-level defaultProvider/defaultModel/defaultThinkingLevel in pi's
+ * settings.json.
  */
 
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
-/** Valid thinking levels, mirroring pi's ThinkingLevel type. */
-const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+/**
+ * Valid thinking levels, mirroring pi's CLI --thinking validation
+ * (VALID_THINKING_LEVELS). "off" disables thinking; "max" is deliberately
+ * excluded — pi's CLI layer does not accept it.
+ */
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 
 const agentFrontmatterSchema = Type.Object({
   name: Type.String({ minLength: 1 }),
   description: Type.String({ minLength: 1 }),
   tools: Type.Optional(Type.Array(Type.String())),
+  provider: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
   thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
 });
@@ -55,13 +67,25 @@ export interface AgentConfig {
   description: string;
   /** Toolset from the frontmatter; undefined means "use the config default". */
   tools?: string[];
+  provider?: string;
   model?: string;
-  /** Thinking level, applied as a ":level" suffix on the model id. */
+  /** Thinking level, applied via --thinking. */
   thinkingLevel?: (typeof THINKING_LEVELS)[number];
   systemPrompt: string;
   filePath: string;
 }
 
+/**
+ * Global defaults resolved for subagents. Fields are optional: an absent
+ * field means "not configured", and applyAgentDefaults leaves the frontmatter
+ * value (or its absence) untouched.
+ */
+export interface SpawnAgentDefaults {
+  provider?: string;
+  model?: string;
+  thinkingLevel?: (typeof THINKING_LEVELS)[number];
+}
+
 export function discoverAgents(dir = join(getAgentDir(), "agents")): AgentConfig[] {
   let entries;
   try {
@@ -91,6 +115,7 @@ export function discoverAgents(dir = join(getAgentDir(), "agents")): AgentConfig
       name: fm.name,
       description: fm.description,
       tools: fm.tools,
+      provider: fm.provider,
       model: fm.model,
       thinkingLevel: fm.thinkingLevel,
       systemPrompt: body,
@@ -100,6 +125,92 @@ export function discoverAgents(dir = join(getAgentDir(), "agents")): AgentConfig
   return agents;
 }
 
+/**
+ * Load the global subagent defaults from `~/.pi/agent/spawn-agent.json`,
+ * falling back per-field to the top-level defaultProvider/defaultModel/
+ * defaultThinkingLevel in pi's settings.json (same pattern as the vision and
+ * session-name extensions). Returns undefined when the spawn-agent.json file
+ * is missing, broken, or empty — in that case applyAgentDefaults leaves agents
+ * untouched and the subagent inherits pi's own defaults.
+ */
+export function loadSpawnAgentConfig(
+  spawnAgentPath: string,
+  settingsPath: string,
+): SpawnAgentDefaults | undefined {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(spawnAgentPath, "utf8"));
+  } catch {
+    return undefined; // 文件缺失或 JSON 损坏
+  }
+  let config: SpawnAgentDefaults;
+  try {
+    config = Value.Parse(spawnAgentConfigSchema, raw);
+  } catch {
+    return undefined; // 结构不符（非 object / thinkingLevel 非法等）
+  }
+  if (!config.provider && !config.model && !config.thinkingLevel) return undefined;
+
+  let fallback: SpawnAgentSettingsFallback | undefined;
+  try {
+    fallback = Value.Parse(
+      spawnAgentSettingsFallbackSchema,
+      JSON.parse(readFileSync(settingsPath, "utf8")),
+    );
+  } catch {
+    // settings.json 缺失或损坏：只用 spawn-agent.json 自身的字段
+  }
+  return {
+    provider: nonEmpty(config.provider) ?? nonEmpty(fallback?.defaultProvider),
+    model: nonEmpty(config.model) ?? nonEmpty(fallback?.defaultModel),
+    thinkingLevel:
+      config.thinkingLevel ??
+      (isThinkingLevel(fallback?.defaultThinkingLevel) ? fallback.defaultThinkingLevel : undefined),
+  };
+}
+
+/** spawn-agent.json 的 schema；thinkingLevel 限定与 frontmatter 相同的合法集合 */
+const spawnAgentConfigSchema = Type.Object({
+  provider: Type.Optional(Type.String()),
+  model: Type.Optional(Type.String()),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+});
+
+/** pi settings.json 顶层的兜底字段；thinkingLevel 用宽松字符串，解析后再过滤 */
+const spawnAgentSettingsFallbackSchema = Type.Object({
+  defaultProvider: Type.Optional(Type.String()),
+  defaultModel: Type.Optional(Type.String()),
+  defaultThinkingLevel: Type.Optional(Type.String()),
+});
+
+type SpawnAgentSettingsFallback = Static<typeof spawnAgentSettingsFallbackSchema>;
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value?.trim() || undefined;
+}
+
+function isThinkingLevel(value: string | undefined): value is (typeof THINKING_LEVELS)[number] {
+  return value !== undefined && (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+/**
+ * Merge global defaults into discovered agents, field by field: a frontmatter
+ * value always wins; otherwise the global default is used. Returns the input
+ * array unchanged when there are no defaults.
+ */
+export function applyAgentDefaults(
+  agents: AgentConfig[],
+  defaults: SpawnAgentDefaults | undefined,
+): AgentConfig[] {
+  if (!defaults) return agents;
+  return agents.map((agent) => ({
+    ...agent,
+    provider: agent.provider ?? defaults.provider,
+    model: agent.model ?? defaults.model,
+    thinkingLevel: agent.thinkingLevel ?? defaults.thinkingLevel,
+  }));
+}
+
 export function formatAgentList(agents: AgentConfig[]): string {
   if (agents.length === 0) return "none";
   return agents.map((a) => `${a.name}: ${a.description}`).join("; ");

package/src/spawn-agent.ts

@@ -34,6 +34,7 @@ import {
   type AgentSessionEvent,
   type ExtensionAPI,
   type ExtensionUIContext,
+  getAgentDir,
   type RpcExtensionUIRequest,
   type RpcExtensionUIResponse,
   truncateTail,
@@ -43,7 +44,13 @@ import {
 import { Type } from "typebox";
 
 import { type ToolPendant } from "./lib/pendant.js";
-import { type AgentConfig, discoverAgents, formatAgentList } from "./spawn-agent-agents.js";
+import {
+  type AgentConfig,
+  applyAgentDefaults,
+  discoverAgents,
+  formatAgentList,
+  loadSpawnAgentConfig,
+} from "./spawn-agent-agents.js";
 
 // ── constants ────────────────────────────────────────────────────────────────
 
@@ -55,6 +62,13 @@ const DEFAULT_TOOLS = ["read", "grep", "find", "ls"];
 const MAX_PROGRESS_LINES = 5;
 /** Progress line content (without the `tool:` / `text:` prefix) is capped at 21 chars; longer text is folded to the first/last 9 chars joined by ` … `. */
 const MAX_PROGRESS_CHARS_PER_LINE = 21;
+/** stderr 采集上限：防止子代理崩溃循环输出撑爆内存；保留尾部（错误信息通常在尾部）。 */
+const MAX_STDERR_CAPTURE_BYTES = 64 * 1024;
+/** 错误消息里 stderr 的展示上限。 */
+const MAX_STDERR_ERROR_BYTES = 4 * 1024;
+/** 全局默认配置：~/.pi/agent/spawn-agent.json，字段可被 frontmatter 覆盖。 */
+const SPAWN_AGENT_CONFIG_PATH = join(getAgentDir(), "spawn-agent.json");
+const SETTINGS_PATH = join(getAgentDir(), "settings.json");
 
 /**
  * Tool → extension override map: when a subagent's frontmatter enables a
@@ -133,6 +147,26 @@ function getFinalOutput(messages: AgentMessage[]): string {
   return "";
 }
 
+/**
+ * 组装失败消息，按来源分行（error/stderr/output）让父模型能分辨信息出处；
+ * stderr 截断到尾部（错误信息通常在最后）。全空时保底 "(no output)"，
+ * 避免只回一个 exit code。
+ */
+export function formatSubagentError(result: SubagentDetails): { reason: string; message: string } {
+  const reason =
+    result.stopReason ?? (result.exitCode === 0 ? "failed" : `exit ${result.exitCode}`);
+  const parts: string[] = [];
+  if (result.errorMessage) parts.push(`error: ${result.errorMessage}`);
+  const stderr = truncateTail(result.stderr, { maxBytes: MAX_STDERR_ERROR_BYTES });
+  if (stderr.content.trim()) {
+    const truncatedMark = stderr.truncated ? "\n[stderr truncated]" : "";
+    parts.push(`stderr: ${stderr.content.trim()}${truncatedMark}`);
+  }
+  const output = getFinalOutput(result.messages);
+  if (output) parts.push(`output: ${output}`);
+  return { reason, message: parts.length > 0 ? parts.join("\n") : "(no output)" };
+}
+
 /**
  * Fold over-long progress line content: keep the first/last 9 chars joined by
  * ` … ` (space, ellipsis, space), so the folded line never exceeds
@@ -219,13 +253,15 @@ export function buildSubagentArgs(
   // per-tool overrides) run inside the subagent.
   const args: string[] = ["--mode", "rpc", "--no-session", "--no-extensions"];
 
-  // Thinking level rides on the model shorthand ("model:level"); it cannot be
-  // set without a model, so a level without a model is ignored.
-  const model =
-    agent.model !== undefined && agent.thinkingLevel !== undefined
-      ? `${agent.model}:${agent.thinkingLevel}`
-      : agent.model;
-  if (model) args.push("--model", model);
+  // provider/model/thinkingLevel 已由 applyAgentDefaults 合并进 agent。
+  // --provider 只在 model 不含 "/" 前缀时传：带前缀的 model（如
+  // "openai/gpt-4o"）由 pi 自己解析 provider，显式传 provider 会冲突。
+  if (agent.model && !agent.model.includes("/") && agent.provider) {
+    args.push("--provider", agent.provider);
+  }
+  if (agent.model) args.push("--model", agent.model);
+  // --thinking 独立传参；pi 支持 "off" 显式关闭思考。
+  if (agent.thinkingLevel) args.push("--thinking", agent.thinkingLevel);
   // Read-only default unless the agent explicitly declares a toolset.
   const tools = agent.tools ?? DEFAULT_TOOLS;
   // Load the opencode override for each built-in tool the agent declares
@@ -514,7 +550,7 @@ export async function runAgent(
     });
 
     proc.stderr.on("data", (data: Buffer) => {
-      result.stderr += data.toString();
+      result.stderr = (result.stderr + data.toString()).slice(-MAX_STDERR_CAPTURE_BYTES);
     });
 
     proc.stdin.on("error", (error) => {
@@ -524,13 +560,23 @@ export async function runAgent(
     sendRpc({ type: "prompt", message: `Task: ${task}` });
 
     const exitCode = await new Promise<number>((resolve) => {
-      proc.on("close", (code) => {
+      proc.on("close", (code, childSignal) => {
         if (buffer.trim()) processLine(buffer);
-        resolve(code ?? 0);
+        // 被信号终止时 code 为 null，不能算 0——否则中断会被误判为成功
+        resolve(code ?? (childSignal ? 1 : 0));
+      });
+      proc.on("error", (error) => {
+        // spawn 失败（如 pi 命令不存在）时 error 先于 close 触发；
+        // 记录真实错误，而不是只留一个 exit code。
+        result.errorMessage = error.message;
+        result.stopReason ??= "error";
+        resolve(1);
       });
-      proc.on("error", () => resolve(1));
 
       const kill = () => {
+        // abort 可能发生在子代理产生任何结果之前；标记 aborted 让上层
+        // 识别中断（已有 stopReason 则保留，避免误报）。
+        result.stopReason ??= "aborted";
         proc.kill("SIGTERM");
         setTimeout(() => {
           if (!proc.killed) proc.kill("SIGKILL");
@@ -599,9 +645,12 @@ export default function spawnAgent(pi: ExtensionAPI) {
 
   // Discover the available subagent types once at extension startup. The
   // extension owns this discovery: the model never has to guess agent names
-  // or read the agent directory itself. Editing ~/.pi/agent/agents/*.md
-  // requires /reload to take effect.
-  const agents = discoverAgents();
+  // or read the agent directory itself. Editing ~/.pi/agent/agents/*.md or
+  // ~/.pi/agent/spawn-agent.json requires /reload to take effect.
+  const agents = applyAgentDefaults(
+    discoverAgents(),
+    loadSpawnAgentConfig(SPAWN_AGENT_CONFIG_PATH, SETTINGS_PATH),
+  );
   const agentListSection = agents.length > 0 ? formatAgentListSection(agents) : null;
 
   if (agentListSection) {
@@ -661,13 +710,10 @@ export default function spawnAgent(pi: ExtensionAPI) {
       const isError =
         result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
       if (isError) {
-        const reason =
-          result.stopReason ?? (result.exitCode === 0 ? "failed" : `exit ${result.exitCode}`);
-        const message =
-          result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+        const { reason, message } = formatSubagentError(result);
         return {
           content: [
-            { type: "text", text: `Subagent "${result.agent}" failed (${reason}): ${message}` },
+            { type: "text", text: `Subagent "${result.agent}" failed (${reason}):\n${message}` },
           ],
           details: {
             ...result,