larkin 0.4.19 → 0.4.21

package/dist/runtime/pi-subagents.bundle.js

@@ -984,7 +984,7 @@ var init_conversation_viewer = __esm(() => {
 });
 
 // node_modules/@tintinweb/pi-subagents/src/index.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync7, unlinkSync as unlinkSync2 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync7, unlinkSync as unlinkSync2 } from "fs";
 import { join as join10 } from "path";
 import { defineTool, getAgentDir as getAgentDir7, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import { Container, Key as Key2, matchesKey as matchesKey4, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
@@ -3548,9 +3548,10 @@ import { isAbsolute as isAbsolute2 } from "path";
 // node_modules/@tintinweb/pi-subagents/src/agent-runner.ts
 init_agent_types();
 init_default_agents();
-import { readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
 import { homedir as homedir3 } from "os";
 import { basename, dirname, isAbsolute, join as join3, resolve } from "path";
+import { fileURLToPath } from "url";
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -3845,6 +3846,29 @@ var SUBAGENT_TOOL_NAMES = {
   GET_RESULT: "get_subagent_result",
   STEER: "steer_subagent"
 };
+function supervisedSiblingPath() {
+  const fromEnv = process.env.LARKIN_PI_SUPERVISED_BUNDLE;
+  if (typeof fromEnv === "string" && fromEnv.length > 0)
+    return fromEnv;
+  return join3(dirname(fileURLToPath(import.meta.url)), "pi-supervised-command.bundle.js");
+}
+function resolveTrustedSupervisedBundle(candidate) {
+  if (candidate === undefined)
+    return;
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    throw new Error("supervised command bundle is missing");
+  }
+  const sibling = supervisedSiblingPath();
+  for (const file of [sibling, candidate]) {
+    if (!existsSync3(file) || lstatSync2(file).isSymbolicLink() || !lstatSync2(file).isFile()) {
+      throw new Error("supervised command bundle is missing");
+    }
+  }
+  if (realpathSync(candidate) !== realpathSync(sibling)) {
+    throw new Error("supervised command bundle is missing");
+  }
+  return realpathSync(sibling);
+}
 var EXCLUDED_TOOL_NAMES = Object.values(SUBAGENT_TOOL_NAMES);
 function extensionCanonicalName(extPath) {
   const base = basename(extPath);
@@ -4120,7 +4144,11 @@ async function runAgent(ctx, type, prompt, options) {
   const excludeNames = new Set((excludeExtensions ?? []).map((n) => n.toLowerCase()));
   const hasExcludes = excludeNames.size > 0;
   const loadAll = extensions === true || extensionsSpec?.wildcard === true;
-  const additionalExtensionPaths = extensionsSpec?.paths.length ? extensionsSpec.paths : undefined;
+  const supervisedPath = resolveTrustedSupervisedBundle(options.allowSupervisedCommands);
+  const additionalExtensionPaths = [
+    ...extensionsSpec?.paths ?? [],
+    ...supervisedPath ? [supervisedPath] : []
+  ];
   let discoveredNames;
   const extensionsOverride = noExtensions || loadAll && !hasExcludes ? undefined : (base) => {
     discoveredNames = new Set(base.extensions.flatMap((e) => extensionCanonicalNames(e.path)));
@@ -4138,7 +4166,7 @@ async function runAgent(ctx, type, prompt, options) {
     cwd: configCwd,
     agentDir,
     noExtensions,
-    additionalExtensionPaths,
+    additionalExtensionPaths: additionalExtensionPaths.length ? additionalExtensionPaths : undefined,
     extensionsOverride,
     noSkills,
     noPromptTemplates: true,
@@ -4395,7 +4423,7 @@ ${toolCalls.join(`
 // node_modules/@tintinweb/pi-subagents/src/worktree.ts
 import { execFileSync } from "child_process";
 import { randomUUID } from "crypto";
-import { existsSync as existsSync3, realpathSync } from "fs";
+import { existsSync as existsSync4, realpathSync as realpathSync2 } from "fs";
 import { tmpdir } from "os";
 import { join as join4, relative } from "path";
 function createWorktree(cwd, agentId) {
@@ -4405,7 +4433,7 @@ function createWorktree(cwd, agentId) {
     execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
     baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 }).toString().trim();
     const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, stdio: "pipe", timeout: 5000 }).toString().trim();
-    subdir = relative(realpathSync(topLevel), realpathSync(cwd));
+    subdir = relative(realpathSync2(topLevel), realpathSync2(cwd));
   } catch {
     return;
   }
@@ -4424,7 +4452,7 @@ function createWorktree(cwd, agentId) {
   }
 }
 function cleanupWorktree(cwd, worktree, agentDescription) {
-  if (!existsSync3(worktree.path)) {
+  if (!existsSync4(worktree.path)) {
     return { hasChanges: false };
   }
   try {
@@ -4530,11 +4558,14 @@ class AgentManager {
   worktreeRepos = new Set;
   queue = [];
   runningBackground = 0;
-  constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart, onCompact) {
+  supervisedKey;
+  supervisedById = new Map;
+  constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart, onCompact, supervisedKey) {
     this.onComplete = onComplete;
     this.onStart = onStart;
     this.onCompact = onCompact;
     this.maxConcurrent = maxConcurrent;
+    this.supervisedKey = supervisedKey;
     this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
     this.cleanupInterval.unref();
   }
@@ -4547,7 +4578,18 @@ class AgentManager {
   }
   spawn(pi, ctx, type, prompt, options) {
     assertValidSpawnCwd(options.cwd);
+    if (Object.prototype.hasOwnProperty.call(options, "allowSupervisedCommands")) {
+      throw new Error("allowSupervisedCommands is not a public spawn option");
+    }
+    const supervisedPath = this.supervisedKey ? options[this.supervisedKey] : undefined;
+    if (typeof supervisedPath === "string" && supervisedPath.length === 0) {
+      throw new Error("supervised command bundle is missing");
+    }
     const id = randomUUID2().slice(0, 17);
+    if (typeof supervisedPath === "string")
+      this.supervisedById.set(id, supervisedPath);
+    else
+      this.supervisedById.delete(id);
     const abortController = new AbortController;
     const record = {
       id,
@@ -4571,6 +4613,7 @@ class AgentManager {
     try {
       this.startAgent(id, record, args);
     } catch (err) {
+      this.supervisedById.delete(id);
       this.agents.delete(id);
       throw err;
     }
@@ -4613,6 +4656,7 @@ class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
+      allowSupervisedCommands: this.supervisedById.get(id),
       cwd: worktreeCwd ?? customCwd,
       configCwd: customCwd !== undefined ? ctx.cwd : undefined,
       signal: record.abortController.signal,
@@ -4642,19 +4686,23 @@ class AgentManager {
         }
         options.onSessionCreated?.(session);
       }
-    }).then(({ responseText, session, aborted, steered, failure }) => {
+    }).then(async ({ responseText, session, aborted, steered, failure }) => {
+      let nextStatus = record.status;
       if (record.status !== "stopped") {
         if (aborted) {
-          record.status = "aborted";
+          nextStatus = "aborted";
         } else if (failure) {
-          record.status = "error";
+          nextStatus = "error";
           record.error = failure;
         } else {
-          record.status = steered ? "steered" : "completed";
+          nextStatus = steered ? "steered" : "completed";
         }
       }
       record.result = responseText;
       record.session = session;
+      await this.finalize(id, record, nextStatus === "error" ? "error" : "complete");
+      if (record.status !== "stopped")
+        record.status = nextStatus;
       record.completedAt ??= Date.now();
       detach();
       if (record.outputCleanup) {
@@ -4687,11 +4735,11 @@ Changes saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git mer
         this.drainQueue();
       }
       return responseText;
-    }).catch((err) => {
-      if (record.status !== "stopped") {
-        record.status = "error";
-      }
+    }).catch(async (err) => {
       record.error = err instanceof Error ? err.message : String(err);
+      await this.finalize(id, record, "error");
+      if (record.status !== "stopped")
+        record.status = "error";
       record.completedAt ??= Date.now();
       detach();
       if (record.outputCleanup) {
@@ -4813,16 +4861,38 @@ Changes saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git mer
       this.queue = this.queue.filter((q) => q.id !== id);
       record.status = "stopped";
       record.completedAt = Date.now();
+      this.supervisedById.delete(id);
       return true;
     }
-    if (record.status !== "running")
+    if (record.status !== "running") {
+      this.supervisedById.delete(id);
       return false;
+    }
     record.abortController?.abort();
-    record.status = "stopped";
-    record.completedAt = Date.now();
+    const done = this.finalize(id, record, "abort").then(() => {
+      record.status = "stopped";
+      record.completedAt ??= Date.now();
+    });
+    this.reaps.set(id, done);
     return true;
   }
+  reaps = new Map;
+  finalize(id, record, reason) {
+    const existing = this.reaps.get(id);
+    if (existing)
+      return existing;
+    const work = (async () => {
+      const session = record.session;
+      const runner = session?._extensionRunner;
+      if (runner?.emit)
+        await runner.emit({ type: "session_shutdown", reason });
+      this.supervisedById.delete(id);
+    })();
+    this.reaps.set(id, work);
+    return work;
+  }
   removeRecord(id, record) {
+    this.supervisedById.delete(id);
     record.session?.dispose?.();
     record.session = undefined;
     this.agents.delete(id);
@@ -4849,25 +4919,14 @@ Changes saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git mer
   hasRunning() {
     return [...this.agents.values()].some((r) => r.status === "running" || r.status === "queued");
   }
-  abortAll() {
+  async abortAll() {
     let count = 0;
-    for (const queued of this.queue) {
-      const record = this.agents.get(queued.id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
+    const ids = [...this.agents.keys()];
+    for (const id of ids) {
+      if (this.abort(id))
         count++;
-      }
-    }
-    this.queue = [];
-    for (const record of this.agents.values()) {
-      if (record.status === "running") {
-        record.abortController?.abort();
-        record.status = "stopped";
-        record.completedAt = Date.now();
-        count++;
-      }
     }
+    await Promise.all([...this.reaps.values()]);
     return count;
   }
   async waitForAll() {
@@ -4879,13 +4938,17 @@ Changes saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git mer
       await Promise.allSettled(pending);
     }
   }
-  dispose() {
+  async dispose() {
     clearInterval(this.cleanupInterval);
+    await this.abortAll();
     this.queue = [];
-    for (const record of this.agents.values()) {
-      record.session?.dispose();
+    for (const [id, record] of this.agents) {
+      this.supervisedById.delete(id);
+      const session = record.session;
+      session?.dispose?.();
     }
     this.agents.clear();
+    this.supervisedById.clear();
     try {
       pruneWorktrees(process.cwd());
     } catch {}
@@ -5006,7 +5069,7 @@ function registerRpcHandlers(deps) {
 
 // node_modules/@tintinweb/pi-subagents/src/custom-agents.ts
 init_agent_types();
-import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
 import { basename as basename2, join as join5 } from "path";
 import { getAgentDir as getAgentDir4, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 function loadCustomAgents(cwd) {
@@ -5020,7 +5083,7 @@ function loadCustomAgents(cwd) {
   return agents2;
 }
 function loadFromDir(dir, agents2, source) {
-  if (!existsSync4(dir))
+  if (!existsSync5(dir))
     return;
   let files;
   try {
@@ -5115,7 +5178,7 @@ function inheritField(val) {
 }
 
 // node_modules/@tintinweb/pi-subagents/src/enabled-models.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 import { join as join6 } from "path";
 import { getAgentDir as getAgentDir5 } from "@earendil-works/pi-coding-agent";
 function settingsPaths(cwd) {
@@ -5125,7 +5188,7 @@ function settingsPaths(cwd) {
   ];
 }
 function readField(path) {
-  if (!existsSync5(path))
+  if (!existsSync6(path))
     return;
   try {
     const raw = JSON.parse(readFileSync4(path, "utf-8"));
@@ -6456,7 +6519,7 @@ class SubagentScheduler {
 }
 
 // node_modules/@tintinweb/pi-subagents/src/schedule-store.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync5, renameSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync5, renameSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname2, join as join8 } from "path";
 var LOCK_RETRY_MS = 50;
 var LOCK_MAX_RETRIES = 100;
@@ -6513,7 +6576,7 @@ class ScheduleStore {
     mkdirSync3(dirname2(this.filePath), { recursive: true });
   }
   load() {
-    if (!existsSync6(this.filePath))
+    if (!existsSync7(this.filePath))
       return;
     try {
       const data = JSON.parse(readFileSync5(this.filePath, "utf-8"));
@@ -6576,7 +6639,7 @@ class ScheduleStore {
     return this.withLock(() => this.jobs.delete(id));
   }
   deleteFileIfEmpty() {
-    if (this.jobs.size === 0 && existsSync6(this.filePath)) {
+    if (this.jobs.size === 0 && existsSync7(this.filePath)) {
       try {
         unlinkSync(this.filePath);
       } catch {}
@@ -6585,7 +6648,7 @@ class ScheduleStore {
 }
 
 // node_modules/@tintinweb/pi-subagents/src/settings.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname3, join as join9 } from "path";
 import { getAgentDir as getAgentDir6 } from "@earendil-works/pi-coding-agent";
 var VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
@@ -6641,7 +6704,7 @@ function projectPath(cwd) {
   return join9(cwd, ".pi", "subagents.json");
 }
 function readSettingsFile(path) {
-  if (!existsSync7(path))
+  if (!existsSync8(path))
     return {};
   try {
     return sanitize(JSON.parse(readFileSync6(path, "utf-8")));
@@ -7141,6 +7204,7 @@ async function waitForSubagentResult(record, timeoutMs, signal) {
   return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
 }
 var LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
+var LARKIN_SUPERVISED_COMMAND_CAPABILITY = "larkin-pi-supervised-command-v1";
 function renderRunningAgentStatus(frame, statsText, activity, theme) {
   const container = new Container;
   container.addChild(new Text(theme.fg("accent", frame) + (statsText ? " " + statsText : ""), 0, 0));
@@ -7416,6 +7480,13 @@ Use get_subagent_result for full output.`,
       tokens
     };
   }
+  function supervisedCommandBundlePath() {
+    const sibling = supervisedSiblingPath();
+    if (!existsSync9(sibling))
+      throw new Error("supervised command bundle is missing");
+    return sibling;
+  }
+  const supervisedKey = Symbol("larkin-supervised-commands");
   const manager = new AgentManager((record) => {
     const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
     const eventData = buildEventData(record);
@@ -7465,7 +7536,7 @@ Use get_subagent_result for full output.`,
       tokensBefore: info.tokensBefore,
       compactionCount: record.compactionCount
     });
-  });
+  }, supervisedKey);
   const MANAGER_KEY = Symbol.for("pi-subagents:manager");
   const registryEntry = {
     waitForAll: () => manager.waitForAll(),
@@ -7522,12 +7593,12 @@ Use get_subagent_result for full output.`,
       delete globalThis[MANAGER_KEY];
     }
     scheduler.stop();
-    manager.abortAll();
+    await manager.abortAll();
     for (const timer of pendingNudges.values())
       clearTimeout(timer);
     pendingNudges.clear();
     fleet.dispose();
-    manager.dispose();
+    await manager.dispose();
   });
   let widgetMode = "background";
   function getWidgetMode() {
@@ -7745,7 +7816,7 @@ Terse command-style prompts produce shallow, generic work.
       join10(getAgentDir7(), "agent-tool-description.md")
     ]) {
       try {
-        if (!existsSync8(path))
+        if (!existsSync9(path))
           continue;
         const text = readFileSync7(path, "utf-8").trim();
         if (text)
@@ -8041,6 +8112,7 @@ ${list}`);
             inheritContext,
             thinkingLevel: thinking,
             isBackground: true,
+            ...params.run_in_background === true ? { [supervisedKey]: supervisedCommandBundlePath() } : {},
             isolation,
             invocation: agentInvocation,
             ...bgCallbacks
@@ -8301,13 +8373,13 @@ ${conversation}`;
   const personalAgentsDir = () => join10(getAgentDir7(), "agents");
   function findAgentFile(name) {
     const projectPath2 = join10(projectAgentsDir(), `${name}.md`);
-    if (existsSync8(projectPath2))
+    if (existsSync9(projectPath2))
       return { path: projectPath2, location: "project" };
     const workspacePath = join10(workspaceAgentsDir(), `${name}.md`);
-    if (existsSync8(workspacePath))
+    if (existsSync9(workspacePath))
       return { path: workspacePath, location: "workspace" };
     const personalPath = join10(personalAgentsDir(), `${name}.md`);
-    if (existsSync8(personalPath))
+    if (existsSync9(personalPath))
       return { path: personalPath, location: "personal" };
     return;
   }
@@ -8538,7 +8610,7 @@ ${conversation}`;
     const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
     mkdirSync5(targetDir, { recursive: true });
     const targetPath = join10(targetDir, `${name}.md`);
-    if (existsSync8(targetPath)) {
+    if (existsSync9(targetPath)) {
       const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
       if (!overwrite)
         return;
@@ -8676,7 +8748,7 @@ enabled: false
       return;
     mkdirSync5(targetDir, { recursive: true });
     const targetPath = join10(targetDir, `${name}.md`);
-    if (existsSync8(targetPath)) {
+    if (existsSync9(targetPath)) {
       const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
       if (!overwrite)
         return;
@@ -8730,7 +8802,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
       return;
     }
     reloadCustomAgents();
-    if (existsSync8(targetPath)) {
+    if (existsSync9(targetPath)) {
       ctx.ui.notify(`Created ${targetPath}`, "info");
     } else {
       ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
@@ -8804,7 +8876,7 @@ ${systemPrompt}
 `;
     mkdirSync5(targetDir, { recursive: true });
     const targetPath = join10(targetDir, `${name}.md`);
-    if (existsSync8(targetPath)) {
+    if (existsSync9(targetPath)) {
       const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
       if (!overwrite)
         return;
@@ -9033,5 +9105,6 @@ export {
   waitForSubagentResult,
   renderRunningAgentStatus,
   src_default as default,
+  LARKIN_SUPERVISED_COMMAND_CAPABILITY,
   LARKIN_BOUNDED_WAIT_CAPABILITY
 };

package/dist/runtime/pi-supervised-command-extension.mjs

@@ -0,0 +1,72 @@
+import { Type } from "typebox";
+import { cancelSupervisedCommand, LARKIN_SUPERVISED_COMMAND_CAPABILITY, reapSupervisedCommands, resolveSupervisedCwd, startSupervisedCommand, supervisedWaitSeconds, waitSupervisedCommand, } from "./pi-supervised-command.mjs";
+void LARKIN_SUPERVISED_COMMAND_CAPABILITY;
+function ownerOf(ctx) {
+    const owner = ctx?.sessionManager;
+    if (!owner)
+        throw new Error("supervised commands require a session");
+    return owner;
+}
+export default function (pi) {
+    const waitCap = supervisedWaitSeconds();
+    let waitUsedThisTurn = false;
+    const resetWaitTurn = () => { waitUsedThisTurn = false; };
+    pi.on("turn_end", resetWaitTurn);
+    const reapOwner = async (_event, ctx) => {
+        const owner = ctx?.sessionManager;
+        if (owner)
+            await reapSupervisedCommands(owner);
+    };
+    pi.on("agent_end", reapOwner);
+    pi.on("session_shutdown", reapOwner);
+    pi.registerTool({
+        name: "supervised_start",
+        label: "supervised_start",
+        description: "Start one supervised process with executable+args (shell:false). Background-agent only. Returns a handle; use supervised_wait in <=60s slices. Do not use bash for work that must outlive 60s.",
+        parameters: Type.Object({
+            executable: Type.String({ description: "Executable path or name. No shell." }),
+            args: Type.Array(Type.String(), { description: "Argument vector. No shell metacharacters are interpreted." }),
+            cwd: Type.Optional(Type.String({ description: "Optional cwd inside the child session root. Symlinks and path escape are rejected." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const session = ctx;
+            const root = typeof session.cwd === "string" && session.cwd.length > 0 ? session.cwd : process.cwd();
+            const started = startSupervisedCommand({
+                owner: ownerOf(session),
+                executable: params.executable,
+                args: params.args ?? [],
+                cwd: resolveSupervisedCwd(root, params.cwd),
+            });
+            return { content: [{ type: "text", text: JSON.stringify(started) }], details: started };
+        },
+    });
+    pi.registerTool({
+        name: "supervised_wait",
+        label: "supervised_wait",
+        description: `Wait on a supervised handle for at most ${waitCap}s. Timeout returns status=running without killing the process. At most one wait per assistant turn so queued Steer is consumed before the next wait.`,
+        parameters: Type.Object({
+            handle: Type.String({ description: "Handle from supervised_start" }),
+            timeout: Type.Optional(Type.Number({ description: `Wait seconds, max ${waitCap}`, maximum: waitCap, minimum: 1 })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (waitUsedThisTurn) {
+                throw new Error("supervised_wait is limited to once per turn; return to the model so queued Steer can run first");
+            }
+            waitUsedThisTurn = true;
+            const result = await waitSupervisedCommand(ownerOf(ctx), params.handle, params.timeout);
+            return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+        },
+    });
+    pi.registerTool({
+        name: "supervised_cancel",
+        label: "supervised_cancel",
+        description: "Cancel a supervised handle and reap its process tree.",
+        parameters: Type.Object({
+            handle: Type.String({ description: "Handle from supervised_start" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const result = await cancelSupervisedCommand(ownerOf(ctx), params.handle);
+            return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+        },
+    });
+}