@trim21/personal-pi-extensions 0.1.662 → 0.1.668

package/README.md

@@ -43,7 +43,8 @@
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
 - **脚本接口**：`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console.*` /
-  `store(key, value)` / `load(key)`；首行可选 `// @options: {"max_output_tokens": 10000}`。
+  `store.set` / `store.get` / `store.list`（会话内持久的键值表）；首行可选
+  `// @options: {"max_output_tokens": 10000}`。
   脚本没有超时：死循环由调用方中止（Esc）结束，等嵌套调用返回（含用户审批弹窗）多久都不算超时。
 - **store** 记在每次成功调用工具结果的 `details.store` 上（与 `src/lib/file-reads.ts` 的
   已读记账同一套做法），下一次调用从当前分支的 toolResult 重放；输出超过 `max_output_tokens`

package/package.json

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

package/src/aft/index.ts

@@ -8,6 +8,11 @@
  * openai_compatible / ollama 且有 base_url）时注册；aft 默认的本地 ONNX
  * fastembed 后端不使用。
  *
+ * 项目根是**会话工作目录**（`session_start` 的 `ctx.cwd`），不是 pi 进程的启动
+ * 目录：引擎按项目根建索引与调用图存储，用错会把用户家目录当项目根并自动关闭这
+ * 些能力。扩展自己只读用户级 aft.jsonc（路径与会话目录无关），项目级 aft.jsonc
+ * 由 bridge 按项目根自行读取。
+ *
  * bridge 状态（日志 + 常驻 aft 子进程）的生命周期跟 session 走：session_start
  * 时先解析 aft 二进制（含 GitHub release auto-download 兜底）——找不到就
  * notify warning 且不注册任何 aft 工具，避免模型看到只会抛 "not initialized"
@@ -19,7 +24,7 @@
  *   pi -e ./aft/index.ts
  */
 
-import { resolveCortexKitConfigPaths } from "@cortexkit/aft-bridge";
+import { resolveCortexKitUserConfigPath } from "@cortexkit/aft-bridge";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { ToolBus } from "../lib/tool-bus.js";
@@ -27,6 +32,7 @@ import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { createAftState, findBinary, resolveSessionId, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
 import {
+  type AftToolContext,
   registerCallgraphTool,
   registerOutlineTool,
   registerSearchTool,
@@ -35,14 +41,15 @@ import {
 
 /**
  * aft 工具集：入口用它。`registerForSession` 必须在会话启动时调用——二进制
- * 探测、semantic_search 的提示、bridge 状态的创建都在里面；找不到二进制就不
- * 注册任何工具（避免模型看到只会抛 "not initialized" 的死工具）。
+ * 探测、semantic_search 的提示、bridge 状态（项目根 = 本会话的 `ctx.cwd`）的
+ * 创建都在里面；找不到二进制就不注册任何工具（避免模型看到只会抛
+ * "not initialized" 的死工具）。
  */
 export function createAftTools(pi: ExtensionAPI): {
   registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void>;
 } {
-  const cwd = process.cwd();
-  const cfg = loadAftConfig(resolveCortexKitConfigPaths(cwd).userConfigPath);
+  // 扩展自己的门控只读用户级配置：项目级 aft.jsonc 由 bridge 按会话工作目录读。
+  const cfg = loadAftConfig(resolveCortexKitUserConfigPath());
   // bridge 状态跟 session 生命周期走，作用域就是本工厂闭包，不落到模块级。
   let state: Awaited<ReturnType<typeof createAftState>> | null = null;
 
@@ -55,7 +62,7 @@ export function createAftTools(pi: ExtensionAPI): {
     return state;
   };
 
-  const toolCtx = { cwd, getState };
+  const toolCtx: AftToolContext = { getState };
 
   async function registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void> {
     if (!cfg.enabled) {
@@ -91,7 +98,7 @@ export function createAftTools(pi: ExtensionAPI): {
       registerSearchTool(bus, toolCtx);
     }
 
-    state = await createAftState(cwd, resolveSessionId(ctx), binaryPath, cfg.semanticRemote);
+    state = await createAftState(ctx.cwd, resolveSessionId(ctx), binaryPath, cfg.semanticRemote);
   }
 
   // 释放当前 session 的 bridge 状态。session_shutdown 是 pi 的正常生命周期；

package/src/aft/tools.ts

@@ -57,13 +57,13 @@ const AFT_GUIDELINES = readFileSync(
 ).trim();
 
 export interface AftToolContext {
-  cwd: string;
   /** 当前 session 的 bridge 状态；session 未初始化时抛错。 */
   getState(): AftState;
 }
 
 function bridgeFor(ctx: AftToolContext): AftProjectTransport {
-  return ctx.getState().pool.pool.getBridge(ctx.cwd);
+  const { pool } = ctx.getState();
+  return pool.pool.getBridge(pool.projectRoot);
 }
 
 /**
@@ -152,7 +152,7 @@ export function registerOutlineTool(bus: ToolBus, ctx: AftToolContext): void {
         filesMode = stats?.isDirectory() ?? false;
       }
       const rawArgs = compactArgs({
-        target: filesMode ? target : resolved,
+        target: resolved,
         files: filesMode || undefined,
         includeTests: params.includeTests,
       });

package/src/codemode/declarations.ts

@@ -97,7 +97,6 @@ export function renderDeclarations(tools: readonly ToolLike[]): string {
     "declare function text(value: unknown): void;",
     "declare function image(value: unknown): void;",
     "declare function exit(): void;",
-    "declare function store(key: string, value: unknown): void;",
-    "declare function load(key: string): unknown;",
+    "declare const store: { set(key: string, value: unknown): void; get(key: string): unknown; list(): string[] };",
   ].join("\n");
 }

package/src/codemode/prelude.ts

@@ -1,7 +1,7 @@
 /**
  * codemode 脚本侧的 prelude：在 QuickJS VM 里先于脚本求值，构建脚本能看到的全部
- * 能力（`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console` / `store` /
- * `load`），并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
+ * 能力（`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console` / `store`），
+ * 并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
  *
  * 值与参数过桥时都是 JSON 文本，本侧负责 parse/stringify；异步调用用一个 pending
  * 表把 id 映射到 promise，由宿主在结果到达时 settle。
@@ -13,7 +13,7 @@
  * - `"done"`（ok, valueJsonOrErrorJson, writesJson）
  */
 
-/** `store()` 单个值的 JSON 上限（字符数）。 */
+/** `store.set()` 单个值的 JSON 上限（字符数）。 */
 export const MAX_STORE_VALUE_CHARS = 256 * 1024;
 /** 全部 store 值的 JSON 上限（字符数）。 */
 export const MAX_STORE_TOTAL_CHARS = 1024 * 1024;
@@ -118,41 +118,47 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 		if (typeof key !== "string") throw new TypeErrorCtor(name + "() key must be a string");
 	}
 
-	function store(key, value) {
-		checkKey("store", key);
-		const previous = stored.has(key) ? key.length + stored.get(key).length : 0;
-		if (value === undefined) {
-			stored.delete(key);
-			storedChars -= previous;
-			writes.set(key, undefined);
-			return;
-		}
-		let json;
-		try {
-			json = stringify(value);
-		} catch (error) {
-			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable: " + format(error));
-		}
-		if (json === undefined) {
-			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable");
-		}
-		if (json.length > ${MAX_STORE_VALUE_CHARS}) {
-			throw new RangeError("store(" + stringify(key) + ") value exceeds ${MAX_STORE_VALUE_CHARS} characters of JSON");
-		}
-		const next = storedChars - previous + key.length + json.length;
-		if (next > ${MAX_STORE_TOTAL_CHARS}) {
-			throw new RangeError("store is full: stored values would exceed ${MAX_STORE_TOTAL_CHARS} characters of JSON");
-		}
-		stored.set(key, json);
-		storedChars = next;
-		writes.set(key, json);
-	}
-
-	function load(key) {
-		checkKey("load", key);
-		const json = stored.get(key);
-		return json === undefined ? undefined : parse(json);
-	}
+	// 脚本侧是一个键值表：store.set / store.get / store.list，数据本身留在闭包里
+	const store = Object.freeze({
+		set(key, value) {
+			checkKey("store.set", key);
+			const previous = stored.has(key) ? key.length + stored.get(key).length : 0;
+			if (value === undefined) {
+				stored.delete(key);
+				storedChars -= previous;
+				writes.set(key, undefined);
+				return;
+			}
+			let json;
+			try {
+				json = stringify(value);
+			} catch (error) {
+				throw new TypeErrorCtor("store.set(" + stringify(key) + ") value is not JSON-serializable: " + format(error));
+			}
+			if (json === undefined) {
+				throw new TypeErrorCtor("store.set(" + stringify(key) + ") value is not JSON-serializable");
+			}
+			if (json.length > ${MAX_STORE_VALUE_CHARS}) {
+				throw new RangeError("store.set(" + stringify(key) + ") value exceeds ${MAX_STORE_VALUE_CHARS} characters of JSON");
+			}
+			const next = storedChars - previous + key.length + json.length;
+			if (next > ${MAX_STORE_TOTAL_CHARS}) {
+				throw new RangeError("store is full: stored values would exceed ${MAX_STORE_TOTAL_CHARS} characters of JSON");
+			}
+			stored.set(key, json);
+			storedChars = next;
+			writes.set(key, json);
+		},
+		get(key) {
+			checkKey("store.get", key);
+			const json = stored.get(key);
+			return json === undefined ? undefined : parse(json);
+		},
+		// 升序返回当前键：上下文压缩后模型可以靠它找回自己写过的名字
+		list() {
+			return Array.from(stored.keys()).sort();
+		},
+	});
 
 	function serializeWrites() {
 		const entries = [];
@@ -161,7 +167,6 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 	}
 
 	Object.defineProperty(globalThis, "store", { value: store, enumerable: true });
-	Object.defineProperty(globalThis, "load", { value: load, enumerable: true });
 
 	// 原始值转字符串，其余 JSON 化
 	function outputText(value) {

package/src/codemode/tool.ts

@@ -3,8 +3,9 @@
  * 的能力是调用 `tools.*`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
  * 内部的审批（工作区外写入、Bash 沙箱提权等）照常生效；codemode 不再加自己的确认层。
  *
- * 可调用集合：总线上实际注册的工具减去 codemode 自身，执行时再与 active 列表求交——
- * pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
+ * 可调用集合：总线上实际注册的工具减去 codemode 自身与 spawn-agent，执行时再与 active
+ * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
+ * spawn-agent 被排除是因为它启动一个新的隔离会话、成本与运行时长都不适合放进脚本编排。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
  */
@@ -26,6 +27,9 @@ import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } f
 
 export const CODEMODE_TOOL_NAME = "codemode";
 
+/** 不暴露给脚本的工具：codemode 自身（防递归）与 spawn-agent（见文件头注释）。 */
+const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([CODEMODE_TOOL_NAME, "spawn-agent"]);
+
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
@@ -56,7 +60,7 @@ function allowedToolNames(pi: ExtensionAPI): Set<string> | undefined {
 function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableTool[] {
   return bus
     .list()
-    .filter((definition) => definition.name !== CODEMODE_TOOL_NAME)
+    .filter((definition) => !EXCLUDED_TOOL_NAMES.has(definition.name))
     .filter((definition) => allowed === undefined || allowed.has(definition.name))
     .map((definition) => ({
       name: definition.name,
@@ -73,7 +77,8 @@ function buildDescription(tools: readonly CallableTool[]): string {
     "  and a failing tool rejects with an `Error` you can catch.",
     "- Only what the script passes to `text(value)` / `console.log(...)` and its `return` value enter",
     "  this conversation; nested calls and their results stay out of it.",
-    "- `store(key, value)` and `load(key)` keep values across codemode calls in this session.",
+    "- `store.set(key, value)`, `store.get(key)` and `store.list()` are a small key/value store that",
+    "  persists across codemode calls in this session; `store.set(key, undefined)` removes a key.",
     "- The sandbox has no file system, network, timers or Node APIs: calling tools is its only",
     "  capability. Tool calls still go through each tool's own approvals, so a call that needs the",
     "  user's consent will ask for it.",

package/src/codemode/worker.js

@@ -103,41 +103,47 @@ var PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson) {
 		if (typeof key !== "string") throw new TypeErrorCtor(name + "() key must be a string");
 	}
 
-	function store(key, value) {
-		checkKey("store", key);
-		const previous = stored.has(key) ? key.length + stored.get(key).length : 0;
-		if (value === undefined) {
-			stored.delete(key);
-			storedChars -= previous;
-			writes.set(key, undefined);
-			return;
-		}
-		let json;
-		try {
-			json = stringify(value);
-		} catch (error) {
-			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable: " + format(error));
-		}
-		if (json === undefined) {
-			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable");
-		}
-		if (json.length > ${MAX_STORE_VALUE_CHARS}) {
-			throw new RangeError("store(" + stringify(key) + ") value exceeds ${MAX_STORE_VALUE_CHARS} characters of JSON");
-		}
-		const next = storedChars - previous + key.length + json.length;
-		if (next > ${MAX_STORE_TOTAL_CHARS}) {
-			throw new RangeError("store is full: stored values would exceed ${MAX_STORE_TOTAL_CHARS} characters of JSON");
-		}
-		stored.set(key, json);
-		storedChars = next;
-		writes.set(key, json);
-	}
-
-	function load(key) {
-		checkKey("load", key);
-		const json = stored.get(key);
-		return json === undefined ? undefined : parse(json);
-	}
+	// 脚本侧是一个键值表：store.set / store.get / store.list，数据本身留在闭包里
+	const store = Object.freeze({
+		set(key, value) {
+			checkKey("store.set", key);
+			const previous = stored.has(key) ? key.length + stored.get(key).length : 0;
+			if (value === undefined) {
+				stored.delete(key);
+				storedChars -= previous;
+				writes.set(key, undefined);
+				return;
+			}
+			let json;
+			try {
+				json = stringify(value);
+			} catch (error) {
+				throw new TypeErrorCtor("store.set(" + stringify(key) + ") value is not JSON-serializable: " + format(error));
+			}
+			if (json === undefined) {
+				throw new TypeErrorCtor("store.set(" + stringify(key) + ") value is not JSON-serializable");
+			}
+			if (json.length > ${MAX_STORE_VALUE_CHARS}) {
+				throw new RangeError("store.set(" + stringify(key) + ") value exceeds ${MAX_STORE_VALUE_CHARS} characters of JSON");
+			}
+			const next = storedChars - previous + key.length + json.length;
+			if (next > ${MAX_STORE_TOTAL_CHARS}) {
+				throw new RangeError("store is full: stored values would exceed ${MAX_STORE_TOTAL_CHARS} characters of JSON");
+			}
+			stored.set(key, json);
+			storedChars = next;
+			writes.set(key, json);
+		},
+		get(key) {
+			checkKey("store.get", key);
+			const json = stored.get(key);
+			return json === undefined ? undefined : parse(json);
+		},
+		// 升序返回当前键：上下文压缩后模型可以靠它找回自己写过的名字
+		list() {
+			return Array.from(stored.keys()).sort();
+		},
+	});
 
 	function serializeWrites() {
 		const entries = [];
@@ -146,7 +152,6 @@ var PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson) {
 	}
 
 	Object.defineProperty(globalThis, "store", { value: store, enumerable: true });
-	Object.defineProperty(globalThis, "load", { value: load, enumerable: true });
 
 	// 原始值转字符串，其余 JSON 化
 	function outputText(value) {

package/src/spawn-agent.ts

@@ -131,7 +131,10 @@ const spawnAgentSchema = Type.Object({
     description:
       "Name of the subagent type to invoke. Choose one of the available subagent types listed in your system prompt.",
   }),
-  task: Type.String({ description: "Task to delegate to the subagent" }),
+  task: Type.String({
+    description:
+      "Self-contained task for the subagent, which sees none of this conversation: state the repository path, the exact question, and what the answer must contain (file paths with line numbers).",
+  }),
 });
 
 // ── result types ─────────────────────────────────────────────────────────────
@@ -499,9 +502,19 @@ export async function runAgent(
 export function formatAgentListSection(agents: AgentConfig[]): string {
   const lines = agents.map((a) => `- \`${a.name}\`: ${a.description}`);
   return [
+    "### Delegating to subagents",
+    "",
+    "Delegate a focused, read-only research task when the answer is a summary rather than source you must quote or edit:",
+    "",
+    "- locating code whose position is unknown, or answering a question that spans several files;",
+    "- several independent lookups at once — issue one `spawn-agent` call per lookup in the same message and they run concurrently;",
+    "- keeping the searching and reading out of your own context window.",
+    "",
+    "Do not delegate work you are about to do yourself — a single file you will edit, a change whose evidence must be the exact source text, or anything that writes. A subagent sees none of this conversation, so its task must be self-contained. Treat its answer as a pointer and read the location it names before acting on it.",
+    "",
     "### Available subagents",
     "",
-    "You can delegate tasks to the following subagent types by calling the `spawn-agent` tool with their name in the `agent` parameter:",
+    "Pass one of these names as the `agent` parameter:",
     "",
     ...lines,
   ].join("\n");
@@ -526,9 +539,11 @@ export function createSpawnAgentTool(): { register(bus: ToolBus): void } {
       bus.register<typeof spawnAgentSchema, SubagentDetails>({
         name: "spawn-agent",
         label: "spawn-agent",
+        promptSnippet: "Delegate focused research to a subagent with its own context window",
         description: [
-          "Delegate a task to a subagent that runs in an isolated session with its own context window, inside this pi process rather than a separate one.",
-          "The call blocks until the subagent finishes its turn; its final output comes back as the tool result.",
+          "Delegate a self-contained research task to a subagent that runs in an isolated session with its own context window, inside this pi process rather than a separate one.",
+          "The call blocks until the subagent finishes its turn and returns only its final answer: its intermediate tool calls are not visible to you.",
+          "Several `spawn-agent` calls issued in the same message run concurrently.",
           "The `agent` parameter must be one of the available subagent types listed in the system prompt.",
           `Subagents run read-only (${DEFAULT_TOOLS.join(", ")}) unless the agent declares an explicit toolset.`,
         ].join(" "),