@buyi1net/pi-toolkit 0.0.1

package/modules/subagents/src/route-error.ts

@@ -0,0 +1,212 @@
+import type { SessionStats } from "./session.ts";
+
+/**
+ * 路由异常结构化分类:子代理的 errorMessage 被归到有限的 kind 集合,连同
+ * retryable 与 suggestedActions 一起作为 tool result details 里的
+ * route_exception 提供给主编排代理。是否重试/换模型由主代理决定——本扩展
+ * 不做自动 fallback,也不暂停其它 sibling 子代理。
+ */
+export type RouteExceptionKind =
+  | "quota_exhausted"
+  | "rate_limited"
+  | "auth_failed"
+  | "model_unavailable"
+  | "context_too_large"
+  | "provider_error"
+  | "tool_failure"
+  | "unknown";
+
+export interface RouteException {
+  kind: RouteExceptionKind;
+  retryable: boolean;
+  /** 原始错误文本(人类可读 content 之外的程序可读副本)。 */
+  message: string;
+  /** 能从已解析模型 id 拆出时提供("openrouter/z-ai/glm-5.2" → "openrouter")。 */
+  provider?: string;
+  /** 已解析模型 id(不含 provider 前缀;能解析时提供)。 */
+  model?: string;
+  /** 子代理会话中已执行的工具调用数(区分"启动即败"与"执行中途失败")。 */
+  toolCount?: number;
+  suggestedActions: string[];
+}
+
+/** 拆分 "provider/model[:thinking]" 形式的模型 id;无 provider 前缀时省略。 */
+export function splitModelRef(modelRef: string): { provider?: string; model: string } {
+  const slash = modelRef.indexOf("/");
+  if (slash > 0 && slash < modelRef.length - 1) {
+    return { provider: modelRef.slice(0, slash), model: modelRef.slice(slash + 1) };
+  }
+  return { model: modelRef };
+}
+
+interface RoutePattern {
+  kind: RouteExceptionKind;
+  retryable: boolean;
+  patterns: RegExp[];
+  suggestedActions: string[];
+}
+
+/**
+ * 分类规则按优先级排列:更具体/更高价值判定(上下文超限、鉴权、额度、
+ * 模型不存在)先于通用供应商错误;通用 5xx/网络类最后兜底,未命中即 unknown。
+ * 模式来自常见供应商错误文案(Anthropic/OpenAI/OpenRouter),保守避免误判。
+ */
+const ROUTE_PATTERNS: RoutePattern[] = [
+  {
+    kind: "context_too_large",
+    retryable: false,
+    patterns: [
+      /context (?:length|window)/i,
+      /maximum context/i,
+      /context too large/i,
+      /prompt is too long/i,
+      /input (?:is )?too long/i,
+      /too many (?:input )?tokens/i,
+      /token limit/i,
+      /exceeds? the maximum/i,
+    ],
+    suggestedActions: [
+      "Reduce or split the task, or attach less context",
+      "Spawn with a model that has a larger context window",
+    ],
+  },
+  {
+    kind: "auth_failed",
+    retryable: false,
+    patterns: [
+      /\b401\b/,
+      /\b403\b/,
+      /unauthorized/i,
+      /forbidden/i,
+      /invalid api key/i,
+      /api key/i,
+      /authentication/i,
+      /not authenticated/i,
+    ],
+    suggestedActions: [
+      "Check the provider credentials/API key configuration",
+      "Fix the credential, then retry manually",
+    ],
+  },
+  {
+    kind: "quota_exhausted",
+    retryable: false,
+    patterns: [
+      /quota/i,
+      /\b402\b/,
+      /insufficient (?:credits?|balance|funds)/i,
+      /out of credits?/i,
+      /credit balance/i,
+      /billing/i,
+      /payment/i,
+      /spending limit/i,
+    ],
+    suggestedActions: [
+      "Check the provider account balance/quota",
+      "Decide on a different provider/model and respawn manually — no automatic switch",
+    ],
+  },
+  {
+    kind: "rate_limited",
+    retryable: true,
+    patterns: [/\b429\b/, /rate limit/i, /too many requests/i, /overloaded/i],
+    suggestedActions: [
+      "Wait for the limit window to pass, then retry manually",
+      "Consider a different model or provider if this recurs",
+    ],
+  },
+  {
+    kind: "model_unavailable",
+    retryable: false,
+    patterns: [
+      /model (?:is )?not found/i,
+      /does not exist/i,
+      /unknown model/i,
+      /invalid model/i,
+      /no such model/i,
+      /model.*not available/i,
+      /has been (?:decommissioned|deprecated)/i,
+    ],
+    suggestedActions: [
+      "Verify the model id for this provider",
+      "Update the pi-subagents tier mapping or pass an explicit model",
+    ],
+  },
+  {
+    kind: "tool_failure",
+    retryable: false,
+    patterns: [/tool (?:call|execution) failed/i, /failed to (?:run|execute) tool/i],
+    suggestedActions: [
+      "Inspect the sub-agent session for the failing tool call",
+      "Retry with a narrower task or different tools",
+    ],
+  },
+  {
+    kind: "provider_error",
+    retryable: true,
+    patterns: [
+      /\b5\d\d\b/,
+      /bad gateway/i,
+      /service unavailable/i,
+      /internal server error/i,
+      /server error/i,
+      /timeout|timed out/i,
+      /econn(?:refused|reset|aborted)/i,
+      /enotfound/i,
+      /fetch failed/i,
+      /connection (?:error|refused|reset)/i,
+    ],
+    suggestedActions: [
+      "Check the provider status page, then retry manually",
+      "Retry with a different provider/model if the outage persists",
+    ],
+  },
+];
+
+/**
+ * 从错误文本分类路由异常。context.model 取自主代理已解析的模型 id
+ * (launch loadout / resume loadout),只做展示拆分,不影响 kind 判定。
+ */
+export function buildRouteException(
+  errorMessage: string,
+  context?: { model?: string | null; toolCount?: number },
+): RouteException {
+  const matched = ROUTE_PATTERNS.find((route) =>
+    route.patterns.some((pattern) => pattern.test(errorMessage)),
+  );
+  const modelRef = context?.model?.trim();
+  const split = modelRef ? splitModelRef(modelRef) : { provider: undefined, model: undefined };
+  const base = matched ?? {
+    kind: "unknown" as const,
+    retryable: false,
+    suggestedActions: [
+      "Inspect the sub-agent session file for the full error",
+      "Retry manually or spawn with a different model",
+    ],
+  };
+  return {
+    kind: base.kind,
+    retryable: base.retryable,
+    message: errorMessage,
+    ...(split.provider ? { provider: split.provider } : {}),
+    ...(split.model ? { model: split.model } : {}),
+    ...(context?.toolCount != null ? { toolCount: context.toolCount } : {}),
+    suggestedActions: base.suggestedActions,
+  };
+}
+
+/**
+ * 子代理结果 → route_exception(details 组装的统一入口):errorMessage 缺失
+ * (成功/取消)或 userClosed(用户关闭 pane,非 provider/agent 错误)返回
+ * undefined;已有 errorMessage 则现场分类,并把 stats.toolCount 一并带上。
+ */
+export function routeExceptionFromResult(
+  result: { errorMessage?: string; stats?: Pick<SessionStats, "toolCount">; userClosed?: boolean },
+  model?: string | null,
+): RouteException | undefined {
+  if (!result.errorMessage || result.userClosed) return undefined;
+  return buildRouteException(result.errorMessage, {
+    model,
+    toolCount: result.stats?.toolCount,
+  });
+}

package/modules/subagents/src/routing.ts

@@ -0,0 +1,235 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+// src/routing.ts → 包根(两层向上),与 status.ts 的 PACKAGE_ROOT 同规则。
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** 规范档位;配置与 params 都归一化到这三个值。 */
+export type ModelTier = "fast" | "balanced" | "deep";
+
+export const MODEL_TIERS: readonly ModelTier[] = ["fast", "balanced", "deep"];
+
+/**
+ * tier 别名表:params 与配置键共用,归一化到 canonical。刻意保持最小集合,
+ * 不再扩大别名——同一含义多个写法只增加配置歧义。
+ */
+const TIER_ALIASES: Record<ModelTier, string[]> = {
+  fast: ["fast", "quick"],
+  balanced: ["balanced", "balance", "standard"],
+  deep: ["deep", "strong"],
+};
+
+/** 归一化 tier 输入;无法识别返回 null,调用方必须报清晰错误,不得静默换档。 */
+export function normalizeTier(input: string): ModelTier | null {
+  const value = input.trim().toLowerCase();
+  for (const tier of MODEL_TIERS) {
+    if (TIER_ALIASES[tier].includes(value)) return tier;
+  }
+  return null;
+}
+
+export interface TierRouteConfig {
+  /** tier → 模型 id(可带 ":thinking" 后缀,由启动参数构造层统一处理)。 */
+  models: Partial<Record<ModelTier, string>>;
+  /** 配置来源文件路径,用于错误提示定位。 */
+  sourcePath: string;
+}
+
+export type TierConfigParseResult = { config: TierRouteConfig } | { error: string };
+
+/**
+ * 严格校验 tier 配置。根对象允许携带其它键(包级 config.json 与 status 配置
+ * 共用同一文件,这里只认 models);models 内部从严:未知 tier 键、非字符串、
+ * 空串、含空白、同 tier 别名重复都报错。models 缺失视为合法但无映射。
+ */
+export function parseTierConfig(raw: unknown, source: string): TierConfigParseResult {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { error: `${source}: root must be a JSON object` };
+  }
+  const root = raw as Record<string, unknown>;
+  const rawModels = root.models;
+  if (rawModels === undefined) {
+    return { config: { models: {}, sourcePath: source } };
+  }
+  if (rawModels == null || typeof rawModels !== "object" || Array.isArray(rawModels)) {
+    return { error: `${source}: models must be an object` };
+  }
+  const models: Partial<Record<ModelTier, string>> = {};
+  const aliasOwner = new Map<ModelTier, string>();
+  for (const [key, value] of Object.entries(rawModels as Record<string, unknown>)) {
+    const tier = normalizeTier(key);
+    if (!tier) {
+      return {
+        error: `${source}: models has unsupported tier key "${key}" (use ${MODEL_TIERS.join(", ")})`,
+      };
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+      return { error: `${source}: models.${key} must be a non-empty string` };
+    }
+    if (/\s/.test(value)) {
+      return { error: `${source}: models.${key} must not contain whitespace` };
+    }
+    const previousKey = aliasOwner.get(tier);
+    if (previousKey !== undefined) {
+      return {
+        error: `${source}: models has conflicting entries for tier "${tier}" ("${previousKey}" and "${key}")`,
+      };
+    }
+    aliasOwner.set(tier, key);
+    models[tier] = value;
+  }
+  return { config: { models, sourcePath: source } };
+}
+
+export interface TierConfigLoadResult {
+  /** null 表示没有任何配置文件(合法;仅在使用 tier 时才需要报错)。 */
+  config: TierRouteConfig | null;
+  /** 实际读取(或读取失败)的配置路径;一个都没找到时为 null。 */
+  sourcePath: string | null;
+  /** 显式指定(PI_SUBAGENTS_CONFIG)的文件缺失/解析失败时的错误。 */
+  error?: string;
+}
+
+/**
+ * 宿主注入的配置层(pi-toolkit 迁入后新增):调用方已经把 `subagents` 节解析好,
+ * 这里只负责把它按优先级插进候选链。`source` 仅用于错误提示定位。
+ */
+export interface TierRouteInjectedSource {
+  readonly source: string;
+  readonly raw: unknown;
+}
+
+/**
+ * 配置读取链:PI_SUBAGENTS_CONFIG → <cwd>/.pi/agent/pi-subagents.json →
+ * PI_CODING_AGENT_DIR(缺省 ~/.pi/agent)/pi-subagents.json → 宿主注入层
+ * (pi-toolkit.json 的 `modules.subagents` 节) → 包 config.json →
+ * 包 config.json.example。第一个存在的文件即最终答案;显式环境变量指向的
+ * 文件缺失或非法视为配置错误,其余候选缺失只跳过。纯读取,不写盘,
+ * 不触碰凭据/余额。
+ */
+export function loadTierRouteConfig(options?: {
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  agentConfigDir?: string;
+  /** 宿主注入的额外候选层,排在全局 pi-subagents.json 之后、包内文件之前 */
+  injected?: readonly TierRouteInjectedSource[];
+}): TierConfigLoadResult {
+  const env = options?.env ?? process.env;
+  const cwd = options?.cwd ?? process.cwd();
+  // 与 index.ts getAgentConfigDir 同规则;以参数注入避免模块反向依赖。
+  const agentConfigDir =
+    options?.agentConfigDir ?? env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+
+  const candidates: Array<{ path: string; explicit: boolean; raw?: unknown }> = [];
+  const explicit = env.PI_SUBAGENTS_CONFIG?.trim();
+  if (explicit) candidates.push({ path: explicit, explicit: true });
+  candidates.push(
+    { path: join(cwd, ".pi", "agent", "pi-subagents.json"), explicit: false },
+    { path: join(agentConfigDir, "pi-subagents.json"), explicit: false },
+  );
+  for (const source of options?.injected ?? []) {
+    candidates.push({ path: source.source, explicit: false, raw: source.raw });
+  }
+  candidates.push(
+    { path: join(PACKAGE_ROOT, "config.json"), explicit: false },
+    { path: join(PACKAGE_ROOT, "config.json.example"), explicit: false },
+  );
+
+  for (const candidate of candidates) {
+    let parsed: unknown;
+    if (candidate.raw !== undefined) {
+      // 宿主注入层:调用方已经读过一次(pi-toolkit.json 是宿主自己的文件),
+      // 这里直接吃解析结果,不再重复读盘。
+      parsed = candidate.raw;
+    } else {
+      let raw: string;
+      try {
+        raw = readFileSync(candidate.path, "utf8");
+      } catch (error) {
+        const errno = error as NodeJS.ErrnoException;
+        if (errno.code === "ENOENT") {
+          if (candidate.explicit) {
+            return {
+              config: null,
+              sourcePath: candidate.path,
+              error: `PI_SUBAGENTS_CONFIG points to a missing file: ${candidate.path}`,
+            };
+          }
+          continue;
+        }
+        return {
+          config: null,
+          sourcePath: candidate.path,
+          error: `Could not read ${candidate.path}: ${errno.message ?? String(error)}`,
+        };
+      }
+      try {
+        parsed = JSON.parse(raw);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+          config: null,
+          sourcePath: candidate.path,
+          error: `Invalid JSON in ${candidate.path}: ${detail}`,
+        };
+      }
+    }
+    const parsedConfig = parseTierConfig(parsed, candidate.path);
+    if ("error" in parsedConfig) {
+      return { config: null, sourcePath: candidate.path, error: parsedConfig.error };
+    }
+    return { config: parsedConfig.config, sourcePath: candidate.path };
+  }
+  return { config: null, sourcePath: null };
+}
+
+/** tier → 具体模型;缺映射给清晰错误,绝不静默换模型。 */
+export function resolveTierModel(
+  tier: ModelTier,
+  config: TierRouteConfig | null,
+): { model: string } | { error: string } {
+  const model = config?.models[tier];
+  if (!model) {
+    const hint = config
+      ? ` Add models.${tier} to ${config.sourcePath}.`
+      : " No pi-subagents config was found (looked at $PI_SUBAGENTS_CONFIG, " +
+        "<cwd>/.pi/agent/pi-subagents.json, $PI_CODING_AGENT_DIR/pi-subagents.json, " +
+        "and the package config).";
+    return { error: `No model configured for tier "${tier}".${hint}` };
+  }
+  return { model };
+}
+
+export type TierLaunchResolution =
+  | { tier: ModelTier | null; model?: string }
+  | { error: string };
+
+/**
+ * launch 前的 tier 解析:显式 params.model 永远优先 tier(同时给出时不读
+ * 配置,tier 仅作 loadout 记录);tier 无法归一化或缺映射时报错,不回退。
+ */
+export function resolveTierForParams(
+  params: { tier?: string; model?: string },
+  loadConfig: () => TierConfigLoadResult,
+): TierLaunchResolution {
+  const requested = params.tier?.trim();
+  if (!requested) return { tier: null };
+  const tier = normalizeTier(requested);
+  if (!tier) {
+    return {
+      error:
+        `Invalid tier "${params.tier}". Use one of: ${MODEL_TIERS.join(", ")} ` +
+        "(aliases: quick, balance/standard, strong).",
+    };
+  }
+  if (params.model) return { tier };
+  const loaded = loadConfig();
+  if (loaded.error) {
+    return { error: `Tier "${tier}" could not be resolved: ${loaded.error}` };
+  }
+  const resolved = resolveTierModel(tier, loaded.config);
+  if ("error" in resolved) return { error: resolved.error };
+  return { tier, model: resolved.model };
+}

package/modules/subagents/src/runtime-registry.ts

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { debugLog } from "./diagnostics.ts";
+import type { SubagentWaitMode, SubagentWaitRelease } from "./types.ts";
+
+export interface RuntimeRecord {
+  version: 1;
+  id: string;
+  name: string;
+  task: string;
+  /** 仅用于展示和结果聚合的并行分组标签。 */
+  cohortId?: string;
+  agent?: string;
+  surface: string;
+  startTime: number;
+  sessionFile: string;
+  activityFile?: string;
+  sentinelToken: string;
+  interactive: boolean;
+  /** 运行载体;缺省(旧记录)按 "pane" 处理。 */
+  kind?: "pane" | "headless";
+  /** headless 运行的子进程 PID,用于 /reload 后探测存活性。 */
+  pid?: number;
+  /** 直接父子代理 run id;顶层子代理为 null。 */
+  parentId?: string | null;
+  /** 本次硬屏障等待上限(毫秒)。 */
+  timeoutMs?: number;
+  /** 启动时的等待载体,供 /reload 后状态观测。 */
+  waitMode?: SubagentWaitMode;
+  /** 主工具等待已被 Escape/timeout 解除,子代理仍在运行。 */
+  waitReleased?: SubagentWaitRelease;
+  /** 持久团队成员(member: true):常驻 headless,恢复路径按 offline 处理。 */
+  member?: boolean;
+}
+
+interface RuntimeRegistry {
+  version: 1;
+  records: RuntimeRecord[];
+}
+
+export type RuntimeSource = Omit<RuntimeRecord, "version">;
+
+/**
+ * 从运行中的 RunningSubagent 挑选可持久化字段构造记录。
+ * 显式挑选而非展开:running 上挂着 statusState/headlessChild 等运行时对象
+ * (ChildProcess 存在循环引用),整体展开会让 JSON.stringify 炸掉。
+ */
+export function createRuntimeRecord(source: RuntimeSource): RuntimeRecord {
+  return {
+    version: 1,
+    id: source.id,
+    name: source.name,
+    task: source.task,
+    ...(source.cohortId ? { cohortId: source.cohortId } : {}),
+    ...(source.agent ? { agent: source.agent } : {}),
+    surface: source.surface,
+    startTime: source.startTime,
+    sessionFile: source.sessionFile,
+    ...(source.activityFile ? { activityFile: source.activityFile } : {}),
+    sentinelToken: source.sentinelToken,
+    interactive: source.interactive,
+    ...(source.kind ? { kind: source.kind } : {}),
+    ...(source.pid != null ? { pid: source.pid } : {}),
+    ...(source.parentId !== undefined ? { parentId: source.parentId } : {}),
+    ...(source.timeoutMs != null ? { timeoutMs: source.timeoutMs } : {}),
+    ...(source.waitMode ? { waitMode: source.waitMode } : {}),
+    ...(source.waitReleased ? { waitReleased: source.waitReleased } : {}),
+    ...(source.member ? { member: true } : {}),
+  };
+}
+
+export function runtimeRegistryPath(artifactDir: string): string {
+  return join(artifactDir, "subagent-runtime.json");
+}
+
+export function readRuntimeRecords(path: string): RuntimeRecord[] {
+  try {
+    if (!existsSync(path)) return [];
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as RuntimeRegistry;
+    if (parsed?.version !== 1 || !Array.isArray(parsed.records)) return [];
+    return parsed.records.filter((record) =>
+      record &&
+      record.version === 1 &&
+      typeof record.id === "string" &&
+      typeof record.name === "string" &&
+      typeof record.task === "string" &&
+      (record.cohortId == null || typeof record.cohortId === "string") &&
+      typeof record.surface === "string" &&
+      typeof record.sessionFile === "string" &&
+      typeof record.sentinelToken === "string" &&
+      typeof record.startTime === "number" &&
+      Number.isFinite(record.startTime) &&
+      typeof record.interactive === "boolean" &&
+      (record.agent == null || typeof record.agent === "string") &&
+      (record.activityFile == null || typeof record.activityFile === "string") &&
+      (record.member == null || typeof record.member === "boolean") &&
+      (record.pid == null || (typeof record.pid === "number" && Number.isInteger(record.pid) && record.pid > 0)) &&
+      (record.parentId == null || typeof record.parentId === "string") &&
+      (record.timeoutMs == null || (typeof record.timeoutMs === "number" && Number.isFinite(record.timeoutMs) && record.timeoutMs >= 1000)) &&
+      (record.waitMode == null ||
+        record.waitMode === "hard-barrier" ||
+        record.waitMode === "interactive" ||
+        record.waitMode === "member-round" ||
+        record.waitMode === "recovered") &&
+      (record.waitReleased == null || record.waitReleased === "escape" || record.waitReleased === "timeout"),
+    );
+  } catch {
+    return [];
+  }
+}
+
+function writeRuntimeRecords(path: string, records: RuntimeRecord[]): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify({ version: 1, records }), "utf8");
+  renameSync(temp, path);
+}
+
+export function upsertRuntimeRecord(path: string, record: RuntimeRecord): void {
+  const records = readRuntimeRecords(path).filter((item) => item.id !== record.id);
+  writeRuntimeRecords(path, [...records, record]);
+}
+
+/** 更新仍在登记中的等待释放原因;记录已被 watcher 移除时不重新创建。 */
+export function markRuntimeWaitReleased(
+  path: string,
+  id: string,
+  waitReleased: SubagentWaitRelease,
+): void {
+  const records = readRuntimeRecords(path);
+  if (!records.some((record) => record.id === id)) return;
+  try {
+    writeRuntimeRecords(
+      path,
+      records.map((record) => record.id === id ? { ...record, waitReleased } : record),
+    );
+  } catch (error) {
+    debugLog(`Could not persist wait release for runtime record ${id}`, error);
+  }
+}
+
+export function removeRuntimeRecord(path: string, id: string): void {
+  const records = readRuntimeRecords(path).filter((item) => item.id !== id);
+  if (records.length === 0) {
+    try {
+      writeRuntimeRecords(path, []);
+    } catch (error) {
+      // 运行态清理失败不能覆盖已经取得的子代理结果。
+      debugLog(`Could not clear runtime registry ${path}`, error);
+    }
+    return;
+  }
+  try {
+    writeRuntimeRecords(path, records);
+  } catch (error) {
+    // watcher 清理是尽力而为，失败不会改变主会话结果。
+    debugLog(`Could not update runtime registry ${path}`, error);
+  }
+}