pi-subagent-feather 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # pi-subagent-feather
 基于 [`@eggmasonvalue/pi-subagent` 2.0.1](https://github.com/eggmasonvalue/pi-subagent) 的独立 MIT 派生版。
 npm 包名 `pi-subagent-feather`，本地目录 `D:\Work\pi-subagent-lite`。
-版本 `0.1.0`。MIT 授权，见 LICENSE / NOTICE。
+版本 `0.2.0`。MIT 授权，见 LICENSE / NOTICE。
 
 目标：保留独立上下文、子会话存档、resume、并行、超时与实时进度；减少父会话重复数据和额外提示词。
 
@@ -99,7 +99,7 @@ subagent_models({})
   "resultLines": 200,
   "progressBytes": 2048,
   "stderrBytes": 4096,
-  "eventBytes": 8388608
+  "eventBytes": 1048576
 }
 ```
 
@@ -110,6 +110,19 @@ subagent_models({})
 - 所有预算必须是正整数；最大 resultBytes 51200 / resultLines 2000 / eventBytes 64MiB。
 - stderr 是运行期最多4KiB的尾部，失败且没有正文时供模型看；不保存在 details。
 
+其他可选键（同一 config.json，未知键直接报错防拼写）：
+
+- `"offlineChildren": true`：子进程附加 `--offline`，跳过启动时的模型目录网络刷新（更快）。适合 API key 型 provider；OAuth 型子代理凭证过期时可能需要先在主会话刷新凭证。
+- `"defaultTimeoutMs": 30000`：调用未传 `timeoutMs` 时的兜底超时，防失控子进程。
+- `"resultKeep": "tail"`：完成的答案超预算时保留结尾（结论常在末尾）；默认 `"head"`。流式进度始终保留头部。
+- `eventBytes` 默认已降为 1MiB（真实子进程事件被 Pi 自身截断在 50KiB/2000 行内，1MiB 足够），单事件超限仍丢弃并在下一行恢复。
+- 收集器解析前按事件类型做廉价预过滤，不关注的事件类型跳过 JSON.parse。
+
+## /subagents 命令
+
+`/subagents` 列出最近的子会话（时间、大小、模型、路径），纯人看界面，不进入模型上下文、零 token。
+有 UI 时可选择一条并复制其 resume 路径；无 UI（或 RPC 降级）时以通知列出。
+
 ## 开发 / 验证
 
 ```sh

package/extensions/subagent/index.ts

@@ -6,10 +6,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { getSupportedThinkingLevels, StringEnum, type Model } from "@earendil-works/pi-ai";
-import { type ExtensionAPI, getAgentDir, getPackageDir, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, copyToClipboard, getAgentDir, getPackageDir, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { ChildCollector, DEFAULT_LIMITS, type CollectorLimits, type CollectorUsage } from "../../src/collector.ts";
+import { ChildCollector, DEFAULT_LIMITS, type CollectorLimits, type CollectorUsage, type KeepMode } from "../../src/collector.ts";
 
 const CHILD_METADATA_SUFFIX = ".subagent.json";
 const INTERNAL_TOOL_NAMES = new Set(["subagent", "subagent_models"]);
@@ -318,19 +318,39 @@ function bounded(text: string, bytes: number): string {
   return Buffer.from(text.slice(0, end), "utf8").toString("utf8");
 }
 
-function loadLimits(agentDir = getAgentDir()): CollectorLimits {
+interface FeatherConfig {
+  limits: CollectorLimits;
+  offlineChildren: boolean;
+  defaultTimeoutMs?: number;
+  resultKeep: KeepMode;
+}
+
+function loadConfig(agentDir = getAgentDir()): FeatherConfig {
   const file = path.join(agentDir, "pi-subagent-feather", "config.json");
-  if (!fs.existsSync(file)) return { ...DEFAULT_LIMITS };
+  if (!fs.existsSync(file)) return { limits: { ...DEFAULT_LIMITS }, offlineChildren: false, resultKeep: "head" };
   const value = JSON.parse(fs.readFileSync(file, "utf8"));
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid config: ${file}`);
   const limits = { ...DEFAULT_LIMITS };
+  const config: FeatherConfig = { limits, offlineChildren: false, resultKeep: "head" };
   const maximum: CollectorLimits = { resultBytes: 51200, resultLines: 2000, progressBytes: 8192, stderrBytes: 16384, eventBytes: 64 * 1024 * 1024 };
-  for (const key of Object.keys(limits) as (keyof CollectorLimits)[]) {
-    if (value[key] === undefined) continue;
-    if (!Number.isInteger(value[key]) || value[key] < 1 || value[key] > maximum[key]) throw new Error(`Invalid ${key} in ${file}`);
-    limits[key] = value[key];
+  for (const key of Object.keys(value)) {
+    if (key in limits) {
+      if (!Number.isInteger(value[key]) || value[key] < 1 || value[key] > maximum[key as keyof CollectorLimits]) throw new Error(`Invalid ${key} in ${file}`);
+      limits[key as keyof CollectorLimits] = value[key];
+    } else if (key === "offlineChildren") {
+      if (typeof value[key] !== "boolean") throw new Error(`Invalid offlineChildren in ${file}`);
+      config.offlineChildren = value[key];
+    } else if (key === "defaultTimeoutMs") {
+      if (!Number.isInteger(value[key]) || value[key] < 1 || value[key] > 2147483647) throw new Error(`Invalid defaultTimeoutMs in ${file}`);
+      config.defaultTimeoutMs = value[key];
+    } else if (key === "resultKeep") {
+      if (value[key] !== "head" && value[key] !== "tail") throw new Error(`Invalid resultKeep in ${file}`);
+      config.resultKeep = value[key];
+    } else {
+      throw new Error(`Unknown config key "${key}" in ${file}`);
+    }
   }
-  return limits;
+  return config;
 }
 
 function resolveSessionFile(sessionDir: string): string | undefined {
@@ -392,6 +412,8 @@ interface RunChildDependencies {
   agentDir?: string;
   invoke?: (args: string[]) => { command: string; args: string[] };
   limits?: Partial<CollectorLimits>;
+  resultKeep?: KeepMode;
+  offlineChildren?: boolean;
 }
 
 async function runChild(
@@ -399,7 +421,8 @@ async function runChild(
   resumePath: string | undefined, signal: AbortSignal | undefined, onUpdate: Update | undefined,
   dependencies: RunChildDependencies = {},
 ): Promise<RunResult> {
-  const collector = new ChildCollector(dependencies.limits ?? loadLimits(dependencies.agentDir));
+  const feather = loadConfig(dependencies.agentDir);
+  const collector = new ChildCollector({ ...feather.limits, ...dependencies.limits }, { resultKeep: dependencies.resultKeep ?? feather.resultKeep });
   let sessionFile = resumePath, exitCode = -1, status: Status = "running";
   const snapshot = (): Receipt => ({ version: 1, status, label, resumed: Boolean(resumePath), timeoutMs, exitCode,
     sessionFile, sessionId: collector.sessionId, model: config.model ?? collector.model, thinking: config.thinking,
@@ -411,6 +434,7 @@ async function runChild(
   if (!resumePath) await fs.promises.mkdir(sessionDir, { recursive: true });
   const args = ["--mode", "json", "-p"];
   if (resumePath) args.push("--session", resumePath); else args.push("--session-dir", sessionDir);
+  if (dependencies.offlineChildren ?? feather.offlineChildren) args.push("--offline");
   if (config.model) args.push("--model", config.model);
   if (config.thinking) args.push("--thinking", config.thinking);
   if (!config.tools.length) args.push("--no-tools"); else args.push("--tools", config.tools.join(","));
@@ -489,7 +513,78 @@ const SubagentParams = Type.Object({
 
 export const __testing = { allowedThinkingLevels, compactModelCatalog, loadModelPolicy, metadataPath,
   modelFacingResult, readChildMetadata, resolveFreshModel, resolveResumePath, runChild,
-  validateModelPolicy, writeChildMetadata, receiptOf, loadLimits, getPiInvocation, SubagentParams };
+  validateModelPolicy, writeChildMetadata, receiptOf, loadConfig, recentChildSessions, formatBytes,
+  getPiInvocation, SubagentParams };
+
+interface ChildSessionInfo {
+  path: string;
+  mtimeMs: number;
+  bytes: number;
+  sessionId?: string;
+  model?: string;
+  cwd?: string;
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)}KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Recent child sessions (newest first). Read-only: stats, sidecar metadata, first-line id. */
+function recentChildSessions(agentDir = getAgentDir(), max = 24): ChildSessionInfo[] {
+  const root = path.join(agentDir, "sessions", "subagent-lite");
+  let runDirs: string[];
+  try {
+    runDirs = fs.readdirSync(root);
+  } catch {
+    return [];
+  }
+  const sessions: ChildSessionInfo[] = [];
+  for (const run of runDirs) {
+    const dir = path.join(root, run);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".jsonl")) continue;
+      const file = path.join(dir, name);
+      let stat: fs.Stats;
+      try {
+        stat = fs.statSync(file);
+      } catch {
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      const info: ChildSessionInfo = { path: file, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      try {
+        const meta = readChildMetadata(file);
+        info.model = meta.model;
+        info.cwd = meta.cwd;
+      } catch {
+        // Sidecar metadata is optional for listing.
+      }
+      try {
+        const fd = fs.openSync(file, "r");
+        try {
+          const buf = Buffer.alloc(512);
+          const read = fs.readSync(fd, buf, 0, 512, 0);
+          const first = JSON.parse(buf.toString("utf8", 0, read).split("\n", 1)[0]);
+          if (first?.type === "session" && first.id) info.sessionId = String(first.id).slice(0, 64);
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch {
+        // First-line probe is optional.
+      }
+      sessions.push(info);
+    }
+  }
+  return sessions.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, max);
+}
 
 export default function (pi: ExtensionAPI) {
   const running = new Map<AbortController, Promise<RunResult>>();
@@ -498,6 +593,36 @@ export default function (pi: ExtensionAPI) {
     await Promise.allSettled(running.values());
     running.clear();
   });
+  pi.registerCommand("subagents", {
+    description: "List recent subagent child sessions (pick one to copy its resume path)",
+    handler: async (_args, ctx) => {
+      const sessions = recentChildSessions();
+      if (sessions.length === 0) {
+        ctx.ui.notify("No subagent child sessions found.", "info");
+        return;
+      }
+      const lines = sessions.map(s => `${new Date(s.mtimeMs).toLocaleString()} ${formatBytes(s.bytes)} ${s.model ?? "?"} ${s.path}`);
+      if (!ctx.hasUI) {
+        ctx.ui.notify(lines.join("\n"), "info");
+        return;
+      }
+      let picked: string | undefined;
+      try {
+        picked = await ctx.ui.select(`Subagent sessions (${sessions.length})`, lines);
+      } catch {
+        picked = undefined;
+      }
+      if (!picked) return;
+      const chosen = sessions[lines.indexOf(picked)];
+      if (!chosen) return;
+      try {
+        await copyToClipboard(chosen.path);
+        ctx.ui.notify(`Copied resume path: ${chosen.path}`, "info");
+      } catch {
+        ctx.ui.notify(`Resume path: ${chosen.path}`, "info");
+      }
+    },
+  });
   pi.registerTool({
     name: "subagent_models", label: "Subagent Models",
     description: "List child model policy, defaults and supported thinking levels. No child starts.",
@@ -537,8 +662,10 @@ export default function (pi: ExtensionAPI) {
           tools: params.tools ? [...new Set(params.tools)] : pi.getActiveTools().filter(name => !INTERNAL_TOOL_NAMES.has(name)) };
       }
       const controller = new AbortController();
-      const child = runChild(config, params.task, params.label, params.timeoutMs, resumePath,
-        signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, onUpdate);
+      const feather = loadConfig();
+      const child = runChild(config, params.task, params.label, params.timeoutMs ?? feather.defaultTimeoutMs, resumePath,
+        signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, onUpdate,
+        { resultKeep: feather.resultKeep });
       running.set(controller, child);
       try {
         const result = await child;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagent-feather",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pi subagent with bounded parent receipts, persistent child sessions and minimal prompt injection.",
   "license": "MIT",

package/src/collector.ts

@@ -22,12 +22,15 @@ export interface CollectorLimits {
 }
 
 /** Default budgets, identical in spirit to upstream but chosen for a safe fork. */
+/** Where an oversized completed answer keeps content: head (default) or tail. */
+export type KeepMode = "head" | "tail";
+
 export const DEFAULT_LIMITS: CollectorLimits = {
 	resultBytes: 8192,
 	resultLines: 200,
 	progressBytes: 2048,
 	stderrBytes: 4096,
-	eventBytes: 8 * 1024 * 1024,
+	eventBytes: 1024 * 1024,
 };
 
 /** Accumulated token/cost accounting exposed by {@link ChildCollector.usage}. */
@@ -266,6 +269,75 @@ class BoundedText {
 	}
 }
 
+/** Anything BoundedText/TailText can append into. */
+interface TextSink {
+	append(input: string): void;
+}
+
+/**
+ * Raw-substring markers for the event types this collector reads. Pi writes compact
+ * JSON (`"type":"x"`, no spaces), so a line without any needle cannot be one of them;
+ * such lines skip JSON.parse entirely. Key order does not matter (scan, not prefix match).
+ */
+const EVENT_TYPE_NEEDLES = [
+	"session",
+	"message_start",
+	"message_update",
+	"message_end",
+	"tool_execution_start",
+	"tool_execution_end",
+].map(type => `"type":"${type}"`);
+
+/**
+ * Bounded accumulator that keeps the most recent content (tail) instead of the head.
+ * Compaction re-slices only when the budget is exceeded; at the default few-KiB budgets
+ * the amortized cost per appended byte is O(1).
+ */
+class TailText {
+	private readonly maxBytes: number;
+	private readonly maxLines: number;
+	private readonly separator: string;
+	private buf = "";
+	private segments = 0;
+	truncated = false;
+
+	constructor(maxBytes: number, maxLines: number, separator: string) {
+		this.maxBytes = maxBytes;
+		this.maxLines = maxLines;
+		this.separator = separator;
+	}
+
+	append(input: string): void {
+		if (input.length === 0) return;
+		if (this.maxBytes <= 0 || this.maxLines <= 0) {
+			this.truncated = true;
+			return;
+		}
+		if (this.segments > 0 && this.separator.length > 0) this.buf += this.separator;
+		this.segments += 1;
+		this.buf += input;
+		this.compact();
+	}
+
+	private compact(): void {
+		if (utf8Length(this.buf) > this.maxBytes) {
+			this.buf = detach(utf8Tail(this.buf, this.maxBytes));
+			this.truncated = true;
+		}
+		let newlines = 0;
+		for (let i = this.buf.indexOf("\n"); i !== -1; i = this.buf.indexOf("\n", i + 1)) newlines += 1;
+		if (newlines >= this.maxLines) {
+			const lines = this.buf.split("\n");
+			this.buf = detach(lines.slice(lines.length - this.maxLines).join("\n"));
+			this.truncated = true;
+		}
+	}
+
+	value(): string {
+		return this.buf;
+	}
+}
+
 function normalizeLimits(overrides?: Partial<CollectorLimits>): CollectorLimits {
 	const out: CollectorLimits = { ...DEFAULT_LIMITS };
 	if (overrides) {
@@ -288,7 +360,7 @@ function shortToolName(name: unknown): string {
 	return dunder >= 0 ? base.slice(dunder + 2) : base;
 }
 
-function appendTextContent(acc: BoundedText, content: unknown): void {
+function appendTextContent(acc: TextSink, content: unknown): void {
 	if (typeof content === "string") {
 		acc.append(content);
 		return;
@@ -325,6 +397,8 @@ function addUsage(target: CollectorUsage, usage: TurnUsage): void {
  */
 export class ChildCollector {
 	readonly limits: CollectorLimits;
+	/** Whether oversized completed answers keep their head or tail. */
+	readonly resultKeep: KeepMode;
 
 	/** Most recent completed non-empty assistant answer (bounded). */
 	finalText = "";
@@ -355,8 +429,9 @@ export class ChildCollector {
 	private bufferBytes = 0;
 	private dropping = false;
 
-	constructor(limits?: Partial<CollectorLimits>) {
+	constructor(limits?: Partial<CollectorLimits>, options?: { resultKeep?: KeepMode }) {
 		this.limits = normalizeLimits(limits);
+		this.resultKeep = options?.resultKeep === "tail" ? "tail" : "head";
 		this.partialBuffer = new BoundedText(this.limits.resultBytes, this.limits.resultLines, "");
 		this.stdoutDecoder = new StringDecoder("utf8");
 		this.stderrDecoder = new StringDecoder("utf8");
@@ -459,7 +534,9 @@ export class ChildCollector {
 		const m = message as Record<string, any>;
 		if (m.role !== "assistant") return;
 
-		const acc = new BoundedText(this.limits.resultBytes, this.limits.resultLines, "\n");
+		const acc = this.resultKeep === "tail"
+			? new TailText(this.limits.resultBytes, this.limits.resultLines, "\n")
+			: new BoundedText(this.limits.resultBytes, this.limits.resultLines, "\n");
 		appendTextContent(acc, m.content);
 		const text = acc.value();
 		if (text.trim().length > 0) {
@@ -577,6 +654,15 @@ export class ChildCollector {
 	}
 
 	private processLine(line: string): void {
+		// Cheap pre-filter before JSON.parse: skip lines whose event type we never read.
+		let interesting = false;
+		for (const needle of EVENT_TYPE_NEEDLES) {
+			if (line.includes(needle)) {
+				interesting = true;
+				break;
+			}
+		}
+		if (!interesting) return;
 		const trimmed = line.trim();
 		if (trimmed.length === 0) return;
 		let event: unknown;