larkin 0.5.4 → 0.5.5

package/dist/runtime/pi-tmux-injection.mjs

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureOwnedTree, writePrivateAtomic } from "./pi-state-dir.mjs";
+import { tmuxAvailable } from "./pi-tmux.mjs";
+const BUNDLE_NAME = "pi-tmux.bundle.js";
+export function materializeEmbeddedPiTmuxBundle(configDir) {
+    const embedded = globalThis.__LARKIN_EMBEDDED_PI_TMUX_BUNDLE__;
+    if (!embedded || !configDir)
+        return null;
+    try {
+        const dir = ensureOwnedTree(path.resolve(configDir), ["providers", "pi", "extensions"]);
+        const target = path.join(dir, BUNDLE_NAME);
+        try {
+            if (fs.lstatSync(target).isSymbolicLink())
+                throw new Error("pi-tmux bundle must not be a symlink");
+            if (fs.readFileSync(target, "utf8") === embedded)
+                return target;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        writePrivateAtomic(target, embedded);
+        return target;
+    }
+    catch (error) {
+        throw new Error("Could not materialize the Larkin tmux extension", { cause: error });
+    }
+}
+export function bundledPiTmuxExtensionPath(configDir) {
+    try {
+        const resolved = fileURLToPath(new URL(`./${BUNDLE_NAME}`, import.meta.url));
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    catch {
+        /* fall through to embedded */
+    }
+    return materializeEmbeddedPiTmuxBundle(configDir);
+}
+export function resolvePiTmuxExtensionArg(input, resolveBundle = () => bundledPiTmuxExtensionPath(input.env.LARKIN_CONFIG_DIR), available = tmuxAvailable) {
+    if (input.platform === "win32" || !available(input.env, input.platform))
+        return null;
+    const bundle = resolveBundle();
+    if (!bundle)
+        throw new Error("Larkin tmux extension bundle is missing; rebuild or reinstall Larkin");
+    return bundle;
+}

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

@@ -0,0 +1,600 @@
+// @bun
+// src/runtime/pi-tmux-extension.ts
+import crypto2 from "crypto";
+import { Type } from "typebox";
+
+// src/runtime/pi-tmux.ts
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs2 from "fs";
+import path2 from "path";
+
+// src/runtime/pi-state-dir.ts
+import fs from "fs";
+import path from "path";
+function ensureOwnedTree(root, parts = [], create = true) {
+  const resolved = path.resolve(root);
+  if (fs.existsSync(resolved)) {
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+      throw new Error(`unsafe private directory: ${resolved}`);
+  } else if (create) {
+    fs.mkdirSync(resolved, { recursive: true, mode: 448 });
+    if (fs.lstatSync(resolved).isSymbolicLink() || !fs.lstatSync(resolved).isDirectory()) {
+      throw new Error(`unsafe private directory: ${resolved}`);
+    }
+  } else {
+    throw new Error(`unsafe private directory: ${resolved}`);
+  }
+  let dir = resolved;
+  for (const part of parts) {
+    if (!part || part === "." || part === ".." || /[\\/]/.test(part))
+      throw new Error(`unsafe owned path component: ${part}`);
+    dir = path.join(dir, part);
+    try {
+      const existing = fs.lstatSync(dir);
+      if (existing.isSymbolicLink() || !existing.isDirectory())
+        throw new Error(`unsafe private directory: ${dir}`);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+      if (!create)
+        throw new Error(`unsafe private directory: ${dir}`);
+      fs.mkdirSync(dir, { mode: 448 });
+      if (fs.lstatSync(dir).isSymbolicLink() || !fs.lstatSync(dir).isDirectory())
+        throw new Error(`unsafe private directory: ${dir}`);
+    }
+    if (process.platform !== "win32")
+      fs.chmodSync(dir, 448);
+  }
+  return dir;
+}
+function mkdirPrivateExclusive(directory) {
+  fs.mkdirSync(directory, { mode: 448 });
+  const created = fs.lstatSync(directory);
+  if (created.isSymbolicLink() || !created.isDirectory())
+    throw new Error(`unsafe private directory: ${directory}`);
+  if (process.platform !== "win32")
+    fs.chmodSync(directory, 448);
+}
+function writePrivateExclusive(file, content) {
+  fs.writeFileSync(file, content, { mode: 384, flag: "wx" });
+  if (process.platform !== "win32")
+    fs.chmodSync(file, 384);
+}
+
+// src/runtime/pi-tmux.ts
+var DEFAULT_BASH_WAIT_SECONDS = 30;
+var OUTPUT_TAIL_BYTES = 32 * 1024;
+var LARKIN_TMUX_COMPLETION_TYPE = "larkin-tmux-completion";
+
+class ForeignTmuxTaskError extends Error {
+  taskId;
+  constructor(taskId) {
+    super(`tmux task ${taskId} is not owned by this Larkin instance`);
+    this.name = "ForeignTmuxTaskError";
+    this.taskId = taskId;
+  }
+}
+function tmuxAvailable(env = process.env, platform = process.platform) {
+  if (platform === "win32")
+    return false;
+  const result = spawnSync("tmux", ["-V"], { env: tmuxClientEnv(env), encoding: "utf8", timeout: 5000 });
+  const version = /tmux\s+(\d+)\.(\d+)/i.exec(`${result.stdout || ""} ${result.stderr || ""}`);
+  return result.status === 0 && version !== null && (Number(version[1]) > 3 || Number(version[1]) === 3 && Number(version[2]) >= 2);
+}
+function posixQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function sanitizeName(value, fallback) {
+  const cleaned = value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24);
+  return cleaned || fallback;
+}
+function taskRoot(stateDir, agentId, instanceId) {
+  return path2.join(stateDir, "pi-tmux", sanitizeName(agentId, "agent"), sanitizeName(instanceId, "inst"));
+}
+function taskDir(stateDir, agentId, instanceId, taskId) {
+  return path2.join(taskRoot(stateDir, agentId, instanceId), taskId);
+}
+function sessionName(agentId, instanceId, taskId) {
+  return `lkn-${sanitizeName(agentId, "agent")}-${sanitizeName(instanceId, "inst")}-${taskId}`;
+}
+function readText(file) {
+  try {
+    return fs2.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writePrivate(file, body) {
+  fs2.writeFileSync(file, body, { mode: 384 });
+  fs2.chmodSync(file, 384);
+}
+function isRegularFile(file) {
+  try {
+    const stat = fs2.lstatSync(file);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+function isInside(root, candidate) {
+  const relative = path2.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path2.isAbsolute(relative);
+}
+function tailBytes(file, maxBytes) {
+  try {
+    const fd = fs2.openSync(file, "r");
+    try {
+      const size = fs2.fstatSync(fd).size;
+      const start = size > maxBytes ? size - maxBytes : 0;
+      const buf = Buffer.alloc(size - start);
+      fs2.readSync(fd, buf, 0, buf.length, start);
+      return buf.toString("utf8");
+    } finally {
+      fs2.closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+function writeEnvScript(file, env) {
+  const lines = ["#!/bin/bash", "set -eu"];
+  for (const [key, value] of Object.entries(env)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    if (value === undefined)
+      continue;
+    if (key === "PWD" || key === "TMUX" || key === "TMUX_PANE")
+      continue;
+    lines.push(`export ${key}=${posixQuote(value)}`);
+  }
+  writePrivateExclusive(file, `${lines.join(`
+`)}
+`);
+}
+function tmuxClientEnv(env) {
+  const next = { ...env };
+  delete next.TMUX;
+  delete next.TMUX_PANE;
+  delete next.BASH_ENV;
+  return next;
+}
+function tmuxHasSession(name, env) {
+  return spawnSync("tmux", ["has-session", "-t", `=${name}`], { env: tmuxClientEnv(env), encoding: "utf8", timeout: 5000 }).status === 0;
+}
+function killSession(name, env) {
+  spawnSync("tmux", ["kill-session", "-t", `=${name}`], { env: tmuxClientEnv(env), encoding: "utf8", timeout: 5000 });
+}
+function parseExitCode(raw) {
+  if (raw === null)
+    return null;
+  const value = Number.parseInt(raw.trim(), 10);
+  return Number.isInteger(value) ? value : null;
+}
+function processTable() {
+  const listed = spawnSync("ps", ["-ax", "-o", "pid=,ppid=,pgid=,state="], { encoding: "utf8", timeout: 5000 });
+  if (listed.status !== 0)
+    return [];
+  return listed.stdout.split(`
+`).flatMap((line) => {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)/);
+    if (!match)
+      return [];
+    return [{
+      pid: Number.parseInt(match[1], 10),
+      ppid: Number.parseInt(match[2], 10),
+      pgid: Number.parseInt(match[3], 10),
+      state: match[4]
+    }];
+  });
+}
+function liveOwnedPanePid(session, env) {
+  if (!tmuxHasSession(session, env))
+    return null;
+  const listed = spawnSync("tmux", ["list-panes", "-t", `=${session}`, "-F", "#{pane_pid}"], {
+    env: tmuxClientEnv(env),
+    encoding: "utf8",
+    timeout: 5000
+  });
+  if (listed.status !== 0)
+    return null;
+  const pid = Number.parseInt(listed.stdout.trim().split(/\s+/)[0] ?? "", 10);
+  if (!Number.isInteger(pid) || pid <= 1)
+    return null;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return null;
+  }
+  return pid;
+}
+function ownedPids(panePid, rows) {
+  const pane = rows.find((row) => row.pid === panePid);
+  const owned = new Set([panePid]);
+  if (pane) {
+    for (const row of rows)
+      if (row.pgid === pane.pgid)
+        owned.add(row.pid);
+  }
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const row of rows) {
+      if (owned.has(row.ppid) && !owned.has(row.pid) && !row.state.startsWith("Z")) {
+        owned.add(row.pid);
+        grew = true;
+      }
+    }
+  }
+  return [...owned].filter((pid) => pid > 1 && pid !== process.pid);
+}
+function pidAlive(pid) {
+  const listed = spawnSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8", timeout: 5000 });
+  const state = listed.stdout.trim();
+  return listed.status === 0 && Boolean(state) && !state.startsWith("Z");
+}
+function signalGroup(pgid, signal) {
+  try {
+    process.kill(-pgid, signal);
+  } catch {}
+}
+function terminateOwnedPane(session, env) {
+  const panePid = liveOwnedPanePid(session, env);
+  const rows = processTable();
+  const pane = rows.find((row) => row.pid === panePid);
+  const pids = panePid ? ownedPids(panePid, rows) : [];
+  if (pane)
+    signalGroup(pane.pgid, "SIGTERM");
+  killSession(session, env);
+  if (pane)
+    signalGroup(pane.pgid, "SIGKILL");
+  for (const pid of pids) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {}
+  }
+  if (tmuxHasSession(session, env))
+    killSession(session, env);
+  if (tmuxHasSession(session, env))
+    throw new Error(`tmux session ${session} still present after kill`);
+  const deadline = Date.now() + 250;
+  while (Date.now() < deadline && pids.some(pidAlive)) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+  if (pids.some(pidAlive))
+    throw new Error(`tmux pane descendants still present after kill`);
+}
+function snapshotFromDir(dir, taskId, env, session) {
+  const live = tmuxHasSession(session, env);
+  const readExit = () => parseExitCode(readText(path2.join(dir, "exit_code")));
+  const cancelled = readText(path2.join(dir, "cancelled")) !== null;
+  let exitCode = readExit();
+  if (!live && exitCode === null)
+    exitCode = readExit();
+  const startedAt = readText(path2.join(dir, "started_at"))?.trim() || null;
+  const endedAt = readText(path2.join(dir, "ended_at"))?.trim() || null;
+  const output = tailBytes(path2.join(dir, "output"), OUTPUT_TAIL_BYTES);
+  let status;
+  if (exitCode === null) {
+    if (live)
+      status = cancelled ? "cancelled" : "running";
+    else
+      status = cancelled ? "cancelled" : "failed";
+  } else if (cancelled)
+    status = "cancelled";
+  else
+    status = exitCode === 0 ? "completed" : "failed";
+  return { taskId, status, exitCode, output, startedAt, endedAt };
+}
+function formatTmuxTaskText(snapshot) {
+  const exit = snapshot.exitCode === null ? "null" : String(snapshot.exitCode);
+  const body = snapshot.output ? `
+${snapshot.output}` : "";
+  return `taskId=${snapshot.taskId} status=${snapshot.status} exitCode=${exit}${body}`;
+}
+function createLarkinTmux(input) {
+  const env = input.env ?? process.env;
+  const agentId = input.agentId;
+  const instanceId = input.instanceId || crypto.randomUUID();
+  const stateDir = path2.resolve(input.stateDir);
+  const ownedParts = ["pi-tmux", sanitizeName(agentId, "agent"), sanitizeName(instanceId, "inst")];
+  const root = taskRoot(stateDir, agentId, instanceId);
+  const expectedSession = (taskId) => sessionName(agentId, instanceId, taskId);
+  const assertPrivateScripts = (dir) => {
+    for (const name of ["env.sh", "command.sh", "run.sh", "meta.json"]) {
+      const file = path2.join(dir, name);
+      if (!fs2.existsSync(file)) {
+        if (name === "meta.json")
+          throw new ForeignTmuxTaskError(path2.basename(dir));
+        continue;
+      }
+      if (!isRegularFile(file))
+        throw new ForeignTmuxTaskError(path2.basename(dir));
+    }
+  };
+  const requireOwned = (taskId) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(taskId))
+      throw new ForeignTmuxTaskError(taskId);
+    let instanceRoot;
+    try {
+      instanceRoot = ensureOwnedTree(stateDir, ownedParts, false);
+    } catch {
+      throw new ForeignTmuxTaskError(taskId);
+    }
+    const dir = taskDir(stateDir, agentId, instanceId, taskId);
+    try {
+      const stat = fs2.lstatSync(dir);
+      if (stat.isSymbolicLink() || !stat.isDirectory() || !isInside(instanceRoot, dir))
+        throw new ForeignTmuxTaskError(taskId);
+    } catch (error) {
+      if (error instanceof ForeignTmuxTaskError)
+        throw error;
+      throw new ForeignTmuxTaskError(taskId);
+    }
+    const metaFile = path2.join(dir, "meta.json");
+    if (!isRegularFile(metaFile))
+      throw new ForeignTmuxTaskError(taskId);
+    let meta;
+    try {
+      meta = JSON.parse(fs2.readFileSync(metaFile, "utf8"));
+    } catch {
+      throw new ForeignTmuxTaskError(taskId);
+    }
+    if (meta.taskId !== taskId || meta.agentId !== agentId || meta.instanceId !== instanceId || meta.session !== expectedSession(taskId) || typeof meta.cwd !== "string")
+      throw new ForeignTmuxTaskError(taskId);
+    try {
+      assertPrivateScripts(dir);
+    } catch (error) {
+      if (error instanceof ForeignTmuxTaskError)
+        throw error;
+      throw new ForeignTmuxTaskError(taskId);
+    }
+    return dir;
+  };
+  const start = (command, cwd) => {
+    const taskId = crypto.randomBytes(8).toString("hex");
+    const parent = ensureOwnedTree(stateDir, ownedParts);
+    const dir = path2.join(parent, taskId);
+    mkdirPrivateExclusive(dir);
+    if (!tmuxAvailable(env))
+      throw new Error("tmux is not available");
+    const session = expectedSession(taskId);
+    writePrivateExclusive(path2.join(dir, "meta.json"), `${JSON.stringify({
+      taskId,
+      agentId,
+      instanceId,
+      session,
+      cwd
+    })}
+`);
+    writeEnvScript(path2.join(dir, "env.sh"), env);
+    writePrivateExclusive(path2.join(dir, "command.sh"), command.endsWith(`
+`) ? command : `${command}
+`);
+    const envFile = path2.join(dir, "env.sh");
+    const commandFile = path2.join(dir, "command.sh");
+    const outputFile = path2.join(dir, "output");
+    const exitFile = path2.join(dir, "exit_code");
+    const startedFile = path2.join(dir, "started_at");
+    const endedFile = path2.join(dir, "ended_at");
+    writePrivateExclusive(path2.join(dir, "run.sh"), [
+      "#!/bin/bash",
+      `PANE_TMUX=\${TMUX-}`,
+      `PANE_TMUX_PANE=\${TMUX_PANE-}`,
+      `. ${posixQuote(envFile)}`,
+      "set +eu",
+      "unset TMUX TMUX_PANE",
+      `if [ -n "$PANE_TMUX" ]; then export TMUX="$PANE_TMUX"; fi`,
+      `if [ -n "$PANE_TMUX_PANE" ]; then export TMUX_PANE="$PANE_TMUX_PANE"; fi`,
+      `cd ${posixQuote(cwd)} || { date -u +%Y-%m-%dT%H:%M:%SZ > ${posixQuote(endedFile)}; printf '%s\\n' 127 > ${posixQuote(exitFile)}; exit 127; }`,
+      `date -u +%Y-%m-%dT%H:%M:%SZ > ${posixQuote(startedFile)}`,
+      `/bin/bash -o pipefail ${posixQuote(commandFile)} > ${posixQuote(outputFile)} 2>&1`,
+      `status=$?`,
+      `date -u +%Y-%m-%dT%H:%M:%SZ > ${posixQuote(endedFile)}`,
+      `printf '%s\\n' "$status" > ${posixQuote(exitFile)}`,
+      ""
+    ].join(`
+`));
+    const created = spawnSync("tmux", ["new-session", "-d", "-s", session, "-n", "bash", "-e", "BASH_ENV=", "/usr/bin/env", "-u", "BASH_ENV", "/bin/bash", path2.join(dir, "run.sh")], {
+      env: tmuxClientEnv(env),
+      encoding: "utf8",
+      timeout: 5000
+    });
+    if (created.status !== 0) {
+      throw new Error(`tmux new-session failed: ${(created.stderr || created.stdout || "").trim() || created.status}`);
+    }
+    return snapshotFromDir(dir, taskId, env, session);
+  };
+  const peek = (taskId) => {
+    const dir = requireOwned(taskId);
+    return snapshotFromDir(dir, taskId, env, expectedSession(taskId));
+  };
+  const list = () => {
+    let instanceRoot;
+    try {
+      instanceRoot = ensureOwnedTree(stateDir, ownedParts, false);
+    } catch {
+      return [];
+    }
+    return fs2.readdirSync(instanceRoot).sort().flatMap((taskId) => {
+      try {
+        return [peek(taskId)];
+      } catch {
+        return [];
+      }
+    });
+  };
+  const wait = async (taskId, timeoutSeconds, signal) => {
+    const deadline = Date.now() + Math.max(0, timeoutSeconds) * 1000;
+    while (true) {
+      if (signal?.aborted) {
+        kill(taskId);
+        return peek(taskId);
+      }
+      const current = peek(taskId);
+      const flushing = current.status === "failed" && current.exitCode === null;
+      if (current.status !== "running" && !flushing)
+        return current;
+      if (Date.now() >= deadline)
+        return current;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  };
+  const kill = (taskId) => {
+    const dir = requireOwned(taskId);
+    const session = expectedSession(taskId);
+    if (parseExitCode(readText(path2.join(dir, "exit_code"))) !== null)
+      return snapshotFromDir(dir, taskId, env, session);
+    const live = tmuxHasSession(session, env) || liveOwnedPanePid(session, env) !== null;
+    if (live) {
+      writePrivate(path2.join(dir, "cancelled"), `1
+`);
+      terminateOwnedPane(session, env);
+      if (!readText(path2.join(dir, "ended_at"))) {
+        writePrivate(path2.join(dir, "ended_at"), `${new Date().toISOString().slice(0, 19)}Z
+`);
+      }
+    }
+    return snapshotFromDir(dir, taskId, env, session);
+  };
+  return { start, peek, list, wait, kill, root, instanceId };
+}
+
+// src/runtime/pi-tmux-extension.ts
+function resultOf(snapshot) {
+  return {
+    content: [{ type: "text", text: formatTmuxTaskText(snapshot) }],
+    details: {
+      taskId: snapshot.taskId,
+      status: snapshot.status,
+      exitCode: snapshot.exitCode,
+      output: snapshot.output
+    }
+  };
+}
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    details: { taskId: "", status: "failed", exitCode: null, output: message }
+  };
+}
+function registerLarkinTmuxExtension(pi) {
+  if (!tmuxAvailable())
+    return false;
+  const stateDir = process.env.LARKIN_STATE_DIR || `${process.cwd()}/.larkin`;
+  const agentId = process.env.LARKIN_AGENT_ID || "agent";
+  const instanceId = process.env.LARKIN_TMUX_INSTANCE_ID || process.env.LARKIN_RUNTIME_OBSERVATION_GENERATION || crypto2.randomUUID();
+  const tmux = createLarkinTmux({ stateDir, agentId, instanceId, env: process.env });
+  const watchers = new Map;
+  const notified = new Set;
+  const stopWatchers = () => {
+    for (const timer of watchers.values())
+      clearInterval(timer);
+    watchers.clear();
+  };
+  const notifyOnce = (snapshot) => {
+    if (snapshot.status === "running" || notified.has(snapshot.taskId))
+      return;
+    notified.add(snapshot.taskId);
+    pi.sendMessage({
+      customType: LARKIN_TMUX_COMPLETION_TYPE,
+      content: formatTmuxTaskText(snapshot),
+      display: true,
+      details: {
+        taskId: snapshot.taskId,
+        exitCode: snapshot.exitCode,
+        output: snapshot.output
+      }
+    }, { triggerTurn: true, deliverAs: "followUp" });
+  };
+  const watch = (taskId) => {
+    if (watchers.has(taskId) || notified.has(taskId))
+      return;
+    const timer = setInterval(() => {
+      try {
+        const snapshot = tmux.peek(taskId);
+        if (snapshot.status === "running")
+          return;
+        clearInterval(timer);
+        watchers.delete(taskId);
+        notifyOnce(snapshot);
+      } catch {
+        clearInterval(timer);
+        watchers.delete(taskId);
+      }
+    }, 250);
+    watchers.set(taskId, timer);
+  };
+  pi.on("session_shutdown", () => {
+    stopWatchers();
+  });
+  pi.registerTool({
+    name: "bash",
+    label: "bash",
+    description: "Run a command in a detached tmux window. timeout is a wait window only and never hard-kills. background:true returns immediately.",
+    parameters: Type.Object({
+      command: Type.String(),
+      timeout: Type.Optional(Type.Number()),
+      background: Type.Optional(Type.Boolean())
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const snapshot = tmux.start(params.command, ctx.cwd);
+      if (params.background === true) {
+        watch(snapshot.taskId);
+        return resultOf(tmux.peek(snapshot.taskId));
+      }
+      const timeout = typeof params.timeout === "number" && params.timeout >= 0 ? params.timeout : DEFAULT_BASH_WAIT_SECONDS;
+      const waited = await tmux.wait(snapshot.taskId, timeout, signal);
+      if (waited.status === "running")
+        watch(waited.taskId);
+      return resultOf(waited);
+    }
+  });
+  pi.registerTool({
+    name: "tmux",
+    label: "tmux",
+    description: "List, peek, or kill Larkin-owned tmux tasks for this Agent. Foreign task IDs are rejected.",
+    parameters: Type.Object({
+      action: Type.Union([Type.Literal("list"), Type.Literal("peek"), Type.Literal("kill")]),
+      taskId: Type.Optional(Type.String())
+    }),
+    async execute(_toolCallId, params) {
+      try {
+        if (params.action === "list") {
+          const tasks = tmux.list();
+          return {
+            content: [{ type: "text", text: tasks.map(formatTmuxTaskText).join(`
+---
+`) || "no owned tmux tasks" }],
+            details: { taskId: "", status: "completed", exitCode: 0, output: "" }
+          };
+        }
+        if (!params.taskId)
+          return errorResult("taskId is required for peek and kill");
+        if (params.action === "peek")
+          return resultOf(tmux.peek(params.taskId));
+        const killed = tmux.kill(params.taskId);
+        notified.add(params.taskId);
+        const timer = watchers.get(params.taskId);
+        if (timer) {
+          clearInterval(timer);
+          watchers.delete(params.taskId);
+        }
+        return resultOf(killed);
+      } catch (error) {
+        if (error instanceof ForeignTmuxTaskError)
+          return errorResult(error.message);
+        throw error;
+      }
+    }
+  });
+  return true;
+}
+function larkinTmuxExtension(pi) {
+  registerLarkinTmuxExtension(pi);
+}
+export {
+  registerLarkinTmuxExtension,
+  larkinTmuxExtension as default
+};