@evandu/super-pi 0.1.84 → 0.1.86

package/dist/server/tool-runner.js

@@ -1,23 +1,163 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { join } from "node:path";
 const MAX_LOG_BYTES = 512_000;
 const MAX_TIMEOUT_MS = 10 * 60_000;
+/** The environment build gets its OWN budget: a cold `pip install` must not eat the tool's timeout. */
+const MAX_ENV_TIMEOUT_MS = 10 * 60_000;
+const isWindows = process.platform === "win32";
 /** Runs a registered Python entrypoint without a shell. It intentionally accepts no command string. */
 export class ToolRunner {
+    dataDir;
     runs = new Map();
+    /** Optional so the existing unit tests can build a runner with no data dir; a tool that needs no venv never touches it. */
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    /**
+     * THE RESOLUTION ORDER, IN ONE PLACE, AND IT IS AN ORDER ON PURPOSE.
+     *
+     *   1. the tool's own venv - a tool's dependencies belong to that tool and to nothing else;
+     *   2. `SUPER_PI_PYTHON_COMMAND` - the user's explicit choice, already honoured before this existed;
+     *   3. the system interpreter - today's behaviour;
+     *   4. nothing usable, which is REPORTED as a sentence rather than discovered as an ENOENT.
+     *
+     * Bundling an interpreter later is a fourth rung on this chain, which is why nothing in a tool's
+     * files has to know about it.
+     */
+    resolvePython(toolId, needsVenv) {
+        if (needsVenv && this.dataDir) {
+            const envPython = this.envPython(toolId);
+            if (existsSync(envPython))
+                return { path: envPython, kind: "tool-env" };
+        }
+        const override = process.env.SUPER_PI_PYTHON_COMMAND?.trim();
+        if (override)
+            return { path: override, kind: "override" };
+        return { path: isWindows ? "python.exe" : "python3", kind: "system" };
+    }
+    /** The venv lives BESIDE the tools, not inside one: export walks the tool directory, and the mount route serves everything under it. */
+    envDir(toolId) { return join(this.dataDir ?? ".", "tool-envs", toolId); }
+    envPython(toolId) { return join(this.envDir(toolId), ".venv", isWindows ? "Scripts" : "bin", isWindows ? "python.exe" : "python"); }
+    /** MEASURE this machine's Python. One spawn; the answer is what every fingerprint is compared to. */
+    async describeLocalPython() {
+        const choice = this.resolvePython("", false);
+        const probe = await runCapture(choice.path, ["-I", "-c", "import json,platform,sys;print(json.dumps({'python':sys.version.split()[0],'platform':platform.system().lower()+'-'+platform.machine()}))"], 10_000);
+        if (!probe.ok)
+            return undefined;
+        try {
+            const parsed = JSON.parse(probe.stdout);
+            if (typeof parsed?.python !== "string")
+                return undefined;
+            return { ...choice, python: parsed.python, platform: parsed.platform };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async environmentState(tool) {
+        const environment = tool.environment;
+        const requires = environment?.requires ?? [];
+        const wants = requires.length > 0 || Boolean(environment?.requiresPython);
+        const local = await this.describeLocalPython();
+        const base = { python: local?.python, platform: local?.platform, requires };
+        if (!wants)
+            return { ...base, state: "zero-deps" };
+        if (!local)
+            return { ...base, state: "needs-python", detail: "这台机器上找不到可用的 Python 解释器。" };
+        if (environment?.requiresPython && !satisfiesRange(local.python ?? "", environment.requiresPython))
+            return { ...base, state: "needs-python", detail: `这个工具需要 Python ${environment.requiresPython}，本机是 ${local.python}。` };
+        if (requires.length > 0 && this.dataDir && !existsSync(this.envPython(tool.id)))
+            return { ...base, state: "needs-env", detail: "首次运行这个工具时会自动安装这些依赖。" };
+        const known = environment?.fingerprint;
+        if (known?.python && known.platform && (majorMinor(known.python) !== majorMinor(local.python ?? "") || known.platform !== local.platform))
+            return { ...base, state: "differs", detail: `导出方是 Python ${known.python} / ${known.platform}，本机是 ${local.python} / ${local.platform}。` };
+        return { ...base, state: "ready" };
+    }
+    /**
+     * Starts a run. It RETURNS SYNCHRONOUSLY - so bad parameters still throw at the call site, exactly
+     * as before - while the interpreter and, if the tool needs one, its virtual environment are prepared
+     * in the background. The run is already `running` at that point and the build's output lands in the
+     * run's own `logs`, which is why the tool's existing dialog shows the progress without knowing
+     * anything about environments.
+     */
     start(input) {
         validateParams(input.definition.parameters ?? {}, input.params);
-        const python = process.env.SUPER_PI_PYTHON_COMMAND?.trim() || (process.platform === "win32" ? "python.exe" : "python3");
         const id = `toolrun_${randomUUID()}`;
         const run = { id, toolId: input.toolId, status: "running", startedAt: new Date().toISOString(), logs: "" };
-        // -I ignores user Python configuration and user site packages. No shell means params never become code.
-        const child = spawn(python, ["-I", "-u", input.script], { cwd: input.cwd, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1", SUPER_PI_TOOL_ID: input.toolId } });
-        const active = { run, child, stdout: "", cancelled: false, timer: setTimeout(() => this.finish(id, "timed_out", `脚本超过 ${boundedTimeout(input.definition.timeoutMs)}ms 时限`), boundedTimeout(input.definition.timeoutMs)) };
-        active.timer.unref();
+        const timer = setTimeout(() => this.finish(id, "timed_out", `准备运行环境超过 ${MAX_ENV_TIMEOUT_MS}ms 时限`), MAX_ENV_TIMEOUT_MS);
+        timer.unref();
+        const active = { run, stdout: "", cancelled: false, timer };
         this.runs.set(id, active);
-        const log = (data) => { active.run.logs = clipped(`${active.run.logs}${data.toString("utf8")}`); };
+        void this.prepare(id, active, input);
+        return copy(run);
+    }
+    async prepare(id, active, input) {
+        try {
+            const requires = input.environment?.requires ?? [];
+            let python = this.resolvePython(input.toolId, false);
+            if (requires.length > 0) {
+                const built = await this.ensureEnvironment(input.toolId, python, requires, active);
+                if (!built.ok) {
+                    this.finish(id, "failed", built.error);
+                    return;
+                }
+                python = { path: this.envPython(input.toolId), kind: "tool-env" };
+            }
+            if (active.cancelled)
+                return;
+            if (active.timer)
+                clearTimeout(active.timer);
+            const scriptTimer = setTimeout(() => this.finish(id, "timed_out", `脚本超过 ${boundedTimeout(input.definition.timeoutMs)}ms 时限`), boundedTimeout(input.definition.timeoutMs));
+            scriptTimer.unref();
+            active.timer = scriptTimer;
+            this.launch(id, active, python, input);
+        }
+        catch (error) {
+            this.finish(id, "failed", error instanceof Error ? error.message : "tool environment could not be prepared");
+        }
+    }
+    /**
+     * THE VENV IS PYTHON'S OWN, ON PURPOSE. `python -m venv` finds its site-packages through the
+     * pyvenv.cfg next to the interpreter, which is why it survives the `-I` a tool runs under - a
+     * PYTHONPATH-based vendor directory does not (verified: `-I` implies `-E`, so PYTHONPATH is
+     * ignored, and dropping `-I` would give up the isolation that keeps a hostile PYTHON* environment
+     * from influencing a shared tool's script).
+     */
+    async ensureEnvironment(toolId, base, requires, active) {
+        if (!this.dataDir)
+            return { ok: false, error: "这个工具需要依赖，但没有可用的数据目录来存放它的虚拟环境。" };
+        const envDir = this.envDir(toolId), envPython = this.envPython(toolId);
+        const recorded = await readFile(join(envDir, "installed.json"), "utf8").then((text) => { try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        } }).catch(() => undefined);
+        if (existsSync(envPython) && Array.isArray(recorded?.requires) && recorded.requires.length === requires.length && recorded.requires.every((item, index) => item === requires[index]))
+            return { ok: true };
+        await rm(envDir, { recursive: true, force: true });
+        await mkdir(envDir, { recursive: true });
+        const requirements = join(envDir, "requirements.txt");
+        await writeFile(requirements, `${requires.join("\n")}\n`, "utf8");
+        logLine(active, `正在准备 Python 虚拟环境（${requires.join("、")}）…\n`);
+        const created = await runCapture(base.path, ["-m", "venv", join(envDir, ".venv")], MAX_ENV_TIMEOUT_MS, (text) => logLine(active, text));
+        if (!created.ok)
+            return { ok: false, error: `创建 Python 虚拟环境失败：${created.error || `解释器 ${base.path} 不可用`}` };
+        const installed = await runCapture(envPython, ["-m", "pip", "install", "--disable-pip-version-check", "--no-input", "-r", requirements], MAX_ENV_TIMEOUT_MS, (text) => logLine(active, text));
+        if (!installed.ok)
+            return { ok: false, error: `安装工具依赖失败：${installed.error || `pip 退出码 ${installed.code}`}（依赖：${requires.join("、")}）` };
+        await writeFile(join(envDir, "installed.json"), JSON.stringify({ requires, python: base.path, builtAt: new Date().toISOString() }, null, 2), "utf8");
+        return { ok: true };
+    }
+    launch(id, active, python, input) {
+        // -I ignores user Python configuration and user site packages. No shell means params never become code.
+        const child = spawn(python.path, ["-I", "-u", input.script], { cwd: input.cwd, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1", SUPER_PI_TOOL_ID: input.toolId } });
+        active.child = child;
         child.stdout.on("data", (data) => { active.stdout = clipped(`${active.stdout}${data.toString("utf8")}`); });
-        child.stderr.on("data", log);
+        child.stderr.on("data", (data) => logLine(active, data.toString("utf8")));
         child.once("error", (error) => this.finish(id, "failed", error.message));
         child.once("close", (code) => {
             if (active.run.status !== "running")
@@ -38,7 +178,6 @@ export class ToolRunner {
             }
         });
         child.stdin.end(JSON.stringify(input.params));
-        return copy(run);
     }
     get(id, toolId) { const active = this.runs.get(id); return active?.run.toolId === toolId ? copy(active.run) : undefined; }
     cancel(id, toolId) { const active = this.runs.get(id); if (!active || active.run.toolId !== toolId)
@@ -47,17 +186,78 @@ export class ToolRunner {
         this.finish(id, "cancelled");
     } return copy(active.run); }
     finish(id, status, error) { const active = this.runs.get(id); if (!active || active.run.status !== "running")
-        return; clearTimeout(active.timer); if (status !== "succeeded" && active.stdout)
+        return; if (active.timer)
+        clearTimeout(active.timer); if (status !== "succeeded" && active.stdout)
         active.run.logs = clipped(`${active.run.logs}${active.stdout}`); active.run.status = status; active.run.finishedAt = new Date().toISOString(); if (error)
-        active.run.error = error; if (!active.child.killed) {
+        active.run.error = error; if (active.child && !active.child.killed) {
         try {
             active.child.kill();
         }
         catch { }
     } }
 }
+/**
+ * Runs a Python process with NO SHELL - the same rule as a tool run, because what is being installed
+ * is code too. There is no command string anywhere on this path, only an argv.
+ */
+function runCapture(python, args, timeoutMs, onOutput) {
+    return new Promise((resolve) => {
+        let stdout = "", stderr = "", settled = false;
+        const child = spawn(python, args, { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1" } });
+        const timer = setTimeout(() => { if (settled)
+            return; settled = true; try {
+            child.kill();
+        }
+        catch { } resolve({ ok: false, code: null, stdout, error: `timed out after ${timeoutMs}ms` }); }, timeoutMs);
+        timer.unref();
+        child.stdout.on("data", (data) => { const text = data.toString("utf8"); stdout += text; onOutput?.(text); });
+        child.stderr.on("data", (data) => { const text = data.toString("utf8"); stderr += text; onOutput?.(text); });
+        child.once("error", (error) => { if (settled)
+            return; settled = true; clearTimeout(timer); resolve({ ok: false, code: null, stdout, error: error.message }); });
+        child.once("close", (code) => { if (settled)
+            return; settled = true; clearTimeout(timer); if (code === 0)
+            resolve({ ok: true, stdout, code });
+        else
+            resolve({ ok: false, code, stdout, error: stderr.split("\n").filter((line) => line.trim()).slice(-4).join("\n") }); });
+    });
+}
+/**
+ * A SMALL, DELIBERATELY SMALL PEP 440 READER: `>=`, `>`, `<=`, `<`, `==`, comma-separated. Anything it
+ * cannot parse counts as NOT satisfied, because a version check that guesses is worse than one that
+ * refuses. A tool needing something exotic declares no range at all and relies on the venv, not here.
+ */
+export function satisfiesRange(version, range) {
+    const actual = version.split(".").map((part) => Number.parseInt(part, 10));
+    if (actual.some((part) => Number.isNaN(part)))
+        return false;
+    for (const term of range.split(",")) {
+        const match = /^(>=|<=|==|>|<)?\s*(\d+(?:\.\d+)*)$/.exec(term.trim());
+        if (!match)
+            return false;
+        const comparison = compareVersions(actual, match[2].split(".").map((part) => Number.parseInt(part, 10)));
+        const operator = match[1] ?? "==";
+        if (operator === ">=" && comparison < 0)
+            return false;
+        if (operator === ">" && comparison <= 0)
+            return false;
+        if (operator === "<=" && comparison > 0)
+            return false;
+        if (operator === "<" && comparison >= 0)
+            return false;
+        if (operator === "==" && comparison !== 0)
+            return false;
+    }
+    return true;
+}
+function compareVersions(left, right) { for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index] ?? 0, b = right[index] ?? 0;
+    if (a !== b)
+        return a < b ? -1 : 1;
+} return 0; }
+function majorMinor(version) { return version.split(".").slice(0, 2).join("."); }
 function boundedTimeout(value) { return Math.max(1_000, Math.min(MAX_TIMEOUT_MS, Number.isFinite(value) ? Math.floor(value) : 60_000)); }
 function clipped(text) { return text.length > MAX_LOG_BYTES ? text.slice(-MAX_LOG_BYTES) : text; }
+function logLine(active, text) { active.run.logs = clipped(`${active.run.logs}${text}`); }
 function copy(run) { return { ...run, result: run.result ? { ...run.result } : undefined }; }
 export function validateParams(schema, params) {
     if (!params || Array.isArray(params) || typeof params !== "object")

package/dist/server/types.d.ts

@@ -105,7 +105,39 @@ export type Message = {
         id?: string;
         name: string;
     };
+    delivery?: MessageDelivery;
 };
+/**
+ * WHERE A USER MESSAGE IS IN ITS OWN DELIVERY, or `undefined` for every message that is not waiting.
+ *
+ * A user message is written into the transcript the instant it is sent, BEFORE any turn has started,
+ * and it stays in that exact position until the agent has answered it. What changes meanwhile is this
+ * field and nothing else - see `docs/QUEUE-UX.md` for why the message must never move.
+ *
+ * ABSENT means "not waiting": a message the agent is answering right now, one it already answered, one
+ * withdrawn, and every `assistant` / `tool` message. Only `role: "user"` ever carries it.
+ *
+ * - `waiting` - said, not yet handed to the agent. CANCELLED freely, EDITED freely, and REORDERED
+ *   freely. This is where essentially every waiting message lives, because a message is only given to
+ *   Pi at the moment it is about to be delivered.
+ * - `sending` - written to a live Pi child's stdin as a `steer` and not yet confirmed delivered. NOT
+ *   cancellable and NOT editable: Pi has no single-item retract (its only queue command is
+ *   `clear_queue`, which clears everything), so a UI offering either would be a promise the transport
+ *   cannot keep. It returns to `waiting` exactly when we can prove Pi never delivered it - the turn
+ *   ended - and stays here when Pi simply has not answered yet.
+ *
+ * WHY A FIELD AND NOT A SEPARATE LIST. The waiting list used to be its own array of content copies
+ * (`QueuedMessage`), and that is what made two bugs structural rather than accidental: a queued entry
+ * was not a message, so promoting one to a turn had to CREATE a message - which is why a steered
+ * message reached Pi and the model and never reached the transcript at all - and "delivered" could only
+ * be expressed by DELETING a row, so every delivery was an opportunity to lose the user's words. A
+ * message with a state has an identity to transition and nothing to delete.
+ *
+ * ORDER IS THE QUEUE. There is no `priority` flag and no second source of truth: the waiting messages
+ * are the trailing `role: "user"` messages of the array, and "put this one first" is a move within
+ * that block.
+ */
+export type MessageDelivery = "waiting" | "sending";
 /**
  * A piece of context attached to a user message that is shown as its OWN block under the bubble, rather
  * than flattened into the prompt. Today: a skill the person picked from the slash menu - the model gets
@@ -691,7 +723,6 @@ export type AppState = {
     workspaces: Workspace[];
     conversations: Conversation[];
     subagentRuns: SubagentRun[];
-    queuedMessages: QueuedMessage[];
     backgroundTasks: BackgroundTaskSummary[];
     todosByConversation?: Record<string, TodoItem[]>;
     workflows?: WorkflowRun[];
@@ -703,63 +734,21 @@ export type TodoItem = {
     status: "pending" | "in_progress" | "completed";
     priority?: "high" | "medium" | "low";
 };
-/**
- * One message the user sent WHILE THE AGENT WAS WORKING, held by Super Pi until a turn boundary can
- * carry it.
- *
- * WHY THE SERVER OWNS THIS LIST AT ALL. Pi's own queues live in the Pi process's memory
- * (`agent-session.ts:394/396`) and Super Pi kills that process unconditionally at the end of every
- * turn (`runtime.ts:539-545`), while Pi never writes a queued message to the session JSONL. A list kept
- * in Pi is therefore guaranteed to be destroyed, with no trace, on every turn boundary. So Pi is used
- * only as a delivery pipe - one steer per turn, handed over at the moment it is allowed to be
- * delivered - and the waiting list is this one.
- *
- * THE ID IS OURS AND IT IS THE POINT. Pi matches a queued message back to its queue entry by
- * `indexOf` on the message TEXT (`agent-session.ts:1123/1129`), so two queued messages with identical
- * text are indistinguishable to it and one of them is left behind in its queue forever. Every entry
- * here therefore carries a Super Pi id that Pi never sees, and cancel/steer address THAT.
- *
- * `state` is the whole lifecycle, and `sending` is the only irreversible step:
- *
- * - `queued`  - in the list, not yet given to Pi. CANCELLED freely; this is where essentially every
- *               message lives, because a message is only handed to Pi when it is about to be delivered.
- * - `sending` - written to Pi's stdin as a `steer` and not yet confirmed delivered. NOT cancellable:
- *               Pi has no single-item retract (its only queue command is `clear_queue`, which clears
- *               everything), so claiming otherwise in the UI would be a lie. It goes back to `queued`
- *               exactly when we can prove Pi never delivered it - the turn ended - and stays here when
- *               Pi simply has not answered yet.
- *
- * A delivered or cancelled message is REMOVED rather than kept with a terminal state: a queue that
- * retains sent messages needs a pruning policy and a way to read it, and a stale row in this list is
- * worse than no row.
- */
-export type QueuedMessage = {
-    /** `q_<uuid>`. Super Pi's own identity for this message, and the only thing cancel/steer name. */
-    id: string;
-    /**
-     * The conversation whose next turn will carry this. Deliberately a CONVERSATION id and never a
-     * `sub_*` run id: sub-agent children run in their own Pi processes under their own supervisor
-     * (`subagents.ts`), they have their own stop and their own lifecycle, and a queue entry keyed by one
-     * would be claimed and delivered by the wrong owner.
-     */
-    conversationId: string;
-    content: string;
-    state: "queued" | "sending";
-    /** Chosen for priority delivery. Survives a Pi turn boundary and a server restart. */
-    priority?: boolean;
-    createdAt: string;
-    images?: MessageImage[];
-    attachments?: MessageAttachments;
-};
 /**
  * What Pi reports about ITS OWN queue, forwarded to the browser as it arrives.
  *
  * `steering` and `followUp` are Pi's in-memory arrays as of this event (`agent-session.ts:204-208`).
- * They are NOT the queue the user sees: the authoritative list is `AppState.queuedMessages`, and this
- * is Pi's own view of the at most one steer that is currently in flight inside the child process. It
- * is forwarded because it is the only signal that proves a steer was really picked up, and because a
- * `followUp` array that is ever non-empty means something outside this server sent a `follow_up` -
- * worth being able to see rather than infer.
+ * They are NOT what the user sees: the authoritative list is the trailing `delivery`-bearing messages
+ * of the conversation itself (`MessageDelivery`), and this is Pi's own view of the at most one steer
+ * that is currently in flight inside the child process. It is forwarded because it is the only signal
+ * that proves a steer was really picked up, and because a `followUp` array that is ever non-empty means
+ * something outside this server sent a `follow_up` - worth being able to see rather than infer.
+ *
+ * It no longer decides anything. A delivery used to be inferred from a DROP in `steering.length` and
+ * applied by DELETING the oldest `sending` row, which is how a steered message could reach the model
+ * and never reach the transcript. Delivery is now announced directly, by the `message_start` Pi emits
+ * when it hands the text to the agent loop, and applied by moving a state on a message that was already
+ * on screen the whole time.
  */
 export type PiQueueSnapshot = {
     steering: string[];
@@ -989,6 +978,14 @@ export type ClientCommandBody =
  * one gets a turn. The browser never picks, which is what makes the guard un-bypassable - the old
  * arrangement had the browser decide by disabling itself, and a second WebSocket client (or a stale
  * tab) walked straight past it into two Pi processes writing one session.
+ *
+ * `clientId` is how the browser's copy and the server's copy become THE SAME MESSAGE instead of two
+ * that have to be matched up afterwards. The browser mints the id, renders the message with it in the
+ * same frame it pressed send, and sends it here; the store uses it as the message id when it is well
+ * formed and not already taken. So when the broadcast arrives there is nothing to reconcile - no
+ * content matching, no `knownIds` set, no window in which the same sentence exists twice. It used to
+ * be matched by `content === content.trim()`, which cannot tell two identical messages apart and made
+ * the tests assert ordinals instead of messages. Omitted means "server, mint one".
  */
  | {
     type: "message.send";
@@ -996,6 +993,7 @@ export type ClientCommandBody =
     content: string;
     images?: MessageImage[];
     attachments?: MessageAttachments;
+    clientId?: string;
 }
 /**
  * Revert the conversation to the state right AFTER one message: every message after it is removed from
@@ -1018,21 +1016,49 @@ export type ClientCommandBody =
     withdraw?: boolean;
 }
 /**
- * Drops ONE queued message, by Super Pi's id.
+ * Withdraws ONE waiting message, by its message id.
  *
- * Addressed by `queueId` rather than by text or by index for the reason `QueuedMessage.id` exists at
- * all: two queued messages can be the same string, and a cancel that matched on text would drop
- * whichever one sorted first. Refused for an entry already in `sending` - Pi holds that text now and
- * cannot be told to forget one item - and an unknown or already-removed id is a no-op rather than an
- * error, exactly as `subagent.stop` treats a run that has already settled.
+ * Addressed by `messageId` rather than by text or by index because two waiting messages can be the
+ * same string. Refused for a message already in `sending` - Pi holds that text now and cannot be told
+ * to forget one item - and an unknown or already-removed id is a no-op rather than an error, exactly
+ * as `subagent.stop` treats a run that has already settled.
  */
  | {
     type: "message.cancel";
     conversationId: string;
-    queueId: string;
+    messageId: string;
 }
 /**
- * Promotes one queued message to a `steer`: Pi takes it at the next turn boundary instead of waiting
+ * Rewrites the text of ONE waiting message that has not been given to Pi yet.
+ *
+ * The one mutation the old waiting list could not express: a row there was a content copy in an array
+ * with no way to say "the user changed their mind about these words", so changing your mind meant
+ * cancelling and retyping. Now the message itself is edited, in place, and it stays exactly where it
+ * is. Refused for `sending`, for the same reason `cancel` is.
+ */
+ | {
+    type: "message.edit";
+    conversationId: string;
+    messageId: string;
+    content: string;
+}
+/**
+ * Moves ONE waiting message to a new position among the waiting messages.
+ *
+ * This is the whole of what the old `priority` boolean meant, expressed as a position instead of a
+ * flag. `toIndex` is counted over the WAITING messages only (`0` is the next one the agent will
+ * start), so moving something to the front does not depend on how many answered messages sit above
+ * it, and moving it back is the same command rather than a separate "un-prioritise" that would be a
+ * second source of truth for one idea.
+ */
+ | {
+    type: "message.reorder";
+    conversationId: string;
+    messageId: string;
+    toIndex: number;
+}
+/**
+ * Promotes one waiting message to a `steer`: Pi takes it at the next turn boundary instead of waiting
  * for the whole task to finish.
  *
  * The timing is Pi's and cannot be finer: `agent-loop.ts:295` polls steering after `turn_end`, which
@@ -1040,17 +1066,23 @@ export type ClientCommandBody =
  * this means "after the tools currently running finish", and during a long single tool call there is
  * nothing to interrupt - Pi offers no preemption. The UI says so in words rather than implying
  * instant delivery.
+ *
+ * What this USED TO DO that it no longer does: it also set a `priority` flag, and on failure it fell
+ * back to setting that flag, so "make this the next one" and "hand this to Pi right now" were one
+ * button and one code path. They are still one button - both move the message to the front of the
+ * waiting block - but the flag is gone, so the fallback is now the same move rather than a second
+ * mechanism that had to be kept in agreement with the first.
  */
  | {
     type: "message.steer";
     conversationId: string;
-    queueId: string;
+    messageId: string;
 }
-/** Starts this saved queued message as the next turn, only after the current turn has ended. */
+/** Starts this waiting message as the next turn, only after the current turn has ended. */
  | {
     type: "message.sendQueued";
     conversationId: string;
-    queueId: string;
+    messageId: string;
 } | {
     type: "run.stop";
     conversationId: string;