paseo-terminal-integration 0.2.0 → 0.4.0

package/server/runner.ts

@@ -1,10 +1,12 @@
+import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { mkdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { constants as osConstants, tmpdir } from "node:os";
 import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { interpreterFor, type Interpreter } from "../shared/code-blocks";
-import { TERMINAL_NAME, type RunSnapshot } from "../shared/contracts";
+import { TERMINAL_NAME, type RunMode, type RunSnapshot } from "../shared/contracts";
 import { fenced, trimBlankEdges } from "../shared/text";
 
 type Paseo = PluginHandlerContext["paseo"];
@@ -23,6 +25,9 @@ const TAIL_LINES = 6;
 const REPORT_MAX_LINES = 300;
 const REPORT_MAX_CHARS = 24_000;
 const FINISHED_RUN_LIMIT = 200;
+const BACKGROUND_MAX_LINES = 5_000;
+const BACKGROUND_MAX_LINE_CHARS = 16_000;
+const BACKGROUND_FLUSH_MS = 1_000;
 
 // sendKeys() expands only a few key names, so control characters are written as raw bytes.
 const CTRL_C = "\x03";
@@ -39,6 +44,7 @@ const EXTENSIONS: Record<Interpreter, string> = {
 interface Run {
   id: string;
   key: string;
+  mode: RunMode;
   agentId: string;
   workspaceId: string;
   cwd: string;
@@ -57,6 +63,7 @@ interface Run {
   error: string | null;
   cancelRequested: boolean;
   terminal: TerminalHandle | null;
+  process: ChildProcess | null;
 }
 
 export interface StartRunInput {
@@ -65,9 +72,13 @@ export interface StartRunInput {
   lang: string;
   code: string;
   send: boolean;
+  mode: RunMode;
 }
 
-/** Runs code blocks in a per-workspace Paseo terminal and reports output back to the agent. */
+/**
+ * Runs code blocks in a per-workspace Paseo terminal, or as background processes, and reports
+ * output back to the agent.
+ */
 export class TerminalRunner {
   private readonly runs = new Map<string, Run>();
   private readonly lanes = new Map<string, Promise<void>>();
@@ -90,6 +101,7 @@ export class TerminalRunner {
     const run: Run = {
       id: randomUUID().slice(0, 8),
       key: input.key,
+      mode: input.mode,
       agentId: input.agentId,
       workspaceId: agent.workspaceId,
       cwd: agent.cwd,
@@ -108,13 +120,21 @@ export class TerminalRunner {
       error: null,
       cancelRequested: false,
       terminal: null,
+      process: null,
     };
     this.runs.delete(input.key);
     this.runs.set(input.key, run);
     this.pruneFinished();
 
-    const lane = (this.lanes.get(run.workspaceId) ?? Promise.resolve()).then(() => this.execute(run));
-    this.lanes.set(run.workspaceId, lane);
+    if (run.mode === "background") {
+      // Background runs never touch the terminal, so they skip its queue.
+      void this.execute(run);
+    } else {
+      const lane = (this.lanes.get(run.workspaceId) ?? Promise.resolve()).then(() =>
+        this.execute(run),
+      );
+      this.lanes.set(run.workspaceId, lane);
+    }
     return snapshot(run);
   }
 
@@ -134,7 +154,13 @@ export class TerminalRunner {
       this.finish(run, "canceled");
     } else if (run.status === "running" && !run.cancelRequested) {
       run.cancelRequested = true;
-      run.terminal?.write(CTRL_C);
+      const child = run.process;
+      if (child) {
+        signalGroup(child, "SIGINT");
+        setTimeout(() => signalGroup(child, "SIGKILL"), CANCEL_GRACE_MS).unref();
+      } else {
+        run.terminal?.write(CTRL_C);
+      }
     }
     return snapshot(run);
   }
@@ -153,6 +179,7 @@ export class TerminalRunner {
   stop(): void {
     this.stopped = true;
     for (const run of this.runs.values()) {
+      if (run.process) signalGroup(run.process, "SIGTERM");
       if (run.status === "queued" || run.status === "running") {
         run.error = "Plugin stopped before the command finished";
         this.finish(run, "failed");
@@ -165,11 +192,15 @@ export class TerminalRunner {
     run.status = "running";
     run.startedAt = Date.now();
     try {
-      const terminal = await this.ensureTerminal(run.workspaceId, run.cwd);
-      run.terminal = terminal;
-      const wrapper = await writeScripts(run);
-      terminal.write(`${CTRL_U} bash ${shellQuote(wrapper)}\r`);
-      await this.watch(run, terminal);
+      if (run.mode === "background") {
+        await this.runInBackground(run);
+      } else {
+        const terminal = await this.ensureTerminal(run.workspaceId, run.cwd);
+        run.terminal = terminal;
+        const wrapper = await writeScripts(run);
+        terminal.write(`${CTRL_U} bash ${shellQuote(wrapper)}\r`);
+        await this.watch(run, terminal);
+      }
     } catch (error) {
       run.error = error instanceof Error ? error.message : String(error);
       this.finish(run, "failed");
@@ -227,6 +258,68 @@ export class TerminalRunner {
     }
   }
 
+  /** Runs the block as a child process with no terminal, stderr merged into stdout. */
+  private async runInBackground(run: Run): Promise<void> {
+    const codeFile = await writeCode(run);
+    const output = new OutputLines();
+    const sync = setInterval(() => (run.output = output.lines()), POLL_MS);
+    let timedOut = false;
+    try {
+      const exitCode = await new Promise<number>((resolve, reject) => {
+        // One pipe for both streams keeps their order, as a terminal shows it. The command gets
+        // its own process group, so Stop reaches its children too, and no controlling terminal or
+        // stdin, so a password prompt fails instead of waiting for input.
+        const child = spawn("/bin/sh", ["-c", 'exec "$@" 2>&1', "sh", run.interpreter, codeFile], {
+          cwd: run.cwd,
+          env: backgroundEnv(),
+          stdio: ["ignore", "pipe", "pipe"],
+          detached: true,
+        });
+        run.process = child;
+        const limit = setTimeout(() => {
+          timedOut = true;
+          signalGroup(child, "SIGKILL");
+        }, MAX_RUN_MS);
+        for (const stream of [child.stdout, child.stderr]) {
+          const decoder = new StringDecoder("utf8");
+          stream.on("data", (chunk: Buffer) => output.write(decoder.write(chunk)));
+        }
+        child.once("error", (error) => {
+          clearTimeout(limit);
+          reject(new Error(`Could not start the command in ${run.cwd}: ${error.message}`));
+        });
+        child.once("exit", (code, signal) => {
+          clearTimeout(limit);
+          const status = code ?? 128 + (signal ? osConstants.signals[signal] : 0);
+          // Output still in the pipes arrives before "close", but a leftover background job that
+          // holds them open must not keep the run going.
+          const flushed = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve(status);
+          }, BACKGROUND_FLUSH_MS);
+          child.once("close", () => {
+            clearTimeout(flushed);
+            resolve(status);
+          });
+        });
+      });
+      run.output = trimBlankEdges(output.lines());
+      run.truncated = output.dropped > 0;
+      if (timedOut) {
+        run.error = "Stopped: the command ran longer than 6 hours";
+        this.finish(run, "failed");
+      } else {
+        run.exitCode = exitCode;
+        this.finish(run, run.cancelRequested ? "canceled" : "done");
+      }
+    } finally {
+      clearInterval(sync);
+      run.process = null;
+      await rm(codeFile, { force: true });
+    }
+  }
+
   private async ensureTerminal(workspaceId: string, cwd: string): Promise<TerminalHandle> {
     const { entries } = await this.paseo.terminals.list({ workspaceId });
     const existing = entries.find((entry) => entry.name === TERMINAL_NAME);
@@ -289,7 +382,10 @@ function finishedCleanly(run: Run): boolean {
 function snapshot(run: Run): RunSnapshot {
   return {
     runId: run.id,
+    workspaceId: run.workspaceId,
+    terminalId: run.terminal?.id ?? null,
     key: run.key,
+    mode: run.mode,
     status: run.status,
     exitCode: run.exitCode,
     startedAt: run.startedAt,
@@ -308,15 +404,14 @@ function snapshot(run: Run): RunSnapshot {
  * of the input line. The wrapper prints concealed begin/end markers around the command's output.
  */
 async function writeScripts(run: Run): Promise<string> {
-  await mkdir(SCRIPT_DIR, { recursive: true });
-  const codeFile = path.join(SCRIPT_DIR, `${run.id}.${EXTENSIONS[run.interpreter]}`);
+  const codeFile = await writeCode(run);
   const wrapper = path.join(SCRIPT_DIR, `${run.id}.run.sh`);
-  const shell = run.interpreter === "bash" || run.interpreter === "zsh" || run.interpreter === "fish";
+  const shell =
+    run.interpreter === "bash" || run.interpreter === "zsh" || run.interpreter === "fish";
   const echo = shell
     ? `sed 's/^/$ /' -- ${shellQuote(codeFile)}`
     : `printf '# %s\\n' ${shellQuote(run.interpreter)}; cat -- ${shellQuote(codeFile)}`;
 
-  await writeFile(codeFile, `${run.code}\n`, "utf8");
   await writeFile(
     wrapper,
     [
@@ -338,6 +433,13 @@ async function writeScripts(run: Run): Promise<string> {
   return wrapper;
 }
 
+async function writeCode(run: Run): Promise<string> {
+  await mkdir(SCRIPT_DIR, { recursive: true });
+  const codeFile = path.join(SCRIPT_DIR, `${run.id}.${EXTENSIONS[run.interpreter]}`);
+  await writeFile(codeFile, `${run.code}\n`, "utf8");
+  return codeFile;
+}
+
 export async function cleanupScripts(): Promise<void> {
   await rm(SCRIPT_DIR, { recursive: true, force: true });
 }
@@ -353,7 +455,11 @@ function formatReport(run: Run): string {
           : "still running; partial output";
 
   let lines = run.output;
-  let note = run.truncated ? " (earlier lines scrolled out of the terminal)" : "";
+  let note = !run.truncated
+    ? ""
+    : run.mode === "background"
+      ? " (earlier lines were dropped)"
+      : " (earlier lines scrolled out of the terminal)";
   if (lines.length > REPORT_MAX_LINES) {
     note = ` (last ${REPORT_MAX_LINES} of ${lines.length} lines)`;
     lines = lines.slice(-REPORT_MAX_LINES);
@@ -364,8 +470,12 @@ function formatReport(run: Run): string {
     note = ` (last ${REPORT_MAX_CHARS} characters)`;
   }
 
+  const where =
+    run.mode === "background"
+      ? "in the background, with no terminal"
+      : `in the Paseo terminal "${TERMINAL_NAME}"`;
   return [
-    `I ran this in the Paseo terminal "${TERMINAL_NAME}" (cwd \`${run.cwd}\`), ${outcome}:`,
+    `I ran this ${where} (cwd \`${run.cwd}\`), ${outcome}:`,
     "",
     fenced(run.code, run.lang),
     "",
@@ -385,6 +495,62 @@ function withoutInterruptEcho(lines: string[]): string[] {
   return trimBlankEdges(lines.slice(0, end));
 }
 
+/** Terminals get the plugin's environment without the flag that runs Electron apps as Node. */
+function backgroundEnv(): NodeJS.ProcessEnv {
+  const { ELECTRON_RUN_AS_NODE: _electronAsNode, ...env } = process.env;
+  // Python block-buffers a pipe; unbuffered output keeps the card's tail live.
+  return { ...env, TERM: "dumb", PYTHONUNBUFFERED: "1" };
+}
+
+function signalGroup(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    // The group is already gone.
+  }
+}
+
+// Terminal output cleaning deliberately matches ANSI and control bytes.
+// oxlint-disable-next-line no-control-regex
+const ANSI_ESCAPE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?|[@-Z\\-_])/g;
+// oxlint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+
+/** Program output as a terminal would show it, without colors: `\r` rewrites the current line. */
+class OutputLines {
+  private readonly finished: string[] = [];
+  private current = "";
+  dropped = 0;
+
+  write(text: string): void {
+    const [first, ...rest] = text.replace(ANSI_ESCAPE, "").replace(CONTROL_CHARS, "").split("\n");
+    this.current += first;
+    for (const part of rest) {
+      this.finished.push(overwrite(this.current));
+      this.current = part;
+    }
+    if (this.current.length > BACKGROUND_MAX_LINE_CHARS) {
+      this.current = overwrite(this.current).slice(-BACKGROUND_MAX_LINE_CHARS);
+    }
+    const excess = this.finished.length - BACKGROUND_MAX_LINES;
+    if (excess > 0) {
+      this.finished.splice(0, excess);
+      this.dropped += excess;
+    }
+  }
+
+  lines(): string[] {
+    return this.current ? [...this.finished, overwrite(this.current)] : [...this.finished];
+  }
+}
+
+/** Each segment after a carriage return overwrites the line from its start. */
+function overwrite(line: string): string {
+  if (!line.includes("\r")) return line;
+  return line.split("\r").reduce((shown, segment) => segment + shown.slice(segment.length));
+}
+
 function lastIndexWhere<T>(items: readonly T[], predicate: (item: T) => boolean): number {
   for (let index = items.length - 1; index >= 0; index--) {
     if (predicate(items[index])) return index;

package/shared/code-blocks.ts

@@ -73,7 +73,8 @@ export function runnableBlocks(markdown: string): CodeBlock[] {
 function normalizeCommand(block: CodeBlock): string {
   const lines = block.code.split("\n");
   const prompted = lines.filter((line) => /^\s*\$ /.test(line));
-  const allPrompted = prompted.length > 0 && prompted.length === lines.filter((l) => l.trim()).length;
+  const allPrompted =
+    prompted.length > 0 && prompted.length === lines.filter((l) => l.trim()).length;
   if (!PROMPT_LANGUAGES.has(block.lang) && !allPrompted) return block.code;
   if (prompted.length === 0) return block.code;
   return prompted.map((line) => line.replace(/^\s*\$ /, "")).join("\n");
@@ -84,3 +85,14 @@ function stripIndent(line: string, indent: number): string {
   while (index < indent && line[index] === " ") index++;
   return line.slice(index);
 }
+
+export const RUNNABLE_LANGUAGES = Object.keys(INTERPRETERS);
+
+/** Receives one already-parsed fence from Paseo, never scans Markdown. */
+export function runnableBlock(code: string, language: string): CodeBlock | null {
+  const lang = language.toLowerCase();
+  if (!interpreterFor(lang)) return null;
+  const normalized = normalizeCommand({ code, lang }).trim();
+  if (!normalized || normalized.length > 8_000) return null;
+  return { lang, code: normalized };
+}

package/shared/contracts.ts

@@ -1,9 +1,18 @@
 import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
-import { panelLocations } from "./settings";
 
 export const TERMINAL_NAME = "Agent commands";
 
+export function inlineRunKey(
+  hostId: string,
+  agentId: string,
+  messageId: string,
+  blockIndex: number,
+): string {
+  return JSON.stringify([hostId, agentId, messageId, blockIndex]);
+}
+
+// COMPAT(legacyRunCards): added in the inline-actions fork, remove after 2027-04-01.
 export const RUN_CARD_KIND = "terminal-run-card";
 export const RUN_CARD_VERSION = 1;
 
@@ -17,9 +26,16 @@ export function runKey(cardId: string, blockIndex: number): string {
   return `${cardId}:${blockIndex}`;
 }
 
+/** `terminal` types the block into "Agent commands"; `background` runs it with no terminal and no stdin. */
+export const runModes = ["terminal", "background"] as const;
+export type RunMode = (typeof runModes)[number];
+
 export const runSnapshotSchema = z.object({
   runId: z.string(),
+  workspaceId: z.string(),
+  terminalId: z.string().nullable(),
   key: z.string(),
+  mode: z.enum(runModes),
   status: z.enum(["queued", "running", "done", "canceled", "failed"]),
   exitCode: z.number().int().nullable(),
   startedAt: z.number().nullable(),
@@ -39,8 +55,9 @@ export const startRun = defineRpc({
     agentId: z.string(),
     key: z.string(),
     lang: z.string(),
-    code: z.string().min(1),
+    code: z.string().min(1).max(8_000),
     send: z.boolean(),
+    mode: z.enum(runModes),
   }),
   output: runSnapshotSchema,
 });
@@ -66,34 +83,7 @@ export const sendRunOutput = defineRpc({
 export const runAdhoc = defineRpc({
   name: "run.adhoc",
   input: z.object({ agentId: z.string(), command: z.string().min(1) }),
-  output: z.object({ cardId: z.string(), panelLocation: z.enum(panelLocations) }),
-});
-
-const terminalSize = { rows: z.number().int().min(2).max(500), cols: z.number().int().min(10).max(1000) };
-
-export const openTerminalView = defineRpc({
-  name: "view.open",
-  input: z.object({ terminalId: z.string(), ...terminalSize }),
-  output: z.object({ viewId: z.string() }),
-});
-
-/** Long-polls for terminal output after `cursor`, which acknowledges everything before it. */
-export const readTerminalView = defineRpc({
-  name: "view.read",
-  input: z.object({ viewId: z.string(), cursor: z.number().int().nonnegative() }),
-  output: z.object({ data: z.string(), cursor: z.number().int(), closed: z.string().nullable() }),
-});
-
-export const resizeTerminalView = defineRpc({
-  name: "view.resize",
-  input: z.object({ viewId: z.string(), ...terminalSize }),
-  output: z.object({}),
-});
-
-export const closeTerminalView = defineRpc({
-  name: "view.close",
-  input: z.object({ viewId: z.string() }),
-  output: z.object({}),
+  output: z.object({ cardId: z.string() }),
 });
 
 export const scanBlocks = defineRpc({
@@ -102,6 +92,12 @@ export const scanBlocks = defineRpc({
   output: z.object({ count: z.number().int() }),
 });
 
+export const enableLegacyCards = defineRpc({
+  name: "legacy.cards.enable",
+  input: z.object({}),
+  output: z.object({ enabled: z.boolean() }),
+});
+
 export const searchTerminalOutput = defineRpc({
   name: "terminals.search",
   input: z.object({ query: z.string() }),

package/shared/settings.ts

@@ -1,19 +1,12 @@
 import { defineSettings } from "@getpaseo/plugin";
 import { z } from "zod";
 
-export const TERMINAL_PANEL_ID = "terminal";
-
-export const panelLocations = ["explorer", "workspace"] as const;
-export type PanelLocation = (typeof panelLocations)[number];
-
 export const preferences = defineSettings({
   id: "preferences",
   scope: "host",
   version: 1,
   schema: z.object({
-    /** Where "Run in side terminal", the Terminal button, and /run show the terminal panel. */
-    panelLocation: z.enum(panelLocations).default("explorer"),
-    /** Initial state of a run card's "Send to agent" checkbox. */
+    /** Initial state of a code block's "Send output to agent" checkbox. */
     sendToAgent: z.boolean().default(true),
   }),
 });

package/shared/text.ts

@@ -6,7 +6,7 @@ export function fenced(content: string, lang = ""): string {
 }
 
 /** Matches the run markers the runner prints, concealed, around command output. */
-export const RUN_MARKER = /__PTI_(?:BEGIN_[0-9a-f]+|END_[0-9a-f]+_\d+)__/g;
+const RUN_MARKER = /__PTI_(?:BEGIN_[0-9a-f]+|END_[0-9a-f]+_\d+)__/g;
 
 /** Removes the run markers from captured lines. */
 export function withoutRunMarkers(lines: readonly string[]): string[] {

package/client/panel-opener.ts

@@ -1,29 +0,0 @@
-import type { PluginClientContext } from "@getpaseo/plugin/client";
-import { TERMINAL_PANEL_ID, type PanelLocation } from "../shared/settings";
-
-type OpenPanel = PluginClientContext["openPanel"];
-
-// Timeline renderers receive no navigation, so the entry hands its openPanel capability here.
-let openPanel: OpenPanel | null = null;
-
-export function setPanelOpener(next: OpenPanel | null): void {
-  openPanel = next;
-}
-
-/**
- * Shows the terminal panel. Compact layouts have no Explorer, so they use a workspace tab and
- * only when asked explicitly: an automatic tab switch would hide the chat on a phone.
- */
-export function openTerminalPanel(
-  workspaceId: string,
-  where: PanelLocation,
-  { compact, explicit }: { compact: boolean; explicit: boolean },
-): void {
-  if (!openPanel || (compact && !explicit)) return;
-  const location = compact ? "workspace" : where;
-  try {
-    openPanel(TERMINAL_PANEL_ID, { workspaceId, location });
-  } catch {
-    if (location === "explorer") openPanel(TERMINAL_PANEL_ID, { workspaceId, location: "workspace" });
-  }
-}