paseo-terminal-integration 0.1.0 → 0.3.0

package/README.md

@@ -6,15 +6,26 @@ Two-way bridge between agent chats and Paseo terminals.
 (`bash`, `sh`, `shell`, `console`, `zsh`, `fish`, `python`, `js`/`node`) get a **Run in terminal**
 card under the reply:
 
-- **Run & send to agent** runs the block in the workspace terminal "Agent commands" and, when it
-  finishes, sends the command, exit code, and output to the agent as a new message. If the agent is
-  busy, delivery waits until its turn ends instead of interrupting it.
-- **Run only** runs it without sending; **Send output** sends it later.
+- **Run** runs the block in the workspace terminal "Agent commands", a regular Paseo terminal tab.
+- **Run in background** runs it as a hidden process in the agent's working directory: no terminal
+  tab, and the card keeps the last 5,000 lines instead of what fits on a terminal screen. Nothing
+  can be typed into it: stdin is empty, so password and confirmation prompts fail instead of
+  waiting. Background runs do not wait for the terminal.
+- With **Send output to agent** checked (the default), the command, exit code, and output go to
+  the agent as a new message when the block finishes. If the agent is busy, delivery waits until
+  its turn ends instead of interrupting it. Unchecked, **Send output** sends it later.
 - **Stop** sends Ctrl-C; **Send output so far** reports a still-running command.
 
-The terminal is a real PTY, so prompts (`sudo`, `y/n`) can be answered in the terminal tab. Runs in
-one workspace are queued so a command never types into another one's stdin. Each block runs as a
-script in the agent's working directory, so `cd` and `export` do not persist between runs.
+**Terminal beside the chat.** "Agent commands" opens as a background tab. Drag the tab onto the
+right or bottom edge of the chat to split the workspace; it stays there while the terminal is open,
+so you can watch runs and type answers to `sudo` passwords or `y/n` questions next to the
+conversation. From the keyboard, split the pane and move the tab into it with the shortcuts in
+**Settings → Shortcuts → Tabs & panes**. Closing the tab ends the terminal; the next run starts a
+new one in a new tab.
+
+Terminal runs in one workspace are queued so a command never types into another one's stdin.
+Each block runs as a script in the agent's working directory, so `cd` and `export` do not persist
+between runs. **Settings → Plugins → Terminal integration** sets the checkbox's default.
 
 **Terminal → agent.** In the composer's attachment menu, **Terminal output** attaches the latest
 lines of any terminal on the daemon. Type part of a name or path to filter, and a number to choose
@@ -44,9 +55,10 @@ Nothing runs until you press a button or submit `/run`.
 
 ## Limitations
 
-- Output is read from the terminal screen, so very long lines arrive wrapped and only the last
+- Terminal output is read from the screen, so very long lines arrive wrapped and only the last
   3,000 rows are visible. The agent receives at most 300 lines or 24,000 characters.
 - Run state lives in the plugin process; reloading the plugin forgets it (the cards stay).
+- Plugins cannot split panes or move tabs, so placing the terminal beside the chat is up to you.
 - A command that has not started within 20 seconds fails, for example when something else is
   running in "Agent commands".
 
@@ -60,6 +72,14 @@ paseo plugin reload terminal-integration
 paseo plugin logs terminal-integration
 ```
 
+To release, bump the version and push the tag; GitHub Actions publishes it to npm through trusted
+publishing, and Paseo Cafe picks up the new version from there:
+
+```bash
+npm version patch   # or minor; commits and tags vX.Y.Z
+git push --follow-tags
+```
+
 ## License
 
 MIT

package/client/run-card.tsx

@@ -1,4 +1,4 @@
-import { useRpc, type PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { useRpc, useSettings, type PluginTimelineItemProps } from "@getpaseo/plugin/client";
 import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useMemo, useState } from "react";
@@ -11,8 +11,10 @@ import {
   startRun,
   TERMINAL_NAME,
   type RunCardData,
+  type RunMode,
   type RunSnapshot,
 } from "../shared/contracts";
+import { preferences } from "../shared/settings";
 
 type Theme = PluginTimelineItemProps["theme"];
 type Styles = ReturnType<typeof createStyles>;
@@ -42,6 +44,17 @@ export function RunCard({ item, agentId, theme, layout }: PluginTimelineItemProp
   const cancel = useRpc(cancelRun);
   const send = useRpc(sendRunOutput);
 
+  const settings = useSettings(preferences);
+  const [sendChoice, setSendChoice] = useState<boolean | null>(null);
+  const sendToAgent =
+    sendChoice ?? (settings.status === "ready" ? settings.values.sendToAgent : true);
+
+  function runBlock(key: string, block: RunCardData["blocks"][number], mode: RunMode) {
+    return act(key, () =>
+      start({ agentId, key, lang: block.lang, code: block.code, send: sendToAgent, mode }),
+    );
+  }
+
   const queryKey = useMemo(() => ["terminal-run-status", cardId], [cardId]);
   const status = useQuery({
     queryKey,
@@ -73,6 +86,14 @@ export function RunCard({ item, agentId, theme, layout }: PluginTimelineItemProp
         <Text style={styles.muted} numberOfLines={1}>
           · {TERMINAL_NAME}
         </Text>
+        <View style={styles.spacer} />
+        <Checkbox
+          styles={styles}
+          theme={theme}
+          label="Send output to agent"
+          checked={sendToAgent}
+          onChange={setSendChoice}
+        />
       </View>
       {blocks.map((block, index) => {
         const key = keys[index];
@@ -116,22 +137,18 @@ export function RunCard({ item, agentId, theme, layout }: PluginTimelineItemProp
                     styles={styles}
                     theme={theme}
                     icon="Play"
-                    label={run ? "Run again & send" : "Run & send to agent"}
+                    label="Run"
                     tone="primary"
                     disabled={busy || active}
-                    onPress={() =>
-                      act(key, () => start({ agentId, key, lang: block.lang, code: block.code, send: true }))
-                    }
+                    onPress={() => runBlock(key, block, "terminal")}
                   />
                   <ActionButton
                     styles={styles}
                     theme={theme}
-                    icon="SquareTerminal"
-                    label="Run only"
+                    icon="EyeOff"
+                    label="Run in background"
                     disabled={busy || active}
-                    onPress={() =>
-                      act(key, () => start({ agentId, key, lang: block.lang, code: block.code, send: false }))
-                    }
+                    onPress={() => runBlock(key, block, "background")}
                   />
                   {run && !run.sent && !active ? (
                     <ActionButton
@@ -170,7 +187,9 @@ function RunStatus({ run, styles }: { run: RunSnapshot; styles: Styles }) {
   const parts: string[] = [];
   let tone: TextStyle = styles.muted;
   if (run.status === "queued") parts.push("Queued, waiting for the terminal");
-  if (run.status === "running") parts.push(`Running · ${elapsed(run)}`);
+  if (run.status === "running") {
+    parts.push(`${run.mode === "background" ? "Running in background" : "Running"} · ${elapsed(run)}`);
+  }
   if (run.status === "done") {
     parts.push(`${run.exitCode === 0 ? "✓" : "✗"} exit ${run.exitCode}`);
     tone = run.exitCode === 0 ? styles.success : styles.danger;
@@ -203,6 +222,37 @@ function RunStatus({ run, styles }: { run: RunSnapshot; styles: Styles }) {
   );
 }
 
+function Checkbox({
+  styles,
+  theme,
+  label,
+  checked,
+  onChange,
+}: {
+  styles: Styles;
+  theme: Theme;
+  label: string;
+  checked: boolean;
+  onChange(checked: boolean): void;
+}) {
+  return (
+    <Pressable
+      accessibilityRole="checkbox"
+      accessibilityLabel={label}
+      accessibilityState={{ checked }}
+      onPress={() => onChange(!checked)}
+      style={({ pressed }) => [styles.checkbox, { opacity: pressed ? 0.75 : 1 }]}
+    >
+      <Icon
+        name={checked ? "SquareCheck" : "Square"}
+        size={16}
+        color={checked ? theme.colors.accent : theme.colors.foregroundMuted}
+      />
+      <Text style={[styles.buttonText, { color: theme.colors.foreground }]}>{label}</Text>
+    </Pressable>
+  );
+}
+
 function ActionButton({
   styles,
   theme,
@@ -260,9 +310,22 @@ function createStyles(theme: Theme, compact: boolean) {
       padding: compact ? 10 : 12,
       backgroundColor: theme.colors.surface1,
     },
-    header: { flexDirection: "row" as const, alignItems: "center" as const, gap: 6 },
+    header: {
+      flexDirection: "row" as const,
+      flexWrap: "wrap" as const,
+      alignItems: "center" as const,
+      gap: 6,
+    },
+    checkbox: {
+      flexDirection: "row" as const,
+      alignItems: "center" as const,
+      gap: 6,
+      paddingHorizontal: 4,
+      paddingVertical: compact ? 7 : 5,
+    },
     title: { color: theme.colors.foreground, fontWeight: "600" as const },
     muted: { color: theme.colors.foregroundMuted, flexShrink: 1 },
+    spacer: { flex: 1 },
     success: { color: theme.colors.statusSuccess },
     danger: { color: theme.colors.statusDanger },
     block: { gap: 8 },

package/client/settings-screen.tsx

@@ -0,0 +1,40 @@
+import { useSettings, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import {
+  SettingsCard,
+  SettingsRow,
+  SettingsSection,
+  SettingsSwitch,
+} from "@getpaseo/plugin/client/ui";
+import { Text } from "react-native";
+import { TERMINAL_NAME } from "../shared/contracts";
+import { preferences } from "../shared/settings";
+
+export function SettingsScreen({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(preferences);
+
+  if (settings.status !== "ready") {
+    const message =
+      settings.status === "loading" ? "Loading…" : `Settings are unavailable: ${settings.error}`;
+    return <Text style={{ color: theme.colors.foregroundMuted }}>{message}</Text>;
+  }
+  const { values, revision } = settings;
+
+  return (
+    <SettingsSection title="Run cards">
+      <SettingsCard>
+        <SettingsSwitch
+          label="Send output to the agent by default"
+          hint={`Initial state of the "Send output to agent" checkbox on each run card.`}
+          value={values.sendToAgent}
+          disabled={settings.saving}
+          error={settings.saveError}
+          onValueChange={(sendToAgent) => void settings.save({ ...values, sendToAgent }, revision)}
+        />
+        <SettingsRow
+          label="Where the terminal appears"
+          hint={`Commands run in the "${TERMINAL_NAME}" terminal tab. To keep it beside the chat, drag the tab onto the right or bottom edge of the chat; it stays there while the terminal is open.`}
+        />
+      </SettingsCard>
+    </SettingsSection>
+  );
+}

package/index.client.tsx

@@ -1,5 +1,7 @@
+import type { PluginCleanup } from "@getpaseo/plugin";
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { RunCard } from "./client/run-card";
+import { SettingsScreen } from "./client/settings-screen";
 import {
   RUN_CARD_KIND,
   RUN_CARD_VERSION,
@@ -9,7 +11,8 @@ import {
   terminalOutputSource,
 } from "./shared/contracts";
 
-export default function contribute(client: PluginClientContext) {
+// A function declaration: the host reads the default export before the module body has run.
+export default function contribute(client: PluginClientContext): PluginCleanup {
   client.addTimelineRenderer({
     kind: RUN_CARD_KIND,
     version: RUN_CARD_VERSION,
@@ -17,6 +20,13 @@ export default function contribute(client: PluginClientContext) {
     Component: RunCard,
   });
 
+  client.addSettingsScreen({
+    id: "preferences",
+    title: "Terminal integration",
+    icon: "SquareTerminal",
+    Component: SettingsScreen,
+  });
+
   client.addAttachmentSource(terminalOutputSource);
 
   client.addSlashCommand({

package/index.server.ts

@@ -2,6 +2,7 @@ import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { searchTerminals } from "./server/attachments";
 import { appendCardForTurn, appendRunCard, scanLatestReply } from "./server/cards";
 import { cleanupScripts, TerminalRunner } from "./server/runner";
+import { preferences } from "./shared/settings";
 import {
   cancelRun,
   runAdhoc,
@@ -14,6 +15,7 @@ import {
 } from "./shared/contracts";
 
 export default function contribute(server: PluginServerContext) {
+  server.registerSettings(preferences);
   let runner: TerminalRunner | null = null;
   const runnerFor = (paseo: ConstructorParameters<typeof TerminalRunner>[0]) =>
     (runner ??= new TerminalRunner(paseo));
@@ -29,7 +31,13 @@ export default function contribute(server: PluginServerContext) {
     const block = { lang: "bash", code: command };
     const cardId = await appendRunCard(paseo, agentId, [block]);
     if (!cardId) throw new Error("Command is too long");
-    await runnerFor(paseo).start({ agentId, key: runKey(cardId, 0), ...block, send: true });
+    await runnerFor(paseo).start({
+      agentId,
+      key: runKey(cardId, 0),
+      ...block,
+      send: true,
+      mode: "terminal",
+    });
     return { cardId };
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-terminal-integration",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "files": [
     "paseo-plugin.json",
     "index.client.tsx",

package/server/attachments.ts

@@ -2,7 +2,7 @@ import { pathToFileURL } from "node:url";
 import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import type { searchTerminalOutput } from "../shared/contracts";
-import { fenced, trimBlankEdges, withoutRunMarkers } from "./text";
+import { fenced, trimBlankEdges, withoutRunMarkers } from "../shared/text";
 
 const DEFAULT_LINES = 200;
 const MAX_LINES = 2_000;

package/server/runner.ts

@@ -1,11 +1,13 @@
+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 { fenced, trimBlankEdges } from "./text";
+import { TERMINAL_NAME, type RunMode, type RunSnapshot } from "../shared/contracts";
+import { fenced, trimBlankEdges } from "../shared/text";
 
 type Paseo = PluginHandlerContext["paseo"];
 type TerminalHandle = ReturnType<Paseo["terminals"]["ref"]>;
@@ -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,19 @@ 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 +152,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 +177,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 +190,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 +256,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);
@@ -290,6 +381,7 @@ function snapshot(run: Run): RunSnapshot {
   return {
     runId: run.id,
     key: run.key,
+    mode: run.mode,
     status: run.status,
     exitCode: run.exitCode,
     startedAt: run.startedAt,
@@ -308,15 +400,13 @@ 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 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 +428,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 +450,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 +465,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 +490,59 @@ 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.
+  }
+}
+
+const ANSI_ESCAPE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?|[@-Z\\-_])/g;
+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/contracts.ts

@@ -16,9 +16,14 @@ 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(),
   key: z.string(),
+  mode: z.enum(runModes),
   status: z.enum(["queued", "running", "done", "canceled", "failed"]),
   exitCode: z.number().int().nullable(),
   startedAt: z.number().nullable(),
@@ -40,6 +45,7 @@ export const startRun = defineRpc({
     lang: z.string(),
     code: z.string().min(1),
     send: z.boolean(),
+    mode: z.enum(runModes),
   }),
   output: runSnapshotSchema,
 });

package/shared/settings.ts

@@ -0,0 +1,12 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const preferences = defineSettings({
+  id: "preferences",
+  scope: "host",
+  version: 1,
+  schema: z.object({
+    /** Initial state of a run card's "Send output to agent" checkbox. */
+    sendToAgent: z.boolean().default(true),
+  }),
+});

package/{server → shared}/text.ts

@@ -5,11 +5,14 @@ export function fenced(content: string, lang = ""): string {
   return `${fence}${lang}\n${content}\n${fence}`;
 }
 
-/** Removes the run markers the runner prints around command output. */
+/** Matches the run markers the runner prints, concealed, around command output. */
+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[] {
   return lines
     .filter((line) => !/^\s*__PTI_BEGIN_[0-9a-f]+__\s*$/.test(line))
-    .map((line) => line.replace(/__PTI_(?:BEGIN_[0-9a-f]+|END_[0-9a-f]+_\d+)__/g, ""));
+    .map((line) => line.replace(RUN_MARKER, ""));
 }
 
 export function trimBlankEdges(lines: readonly string[]): string[] {