@trim21/personal-pi-extensions 0.0.193 → 0.0.195

package/README.md

@@ -13,6 +13,7 @@
 | [vision-agent](#vision-agent)                 | 视觉代理：主模型不支持视觉时，spawn 子 agent 识别图片  |
 | [todowrite](#todowrite)                       | opencode 风格的任务列表工具，完整列表替换语义          |
 | [question](#question)                         | opencode 风格的提问工具，阻塞式询问用户选择            |
+| [talk](#talk)                                 | session 间消息传递，SQLite 邮箱 + 双向 ask 时间戳仲裁  |
 
 ---
 
@@ -213,6 +214,70 @@ pi -e ./src/question.ts
 
 ---
 
+## talk
+
+session 间消息传递：不同 pi session（同一台机器）通过一个共享的 SQLite 邮箱互相发送消息、提问并等待回复。
+
+### 架构（三层）
+
+```
+storage.ts   —— 存储层：TalkStorage 接口 + SqliteTalkStorage 实现（node:sqlite，零 npm 依赖）
+core.ts      —— talk 核心：registry/mailbox/policy/format + TalkCore 协调器，只依赖存储层，通过回调 yield 投递/通知
+index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周期事件 / 工具注册
+```
+
+存储层抽象成接口是为了后续可换成 HTTP / remote 后端，talk 核心无需改动。
+
+### 工具（LLM 可见）
+
+| 工具                 | 作用                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| `talk-list-sessions` | 列出其他 session（presence：idle/working/not responding/offline） |
+| `talk-read-messages` | 主动读收件箱（读即消费）                                          |
+| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 120s 超时）               |
+| `talk-wait`          | 阻塞等待新消息到达                                                |
+| `talk-send`          | 发送纯文本消息（`to: "*"` 广播所有，`to: "cwd"` 广播同 cwd）      |
+| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）             |
+
+对端消息在模型工作过程中以 steer 方式注入上下文；模型也可主动 `talk-read-messages` 拉取。
+
+### 关键设计
+
+- **投递成功才消费**：信件只在成功交给 `sendMessage` 后才从 inbox 删除，投递失败留在 inbox 下次重试——不会因 `sendMessage` 吞异常而静默丢信。
+- **双向 ask 仲裁**：`talk-ask` 发起前先检查收件箱（有对方消息就先读/先回）；阻塞等待期间若收到对方的 ask（而非 reply），按两个 ask 的 `ts` 字段仲裁——先 ask 者主导继续等，后 ask 者让位并先回复对方。`ts` 是信件内固定字段，双方读到同一对值，结论天然对称；同毫秒碰撞用 `session dir + session id` 字符串比较兜底。
+- **typebox runtime 验证**：所有从存储读出的值经 TypeBox schema 校验，损坏/伪造数据被拒绝，不做 `as T` 强转。
+- **安全**：纯文本 ≤32KB；10s 去重 / 30s 限速 8 条 / 50 积压上限（防环）；每条投递带「来自其他 session、无权威」声明。
+
+### 配置
+
+sqlite 文件路径按优先级取第一个可用值：
+
+1. 环境变量 `PI_TALK_DB`
+2. global `~/.pi/agent/settings.json` 里的 `talk.db_path`
+3. 默认 `~/.pi/agent/talk.db`
+
+`db_path` 支持 `~` 展开（`~/…` → 用户主目录），相对路径相对 `~/.pi/agent` 解析；绝对路径原样使用。
+
+```jsonc
+// ~/.pi/agent/settings.json
+{
+  "talk": { "db_path": "~/data/talk.db" },
+}
+```
+
+| 变量              | 默认                              | 含义                          |
+| ----------------- | --------------------------------- | ----------------------------- |
+| `PI_TALK_DB`      | settings 或 `~/.pi/agent/talk.db` | SQLite 邮箱数据库路径         |
+| `PI_TALK_INBOUND` | `accept`                          | `refuse` 时丢弃所有 peer 消息 |
+
+### 使用
+
+```bash
+pi -e ./src/talk/index.ts
+```
+
+---
+
 ## 安装
 
 ### 通过 npm/git 包

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.193",
+  "version": "0.0.195",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -65,7 +65,8 @@
       "src/gh-readonly.ts",
       "src/spawn-agent.ts",
       "src/opencode-todo.ts",
-      "src/question.ts"
+      "src/question.ts",
+      "src/talk/index.ts"
     ]
   },
   "lint-staged": {

package/src/bwrap/index.ts

@@ -67,6 +67,8 @@ import { type BashOperations, createBashTool, getAgentDir } from "@earendil-work
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { expandHome } from "../lib/path.js";
+
 const SANDBOX_PROMPT = `
 ## Command Execution
 You are running inside a sandbox.
@@ -232,17 +234,8 @@ function deepMerge(base: BwrapConfig, overrides: Partial<BwrapConfig>): BwrapCon
   };
 }
 
-function expandPath(p: string): string {
-  if (p.startsWith("~/")) {
-    const home = process.env.HOME;
-    if (home === undefined) return p;
-    return join(home, p.slice(2));
-  }
-  return p;
-}
-
 function resolvePath(p: string, cwd: string): string {
-  const expanded = expandPath(p);
+  const expanded = expandHome(p);
   if (expanded === ".") return cwd;
   return expanded;
 }

package/src/lib/path.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared path helpers used by multiple extensions.
+ */
+
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+/**
+ * Expand a leading `~` to the user's home directory.
+ * - `~` → home
+ * - `~/rest` → `home/rest`
+ * - anything else (including `~user`) is left untouched.
+ */
+export function expandHome(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Resolve a path that may start with `~` (expanded to home) and may be
+ * relative (resolved against `baseDir`). Absolute paths are returned
+ * normalized.
+ */
+export function resolveHomePath(p: string, baseDir: string): string {
+  const expanded = expandHome(p);
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(baseDir, expanded);
+}