tau-coding-agent 0.1.6 → 0.2.0

package/extensions/{branch-term.ts → branch-term/index.ts}

@@ -1,14 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as path from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import {
-  CURRENT_SESSION_VERSION,
-  SessionManager,
-  highlightCode,
-  type SessionHeader,
-} from "@earendil-works/pi-coding-agent";
+import { SessionManager, highlightCode, type SessionHeader } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 
 const TERMINAL_FLAG = "branch-term";
@@ -46,7 +39,7 @@ const TMUX_LAYOUT_CONFIG: Record<
 };
 
 function getStringFlag(pi: ExtensionAPI, flagName: string): string | undefined {
-  const value = pi.getFlag(`--${flagName}`);
+  const value = pi.getFlag(flagName);
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
@@ -55,7 +48,7 @@ function getStringFlag(pi: ExtensionAPI, flagName: string): string | undefined {
 function parseTmuxLayout(value: string | undefined): TmuxLayout | undefined {
   if (!value) return undefined;
   const normalized = value.trim().toLowerCase();
-  if (normalized in TMUX_LAYOUT_CONFIG) {
+  if (Object.hasOwn(TMUX_LAYOUT_CONFIG, normalized)) {
     return normalized as TmuxLayout;
   }
   return undefined;
@@ -103,73 +96,23 @@ function getBranchArgumentCompletions(
   return matches;
 }
 
-function renderTerminalCommand(template: string, cwd: string, sessionFile: string): string {
-  let command = template;
-  command = command.split("{cwd}").join(cwd);
-
-  if (command.includes("{command}")) {
-    const piCommand = `pi --session ${shellQuote(sessionFile)}`;
-    command = command.split("{command}").join(piCommand);
-  }
-
-  if (command.includes("{session}")) {
-    command = command.split("{session}").join(sessionFile);
-  }
-
-  if (template.includes("{command}") || template.includes("{session}")) {
-    return command;
-  }
-
-  return `${command} ${sessionFile}`;
+function renderTerminalCommand(template: string): string {
+  // Paths stay data even when they contain shell syntax or placeholder-like text.
+  const command = template.replace(
+    /\{(cwd|session|command)\}/g,
+    (_match, name: string) => `"$TAU_BRANCH_${name.toUpperCase()}"`,
+  );
+  return /\{(command|session)\}/.test(template) ? command : `${command} "$TAU_BRANCH_SESSION"`;
 }
 
-function spawnDetached(command: string, args: string[], onError?: (error: Error) => void): void {
-  const child = spawn(command, args, { detached: true, stdio: "ignore" });
-  child.unref();
-  if (onError) child.on("error", onError);
-}
+// Shared outside the factory so detached children cannot retain a session through this listener.
+function ignoreDetachedLauncherError(): void {}
 
 function shellQuote(value: string): string {
   if (value.length === 0) return "''";
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
-function escapeForDoubleQuotes(value: string): string {
-  return value.replace(/(["\\$`!])/g, "\\$1");
-}
-
-function shellQuoteCompact(value: string): string {
-  const home = process.env.HOME;
-  if (!home) return shellQuote(value);
-
-  if (value === home) return "$HOME";
-
-  if (value.startsWith(`${home}/`)) {
-    const suffix = value.slice(home.length + 1);
-    return `"$HOME/${escapeForDoubleQuotes(suffix)}"`;
-  }
-
-  return shellQuote(value);
-}
-
-function parseSessionIdFromFile(sessionFile: string): string | undefined {
-  const fileName = path.basename(sessionFile, ".jsonl");
-  const separatorIndex = fileName.lastIndexOf("_");
-  if (separatorIndex <= 0) return undefined;
-
-  const candidate = fileName.slice(separatorIndex + 1);
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate)
-    ? candidate
-    : undefined;
-}
-
-function formatResumeSessionArgument(sessionFile: string): string {
-  const sessionId = parseSessionIdFromFile(sessionFile);
-  if (sessionId) return sessionId;
-
-  return shellQuoteCompact(sessionFile);
-}
-
 function runClipboardCommand(command: string, args: string[], text: string): boolean {
   try {
     const result = spawnSync(command, args, {
@@ -241,26 +184,32 @@ function hasValidSessionFile(sessionFile: string): boolean {
   }
 }
 
-function createFreshSessionFile(cwd: string, sessionDir: string): string {
-  fs.mkdirSync(sessionDir, { recursive: true });
-
-  const sessionId = randomUUID();
-  const timestamp = new Date().toISOString();
-  const fileTimestamp = timestamp.replace(/[:.]/g, "-");
-  const sessionFile = path.join(sessionDir, `${fileTimestamp}_${sessionId}.jsonl`);
-  const header: SessionHeader = {
-    type: "session",
-    version: CURRENT_SESSION_VERSION,
-    id: sessionId,
-    timestamp,
-    cwd,
-  };
-
-  fs.writeFileSync(sessionFile, `${JSON.stringify(header)}\n`);
+/** Write a standalone handoff snapshot when Pi defers persistence; discard the manager afterward. */
+function persistFork(manager: SessionManager): string {
+  const sessionFile = manager.getSessionFile();
+  const header = manager.getHeader();
+  if (!sessionFile || !header) throw new Error("Failed to create branched session");
+  if (!fs.existsSync(sessionFile)) {
+    const contents =
+      [header, ...manager.getEntries()].map((entry) => JSON.stringify(entry)).join("\n") + "\n";
+    const fd = fs.openSync(sessionFile, "wx");
+    try {
+      fs.writeFileSync(fd, contents);
+    } catch (error) {
+      fs.rmSync(sessionFile, { force: true });
+      throw error;
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
   return sessionFile;
 }
 
 export default function (pi: ExtensionAPI) {
+  const launchObservers = new Set<() => void>();
+  pi.on("session_start", releaseLaunchObservers);
+  pi.on("session_shutdown", releaseLaunchObservers);
+
   pi.registerEntryRenderer<CommandMessageDetails>(BRANCH_ENTRY_TYPE, (entry, _options, theme) => {
     const details = entry.data;
     if (!details || typeof details.intro !== "string" || typeof details.command !== "string") {
@@ -287,7 +236,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerFlag(TERMINAL_FLAG, {
     description:
-      "Command to open a new terminal. Use {cwd} for working directory and optional {command} for the pi command.",
+      "Bash launcher template. Unquoted {cwd}, {session}, and {command} become single arguments; {command} is a command string for e.g. bash -c.",
     type: "string",
   });
 
@@ -326,38 +275,38 @@ export default function (pi: ExtensionAPI) {
 
       let forkFile: string;
       if (leafId && hasValidSessionFile(sessionFile)) {
-        const forkManager = SessionManager.open(sessionFile);
-        const branchedSessionFile = forkManager.createBranchedSession(leafId);
-        if (!branchedSessionFile) {
+        const forkManager = SessionManager.open(
+          sessionFile,
+          ctx.sessionManager.getSessionDir(),
+          ctx.cwd,
+        );
+        if (!forkManager.createBranchedSession(leafId)) {
           throw new Error("Failed to create branched session");
         }
-        forkFile = branchedSessionFile;
+        forkFile = persistFork(forkManager);
       } else {
-        if (hasAssistantReply) {
+        if (leafId && hasAssistantReply) {
           throw new Error(`Current session file is missing or invalid: ${sessionFile}`);
         }
 
-        const message = "Current session has no persisted history yet. Opening a fresh session.";
+        const message = leafId
+          ? "Current session has no persisted history yet. Opening a fresh session."
+          : "Selected conversation is empty. Opening a fresh session.";
         if (ctx.hasUI) ctx.ui.notify(message, "warning");
         else console.log(message);
 
-        forkFile = createFreshSessionFile(ctx.cwd, ctx.sessionManager.getSessionDir());
+        forkFile = persistFork(
+          SessionManager.create(ctx.cwd, ctx.sessionManager.getSessionDir(), {
+            parentSession: sessionFile,
+          }),
+        );
       }
 
-      const resumeCommand = `cd ${shellQuoteCompact(ctx.cwd)} && pi --session ${formatResumeSessionArgument(forkFile)}`;
+      const resumeCommand = `cd ${shellQuote(ctx.cwd)} && pi --session ${shellQuote(forkFile)}`;
 
       const terminalFlag = getStringFlag(pi, TERMINAL_FLAG);
       if (terminalFlag) {
-        const command = renderTerminalCommand(terminalFlag, ctx.cwd, forkFile);
-        spawnDetached("bash", ["-lc", command], (error) => {
-          if (ctx.hasUI) {
-            ctx.ui.notify(`Terminal command failed: ${error.message}`, "error");
-          } else {
-            console.error(`Terminal command failed: ${error.message}`);
-          }
-          showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
-        });
-        if (ctx.hasUI) ctx.ui.notify("Opened fork in new terminal", "info");
+        launchTerminal(terminalFlag, forkFile, resumeCommand, ctx);
         return;
       }
 
@@ -397,4 +346,64 @@ export default function (pi: ExtensionAPI) {
       showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
     },
   });
+
+  function launchTerminal(
+    template: string,
+    forkFile: string,
+    resumeCommand: string,
+    ctx: ExtensionCommandContext,
+  ) {
+    const reportFailure = (message: string) => {
+      try {
+        if (ctx.hasUI) ctx.ui.notify(`Terminal command failed: ${message}`, "error");
+        else console.error(`Terminal command failed: ${message}`);
+        showCommandMessage(pi, ctx, MANUAL_RESUME_INTRO, resumeCommand);
+      } catch (error) {
+        console.error(
+          `Could not show terminal recovery instructions: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        console.error(`${MANUAL_RESUME_INTRO}:\n${resumeCommand}`);
+      }
+    };
+    try {
+      const child = spawn("bash", ["-c", renderTerminalCommand(template)], {
+        cwd: ctx.cwd,
+        env: {
+          ...process.env,
+          TAU_BRANCH_CWD: ctx.cwd,
+          TAU_BRANCH_SESSION: forkFile,
+          TAU_BRANCH_COMMAND: `pi --session ${shellQuote(forkFile)}`,
+        },
+        detached: true,
+        stdio: "ignore",
+      });
+      const stopObserving = () => {
+        child.removeListener("error", onError);
+        child.removeListener("close", onClose);
+        launchObservers.delete(stopObserving);
+      };
+      const onError = (error: Error) => {
+        stopObserving();
+        reportFailure(error.message);
+      };
+      const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
+        stopObserving();
+        if (code !== 0) reportFailure(signal ? `terminated by ${signal}` : `exit code ${code}`);
+      };
+      // A detached, user-owned launcher may still emit an error after Pi stops observing it.
+      child.on("error", ignoreDetachedLauncherError);
+      child.once("error", onError);
+      child.once("close", onClose);
+      launchObservers.add(stopObserving);
+      child.unref();
+    } catch (error) {
+      reportFailure(error instanceof Error ? error.message : String(error));
+      return;
+    }
+    if (ctx.hasUI) ctx.ui.notify("Terminal launch requested", "info");
+  }
+
+  function releaseLaunchObservers() {
+    for (const stopObserving of launchObservers) stopObserving();
+  }
 }

package/extensions/btw.ts

@@ -31,6 +31,7 @@ import {
 
 const STATUS_KEY = "0-btw";
 const RESULT_MARKDOWN_THEME = getMarkdownTheme();
+const MIN_RESULT_WIDTH = 50;
 const STATUS_SPINNER_INTERVAL_MS = 80;
 const STATUS_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -380,6 +381,7 @@ function extractText(content: AssistantMessage["content"]): string {
 class BtwResultComponent implements Component {
   private readonly markdown: Markdown;
   private scrollOffset = 0;
+  private renderWidth?: number;
   private cachedBodyWidth?: number;
   private cachedBodyLines?: string[];
 
@@ -409,8 +411,11 @@ class BtwResultComponent implements Component {
       return;
     }
 
+    const width = this.renderWidth ?? this.tui.terminal.columns;
+    if (width < MIN_RESULT_WIDTH) return;
+
     const bodyHeight = this.getBodyHeight();
-    const boxWidth = this.getBoxWidth(this.tui.terminal.columns);
+    const boxWidth = this.getBoxWidth(width);
     const bodyLines = this.getBodyLines(this.getContentWidth(boxWidth));
     const maxScroll = Math.max(0, bodyLines.length - bodyHeight);
 
@@ -434,6 +439,16 @@ class BtwResultComponent implements Component {
   }
 
   render(width: number): string[] {
+    this.renderWidth = width;
+    if (width < MIN_RESULT_WIDTH) {
+      return [
+        truncateToWidth(
+          this.theme.fg("muted", `Resize to ${MIN_RESULT_WIDTH}+ columns to view answer.`),
+          width,
+        ),
+      ];
+    }
+
     const boxWidth = this.getBoxWidth(width);
     const contentWidth = this.getContentWidth(boxWidth);
     const questionLines = wrapTextWithAnsi(
@@ -486,7 +501,7 @@ class BtwResultComponent implements Component {
   }
 
   private getBoxWidth(width: number): number {
-    return Math.max(50, Math.min(width - 2, 140));
+    return Math.max(MIN_RESULT_WIDTH, Math.min(width - 2, 140));
   }
 
   private getContentWidth(boxWidth: number): number {

package/extensions/caffeinate/README.md

@@ -0,0 +1,5 @@
+# Caffeinate
+
+`caffeinate` prevents system sleep during agent runs, including retries, automatic compaction, and queued follow-ups. It releases the inhibitor when the agent settles or the session closes or reloads. Display sleep settings remain unchanged.
+
+macOS uses `caffeinate -i`; Linux uses `systemd-inhibit --what=sleep` and requires an accessible, authorized logind service. Linux's sleep lock can also block manual suspend; lid-close and forced-sleep behavior remain OS-policy decisions. If inhibition is unavailable, Pi warns once per load, on the first failed attempt, and continues normally. There are no commands or settings; disable the extension through Pi's package configuration if unwanted.

package/extensions/caffeinate/index.ts

@@ -0,0 +1,144 @@
+/** Keep the system awake during agent runs without inhibiting display sleep. */
+
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { stripVTControlCharacters } from "node:util";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface InhibitCommand {
+  command: string;
+  args: string[];
+  waitForStdin: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+  let inhibitor: ReturnType<typeof startInhibitor> | undefined;
+  let releasing = Promise.resolve();
+  let shutdown = false;
+  let warned = false;
+
+  pi.on("agent_start", async (_event, ctx) => {
+    await releasing;
+    if (shutdown || inhibitor) return;
+    const command = inhibitCommand();
+    if (!command) return;
+    try {
+      inhibitor = startInhibitor(command, ctx.cwd, (reason) => warn(ctx, reason));
+    } catch (error) {
+      warn(ctx, error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!shutdown && ctx.isIdle()) await release();
+  });
+
+  pi.on("session_shutdown", async () => {
+    shutdown = true;
+    await release();
+  });
+
+  async function release() {
+    if (inhibitor) {
+      releasing = inhibitor.stop();
+      inhibitor = undefined;
+    }
+    await releasing;
+  }
+
+  function warn(ctx: ExtensionContext, reason: string) {
+    if (shutdown || warned) return;
+    warned = true;
+    const message = `Caffeinate: sleep prevention unavailable. ${stripVTControlCharacters(reason)}`;
+    try {
+      if (ctx.hasUI) {
+        ctx.ui.notify(message, "warning");
+        return;
+      }
+    } catch {
+      // A missing UI must not turn an optional inhibitor failure into an uncaught error.
+    }
+    console.warn(message);
+  }
+}
+
+function inhibitCommand(): InhibitCommand | undefined {
+  switch (platform()) {
+    case "darwin":
+      return {
+        command: "/usr/bin/caffeinate",
+        args: ["-i", "-w", String(process.pid)],
+        waitForStdin: false,
+      };
+    case "linux":
+      return {
+        command: "systemd-inhibit",
+        args: [
+          "--what=sleep",
+          "--mode=block",
+          "--who=Pi",
+          "--why=Pi agent is running",
+          "--",
+          "cat",
+        ],
+        waitForStdin: true,
+      };
+  }
+}
+
+/** Own the inhibitor through close; a parent PID watch or stdin EOF also releases it if Pi exits. */
+function startInhibitor(command: InhibitCommand, cwd: string, onFailure: (reason: string) => void) {
+  const child = spawn(command.command, command.args, {
+    cwd,
+    detached: true,
+    stdio: ["pipe", "ignore", "pipe"],
+  });
+  let stderr = "";
+  let error: string | undefined;
+  let stopped = false;
+  let closed = false;
+  let escalation: NodeJS.Timeout | undefined;
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => {
+    stderr = (stderr + chunk).slice(0, 2048);
+  });
+  child.on("error", (cause: Error) => {
+    error = cause.message;
+  });
+  child.stdin.on("error", (cause: Error) => {
+    error = cause.message;
+  });
+  const completion = new Promise<void>((resolve) => {
+    child.once("close", (code, signal) => {
+      closed = true;
+      clearTimeout(escalation);
+      if (!stopped) {
+        onFailure(
+          error || stderr.trim() || `${command.command} exited unexpectedly (${signal ?? code}).`,
+        );
+      }
+      resolve();
+    });
+  });
+
+  return {
+    stop() {
+      if (!stopped && !closed) {
+        stopped = true;
+        child.stdin.end();
+        if (!command.waitForStdin) sendSignal("SIGTERM");
+        escalation = setTimeout(() => sendSignal("SIGKILL"), 500);
+      }
+      return completion;
+    },
+  };
+
+  function sendSignal(signal: "SIGTERM" | "SIGKILL") {
+    if (closed || child.pid === undefined) return;
+    try {
+      process.kill(-child.pid, signal);
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "ESRCH") child.kill(signal);
+    }
+  }
+}