@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/agents.js

@@ -0,0 +1,484 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * A guard rather than a cast: it is the only thing that lets `tools:` be checked once and then used as
+ * a map everywhere without the compiler complaining. It narrows to the index-signature shape that
+ * `object` cannot express on its own.
+ */
+const isFrontmatter = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+/**
+ * Every tool name Super Pi can know STATICALLY, read out of Pi's own source rather than from memory.
+ * Each entry carries the place it came from, because this list is the whole safety net behind
+ * `validateToolNames` and it has to be re-checked whenever Pi is upgraded.
+ *
+ * It is deliberately NOT the 8 built-ins alone. Pi's registry also holds:
+ *
+ *   - `codemode` and `tool_search`, registered by the two built-in extensions
+ *     (extensions/codemode/tool.ts:50, extensions/tool-search/tool.ts:20). Pi's own CLI help offers
+ *     `--tools read,bash,codemode,'mcp__radius__*'` as an example (cli/args.ts:409), so treating
+ *     these as unknown would reject configuration Pi documents.
+ *   - the three MCP resource tools (core/mcp-servers.ts:31-37).
+ *   - MCP server tools, named `mcp__<server>__<tool>` (core/mcp-servers.ts:38-41). The server list
+ *     is runtime state, so those are recognised by PREFIX instead of by name - see `isKnownPiToolName`.
+ *
+ * Anything else Pi can hold - a third-party extension tool, an SDK-supplied tool
+ * (agent-session.ts:3503-3509) - has an arbitrary name that no static list can contain. Those names
+ * are indistinguishable from typos by construction, which is the limit of this check; see
+ * `validateToolNames` for what is rejected on that account and why.
+ */
+export const PI_TOOL_NAMES = [
+    // core/tools/index.ts:95-105 - the ToolName union and the allToolNames set.
+    "read", "bash", "powershell", "edit", "write", "grep", "find", "ls",
+    // Registered by Pi's built-in extensions.
+    "codemode", "tool_search",
+    // core/mcp-servers.ts:31-37 - reachable on any server that exposes resources.
+    "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource",
+];
+const PI_TOOL_NAME_SET = new Set(PI_TOOL_NAMES);
+/**
+ * Whether a name can be a real Pi tool. A name is real if it is one of `PI_TOOL_NAMES`, an MCP
+ * server tool, or a PATTERN.
+ *
+ * Patterns are a real feature, not an escape hatch: Pi turns every `--tools` entry into a matcher
+ * that treats a `*` entry as a glob (core/mcp-servers.ts:21-25), and `--tools` is exactly what an
+ * agent's `tools` map becomes. Rejecting `mcp__radius__*` would reject Pi's documented syntax.
+ */
+export function isKnownPiToolName(name) {
+    if (PI_TOOL_NAME_SET.has(name))
+        return true;
+    if (name.includes("*"))
+        return true;
+    return name.startsWith("mcp__");
+}
+function editDistance(left, right) {
+    const row = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const above = row[j];
+            row[j] = left[i - 1] === right[j - 1] ? diagonal : Math.min(diagonal + 1, above + 1, row[j - 1] + 1);
+            diagonal = above;
+        }
+    }
+    return row[right.length];
+}
+function closestToolName(name) {
+    const ranked = PI_TOOL_NAMES.map((candidate) => ({ candidate, distance: editDistance(name, candidate) })).sort((a, b) => a.distance - b.distance);
+    return ranked[0]?.distance <= Math.max(2, Math.floor(name.length / 2)) ? ranked[0].candidate : undefined;
+}
+/**
+ * Reports every `tools` key that cannot be a Pi tool name, or undefined when they all can.
+ *
+ * WHY THIS CHECK EXISTS. Pi's own validator for a tool list (`getToolListError`,
+ * core/settings-manager.ts:227-234) only looks at `+name`/`-name` SYNTAX and never asks whether the
+ * tool exists. An allowlist naming one misspelled tool therefore passes Pi's validation and then
+ * matches nothing, so the agent is registered with NO tools at all and no warning is printed
+ * anywhere: the picker shows a working agent that cannot read, search or edit anything.
+ *
+ * WHAT IS REJECTED, AND WHAT THAT COSTS. A name that is neither statically known, nor `mcp__`-prefixed,
+ * nor a pattern is reported as a problem, which takes the whole definition out of the roster. The cost
+ * is a false positive on a third-party extension or SDK tool (agent-session.ts:3503-3509), whose names
+ * are arbitrary and unknowable from here. That direction is deliberate: a rejected agent is VISIBLE in
+ * the picker with the reason and the full known list attached, while an accepted typo is invisible and
+ * produces a silently useless agent - the exact failure this check exists to remove.
+ */
+function validateToolNames(tools) {
+    if (!isFrontmatter(tools))
+        return undefined;
+    const unknown = Object.keys(tools).filter((name) => name !== "*" && !isKnownPiToolName(name));
+    if (!unknown.length)
+        return undefined;
+    const details = unknown.map((name) => {
+        const suggestion = closestToolName(name);
+        return `${JSON.stringify(name)}${suggestion ? ` (did you mean ${JSON.stringify(suggestion)}?)` : ""}`;
+    });
+    return `tools names ${details.join(", ")}, which Pi does not have. Statically known tools: ${PI_TOOL_NAMES.join(", ")}; MCP tools are named mcp__<server>__<tool>, and a "*" in a name is a Pi glob.`;
+}
+/**
+ * Splits a definition file into frontmatter and body. The body is the system prompt, exactly as in
+ * OpenCode - a file with no frontmatter is not an agent definition, and is reported rather than
+ * silently treated as an empty-prompt agent.
+ */
+export function splitDefinition(source) {
+    const match = FRONTMATTER_BLOCK.exec(source);
+    if (!match)
+        return undefined;
+    return { frontmatter: parseYaml(match[1]), body: source.slice(match[0].length) };
+}
+/**
+ * A deliberately small YAML reader: scalars, nested one-level maps, inline `[a, b]` lists and `- item`
+ * lists. That is the whole grammar OpenCode agent frontmatter uses (`tools:` is a map, `model:` and
+ * `color:` are scalars), and it keeps Super Pi free of a YAML dependency for four fields.
+ *
+ * Anything it cannot represent is DROPPED rather than guessed: a malformed agent file must fail its
+ * own parse and be reported, not load with a field the author thought they set.
+ */
+export function parseYaml(text) {
+    const root = {};
+    const lines = text.split(/\r?\n/);
+    let index = 0;
+    const indentOf = (line) => line.length - line.trimStart().length;
+    /**
+     * Drops a trailing `# comment`, respecting quotes. Agent frontmatter carries explanatory comments -
+     * especially on the `tools` map, where `"*": false` is worth a line of prose - and without this a
+     * colour would come out as `"#4C9AFF"   # the agent's brand colour`, which then fails the hex check
+     * and silently loses the colour. Quote-aware so a `#` inside a quoted value survives.
+     */
+    const stripComment = (value) => {
+        let quote;
+        for (let at = 0; at < value.length; at += 1) {
+            const character = value[at];
+            if (quote) {
+                if (character === quote)
+                    quote = undefined;
+                continue;
+            }
+            if (character === '"' || character === "'") {
+                quote = character;
+                continue;
+            }
+            // Only a `#` preceded by whitespace starts a comment, so `color: #4C9AFF` still parses.
+            if (character === "#" && (at === 0 || /\s/.test(value[at - 1])))
+                return value.slice(0, at);
+        }
+        return value;
+    };
+    const valueAfter = (keyLine) => stripComment(keyLine.slice(keyLine.indexOf(":") + 1)).trim();
+    /**
+     * Reads whatever follows a key on the deeper-indented lines below it: either a `- item` block list or
+     * a nested map, and `undefined` when the next line is not deeper at all.
+     *
+     * This is the single place a block value is read, because the two shapes are easy to confuse and the
+     * failure is silent: treating a `- item` list as a map yields `{}`, and treating a map as a list
+     * yields `[]`. Both load as "an empty frontmatter field" rather than as an error.
+     */
+    const readDeeper = (parentIndent) => {
+        const next = lines[index];
+        if (next === undefined || next.trim() === "" || indentOf(next) <= parentIndent)
+            return undefined;
+        if (next.trim().startsWith("- ")) {
+            const items = [];
+            while (index < lines.length && lines[index].trim().startsWith("- ")) {
+                items.push(unquote(lines[index].trim().slice(2).trim()));
+                index += 1;
+            }
+            return items;
+        }
+        return readMap(parentIndent);
+    };
+    /** Reads the value belonging to `keyLine`, which the caller has ALREADY stepped past.
+     *
+     *  `keyIndent` is the KEY's OWN indent, deliberately not its parent's. A block value must be indented
+     *  deeper than the key that owns it; compared against the parent's indent instead, the first scalar in
+     *  a map would swallow its next SIBLING - `tools:` -> `"*": false` -> `read: true` would parse the
+     *  boolean as a map containing `read`, which loads as a permission map that reads back empty. */
+    const readValue = (keyLine, keyIndent) => {
+        const rest = valueAfter(keyLine);
+        if (rest.startsWith("["))
+            return parseInlineList(rest) ?? "";
+        const deeper = readDeeper(keyIndent);
+        return deeper === undefined ? parseScalar(rest) : deeper;
+    };
+    /** Reads `key:` followed by lines indented deeper than it, as a nested map. */
+    const readMap = (parentIndent) => {
+        const nested = {};
+        while (index < lines.length && lines[index].trim() !== "" && indentOf(lines[index]) > parentIndent) {
+            const child = lines[index];
+            const childColon = child.indexOf(":");
+            if (childColon < 0) {
+                index += 1;
+                continue;
+            }
+            const childKey = unquote(child.slice(0, childColon).trim());
+            index += 1;
+            nested[childKey] = readValue(child, indentOf(child));
+        }
+        return nested;
+    };
+    while (index < lines.length) {
+        const line = lines[index];
+        if (!line.trim() || line.trim().startsWith("#")) {
+            index += 1;
+            continue;
+        }
+        const colon = line.indexOf(":");
+        if (colon < 0) {
+            index += 1;
+            continue;
+        }
+        const key = unquote(line.slice(0, colon).trim());
+        const indent = indentOf(line);
+        // Stepped past the key's own line FIRST, so a block value is read from what actually follows it.
+        index += 1;
+        root[key] = readValue(line, indent);
+    }
+    return root;
+}
+const parseInlineList = (value) => {
+    if (!value.startsWith("[") || !value.endsWith("]"))
+        return undefined;
+    return value.slice(1, -1).split(",").map((item) => unquote(item.trim())).filter((item) => item !== "");
+};
+/** Booleans, numbers and quoted strings are the only scalar shapes agent frontmatter uses. */
+function parseScalar(value) {
+    if (value === "" || value === "~" || value === "null")
+        return "";
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+$/.test(value))
+        return Number.parseInt(value, 10);
+    return unquote(value);
+}
+function unquote(value) {
+    if ((value.startsWith('"') && value.endsWith('"') && value.length > 1) || (value.startsWith("'") && value.endsWith("'") && value.length > 1))
+        return value.slice(1, -1);
+    return value;
+}
+/**
+ * The Pi CLI flags an agent's `tools` map becomes. Returned flat so the caller can push them into the
+ * spawn argv in order, and so a test can assert on the exact list.
+ *
+ * THE TRANSLATION, from OpenCode's semantics (`tools` is a map whose `"*"` entry sets the default for
+ * every tool, and other keys override it) to Pi's three flags:
+ *
+ *   tools: { "*": false, read: true }  ->  ["--tools", "read"]     allowlist, everything else denied
+ *   tools: { "*": false }              ->  ["--no-tools"]          nothing at all
+ *   tools: { bash: false }             ->  ["--exclude-tools","bash"]  deny one, keep Pi's defaults
+ *   tools: { "*": true, bash: false }  ->  ["--exclude-tools","bash"]  same, stated explicitly
+ *   no `tools` key                     ->  []                      Pi's own default tool set
+ *
+ * The allowlist form is a real permission boundary, not a courtesy: Pi filters the tool REGISTRY
+ * through the same allowlist (agent-session.ts:3536-3545), so a tool that is not on the list is never
+ * registered, never declared to the model, and therefore cannot be called - the model does not even
+ * see a schema for it. Naming a tool on the allowlist also activates it (agent-session.ts:3569-3574).
+ */
+export function toolFlags(tools, options = {}) {
+    const denied = new Set((options.denyTools ?? []).filter((name) => name !== ""));
+    // An agent with no `tools:` map runs on Pi's own default set, so there is nothing to translate - but a
+    // DENY inherited from a parent still has to become an explicit exclusion, because there is no allowlist
+    // here to drop the name from.
+    if (!tools || typeof tools !== "object")
+        return denied.size ? ["--exclude-tools", [...denied].join(",")] : [];
+    const entries = Object.entries(tools).filter(([key]) => key !== "*");
+    // An absent `"*"` is OpenCode's default: every tool is allowed unless a key says otherwise.
+    const wildcard = tools["*"];
+    // An explicit `false` is the author's own refusal and outranks any extra the host is adding.
+    const explicit = new Map(entries);
+    const extra = (options.extraAllowedTools ?? []).filter((name) => name !== "" && explicit.get(name) !== false);
+    // An inherited deny is applied to the DECLARED list first, so `tools: {"read": true, "bash": true}` from
+    // a child whose parent denied `bash` becomes an allowlist of `read` - the intersection the child is
+    // entitled to, and the whole reason `denyTools` is applied here rather than at the call site.
+    const declared = entries.filter(([, on]) => on === true).map(([name]) => name).filter((name) => !denied.has(name));
+    const deny = entries.filter(([, on]) => on === false).map(([name]) => name)
+        .filter((name) => !declared.includes(name));
+    if (wildcard === false) {
+        // `{"*": false}` with nothing switched back on is the strongest statement an agent author can make -
+        // "this role talks, it does not act" - and an allowlist of nothing is where a host capability stops.
+        // Extending it would make `extraAllowedTools` an override of the author's intent rather than a
+        // completion of it, and the one agent that most clearly does not want a delegation tool is the one
+        // that has just said it wants no tools at all.
+        if (!declared.length)
+            return ["--no-tools"];
+        const allow = [...declared, ...extra.filter((name) => !declared.includes(name) && !denied.has(name))];
+        return ["--tools", allow.join(",")];
+    }
+    // A map with no allowlist is Pi's defaults, so a denied name has to become an explicit exclusion
+    // rather than being dropped - there is nothing to drop it FROM.
+    const excluded = [...new Set([...deny, ...[...denied].filter((name) => !deny.includes(name))])];
+    if (excluded.length)
+        return ["--exclude-tools", excluded.join(",")];
+    // `{"*": true}`, or an empty map, means "Pi's defaults" - the same as passing no flag at all.
+    return [];
+}
+/**
+ * Whether the map denies everything, which is `{"*": false}` with nothing switched back on. Split out
+ * of `toolFlags` because the picker needs to say "no tools" rather than render an empty allowlist.
+ */
+export function deniesAllTools(tools) {
+    if (!isFrontmatter(tools))
+        return false;
+    return tools["*"] === false && !Object.entries(tools).some(([key, on]) => key !== "*" && on === true);
+}
+/** The tools an allowlist names, for display. Empty when the agent adds no allowlist of its own. */
+export function allowedToolNames(tools) {
+    if (!isFrontmatter(tools) || tools["*"] !== false)
+        return [];
+    return Object.entries(tools).filter(([key, on]) => key !== "*" && on === true).map(([name]) => name);
+}
+/** `provider/modelId`, split into the two halves Pi's `set_model` and `--provider/--model` both need. */
+export function parseAgentModel(model) {
+    if (typeof model !== "string")
+        return undefined;
+    // The slash is required: Pi rejects a model id with no provider (rpc-types.ts:33 needs both), and a
+    // bare string here would otherwise be stored as a provider with an empty modelId.
+    const slash = model.indexOf("/");
+    if (slash <= 0 || slash === model.length - 1)
+        return undefined;
+    return { provider: model.slice(0, slash), modelId: model.slice(slash + 1) };
+}
+/**
+ * Reads every `*.md` in `directory` as an agent definition. The file's base name is the agent id,
+ * matching OpenCode, so `agents/triage.md` is the agent `triage` and renaming the file renames it.
+ *
+ * A file that fails to parse is COLLECTED as a problem instead of throwing: one typo in one agent must
+ * not take down the picker and hide every other agent with it.
+ *
+ * `mode` picks WHICH half of one directory of definitions comes back, and defaults to `primary`. Both
+ * halves live in the same `agents/*.md` files - a sub-agent is the same format with `mode: subagent` -
+ * so the split is a filter on the parsed field, never a second directory or a second parser. A caller
+ * with no argument gets exactly what it always got.
+ */
+export async function readAgents(directory, options = {}) {
+    const mode = options.mode ?? "primary";
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { agents: [], problems: [] };
+        throw error;
+    }
+    const agents = [];
+    const problems = [];
+    for (const file of entries.filter((name) => name.toLowerCase().endsWith(".md")).sort()) {
+        const source = await readFile(join(directory, file), "utf8");
+        const parsed = parseDefinition(file, source);
+        if ("message" in parsed)
+            problems.push({ file, message: parsed.message });
+        else
+            agents.push(parsed);
+    }
+    // The half that was NOT asked for is filtered out here rather than marked in the UI: sub-agents are
+    // invoked BY an agent and never chosen by a human, so listing one in the picker would promise a role
+    // the runtime cannot honour. The remainder is alphabetical by id, so either roster reads as a list
+    // rather than as a directory listing.
+    return { agents: agents.filter((agent) => agent.mode === mode).sort((a, b) => a.id.localeCompare(b.id)), problems };
+}
+/** Only `#rgb` and `#rrggbb`. A `color:` frontmatter value is rendered as a CSS background, so it has to
+ *  be a colour and nothing else - accepting an arbitrary string would put author-controlled text into a
+ *  style declaration. Anything else is dropped rather than sanitised into something misleading. */
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const color = (value) => (typeof value === "string" && HEX_COLOR.test(value.trim()) ? value.trim() : undefined);
+/**
+ * The `task:` decision vocabulary, spelled the way OpenCode spells it in `agent.ts:165-167`, where the
+ * `plan` agent declares `task: { general: "deny" }`. `true`/`false` are accepted as the boolean
+ * equivalents so a definition can be written either way.
+ */
+const TASK_DECISIONS = new Set(["allow", "deny", true, false]);
+/**
+ * Reports a malformed `task:` value, or undefined when the map is usable.
+ *
+ * The same reasoning as `validateToolNames`, applied to the field one step along: `task:` is read by
+ * whatever implements dispatch, and a value outside this set cannot be acted on. `deny` is the safe
+ * direction, so the check exists to catch a typo (`allew`, `yes`) that would otherwise read as a
+ * misspelled permission and quietly mean nothing.
+ */
+function validateTaskPolicy(taskPolicy) {
+    if (!isFrontmatter(taskPolicy))
+        return undefined;
+    const bad = Object.entries(taskPolicy).filter(([, decision]) => !TASK_DECISIONS.has(decision));
+    if (!bad.length)
+        return undefined;
+    return `task 的值只能是 allow 或 deny，收到 ${bad.map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(", ")}`;
+}
+/** Parses one definition file, or returns the reason it is not a usable agent. */
+export function parseDefinition(file, source) {
+    const split = splitDefinition(source);
+    if (!split)
+        return { file, message: "缺少 YAML frontmatter（文件必须以 --- 开头）" };
+    const { frontmatter, body } = split;
+    const id = file.replace(/\.md$/i, "");
+    const mode = typeof frontmatter.mode === "string" ? frontmatter.mode.trim() : "primary";
+    if (mode !== "primary" && mode !== "subagent")
+        return { file, message: `mode 只能是 primary 或 subagent，收到 ${JSON.stringify(mode)}` };
+    const prompt = body.trim();
+    if (!prompt)
+        return { file, message: "正文为空：正文就是该 agent 的 system prompt" };
+    const tools = frontmatter.tools;
+    if (tools !== undefined && !isFrontmatter(tools))
+        return { file, message: "tools 必须是一个映射，例如 tools:\n  \"*\": false\n  read: true" };
+    const unknownTool = validateToolNames(tools);
+    if (unknownTool)
+        return { file, message: unknownTool };
+    const taskPolicy = frontmatter.task;
+    if (taskPolicy !== undefined && !isFrontmatter(taskPolicy))
+        return { file, message: "task 必须是一个映射，例如 task:\n  \"*\": allow\n  scout: deny" };
+    const badTaskDecision = validateTaskPolicy(taskPolicy);
+    if (badTaskDecision)
+        return { file, message: badTaskDecision };
+    const model = parseAgentModel(frontmatter.model);
+    if (frontmatter.model !== undefined && !model)
+        return { file, message: `model 必须是 provider/modelId 形式，收到 ${JSON.stringify(frontmatter.model)}` };
+    const promptMode = frontmatter.promptMode === undefined ? "append" : frontmatter.promptMode;
+    if (promptMode !== "append" && promptMode !== "replace")
+        return { file, message: `promptMode 只能是 append 或 replace，收到 ${JSON.stringify(promptMode)}` };
+    return {
+        id,
+        name: typeof frontmatter.name === "string" && frontmatter.name.trim() ? frontmatter.name.trim() : id,
+        mode,
+        description: typeof frontmatter.description === "string" ? frontmatter.description.trim() : "",
+        color: color(frontmatter.color),
+        hidden: frontmatter.hidden === true,
+        model,
+        thinkingLevel: typeof frontmatter.thinking === "string" && frontmatter.thinking.trim() ? frontmatter.thinking.trim() : undefined,
+        promptMode,
+        toolFlags: toolFlags(tools),
+        /** Which subagents this agent may dispatch, from the frontmatter `task:` map. Absent means no
+         *  policy is expressed, NOT "allow everything" - the consuming dispatch code decides that, and
+         *  this file deliberately does not implement the `task` tool itself. */
+        taskPolicy,
+        /** What the picker shows under the agent name. Empty means "Pi's own default tool set". */
+        toolNames: deniesAllTools(tools) ? [] : allowedToolNames(tools),
+        tools,
+        prompt,
+    };
+}
+/**
+ * Writes an agent's prompt body to `path` and returns that path, so it can be handed to Pi as
+ * `--append-system-prompt <file>` / `--system-prompt <file>`.
+ *
+ * A FILE, never the prompt text on the command line, and that is not a style choice. Pi resolves an
+ * existing path to its contents and anything else to literal text (resource-loader.ts:167-182), and
+ * Super Pi spawns Pi through `shell: true` on Windows because Pi is installed as a .cmd shim - so
+ * prompt text on argv would travel through cmd.exe, where a quote or an ampersand in an agent's
+ * instructions is a metacharacter. Writing the file also means the exact text Pi was given is a
+ * file on disk that can be read back as evidence.
+ */
+export async function writeAgentPrompt(promptDir, agent) {
+    const path = join(promptDir, `${agent.id}.txt`);
+    // The directory is created here rather than assumed. `dataDir` exists at startup, but `agent-prompts`
+    // lives one level below it and nothing else creates it - and a missing directory would fail the very
+    // first turn of the very first conversation that selected an agent.
+    await mkdir(promptDir, { recursive: true });
+    await writeFile(path, agent.prompt, "utf8");
+    return path;
+}
+/**
+ * The spawn argv an agent adds, in the order Pi must receive it. Exported so the translation can be
+ * asserted without spawning anything, and so a probe can report exactly what was asked for.
+ *
+ * `options` are the caller's constraints on top of the definition's own `tools:` map - the two that
+ * exist are described on `ToolFlagOptions`. They are applied here rather than baked into
+ * `AgentDefinition.toolFlags` because they belong to the CALL: `PiRpcRuntime` adds `task` to the primary
+ * agent it is about to spawn, and the supervisor strips the parent's denies from the child it is about
+ * to spawn, and neither fact is a property of the definition file on disk.
+ */
+export async function agentSpawnArgs(promptDir, agent, options = {}) {
+    if (!agent)
+        return [];
+    const args = [];
+    // Tools before the prompt: both are startup-time flags, and `--tools` also decides which tools the
+    // system prompt describes, so it has to be in effect before Pi builds the prompt at all.
+    args.push(...toolFlags(agent.tools, options));
+    const promptPath = await writeAgentPrompt(promptDir, agent);
+    // `append` keeps Pi's own coding-agent baseline (tool guidance, environment facts) and adds the
+    // role on top, which is what Pi's flag is for. `replace` is OpenCode's semantics - the agent's
+    // words are the whole system prompt - and is opt-in per agent because it strips that baseline.
+    args.push(agent.promptMode === "replace" ? "--system-prompt" : "--append-system-prompt", promptPath);
+    return args;
+}

package/dist/server/application/catalog-service.d.ts

@@ -0,0 +1,44 @@
+import type { AgentRuntime } from "../runtime.js";
+import type { AgentCatalog, ModelCatalog, ModelSelection } from "../types.js";
+import type { EventBroadcaster } from "../server-context.js";
+/**
+ * Service managing model catalogs and agent definitions (primary and subagents).
+ */
+export declare class CatalogService {
+    private readonly runtime;
+    private readonly broadcaster;
+    private readonly agentsDir;
+    constructor(runtime: AgentRuntime, broadcaster: EventBroadcaster, agentsDir: string);
+    /**
+     * Fetches the model catalog from runtime, optionally tailored to a selected model.
+     */
+    getCatalog(selection?: ModelSelection): Promise<ModelCatalog>;
+    /**
+     * Broadcasts the model catalog to connected clients.
+     */
+    broadcastCatalog(selection?: ModelSelection): Promise<void>;
+    /**
+     * Reads one catalog filtered by mode at source.
+     */
+    readAgentCatalog(mode: "primary" | "subagent"): Promise<AgentCatalog>;
+    /**
+     * Reads primary agent definitions from disk.
+     */
+    agentCatalog(): Promise<AgentCatalog>;
+    /**
+     * Broadcasts primary agents to connected clients.
+     */
+    broadcastAgents(): Promise<void>;
+    /**
+     * Reads subagent definitions from disk.
+     */
+    subagentCatalog(): Promise<AgentCatalog>;
+    /**
+     * Broadcasts subagents to connected clients.
+     */
+    broadcastSubagents(): Promise<void>;
+    /**
+     * Helper formatting an error when a requested model/thinking level is not offered by Pi.
+     */
+    notOffered(what: string, catalog: ModelCatalog): Error;
+}

package/dist/server/application/catalog-service.js

@@ -0,0 +1,94 @@
+import { readAgents } from "../agents.js";
+function summarize(agent) {
+    const { prompt, toolFlags, ...summary } = agent;
+    const toolSummary = toolFlags.includes("--no-tools")
+        ? "禁用全部工具"
+        : agent.toolNames.length
+            ? `工具：${agent.toolNames.join("、")}`
+            : toolFlags.includes("--exclude-tools")
+                ? `Pi 默认工具，去掉 ${toolFlags[toolFlags.indexOf("--exclude-tools") + 1]?.split(",").join("、") ?? ""}`
+                : "Pi 默认工具";
+    return { ...summary, toolSummary };
+}
+/**
+ * Service managing model catalogs and agent definitions (primary and subagents).
+ */
+export class CatalogService {
+    runtime;
+    broadcaster;
+    agentsDir;
+    constructor(runtime, broadcaster, agentsDir) {
+        this.runtime = runtime;
+        this.broadcaster = broadcaster;
+        this.agentsDir = agentsDir;
+    }
+    /**
+     * Fetches the model catalog from runtime, optionally tailored to a selected model.
+     */
+    async getCatalog(selection) {
+        return this.runtime.catalog(selection);
+    }
+    /**
+     * Broadcasts the model catalog to connected clients.
+     */
+    async broadcastCatalog(selection) {
+        const catalog = await this.getCatalog(selection);
+        this.broadcaster.broadcast({ type: "model.catalog", catalog });
+    }
+    /**
+     * Reads one catalog filtered by mode at source.
+     */
+    async readAgentCatalog(mode) {
+        try {
+            const scan = await readAgents(this.agentsDir, { mode });
+            for (const problem of scan.problems) {
+                console.warn(`Super Pi: ${this.agentsDir}/${problem.file} is not a usable agent - ${problem.message}`);
+            }
+            const agents = scan.agents.filter((agent) => !agent.hidden).map(summarize);
+            if (!agents.length) {
+                console.warn(`Super Pi: no ${mode} agents found in ${this.agentsDir} (${scan.problems.length} file(s) rejected).`);
+            }
+            return { source: "directory", agents, problems: scan.problems, directory: this.agentsDir, fetchedAt: new Date().toISOString() };
+        }
+        catch (error) {
+            return {
+                source: "unavailable",
+                agents: [],
+                problems: [],
+                directory: this.agentsDir,
+                fetchedAt: new Date().toISOString(),
+                error: error instanceof Error ? error.message : "unknown error",
+            };
+        }
+    }
+    /**
+     * Reads primary agent definitions from disk.
+     */
+    async agentCatalog() {
+        return this.readAgentCatalog("primary");
+    }
+    /**
+     * Broadcasts primary agents to connected clients.
+     */
+    async broadcastAgents() {
+        this.broadcaster.broadcast({ type: "agent.catalog", catalog: await this.agentCatalog() });
+    }
+    /**
+     * Reads subagent definitions from disk.
+     */
+    async subagentCatalog() {
+        return this.readAgentCatalog("subagent");
+    }
+    /**
+     * Broadcasts subagents to connected clients.
+     */
+    async broadcastSubagents() {
+        this.broadcaster.broadcast({ type: "subagent.catalog", catalog: await this.subagentCatalog() });
+    }
+    /**
+     * Helper formatting an error when a requested model/thinking level is not offered by Pi.
+     */
+    notOffered(what, catalog) {
+        return new Error(`Pi 当前不提供${what}（列表读取于 ${catalog.fetchedAt}${catalog.error ? `，读取有误：${catalog.error}` : ""}）`);
+    }
+}