@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/tool-calls.js

@@ -0,0 +1,141 @@
+/**
+ * Turning one Pi tool call into something a human reads, and nothing more.
+ *
+ * WHY THIS IS ITS OWN MODULE. Two drain loops need exactly this derivation - the sub-agent supervisor
+ * (`subagents.ts`) and the PRIMARY agent's runtime (`runtime.ts`) - and `subagents.ts` already imports
+ * `runtime.ts` for `RpcChannel`, so the reverse import would be a cycle. One definition of "what does
+ * this call show" therefore has to live below both of them, or the two surfaces would drift: a `read`
+ * labelled by its path on a card and by its working directory on a call block is worse than either.
+ *
+ * The rule the whole module exists to enforce: DERIVED AND BOUNDED, NEVER COPIED. What Pi sends in
+ * `args` is an arbitrary object that may hold a file's contents, a multi-kilobyte patch or an entire
+ * shell script. What leaves here is short strings with a hard character cap, or a bare type word.
+ */
+/**
+ * The longest label one tool call may contribute. See `SubagentToolCall.detail` and `ToolCallBlock.detail`
+ * for why the argument is summarised rather than carried: the cap is what makes the bound structural
+ * instead of aspirational, because nothing downstream can grow past it.
+ */
+export const TOOL_DETAIL_CAP = 120;
+/**
+ * How many parameters one call block may list.
+ *
+ * A bound on the COUNT as well as on each value, for the same reason `TOOL_DETAIL_CAP` exists: without
+ * it, a tool that Pi sends a dozen arguments to would put twelve rows - and twelve times the cap - into a
+ * field that is rewritten on every text delta of the message it belongs to. Six covers every call shape
+ * this project has seen (`read`'s path/offset/limit, `bash`'s command/description/timeout) and truncating
+ * past it is announced by the caller through the row count rather than silently.
+ */
+export const TOOL_ARG_CAP = 6;
+/** Argument fields that name a FILE, in the order the tools that read files tend to spell them. */
+const PATH_KEYS = ["path", "file_path", "filePath", "target_file", "filename", "file"];
+/** Argument fields that name a SEARCH, which is the thing a human wants to see on a `grep` row. */
+const PATTERN_KEYS = ["pattern", "query", "regex", "search", "glob"];
+/** Argument fields that name a COMMAND LINE. */
+const COMMAND_KEYS = ["command", "cmd", "script"];
+/**
+ * Which argument field names what a given tool was aimed at.
+ *
+ * A per-tool table rather than one generic scan, because the generic answer is wrong in a way a person
+ * would notice: scanning `path` before `command` would label a `bash` row with a working directory, and
+ * scanning `pattern` before `path` would label a `read` row with nothing at all. Unknown tools fall
+ * back to the union, which is imprecise by construction - and imprecise is acceptable here, because a
+ * missing label costs the reader one line and a WRONG one costs them trust in every other label.
+ */
+const TARGET_KEYS = {
+    read: PATH_KEYS, write: PATH_KEYS, edit: PATH_KEYS, multiedit: PATH_KEYS, notebookread: PATH_KEYS, notebookedit: PATH_KEYS,
+    glob: PATTERN_KEYS, grep: PATTERN_KEYS, search: PATTERN_KEYS,
+    bash: COMMAND_KEYS, shell: COMMAND_KEYS, run: COMMAND_KEYS,
+};
+const FALLBACK_KEYS = [...COMMAND_KEYS, ...PATH_KEYS, ...PATTERN_KEYS];
+/** One line, whitespace collapsed, hard-capped. The ONLY way a value becomes text in this module. */
+const oneLine = (value) => {
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (!collapsed)
+        return "";
+    return collapsed.length > TOOL_DETAIL_CAP ? `${collapsed.slice(0, TOOL_DETAIL_CAP - 1)}…` : collapsed;
+};
+/**
+ * The one line that tells a reader what a tool call was FOR: the file it opened, the pattern it searched
+ * for, the command it ran.
+ *
+ * Returns `undefined` rather than a placeholder when nothing is recognised, so a row omits the column
+ * instead of rendering a column of emptiness.
+ *
+ * Exported so the mapping can be asserted without spawning a child, which is the only way a table this
+ * shape can be regression-tested at all.
+ */
+export function describeToolCall(name, args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return undefined;
+    const record = args;
+    for (const key of TARGET_KEYS[name.trim().toLowerCase()] ?? FALLBACK_KEYS) {
+        const value = record[key];
+        if (typeof value !== "string")
+            continue;
+        const line = oneLine(value);
+        if (line)
+            return line;
+    }
+    return undefined;
+}
+/**
+ * How one non-string argument value is NAMED without being read.
+ *
+ * THE MOST IMPORTANT LINE IN THIS FILE. An `edit` tool's arguments routinely carry the replacement text
+ * for a whole file, and a `bash` call's arguments can carry anything the model wrote. Rendering such a
+ * value - even truncated, even `JSON.stringify`d - would put file contents into a field that is
+ * persisted in `state.json` and broadcast to every browser, which is precisely the line
+ * `SubagentToolCall.detail` is documented as drawing. So a non-primitive contributes its KIND and
+ * nothing else: a reader learns that a patch was applied or an array was passed, and cannot learn what
+ * was in it.
+ */
+const describeShape = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `（数组 ${value.length} 项）`;
+    switch (typeof value) {
+        case "number": return Number.isFinite(value) ? String(value) : undefined;
+        case "boolean": return String(value);
+        case "object": return "（对象）";
+        default: return undefined;
+    }
+};
+/**
+ * Every parameter of one call, as a bounded list of `key`/`value` pairs a block can show when expanded.
+ *
+ * THIS IS THE SAME LINE `describeToolCall` DRAWS, APPLIED PER KEY. `describeToolCall` answers "what was
+ * this aimed at" with one label; this answers "what was this given" with the whole bounded list, which is
+ * the difference between a row that says `bash` and a block that says which command, plus its timeout
+ * and description. Both are derived: a string is whitespace-collapsed and capped at `TOOL_DETAIL_CAP`, and
+ * anything that is not a string or a number or a boolean becomes a type word (see `describeShape`).
+ *
+ * Order is Pi's own key order rather than this module's table order, because once every key is listed the
+ * per-tool table has said everything it knows - and a reader scanning a list wants the order the caller
+ * wrote it in, not one this file invented.
+ *
+ * Capped at `TOOL_ARG_CAP` ENTRIES, and the cap is applied by taking the first N rather than by sampling
+ * across the object: a truncated tail is a prefix of the real argument list, so what is shown is never
+ * a selection that implies the omitted keys did not exist.
+ *
+ * Returns `undefined` when there is nothing readable at all, so a call with no usable arguments renders
+ * no parameter section rather than an empty one.
+ */
+export function describeToolCallArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return undefined;
+    const listed = [];
+    // `Object.keys` rather than `for..in`: a key this file cannot render is skipped rather than emitted
+    // with an empty value, and an inherited key is not a parameter Pi sent.
+    for (const key of Object.keys(args)) {
+        if (listed.length >= TOOL_ARG_CAP)
+            break;
+        const raw = args[key];
+        const value = typeof raw === "string" ? oneLine(raw) : describeShape(raw);
+        if (value === undefined || value === "")
+            continue;
+        listed.push({ key, value });
+    }
+    return listed.length ? listed : undefined;
+}