pi-pier 0.1.0

package/src/role-manifest.ts

@@ -0,0 +1,166 @@
+/**
+ * 档2 Week1：role manifest 类型 + 校验器（D76 v2；2026-08-18）。
+ *
+ * 契约镜像 `schemas/role-manifest.schema.json`（JSON Schema 文件是合同文档，
+ * 运行时用零依赖手写校验——不引 ajv，worker 侧不背包袱）。
+ *
+ * 严格契约：未知顶层键报 issue（防 "rulez" 类 typo 静默失效）；
+ * 错误收集式（一次报全，便于修档案）。
+ */
+export type PermissionAction = 'allow' | 'ask' | 'deny';
+export type TodosMode = 'serial' | 'parallel';
+/** D82：未知工具姿态——可见性=信任关系（用户→master 凭 install；master→被委派凭镜像）。 */
+export type UnknownToolStance = 'allow' | 'deny';
+
+export interface RoleManifest {
+  role: string;
+  /** 语义版本 x.y.z（档案演化追溯；P2）。 */
+  version: string;
+  /**
+   * WS-D10：按角色路由模型——`provider/model` 形态（advisor = 高级别第三方判断）。
+   * 可省略 = 跟随进程默认（master/worker 不设）。spawn 时注入 `--provider/--model`。
+   */
+  model?: string;
+  description?: string;
+  manifest: {
+    /** 基线工具（非空，必含 todo_write + ask_user_question——协调工具）。 */
+    tools: string[];
+    /** 三态权限；`*` 通配符默认；可省略 = `{"*":"allow"}`。 */
+    rules?: Record<string, PermissionAction>;
+    /**
+     * D82 unknownTools：清单外工具的姿态（缺省 deny = 安全默认）。
+     * master/worker = allow（用户安装的扩展默认可见可用——install 即授予）；
+     * 自定义角色缺省 deny。与 rules 的 `*` 通配分属两轴：可见性 vs 强制力。
+     * 排除族（如 worker 的 subagent/terminal）须显式 deny 才能在 allow 姿态下持禁令。
+     */
+    unknownTools?: UnknownToolStance;
+  };
+  services?: {
+    todos?: {
+      mode?: TodosMode;
+      reminderLimit?: number;
+    };
+  };
+}
+
+export type ValidateResult =
+  | { ok: true; value: RoleManifest }
+  | { ok: false; code: 'INVALID_ROLE_CONFIG'; issues: string[] };
+
+/** 所有角色必需的协调工具（C7 边界约束 1）。 */
+export const COORDINATION_TOOLS = ['todo_write', 'ask_user_question'] as const;
+
+const ROLE_NAME_RE = /^[a-z0-9-]+$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const TOOL_KEY_RE = /^[a-z0-9_*-]+$/;
+const ACTIONS: readonly PermissionAction[] = ['allow', 'ask', 'deny'];
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isPosInt(v: unknown): boolean {
+  return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
+
+export function validateRoleManifest(input: unknown): ValidateResult {
+  const issues: string[] = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, code: 'INVALID_ROLE_CONFIG', issues: ['role 档案必须是 JSON 对象'] };
+  }
+
+  /* ── 顶层键 ── */
+  const KNOWN_TOP = new Set(['role', 'version', 'model', 'description', 'manifest', 'services']);
+  for (const k of Object.keys(input)) {
+    if (!KNOWN_TOP.has(k)) issues.push(`未知顶层键 "${k}"（契约外字段，检查拼写）`);
+  }
+
+  /* ── role 名 ── */
+  if (typeof input.role !== 'string' || !ROLE_NAME_RE.test(input.role)) {
+    issues.push(`role 必须是 [a-z0-9-]+ 字符串，收到 ${JSON.stringify(input.role)}`);
+  }
+
+  /* ── version（P2 semver） ── */
+  if (typeof input.version !== 'string' || !SEMVER_RE.test(input.version)) {
+    issues.push(`version 必须是 x.y.z 三段数字（如 1.0.0），收到 ${JSON.stringify(input.version)}`);
+  }
+
+  /* ── model（WS-D10：provider/model 按角色路由；可选） ── */
+  if (input.model !== undefined) {
+    if (typeof input.model !== 'string' || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input.model)) {
+      issues.push(`model 必须是 provider/model 形态（如 opencode-go/muse-spark-1.2-contributor），收到 ${JSON.stringify(input.model)}`);
+    }
+  }
+
+  /* ── description 可选 ── */
+  if (input.description !== undefined && typeof input.description !== 'string') {
+    issues.push('description 必须是字符串');
+  }
+
+  /* ── manifest ── */
+  const m = input.manifest;
+  if (!isPlainObject(m)) {
+    issues.push('manifest 必须是对象');
+  } else {
+    const KNOWN_MANIFEST = new Set(['tools', 'rules', 'unknownTools']);
+    for (const k of Object.keys(m)) {
+      if (!KNOWN_MANIFEST.has(k)) issues.push(`manifest 内未知键 "${k}"`);
+    }
+
+    // D82 unknownTools：enum 校验，缺省 = deny（安全默认）
+    if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
+      issues.push(`manifest.unknownTools 必须是 allow/deny，收到 ${JSON.stringify(m.unknownTools)}`);
+    }
+
+    // tools：字符串数组、无重复、非空、含协调工具（空数组也要报缺协调工具）
+    const tools = m.tools;
+    if (!Array.isArray(tools) || !tools.every((t) => typeof t === 'string' && TOOL_KEY_RE.test(t))) {
+      issues.push('manifest.tools 必须是非空字符串数组（工具名 [a-z0-9_-]）');
+    } else {
+      const seen = new Set<string>();
+      for (const t of tools) {
+        if (seen.has(t)) issues.push(`manifest.tools 重复项 "${t}"`);
+        seen.add(t);
+      }
+      for (const need of COORDINATION_TOOLS) {
+        if (!seen.has(need)) issues.push(`基线非空约束：manifest.tools 必须包含 "${need}"（协调工具）`);
+      }
+    }
+
+    // rules：三态值；键 = 工具名或 *
+    if (m.rules !== undefined) {
+      if (!isPlainObject(m.rules)) {
+        issues.push('manifest.rules 必须是对象');
+      } else {
+        for (const [k, v] of Object.entries(m.rules)) {
+          if (!TOOL_KEY_RE.test(k)) issues.push(`rules 键 "${k}" 不是合法工具名（[a-z0-9_-] 或 *）`);
+          if (!ACTIONS.includes(v as PermissionAction)) {
+            issues.push(`rules["${k}"] 必须是 ${ACTIONS.join('/')} 之一，收到 ${JSON.stringify(v)}`);
+          }
+        }
+      }
+    }
+  }
+
+  /* ── services ── */
+  if (input.services !== undefined) {
+    if (!isPlainObject(input.services)) {
+      issues.push('services 必须是对象');
+    } else if (input.services.todos !== undefined) {
+      const t = input.services.todos;
+      if (!isPlainObject(t)) {
+        issues.push('services.todos 必须是对象');
+      } else {
+        if (t.mode !== undefined && t.mode !== 'serial' && t.mode !== 'parallel') {
+          issues.push(`services.todos.mode 必须是 serial/parallel，收到 ${JSON.stringify(t.mode)}`);
+        }
+        if (t.reminderLimit !== undefined && !isPosInt(t.reminderLimit)) {
+          issues.push(`services.todos.reminderLimit 必须是正整数，收到 ${JSON.stringify(t.reminderLimit)}`);
+        }
+      }
+    }
+  }
+
+  if (issues.length > 0) return { ok: false, code: 'INVALID_ROLE_CONFIG', issues };
+  return { ok: true, value: input as unknown as RoleManifest };
+}

package/src/roles/master.json

@@ -0,0 +1,21 @@
+{
+  "role": "master",
+  "version": "1.3.0",
+  "description": "主控角色（WS-D7 自应用；D83 镜像源）：自研核心全量（todos/协调/subagent 族/终端族）+ pi 内建检视执行 + web_search；D82 unknownTools=allow——用户安装的任意扩展默认可见可用（install 即授予）",
+  "manifest": {
+    "unknownTools": "allow",
+    "tools": [
+      "todo_write", "ask_user_question",
+      "subagent", "resume_subagent", "list_agents", "send_message", "interrupt_agent",
+      "terminal_open", "terminal_send", "terminal_read", "terminal_signal", "terminal_close", "terminal_list",
+      "read", "grep", "glob", "bash", "pwsh", "edit", "write",
+      "web_search"
+    ],
+    "rules": {
+      "*": "allow"
+    }
+  },
+  "services": {
+    "todos": { "mode": "parallel", "reminderLimit": 5 }
+  }
+}

package/src/roles/worker-default.json

@@ -0,0 +1,30 @@
+{
+  "role": "worker-default",
+  "version": "1.3.0",
+  "description": "默认worker角色（D83 继承制）：镜像 master.tools 减 subagent 族（禁嵌套）减 terminal 族（M14 资源归属）；排除族显式 deny——在 D82 unknownTools=allow 姿态下仍持禁令；todos serial/3",
+  "manifest": {
+    "unknownTools": "allow",
+    "tools": [
+      "todo_write", "ask_user_question",
+      "read", "grep", "glob", "bash", "pwsh", "edit", "write",
+      "web_search"
+    ],
+    "rules": {
+      "subagent": "deny",
+      "resume_subagent": "deny",
+      "list_agents": "deny",
+      "send_message": "deny",
+      "interrupt_agent": "deny",
+      "terminal_open": "deny",
+      "terminal_send": "deny",
+      "terminal_read": "deny",
+      "terminal_signal": "deny",
+      "terminal_close": "deny",
+      "terminal_list": "deny",
+      "*": "allow"
+    }
+  },
+  "services": {
+    "todos": { "mode": "serial", "reminderLimit": 3 }
+  }
+}

package/src/session-tail.ts

@@ -0,0 +1,169 @@
+/**
+ * pi 会话 JSONL 尾部解析（纯函数库，v1.1 结果通道）。
+ *
+ * v1.1（DESIGN.md §12）起，子代理的结果不再从 pane 文本解析，而是读子代理的
+ * 会话文件（pi 会话 JSONL，权威、机器精确、无回声污染/滚动盲区）。
+ * 本模块只依赖 pi 会话格式（session-format 文档实测形状）：
+ *   行 = {type, id, parentId, message:{role, content:[{type:'text',text}...], timestamp, stopReason}}
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface SessionMessageLike {
+  role?: string;
+  content?: Array<{ type?: string; text?: string } | unknown> | unknown;
+  timestamp?: number;
+  stopReason?: string;
+}
+
+export interface SessionEntryLike {
+  type?: string;
+  message?: SessionMessageLike | unknown;
+  [k: string]: unknown;
+}
+
+/** 容忍式逐行解析（损坏行/非 JSON 行跳过）。 */
+export function parseSessionEntries(text: string): SessionEntryLike[] {
+  const entries: SessionEntryLike[] = [];
+  for (const line of (text ?? '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const obj = JSON.parse(t);
+      if (obj && typeof obj === 'object') entries.push(obj as SessionEntryLike);
+    } catch {
+      /* 截断/损坏行跳过 */
+    }
+  }
+  return entries;
+}
+
+function messageOf(entry: SessionEntryLike): SessionMessageLike | null {
+  if (entry.type !== 'message') return null;
+  const m = entry.message;
+  if (typeof m !== 'object' || m === null) return null;
+  return m as SessionMessageLike;
+}
+
+function textOf(m: SessionMessageLike): string {
+  const content = m.content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((c) => {
+      if (typeof c === 'object' && c !== null && (c as { type?: string }).type === 'text') {
+        return (c as { text?: string }).text ?? '';
+      }
+      return '';
+    })
+    .join('\n')
+    .trim();
+}
+
+/**
+ * 取最后一次"已定稿"的 assistant 文本（stopReason === 'stop'，排除 toolUse 中间态）。
+ * sinceTs 用于过滤注入时间点之前的旧消息。
+ */
+export function lastAssistantText(
+  entries: readonly SessionEntryLike[],
+  opts: { sinceTs?: number } = {},
+): { text: string; timestamp: number } | null {
+  let best: { text: string; timestamp: number } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    if (m.stopReason !== 'stop') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (opts.sinceTs !== undefined && ts < opts.sinceTs) continue;
+    if (!best || ts >= best.timestamp) best = { text: textOf(m), timestamp: ts };
+  }
+  return best;
+}
+
+/** 会话是否出现注入时间点之后的 assistant 消息（任意 stopReason，探测活跃）。 */
+export function hasAssistantAfter(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): boolean {
+  return entries.some((e) => {
+    const m = messageOf(e);
+    return !!m && m.role === 'assistant' && (typeof m.timestamp === 'number' ? m.timestamp : 0) >= sinceTs;
+  });
+}
+
+/**
+ * 注入后是否存在"已发起但尚无结果"的 toolCall（工具执行中，如 ask_user_question
+ * 等人类输入）→ 未真正结算（v1.3 M8 结算竞态修复）。并行调用按深度计数。
+ */
+export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs: number): boolean {
+  let depth = 0;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m) continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (m.role === 'assistant') {
+      const content = m.content;
+      if (Array.isArray(content)) {
+        depth += content.filter((c) => typeof c === 'object' && c !== null && (c as { type?: string }).type === 'toolCall').length;
+      }
+    }
+    if (m.role === 'toolResult') depth -= 1;
+  }
+  return depth > 0;
+}
+
+/** pi 会话目录名：cwd → `--F--herdr-pi--` 形态（实测命名约定）。 */
+export function sessionDirName(cwd: string): string {
+  const flat = cwd.replace(/[\\/]/g, '-').replace(/:/g, '-');
+  return `--${flat}--`;
+}
+
+/** cwd 会话目录下按 mtime 倒序取最新 limit 个会话文件（v1.3 M7 候选定位）。 */
+export function listSessionFiles(cwd: string, agentDir: string, limit = 4): string[] {
+  const dir = path.join(agentDir, sessionDirName(cwd));
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const files: Array<{ file: string; mtime: number }> = [];
+  for (const name of names) {
+    if (!name.endsWith('.jsonl')) continue;
+    const full = path.join(dir, name);
+    try {
+      files.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+    } catch {
+      /* 跳过消失文件 */
+    }
+  }
+  files.sort((a, b) => b.mtime - a.mtime);
+  return files.slice(0, limit).map((f) => f.file);
+}
+
+/**
+ * 按 session id 定位会话文件（文件名形如 `<ts>_<id>.jsonl`，pi 实测命名）。
+ * 官方 herdr 集成上报 agent_session 为 kind 'id' 时用它还原路径。
+ */
+export function sessionFileById(cwd: string, agentDir: string, id: string): string | null {
+  const dir = path.join(agentDir, sessionDirName(cwd));
+  const suffix = `_${id}.jsonl`;
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    if (name.endsWith(suffix)) return path.join(dir, name);
+  }
+  return null;
+}
+
+export function readSessionFile(file: string): SessionEntryLike[] | null {
+  try {
+    return parseSessionEntries(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}