@buyi1net/pi-toolkit 0.0.1

package/modules/subagents/src/launch-config.ts

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { AgentDefaults, AgentSessionMode } from "./agents.ts";
+import type { SubagentParams } from "./params.ts";
+
+export const SPAWNING_TOOLS = [
+  "subagent",
+  "subagent_message",
+  "subagents_list",
+  "subagent_inspect",
+] as const;
+
+/** 成员间直信工具:仅 member spawn 注入白名单(注册在 subagent-done.ts)。 */
+export const TEAM_TOOLS = ["team_send"] as const;
+
+export type SubagentSessionMode = AgentSessionMode;
+
+export function resolveSubagentPaths(
+  params: SubagentParams,
+  agentDefs: AgentDefaults | null,
+  getAgentConfigDir: () => string,
+): { effectiveCwd: string | null; localAgentDir: string | null; effectiveAgentDir: string } {
+  const rawCwd = params.cwd ?? agentDefs?.cwd ?? null;
+  const cwdIsFromAgent = !params.cwd && agentDefs?.cwd != null;
+  const cwdBase = cwdIsFromAgent ? getAgentConfigDir() : process.cwd();
+  const effectiveCwd = rawCwd
+    ? isAbsolute(rawCwd)
+      ? rawCwd
+      : join(cwdBase, rawCwd)
+    : null;
+  const localAgentDir = effectiveCwd ? join(effectiveCwd, ".pi", "agent") : null;
+  const effectiveAgentDir =
+    localAgentDir && existsSync(localAgentDir) ? localAgentDir : getAgentConfigDir();
+  return { effectiveCwd, localAgentDir, effectiveAgentDir };
+}
+
+export function getDefaultSessionDirFor(cwd: string, agentDir: string): string {
+  const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+  const sessionDir = join(agentDir, "sessions", safePath);
+  if (!existsSync(sessionDir)) mkdirSync(sessionDir, { recursive: true });
+  return sessionDir;
+}
+
+export function resolveEffectiveSessionMode(
+  agentDefs: AgentDefaults | null,
+): SubagentSessionMode {
+  return agentDefs?.sessionMode ?? "standalone";
+}
+
+export function resolveLaunchBehavior(
+  params: SubagentParams,
+  agentDefs: AgentDefaults | null,
+): {
+  sessionMode: SubagentSessionMode;
+  seededSessionMode: "lineage-only" | "fork" | null;
+  inheritsConversationContext: boolean;
+  taskDelivery: "direct" | "artifact";
+} {
+  const sessionMode = resolveEffectiveSessionMode(agentDefs);
+  const inheritsConversationContext = sessionMode === "fork";
+  return {
+    sessionMode,
+    seededSessionMode: sessionMode === "standalone" ? null : sessionMode,
+    inheritsConversationContext,
+    taskDelivery: inheritsConversationContext ? "direct" : "artifact",
+  };
+}
+
+export function resolveEffectiveInteractive(
+  _params: SubagentParams,
+  agentDefs: AgentDefaults | null,
+): boolean {
+  if (agentDefs?.interactive != null) return agentDefs.interactive;
+  return !(agentDefs?.autoExit ?? false);
+}
+
+/**
+ * Resolve the lifecycle flag that is actually passed to the child process.
+ * `interactive` and `auto-exit` describe the same boundary from opposite
+ * directions, so an explicit value on either side must not leave the other
+ * side undefined. In particular, `interactive: false` without
+ * `auto-exit: true` must still terminate a headless child after its turn.
+ */
+export function resolveEffectiveAutoExit(agentDefs: AgentDefaults | null): boolean {
+  if (agentDefs?.interactive != null) return !agentDefs.interactive;
+  return agentDefs?.autoExit ?? false;
+}
+
+/** Reject contradictory frontmatter instead of silently creating a hanging or
+ * prematurely self-closing subagent. A valid pair is interactive=true,
+ * auto-exit=false, or interactive=false, auto-exit=true. */
+export function validateAgentLifecycleConfig(agentDefs: AgentDefaults | null): string | null {
+  if (
+    agentDefs?.interactive != null &&
+    agentDefs.autoExit != null &&
+    agentDefs.interactive === agentDefs.autoExit
+  ) {
+    return (
+      `Agent lifecycle settings conflict: interactive=${agentDefs.interactive} and ` +
+      `auto-exit=${agentDefs.autoExit}. Set interactive=false with auto-exit=true ` +
+      `for an autonomous agent, or interactive=true with auto-exit=false for a demo pane.`
+    );
+  }
+  return null;
+}
+
+export type SubagentSurfaceChoice = "headless" | "pane";
+
+/**
+ * 表面选择(纯函数):
+ *   - "pane":强制可见 pane(现有 herdr/tmux 路径,行为不变)。
+ *   - "background":强制 headless——独立后台 pi 进程,不创建 pane。
+ *     interactive(演示型)子代理必须拒绝:它们依赖用户在 pane 中操作,
+ *     静默降级成 headless 或反过来静默建 pane 都是错的,直接报错返回。
+ *   - "auto"(默认,兼容旧调用不传 surface):interactive → pane,自动任务 → headless。
+ *
+ * 返回 { choice } 或 { error }(error 为面向 tool result 的完整错误文本)。
+ */
+export function resolveSurfaceChoice(
+  surface: string | undefined,
+  effectiveInteractive: boolean,
+): { choice: SubagentSurfaceChoice } | { error: string } {
+  const requested = surface ?? "auto";
+  if (requested === "pane") return { choice: "pane" };
+  if (requested === "background") {
+    if (effectiveInteractive) {
+      const reason =
+        'interactive (demo) sub-agents run in a visible pane the user operates; ' +
+        'surface "background" (headless) was refused instead of silently creating a pane. ' +
+        "Spawn an autonomous agent, or omit `surface` to place this sub-agent in a pane.";
+      return { error: reason };
+    }
+    return { choice: "headless" };
+  }
+  if (requested === "auto") {
+    return { choice: effectiveInteractive ? "pane" : "headless" };
+  }
+  return {
+    error: `Invalid surface "${requested}". Use "auto", "background", or "pane".`,
+  };
+}
+
+export function buildSubagentToolAllowlist(
+  effectiveTools: string | undefined,
+  opts?: { grantSpawning?: boolean; grantTeamSend?: boolean },
+): string | null {
+  const requested = (effectiveTools ?? "")
+    .split(",")
+    .map((tool) => tool.trim())
+    .filter(Boolean);
+  const grantSpawning = opts?.grantSpawning ?? false;
+  const grantTeamSend = opts?.grantTeamSend ?? false;
+  const hasExplicitTools = effectiveTools !== undefined;
+  const spawningNames = new Set<string>(SPAWNING_TOOLS);
+  const teamNames = new Set<string>(TEAM_TOOLS);
+
+  // A profile cannot opt itself into delegation merely by putting a spawning
+  // tool in `tools`; the explicit subagent_agents grant is the authority.
+  // team_send 同理:profile 不能靠把工具名写进 tools 自授;member spawn 的
+  // 显式注入才是授权来源。
+  const allow = new Set(
+    requested.filter((tool) =>
+      (grantSpawning || !spawningNames.has(tool)) && (grantTeamSend || !teamNames.has(tool)),
+    ),
+  );
+  if (grantSpawning) {
+    for (const tool of SPAWNING_TOOLS) allow.add(tool);
+  }
+  if (grantTeamSend) {
+    for (const tool of TEAM_TOOLS) allow.add(tool);
+  }
+  if (requested.length > 0 || grantSpawning || grantTeamSend) allow.add("ask_question");
+
+  // null means "use Pi's normal defaults". An explicitly empty/forbidden
+  // list must remain an empty allowlist rather than widening back to defaults.
+  if (allow.size === 0 && !hasExplicitTools && !grantSpawning && !grantTeamSend) return null;
+  return [...allow].join(",");
+}
+
+export function buildPiPromptArgs(params: {
+  effectiveSkills?: string;
+  taskDelivery: "direct" | "artifact";
+  taskArg: string;
+}): string[] {
+  const skillPrompts = (params.effectiveSkills ?? "")
+    .split(",")
+    .map((skill) => skill.trim())
+    .filter(Boolean)
+    .map((skill) => `/skill:${skill}`);
+  const needsSeparator = params.taskDelivery === "artifact" && skillPrompts.length > 0;
+  return [
+    ...(needsSeparator ? [""] : []),
+    ...skillPrompts,
+    params.taskArg,
+  ];
+}

package/modules/subagents/src/layout-budget.ts

@@ -0,0 +1,26 @@
+/**
+ * 布局预算 —— 子代理 pane 的最小可用尺寸。
+ *
+ * 背景(2026-08-30 事故):同一 tab 内连环分屏会把每个 pane 挤到极窄,
+ * 63 列时宿主 TUI 状态栏渲染超宽直接崩溃 pi(uncaughtException)。即使
+ * 不崩,过窄的 pane 也无法正常使用。防线必须在编排层:低于预算的 pane
+ * 不能作为子代理载体;单 Tab 无法继续安全分屏时直接拒绝创建。
+ *
+ * 两表面(herdr/tmux)共用;调整阈值时两边行为自动一致。
+ */
+
+/** 子代理 pane 的最小列数。63 列已实证崩溃,70 留出余量。 */
+export const MIN_PANE_COLS = 70;
+
+/** 子代理 pane 的最小行数。 */
+export const MIN_PANE_ROWS = 15;
+
+export interface PaneRect {
+  width: number;
+  height: number;
+}
+
+/** 尺寸是否满足子代理最低可用预算。 */
+export function rectMeetsBudget(rect: PaneRect | null | undefined): boolean {
+  return !!rect && rect.width >= MIN_PANE_COLS && rect.height >= MIN_PANE_ROWS;
+}

package/modules/subagents/src/list-tool.ts

@@ -0,0 +1,292 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { existsSync } from "node:fs";
+import type { ListedAgentDefinition } from "./agents.ts";
+import type { NameRegistry, NameRegistryEntry, SubagentLoadout } from "./session.ts";
+import type { RuntimeRecord } from "./runtime-registry.ts";
+import type { RunningSubagent } from "./types.ts";
+
+export interface SubagentsListDeps {
+  discoverAgents: () => ListedAgentDefinition[];
+  /** scope=session/all 需要:父会话 artifact 目录解析。缺省时 session 视图明确报不可用。 */
+  getArtifactDir?: (sessionDir: string, sessionId: string) => string;
+  /** 本进程正在运行的子代理(状态判定用)。 */
+  runningSubagents?: Map<string, RunningSubagent>;
+  readNameRegistry?: (artifactDir: string) => NameRegistry;
+  readSubagentLoadout?: (sessionFile: string) => SubagentLoadout | null;
+  readRuntimeRecords?: (path: string) => RuntimeRecord[];
+  runtimeRegistryPath?: (artifactDir: string) => string;
+}
+
+export interface SessionSubagentView {
+  name: string;
+  agent?: string | null;
+  /** running:本进程仍在运行;finished:已到终态;discarded:会话工件已被 retention 清理。 */
+  status: "running" | "finished" | "discarded";
+  /** 持久团队成员:finished 实为 offline(running 时不区分轮次内细态)。 */
+  member?: boolean;
+  /** running 成员的轮次状态(idle = 等待派单)。 */
+  memberRound?: "idle" | "dispatched";
+  /** 会话文件存在且带 loadout 快照,可被 subagent_message resume。 */
+  resumable: boolean;
+  model?: string | null;
+  tier?: string | null;
+  cohortId?: string;
+}
+
+/**
+ * 从会话名字注册表(补充运行态登记)构建当前父会话的子代理只读视图:
+ * 只读展示名称、运行/完成/可恢复状态与 model/tier,不泄漏凭据。
+ */
+export function buildSessionSubagentViews(
+  registry: NameRegistry,
+  runningSubagents: Map<string, RunningSubagent> | undefined,
+  readSubagentLoadout: (sessionFile: string) => SubagentLoadout | null,
+): SessionSubagentView[] {
+  const views: SessionSubagentView[] = [];
+  const consider = (name: string, entry: NameRegistryEntry) => {
+    const running = runningSubagents
+      ? Array.from(runningSubagents.values()).find((candidate) => candidate.name === name)
+      : undefined;
+    if (running) {
+      views.push({
+        name,
+        ...(running.agent ? { agent: running.agent } : {}),
+        status: "running",
+        ...(running.member ? { member: true, memberRound: running.dispatchedRound ? "dispatched" : "idle" } : {}),
+        resumable: false,
+        ...(running.model ? { model: running.model } : {}),
+        ...(running.cohortId ? { cohortId: running.cohortId } : {}),
+      });
+      return;
+    }
+    const sessionExists = Boolean(entry.sessionFile) && existsSync(entry.sessionFile);
+    if (!sessionExists) {
+      // retention 清理或外部删除:保留登记仅供追溯,resume 已不可能。
+      views.push({
+        name,
+        status: "discarded",
+        resumable: false,
+        ...(entry.cohortId ? { cohortId: entry.cohortId } : {}),
+      });
+      return;
+    }
+    const loadout = readSubagentLoadout(entry.sessionFile);
+    const cohortId = loadout?.cohortId ?? entry.cohortId;
+    views.push({
+      name,
+      ...(loadout?.agent ? { agent: loadout.agent } : {}),
+      status: "finished",
+      ...(loadout?.member ? { member: true } : {}),
+      resumable: Boolean(loadout),
+      ...(loadout?.model ? { model: loadout.model } : {}),
+      ...(loadout?.tier ? { tier: loadout.tier } : {}),
+      ...(cohortId ? { cohortId } : {}),
+    });
+  };
+  for (const [name, entry] of Object.entries(registry)) {
+    if (entry && typeof entry.sessionFile === "string") consider(name, entry);
+  }
+  // 运行态登记里可能还有尚未写入名字注册表的名字(启动竞态/reload 边界)。
+  if (runningSubagents) {
+    const known = new Set(views.map((view) => view.name));
+    for (const running of runningSubagents.values()) {
+      if (!known.has(running.name)) consider(running.name, {
+        sessionFile: running.sessionFile,
+        sessionId: null,
+        ...(running.cohortId ? { cohortId: running.cohortId } : {}),
+      });
+    }
+  }
+  views.sort((a, b) => a.name.localeCompare(b.name));
+  return views;
+}
+
+function formatSessionViewLine(view: SessionSubagentView): string {
+  const memberBadge = view.member
+    ? view.status === "running"
+      ? ` (member · ${view.memberRound ?? "idle"})`
+      : " (member · offline)"
+    : "";
+  const badge =
+    view.status === "running" && !view.member ? " (running)"
+      : view.status === "discarded" ? " (discarded)" : "";
+  const resumable = view.status === "finished" ? (view.resumable ? " [resumable]" : " [not resumable]") : "";
+  const agent = view.agent ? ` — ${view.agent}` : "";
+  const model = view.model ? ` [${view.model}]` : "";
+  const tier = view.tier ? ` [tier: ${view.tier}]` : "";
+  const cohort = view.cohortId ? ` [cohort: ${view.cohortId}]` : "";
+  return `• ${view.name}${memberBadge}${badge}${resumable}${agent}${model}${tier}${cohort}`;
+}
+
+export function registerSubagentsListTool(
+  pi: ExtensionAPI,
+  deps: SubagentsListDeps,
+): void {
+  pi.registerTool({
+    name: "subagents_list",
+    label: "List Subagents",
+    description:
+      "List all available subagent definitions. " +
+      "Scans project-local .pi/agents/ and global ~/.pi/agent/agents/. " +
+      "Project-local agents override global ones with the same name. " +
+      "scope=session|all additionally shows a READ-ONLY view of the subagents registered by the CURRENT parent session: " +
+      "their names, whether their session files still exist, running/finished/resumable state, model/tier, and optional cohortId. " +
+      "No credentials are included.",
+    promptSnippet:
+      "List available subagent definitions; scope=session|all also shows a read-only view of this session's registered subagents (name, session present, running/finished/resumable, model/tier, cohortId).",
+    parameters: Type.Object({
+      scope: Type.Optional(
+        Type.Union(
+          [Type.Literal("definitions"), Type.Literal("session"), Type.Literal("all")],
+          {
+            description:
+              "'definitions' (default): available agent definitions only. 'session': subagents registered by the current parent session only. " +
+              "'all': both views.",
+          },
+        ),
+      ),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const scope = params?.scope ?? "definitions";
+      const definitionList = deps.discoverAgents().filter((agent) => !agent.disableModelInvocation);
+
+      const definitionsResult = () => {
+        if (definitionList.length === 0) {
+          return {
+            text: "No subagent definitions found.",
+            details: { scope, agents: [] as ListedAgentDefinition[] },
+          };
+        }
+        const lines = definitionList.map((agent) => {
+          const badge = agent.source === "project" ? " (project)" : "";
+          const description = agent.description ? ` — ${agent.description}` : "";
+          const model = agent.model ? ` [${agent.model}]` : "";
+          return `• ${agent.name}${badge}${model}${description}`;
+        });
+        return {
+          text: lines.join("\n"),
+          details: { scope, agents: definitionList },
+        };
+      };
+
+      if (scope === "definitions") {
+        const result = definitionsResult();
+        return { content: [{ type: "text", text: result.text }], details: result.details };
+      }
+
+      // ── session 视图 ──
+      const sessionFile = ctx?.sessionManager?.getSessionFile?.();
+      if (!sessionFile || !deps.getArtifactDir || !deps.readNameRegistry) {
+        return {
+          content: [{
+            type: "text",
+            text:
+              "The session view is unavailable in this context: no parent session file or no registry access. " +
+              "Start pi with a persistent session to see registered subagents.",
+          }],
+          details: { scope, error: "session-unavailable" },
+        };
+      }
+      const artifactDir = deps.getArtifactDir(
+        ctx.sessionManager.getSessionDir(),
+        ctx.sessionManager.getSessionId(),
+      );
+      const registry = deps.readNameRegistry(artifactDir);
+      const views = buildSessionSubagentViews(registry, deps.runningSubagents, (file) =>
+        deps.readSubagentLoadout
+          ? deps.readSubagentLoadout(file)
+          : null,
+      );
+
+      const sessionLines = () =>
+        views.length === 0
+          ? "No subagents have been registered in this session yet."
+          : views.map(formatSessionViewLine).join("\n");
+
+      if (scope === "session") {
+        return {
+          content: [{ type: "text", text: sessionLines() }],
+          details: { scope, subagents: views },
+        };
+      }
+
+      // scope === "all":两个视图一起给。
+      const definitions = definitionsResult();
+      const agents = definitions.details.agents;
+      const text = agents.length > 0 ? definitions.text : "No subagent definitions found.";
+      return {
+        content: [{
+          type: "text",
+          text: `${text}\n\n— Session subagents —\n${sessionLines()}`,
+        }],
+        details: { scope: "all", agents: definitions.details.agents, subagents: views },
+      };
+    },
+
+    renderResult(result, _opts, theme) {
+      const details = result.details as any;
+      const scope = details?.scope ?? "definitions";
+      const renderDefinitions = (): string | null => {
+        const agents = details?.agents ?? [];
+        if (agents.length === 0) return null;
+        return agents
+          .map((agent: any) => {
+            const badge = agent.source === "project" ? theme.fg("accent", " (project)") : "";
+            const description = agent.description ? theme.fg("dim", ` — ${agent.description}`) : "";
+            const model = agent.model ? theme.fg("dim", ` [${agent.model}]`) : "";
+            return `  ${theme.fg("toolTitle", theme.bold(agent.name))}${badge}${model}${description}`;
+          })
+          .join("\n");
+      };
+      const renderSession = (): string => {
+        const subagents: SessionSubagentView[] = details?.subagents ?? [];
+        if (subagents.length === 0) {
+          return theme.fg("dim", "No subagents have been registered in this session yet.");
+        }
+        return subagents
+          .map((view) => {
+            const memberBadge = view.member
+              ? view.status === "running"
+                ? theme.fg("accent", ` (member · ${view.memberRound ?? "idle"})`)
+                : theme.fg("muted", " (member · offline)")
+              : "";
+            const statusColor =
+              view.status === "running" && !view.member ? "accent" : view.status === "discarded" ? "muted" : view.member ? "muted" : "success";
+            const badge = memberBadge
+              || (view.status === "running"
+                ? theme.fg("accent", " (running)")
+                : view.status === "discarded"
+                  ? theme.fg("dim", " (discarded)")
+                  : "");
+            const resumable =
+              view.status === "finished"
+                ? view.resumable
+                  ? theme.fg("success", " [resumable]")
+                  : theme.fg("dim", " [not resumable]")
+                : "";
+            const agent = view.agent ? theme.fg("dim", ` — ${view.agent}`) : "";
+            const model = view.model ? theme.fg("dim", ` [${view.model}]`) : "";
+            const tier = view.tier ? theme.fg("dim", ` [tier: ${view.tier}]`) : "";
+            const cohort = view.cohortId ? theme.fg("dim", ` [cohort: ${view.cohortId}]`) : "";
+            return `  ${theme.fg("toolTitle", theme.bold(view.name))}${theme.fg(statusColor, badge)}${resumable}${agent}${model}${tier}${cohort}`;
+          })
+          .join("\n");
+      };
+
+      if (scope === "session") return new Text(renderSession(), 0, 0);
+      if (scope === "all") {
+        const defs = renderDefinitions();
+        return new Text(
+          `${defs ?? theme.fg("dim", "No subagent definitions found.")}\n\n${theme.fg("toolTitle", "— Session subagents —")}\n${renderSession()}`,
+          0,
+          0,
+        );
+      }
+      const defs = renderDefinitions();
+      return new Text(defs ?? theme.fg("dim", "No subagent definitions found."), 0, 0);
+    },
+  });
+}