paseo-terminal-integration 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chechulin Serhii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Terminal integration for Paseo
+
+Two-way bridge between agent chats and Paseo terminals.
+
+**Agent → terminal.** When a turn ends, runnable fenced code blocks in the agent's reply
+(`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.
+- **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 → 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
+the line count (`build 500`; default 200).
+
+## Install
+
+Requires Paseo 0.10.1 or later and a macOS or Linux daemon host with `bash` (plus `python3` or
+`node` for those blocks). Enable plugins under **Settings → Plugins**, then:
+
+```bash
+paseo plugin install npm:paseo-terminal-integration
+# or from GitHub
+paseo plugin install github:keefeere/paseo-terminal-integration
+```
+
+Plugins are trusted, unsandboxed code: this one types commands into terminals on the daemon host.
+Nothing runs until you press a button or submit `/run`.
+
+## Commands
+
+| Command                                         | Effect                                                      |
+| ----------------------------------------------- | ----------------------------------------------------------- |
+| `/run <command>`                                | Run a shell command and send its output to the agent        |
+| `/blocks`                                       | Add a run card for the latest reply (e.g. older chats)      |
+| ⌘K / Ctrl+K → "Terminal: add run buttons to …"  | Same as `/blocks`                                           |
+
+## Limitations
+
+- Output is read from the terminal 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).
+- A command that has not started within 20 seconds fails, for example when something else is
+  running in "Agent commands".
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+paseo plugin install "$PWD"   # first time
+paseo plugin reload terminal-integration
+paseo plugin logs terminal-integration
+```
+
+## License
+
+MIT

package/client/run-card.tsx

@@ -0,0 +1,309 @@
+import { useRpc, 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";
+import { Platform, Pressable, Text, View, type TextStyle } from "react-native";
+import {
+  cancelRun,
+  runKey,
+  runStatus,
+  sendRunOutput,
+  startRun,
+  TERMINAL_NAME,
+  type RunCardData,
+  type RunSnapshot,
+} from "../shared/contracts";
+
+type Theme = PluginTimelineItemProps["theme"];
+type Styles = ReturnType<typeof createStyles>;
+
+const POLL_MS = 700;
+const MONOSPACE = Platform.select({
+  ios: "Menlo",
+  android: "monospace",
+  default: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+});
+
+function isActive(run: RunSnapshot): boolean {
+  if (run.status === "queued" || run.status === "running" || run.sending) return true;
+  return run.status === "done" && run.sendOnFinish && !run.sent && !run.error;
+}
+
+export function RunCard({ item, agentId, theme, layout }: PluginTimelineItemProps<RunCardData>) {
+  const { cardId, blocks } = item.data;
+  const keys = useMemo(() => blocks.map((_, index) => runKey(cardId, index)), [cardId, blocks]);
+  const styles = useMemo(() => createStyles(theme, layout.compact), [theme, layout.compact]);
+  const toast = useToast();
+  const queryClient = useQueryClient();
+  const [pending, setPending] = useState<string | null>(null);
+
+  const fetchStatus = useRpc(runStatus);
+  const start = useRpc(startRun);
+  const cancel = useRpc(cancelRun);
+  const send = useRpc(sendRunOutput);
+
+  const queryKey = useMemo(() => ["terminal-run-status", cardId], [cardId]);
+  const status = useQuery({
+    queryKey,
+    queryFn: () => fetchStatus({ keys }),
+    refetchInterval: (query) => (query.state.data?.runs.some(isActive) ? POLL_MS : false),
+  });
+  const runs = useMemo(
+    () => new Map((status.data?.runs ?? []).map((run) => [run.key, run])),
+    [status.data],
+  );
+
+  async function act(key: string, action: () => Promise<unknown>) {
+    setPending(key);
+    try {
+      await action();
+      await queryClient.invalidateQueries({ queryKey });
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : String(error));
+    } finally {
+      setPending(null);
+    }
+  }
+
+  return (
+    <View style={styles.card}>
+      <View style={styles.header}>
+        <Icon name="SquareTerminal" size={16} color={theme.colors.foregroundMuted} />
+        <Text style={styles.title}>Run in terminal</Text>
+        <Text style={styles.muted} numberOfLines={1}>
+          · {TERMINAL_NAME}
+        </Text>
+      </View>
+      {blocks.map((block, index) => {
+        const key = keys[index];
+        const run = runs.get(key);
+        const active = run ? isActive(run) : false;
+        const busy = pending === key;
+        return (
+          <View key={key} style={index > 0 ? [styles.block, styles.separated] : styles.block}>
+            <View style={styles.codeRow}>
+              <Text style={styles.lang}>{block.lang}</Text>
+              <Text style={styles.code} numberOfLines={3}>
+                {block.code}
+              </Text>
+            </View>
+            <View style={styles.actions}>
+              {run && (run.status === "queued" || run.status === "running") ? (
+                <>
+                  <ActionButton
+                    styles={styles}
+                    theme={theme}
+                    icon="Square"
+                    label="Stop"
+                    tone="danger"
+                    disabled={busy}
+                    onPress={() => act(key, () => cancel({ key }))}
+                  />
+                  {run.status === "running" && !run.sendOnFinish ? (
+                    <ActionButton
+                      styles={styles}
+                      theme={theme}
+                      icon="Send"
+                      label="Send output so far"
+                      disabled={busy || run.sending}
+                      onPress={() => act(key, () => send({ key }))}
+                    />
+                  ) : null}
+                </>
+              ) : (
+                <>
+                  <ActionButton
+                    styles={styles}
+                    theme={theme}
+                    icon="Play"
+                    label={run ? "Run again & send" : "Run & send to agent"}
+                    tone="primary"
+                    disabled={busy || active}
+                    onPress={() =>
+                      act(key, () => start({ agentId, key, lang: block.lang, code: block.code, send: true }))
+                    }
+                  />
+                  <ActionButton
+                    styles={styles}
+                    theme={theme}
+                    icon="SquareTerminal"
+                    label="Run only"
+                    disabled={busy || active}
+                    onPress={() =>
+                      act(key, () => start({ agentId, key, lang: block.lang, code: block.code, send: false }))
+                    }
+                  />
+                  {run && !run.sent && !active ? (
+                    <ActionButton
+                      styles={styles}
+                      theme={theme}
+                      icon="Send"
+                      label="Send output"
+                      disabled={busy}
+                      onPress={() => act(key, () => send({ key }))}
+                    />
+                  ) : null}
+                </>
+              )}
+              <ActionButton
+                styles={styles}
+                theme={theme}
+                icon="Copy"
+                label="Copy"
+                onPress={() =>
+                  act(key, async () => {
+                    await copyText(block.code);
+                    toast.show("Command copied", { variant: "success" });
+                  })
+                }
+              />
+            </View>
+            {run ? <RunStatus run={run} styles={styles} /> : null}
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
+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 === "done") {
+    parts.push(`${run.exitCode === 0 ? "✓" : "✗"} exit ${run.exitCode}`);
+    tone = run.exitCode === 0 ? styles.success : styles.danger;
+  }
+  if (run.status === "canceled") parts.push("Stopped");
+  if (run.status === "failed") tone = styles.danger;
+  if (run.status !== "queued" && run.status !== "failed") {
+    parts.push(`${run.lineCount} ${run.lineCount === 1 ? "line" : "lines"}`);
+  }
+  if (run.sent) parts.push("sent to agent");
+  else if (run.sending) parts.push("sending when the agent is idle…");
+  else if (run.sendOnFinish && (run.status === "queued" || run.status === "running")) {
+    parts.push("output goes to the agent");
+  }
+
+  return (
+    <View style={styles.status}>
+      {parts.length > 0 ? <Text style={tone}>{parts.join(" · ")}</Text> : null}
+      {run.error ? <Text style={styles.danger}>{run.error}</Text> : null}
+      {run.tail.length > 0 ? (
+        <View style={styles.tail}>
+          {run.tail.map((line, index) => (
+            <Text key={index} style={styles.tailLine} numberOfLines={1}>
+              {line || " "}
+            </Text>
+          ))}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+function ActionButton({
+  styles,
+  theme,
+  icon,
+  label,
+  tone = "default",
+  disabled = false,
+  onPress,
+}: {
+  styles: Styles;
+  theme: Theme;
+  icon: string;
+  label: string;
+  tone?: "default" | "primary" | "danger";
+  disabled?: boolean;
+  onPress(): void;
+}) {
+  const color =
+    tone === "primary"
+      ? theme.colors.accentForeground
+      : tone === "danger"
+        ? theme.colors.statusDanger
+        : theme.colors.foreground;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      accessibilityState={{ disabled }}
+      disabled={disabled}
+      onPress={onPress}
+      style={({ pressed }) => [
+        styles.button,
+        tone === "primary" ? styles.primaryButton : null,
+        { opacity: disabled ? 0.5 : pressed ? 0.75 : 1 },
+      ]}
+    >
+      <Icon name={icon} size={14} color={color} />
+      <Text style={[styles.buttonText, { color }]}>{label}</Text>
+    </Pressable>
+  );
+}
+
+function elapsed(run: RunSnapshot): string {
+  const seconds = Math.max(0, Math.round((Date.now() - (run.startedAt ?? Date.now())) / 1000));
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+
+function createStyles(theme: Theme, compact: boolean) {
+  return {
+    card: {
+      gap: compact ? 8 : 10,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      borderRadius: 10,
+      padding: compact ? 10 : 12,
+      backgroundColor: theme.colors.surface1,
+    },
+    header: { flexDirection: "row" as const, alignItems: "center" as const, gap: 6 },
+    title: { color: theme.colors.foreground, fontWeight: "600" as const },
+    muted: { color: theme.colors.foregroundMuted, flexShrink: 1 },
+    success: { color: theme.colors.statusSuccess },
+    danger: { color: theme.colors.statusDanger },
+    block: { gap: 8 },
+    separated: {
+      borderTopWidth: 1,
+      borderTopColor: theme.colors.border,
+      paddingTop: compact ? 8 : 10,
+    },
+    codeRow: { flexDirection: "row" as const, gap: 8, alignItems: "flex-start" as const },
+    lang: {
+      color: theme.colors.foregroundMuted,
+      fontSize: 12,
+      paddingHorizontal: 6,
+      paddingVertical: 2,
+      borderRadius: 4,
+      backgroundColor: theme.colors.surface2,
+      overflow: "hidden" as const,
+    },
+    code: { color: theme.colors.foreground, fontFamily: MONOSPACE, fontSize: 13, flex: 1 },
+    actions: { flexDirection: "row" as const, flexWrap: "wrap" as const, gap: 8 },
+    button: {
+      flexDirection: "row" as const,
+      alignItems: "center" as const,
+      gap: 6,
+      paddingHorizontal: 10,
+      paddingVertical: compact ? 7 : 5,
+      borderRadius: 6,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      backgroundColor: theme.colors.surface2,
+    },
+    primaryButton: { backgroundColor: theme.colors.accent, borderColor: theme.colors.accent },
+    buttonText: { fontSize: 13 },
+    status: { gap: 6 },
+    tail: {
+      padding: 8,
+      borderRadius: 6,
+      backgroundColor: theme.colors.surface0,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+    },
+    tailLine: { color: theme.colors.foregroundMuted, fontFamily: MONOSPACE, fontSize: 12 },
+  };
+}

package/index.client.tsx

@@ -0,0 +1,56 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { RunCard } from "./client/run-card";
+import {
+  RUN_CARD_KIND,
+  RUN_CARD_VERSION,
+  runAdhoc,
+  runCardSchema,
+  scanBlocks,
+  terminalOutputSource,
+} from "./shared/contracts";
+
+export default function contribute(client: PluginClientContext) {
+  client.addTimelineRenderer({
+    kind: RUN_CARD_KIND,
+    version: RUN_CARD_VERSION,
+    schema: runCardSchema,
+    Component: RunCard,
+  });
+
+  client.addAttachmentSource(terminalOutputSource);
+
+  client.addSlashCommand({
+    name: "run",
+    description: "Run a shell command in the workspace terminal and send its output to the agent",
+    argumentHint: "<command>",
+    context: "agent",
+    async onSubmit({ args, agent, rpc }) {
+      if (!args) throw new Error("Usage: /run <command>");
+      await rpc(runAdhoc, { agentId: agent.id, command: args });
+    },
+  });
+
+  async function addRunButtons(agentId: string, rpc: PluginClientContext["rpc"]) {
+    const { count } = await rpc(scanBlocks, { agentId });
+    if (count === 0) throw new Error("The latest reply has no runnable code blocks");
+  }
+
+  client.addSlashCommand({
+    name: "blocks",
+    description: "Add terminal run buttons for code blocks in the agent's latest reply",
+    argumentHint: "",
+    context: "agent",
+    onSubmit: ({ agent, rpc }) => addRunButtons(agent.id, rpc),
+  });
+
+  client.addCommandCenterItem({
+    id: "scan-latest-reply",
+    title: "Terminal: add run buttons to the latest reply",
+    icon: "SquareTerminal",
+    keywords: ["run", "code block", "terminal", "execute"],
+    context: "agent",
+    onSelect: ({ agent, rpc }) => addRunButtons(agent.id, rpc),
+  });
+
+  return () => {};
+}

package/index.server.ts

@@ -0,0 +1,46 @@
+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 {
+  cancelRun,
+  runAdhoc,
+  runKey,
+  runStatus,
+  scanBlocks,
+  searchTerminalOutput,
+  sendRunOutput,
+  startRun,
+} from "./shared/contracts";
+
+export default function contribute(server: PluginServerContext) {
+  let runner: TerminalRunner | null = null;
+  const runnerFor = (paseo: ConstructorParameters<typeof TerminalRunner>[0]) =>
+    (runner ??= new TerminalRunner(paseo));
+
+  server.on("agent.turn_ended", (event, { paseo }) => appendCardForTurn(paseo, event));
+
+  server.handle(startRun, (input, { paseo }) => runnerFor(paseo).start(input));
+  server.handle(runStatus, ({ keys }, { paseo }) => ({ runs: runnerFor(paseo).status(keys) }));
+  server.handle(cancelRun, ({ key }, { paseo }) => runnerFor(paseo).cancel(key));
+  server.handle(sendRunOutput, ({ key }, { paseo }) => runnerFor(paseo).sendOutput(key));
+
+  server.handle(runAdhoc, async ({ agentId, command }, { paseo }) => {
+    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 });
+    return { cardId };
+  });
+
+  server.handle(scanBlocks, async ({ agentId }, { paseo }) => ({
+    count: await scanLatestReply(paseo, agentId),
+  }));
+
+  server.handle(searchTerminalOutput, searchTerminals);
+
+  return async () => {
+    runner?.stop();
+    await cleanupScripts();
+  };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "paseo-terminal-integration",
+  "version": "0.1.0",
+  "files": [
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.10.1",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^26.6.2",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  },
+  "description": "Run agent code blocks in a Paseo terminal and send the output back to the agent; attach terminal output to prompts",
+  "license": "MIT",
+  "author": "Chechulin Serhii",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keefeere/paseo-terminal-integration.git"
+  },
+  "homepage": "https://github.com/keefeere/paseo-terminal-integration#readme",
+  "bugs": {
+    "url": "https://github.com/keefeere/paseo-terminal-integration/issues"
+  },
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "terminal",
+    "agents"
+  ]
+}

package/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "terminal-integration",
+  "description": "Run agent code blocks in a Paseo terminal and send terminal output back to the agent",
+  "requirements": {
+    "paseo": ">=0.10.1"
+  }
+}

package/server/attachments.ts

@@ -0,0 +1,62 @@
+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";
+
+const DEFAULT_LINES = 200;
+const MAX_LINES = 2_000;
+const MAX_RESULTS = 20;
+
+/** Lists every terminal on the daemon with a snapshot of its latest lines. */
+export async function searchTerminals(
+  { query }: RpcInput<typeof searchTerminalOutput>,
+  { paseo }: PluginHandlerContext,
+): Promise<RpcOutput<typeof searchTerminalOutput>> {
+  const { lineCount, filter } = parseQuery(query);
+  const [{ entries }, workspaces] = await Promise.all([
+    paseo.terminals.list(),
+    paseo.workspaces.list().catch(() => null),
+  ]);
+  const workspaceNames = new Map(
+    (workspaces?.entries ?? []).map((workspace) => [workspace.id, workspace.name]),
+  );
+
+  const matches = entries
+    .filter((entry) => {
+      if (!filter) return true;
+      const haystack = `${entry.name} ${entry.cwd} ${workspaceNames.get(entry.workspaceId) ?? ""}`;
+      return haystack.toLowerCase().includes(filter);
+    })
+    .slice(0, MAX_RESULTS);
+
+  const items = await Promise.all(
+    matches.map(async (entry) => {
+      const capture = await paseo.terminals.ref(entry).capture({ start: -lineCount, stripAnsi: true });
+      const lines = trimBlankEdges(withoutRunMarkers(capture.lines));
+      const name = entry.name || "Terminal";
+      const workspace = workspaceNames.get(entry.workspaceId);
+      return {
+        id: `${entry.id}:${lineCount}`,
+        identifier: name,
+        title: `${name} · last ${lines.length} lines`,
+        subtitle: workspace ? `${workspace} · ${entry.cwd}` : entry.cwd,
+        url: pathToFileURL(entry.cwd).href,
+        resourceType: "terminal-output",
+        text: [
+          `Output of the Paseo terminal "${name}" (cwd \`${entry.cwd}\`), last ${lines.length} lines:`,
+          "",
+          fenced(lines.join("\n"), "text"),
+        ].join("\n"),
+      };
+    }),
+  );
+  return { items };
+}
+
+function parseQuery(query: string): { lineCount: number; filter: string } {
+  const number = /(?:^|\s)(\d{1,5})(?:\s|$)/.exec(query);
+  const lineCount = number ? Math.min(MAX_LINES, Math.max(1, Number(number[1]))) : DEFAULT_LINES;
+  const filter = (number ? query.replace(number[0], " ") : query).trim().toLowerCase();
+  return { lineCount, filter };
+}

package/server/cards.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from "node:crypto";
+import type { PluginHandlerContext, PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import { runnableBlocks, type CodeBlock } from "../shared/code-blocks";
+import { RUN_CARD_KIND, RUN_CARD_VERSION, type RunCardData } from "../shared/contracts";
+
+type Paseo = PluginHandlerContext["paseo"];
+type TimelineItem = PluginLifecycleEvents["agent.turn_ended"]["timeline"][number];
+
+const MAX_CARD_BYTES = 60 * 1024;
+const SCAN_LIMIT = 400;
+
+/**
+ * Assistant text after the latest user message. Consecutive assistant items are stream chunks of
+ * one message; any other item between them separates messages.
+ */
+export function latestAssistantText(timeline: readonly TimelineItem[]): string {
+  let text = "";
+  let previous: TimelineItem["type"] | null = null;
+  for (const item of timeline) {
+    if (item.type === "user_message") {
+      text = "";
+    } else if (item.type === "assistant_message") {
+      if (previous !== "assistant_message" && text) text += "\n\n";
+      text += item.text;
+    }
+    previous = item.type;
+  }
+  return text;
+}
+
+export async function appendRunCard(
+  paseo: Paseo,
+  agentId: string,
+  blocks: CodeBlock[],
+): Promise<string | null> {
+  const fitting: CodeBlock[] = [];
+  for (const block of blocks) {
+    const data: RunCardData = { cardId: "", blocks: [...fitting, block] };
+    if (JSON.stringify(data).length > MAX_CARD_BYTES) break;
+    fitting.push(block);
+  }
+  if (fitting.length === 0) return null;
+
+  const cardId = randomUUID();
+  const data: RunCardData = { cardId, blocks: fitting };
+  await paseo.agents.ref(agentId).timeline.append({
+    type: "plugin",
+    id: cardId,
+    kind: RUN_CARD_KIND,
+    version: RUN_CARD_VERSION,
+    data,
+  });
+  return cardId;
+}
+
+export async function appendCardForTurn(
+  paseo: Paseo,
+  event: PluginLifecycleEvents["agent.turn_ended"],
+): Promise<void> {
+  if (event.outcome.kind !== "completed") return;
+  const blocks = runnableBlocks(latestAssistantText(event.timeline));
+  if (blocks.length > 0) await appendRunCard(paseo, event.agent.id, blocks);
+}
+
+/** Re-scans the latest reply, for conversations that predate the plugin. */
+export async function scanLatestReply(paseo: Paseo, agentId: string): Promise<number> {
+  const page = await paseo.agents
+    .ref(agentId)
+    .timeline.refetch({ direction: "tail", limit: SCAN_LIMIT, projection: "projected" });
+  if (page.error) throw new Error(page.error);
+  const blocks = runnableBlocks(latestAssistantText(page.entries.map((entry) => entry.item)));
+  if (blocks.length === 0) return 0;
+  await appendRunCard(paseo, agentId, blocks);
+  return blocks.length;
+}

package/server/runner.ts

@@ -0,0 +1,397 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+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";
+
+type Paseo = PluginHandlerContext["paseo"];
+type TerminalHandle = ReturnType<Paseo["terminals"]["ref"]>;
+
+const SCRIPT_DIR = path.join(tmpdir(), "paseo-terminal-integration");
+const POLL_MS = 500;
+const CAPTURE_WINDOW = 3_000;
+const PROMPT_WAIT_MS = 10_000;
+const PROMPT_SETTLE_POLLS = 4;
+const START_TIMEOUT_MS = 20_000;
+const CANCEL_GRACE_MS = 1_500;
+const MAX_RUN_MS = 6 * 60 * 60 * 1000;
+const AGENT_IDLE_WAIT_MS = 30 * 60 * 1000;
+const TAIL_LINES = 6;
+const REPORT_MAX_LINES = 300;
+const REPORT_MAX_CHARS = 24_000;
+const FINISHED_RUN_LIMIT = 200;
+
+// sendKeys() expands only a few key names, so control characters are written as raw bytes.
+const CTRL_C = "\x03";
+const CTRL_U = "\x15";
+
+const EXTENSIONS: Record<Interpreter, string> = {
+  bash: "sh",
+  zsh: "zsh",
+  fish: "fish",
+  python3: "py",
+  node: "mjs",
+};
+
+interface Run {
+  id: string;
+  key: string;
+  agentId: string;
+  workspaceId: string;
+  cwd: string;
+  lang: string;
+  code: string;
+  interpreter: Interpreter;
+  status: RunSnapshot["status"];
+  exitCode: number | null;
+  startedAt: number | null;
+  finishedAt: number | null;
+  output: string[];
+  truncated: boolean;
+  sendOnFinish: boolean;
+  sending: boolean;
+  sent: boolean;
+  error: string | null;
+  cancelRequested: boolean;
+  terminal: TerminalHandle | null;
+}
+
+export interface StartRunInput {
+  agentId: string;
+  key: string;
+  lang: string;
+  code: string;
+  send: boolean;
+}
+
+/** Runs code blocks in a per-workspace Paseo terminal 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>>();
+  private stopped = false;
+
+  constructor(private readonly paseo: Paseo) {}
+
+  async start(input: StartRunInput): Promise<RunSnapshot> {
+    const active = this.runs.get(input.key);
+    if (active && (active.status === "queued" || active.status === "running")) {
+      return snapshot(active);
+    }
+    const interpreter = interpreterFor(input.lang);
+    if (!interpreter) throw new Error(`Cannot run ${input.lang || "unlabeled"} code blocks`);
+
+    const agent = this.paseo.agents.ref(input.agentId);
+    await agent.refresh();
+    if (!agent.workspaceId || !agent.cwd) throw new Error("This agent has no workspace to run in");
+
+    const run: Run = {
+      id: randomUUID().slice(0, 8),
+      key: input.key,
+      agentId: input.agentId,
+      workspaceId: agent.workspaceId,
+      cwd: agent.cwd,
+      lang: input.lang,
+      code: input.code,
+      interpreter,
+      status: "queued",
+      exitCode: null,
+      startedAt: null,
+      finishedAt: null,
+      output: [],
+      truncated: false,
+      sendOnFinish: input.send,
+      sending: false,
+      sent: false,
+      error: null,
+      cancelRequested: false,
+      terminal: 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);
+    return snapshot(run);
+  }
+
+  status(keys: readonly string[]): RunSnapshot[] {
+    return keys.flatMap((key) => {
+      const run = this.runs.get(key);
+      return run ? [snapshot(run)] : [];
+    });
+  }
+
+  cancel(key: string): RunSnapshot | null {
+    const run = this.runs.get(key);
+    if (!run) return null;
+    run.sendOnFinish = false;
+    if (run.status === "queued") {
+      run.cancelRequested = true;
+      this.finish(run, "canceled");
+    } else if (run.status === "running" && !run.cancelRequested) {
+      run.cancelRequested = true;
+      run.terminal?.write(CTRL_C);
+    }
+    return snapshot(run);
+  }
+
+  sendOutput(key: string): RunSnapshot | null {
+    const run = this.runs.get(key);
+    if (!run) return null;
+    if (run.status === "queued") {
+      run.sendOnFinish = true;
+    } else {
+      void this.deliver(run);
+    }
+    return snapshot(run);
+  }
+
+  stop(): void {
+    this.stopped = true;
+    for (const run of this.runs.values()) {
+      if (run.status === "queued" || run.status === "running") {
+        run.error = "Plugin stopped before the command finished";
+        this.finish(run, "failed");
+      }
+    }
+  }
+
+  private async execute(run: Run): Promise<void> {
+    if (run.status !== "queued" || this.stopped) return;
+    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);
+    } catch (error) {
+      run.error = error instanceof Error ? error.message : String(error);
+      this.finish(run, "failed");
+    }
+    // Delivery waits for the agent to go idle; keep it off the lane so queued runs proceed.
+    if (finishedCleanly(run) && run.sendOnFinish) void this.deliver(run);
+  }
+
+  private async watch(run: Run, terminal: TerminalHandle): Promise<void> {
+    const begin = `__PTI_BEGIN_${run.id}__`;
+    const end = new RegExp(`__PTI_END_${run.id}_(\\d+)__`);
+    let sawBegin = false;
+    let canceledAt: number | null = null;
+    let polls = 0;
+
+    while (!this.stopped && run.startedAt !== null && Date.now() - run.startedAt < MAX_RUN_MS) {
+      await delay(POLL_MS);
+      polls++;
+      const { lines } = await terminal.capture({ start: -CAPTURE_WINDOW, stripAnsi: true });
+      if (lines.length === 0 && polls % 10 === 0 && !(await terminal.refresh())) {
+        run.error = `Terminal "${TERMINAL_NAME}" was closed`;
+        this.finish(run, "failed");
+        return;
+      }
+
+      const beginIndex = lastIndexWhere(lines, (line) => line.includes(begin));
+      if (beginIndex >= 0) sawBegin = true;
+      if (!sawBegin && !run.cancelRequested && Date.now() - run.startedAt > START_TIMEOUT_MS) {
+        run.error = `The command did not start. Is something else running in the "${TERMINAL_NAME}" terminal?`;
+        this.finish(run, "failed");
+        return;
+      }
+      const from = beginIndex >= 0 ? beginIndex + 1 : sawBegin ? 0 : lines.length;
+      run.truncated = sawBegin && beginIndex < 0;
+      const endIndex = lines.findIndex((line, index) => index >= from && end.test(line));
+      const output = lines.slice(from, endIndex >= 0 ? endIndex : lines.length);
+      run.output = withoutInterruptEcho(trimBlankEdges(output));
+
+      if (endIndex >= 0) {
+        run.exitCode = Number(end.exec(lines[endIndex])?.[1] ?? NaN);
+        this.finish(run, run.cancelRequested ? "canceled" : "done");
+        return;
+      }
+      if (run.cancelRequested) {
+        canceledAt ??= Date.now();
+        if (Date.now() - canceledAt > CANCEL_GRACE_MS) {
+          this.finish(run, "canceled");
+          return;
+        }
+      }
+    }
+    if (run.status === "running") {
+      run.error = "Stopped watching: the command ran longer than 6 hours";
+      this.finish(run, "failed");
+    }
+  }
+
+  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);
+    if (existing) return this.paseo.terminals.ref(existing);
+
+    const terminal = await this.paseo.terminals.create({ workspaceId, cwd, name: TERMINAL_NAME });
+    // Input typed while the shell's rc files still run can be dropped; wait for output to settle.
+    const deadline = Date.now() + PROMPT_WAIT_MS;
+    let previous = "";
+    let stablePolls = 0;
+    while (Date.now() < deadline && stablePolls < PROMPT_SETTLE_POLLS) {
+      await delay(250);
+      const { lines } = await terminal.capture({ stripAnsi: true });
+      const current = lines.join("\n");
+      stablePolls = current.trim() && current === previous ? stablePolls + 1 : 0;
+      previous = current;
+    }
+    return terminal;
+  }
+
+  private async deliver(run: Run): Promise<void> {
+    if (run.sending) return;
+    run.sending = true;
+    run.error = null;
+    try {
+      const agent = this.paseo.agents.ref(run.agentId);
+      await agent.refresh();
+      if (agent.status === "running" || agent.status === "initializing") {
+        await agent.waitForFinish(AGENT_IDLE_WAIT_MS);
+      }
+      await agent.send(formatReport(run));
+      run.sent = true;
+    } catch (error) {
+      run.error = `Could not send output: ${error instanceof Error ? error.message : String(error)}`;
+    } finally {
+      run.sending = false;
+    }
+  }
+
+  private finish(run: Run, status: RunSnapshot["status"]): void {
+    run.status = status;
+    run.finishedAt = Date.now();
+  }
+
+  private pruneFinished(): void {
+    const finished = [...this.runs.values()].filter(
+      (run) => run.status !== "queued" && run.status !== "running",
+    );
+    for (const run of finished.slice(0, Math.max(0, finished.length - FINISHED_RUN_LIMIT))) {
+      this.runs.delete(run.key);
+    }
+  }
+}
+
+/** Read through a call: TypeScript keeps `run.status` narrowed across the awaits in execute(). */
+function finishedCleanly(run: Run): boolean {
+  return run.status === "done";
+}
+
+function snapshot(run: Run): RunSnapshot {
+  return {
+    runId: run.id,
+    key: run.key,
+    status: run.status,
+    exitCode: run.exitCode,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    lineCount: run.output.length,
+    tail: run.output.slice(-TAIL_LINES),
+    sendOnFinish: run.sendOnFinish,
+    sending: run.sending,
+    sent: run.sent,
+    error: run.error,
+  };
+}
+
+/**
+ * The typed command only names a wrapper script, so the markers never appear in the shell's echo
+ * 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 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,
+    [
+      // A trap handler (unlike an ignored signal) is reset in the child, so Ctrl-C still stops the
+      // command while this script survives to print the end marker.
+      `trap ':' INT`,
+      `cd -- ${shellQuote(run.cwd)} 2>/dev/null`,
+      `printf '\\033[2m'; ${echo}; printf '\\033[0m'`,
+      `printf '\\033[8m%s\\033[0m\\n' '__PTI_BEGIN_${run.id}__'`,
+      `${run.interpreter} ${shellQuote(codeFile)}`,
+      `__pti_code=$?`,
+      `printf '\\n\\033[8m%s\\033[0m\\033[2m[exit %s]\\033[0m\\n' "__PTI_END_${run.id}_\${__pti_code}__" "$__pti_code"`,
+      `rm -f -- ${shellQuote(codeFile)} "$0"`,
+      `exit $__pti_code`,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return wrapper;
+}
+
+export async function cleanupScripts(): Promise<void> {
+  await rm(SCRIPT_DIR, { recursive: true, force: true });
+}
+
+function formatReport(run: Run): string {
+  const outcome =
+    run.status === "done"
+      ? `exit code ${run.exitCode}`
+      : run.status === "canceled"
+        ? "stopped by the user before it finished"
+        : run.status === "failed"
+          ? `failed: ${run.error ?? "unknown error"}`
+          : "still running; partial output";
+
+  let lines = run.output;
+  let note = run.truncated ? " (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);
+  }
+  let output = lines.join("\n");
+  if (output.length > REPORT_MAX_CHARS) {
+    output = output.slice(-REPORT_MAX_CHARS);
+    note = ` (last ${REPORT_MAX_CHARS} characters)`;
+  }
+
+  return [
+    `I ran this in the Paseo terminal "${TERMINAL_NAME}" (cwd \`${run.cwd}\`), ${outcome}:`,
+    "",
+    fenced(run.code, run.lang),
+    "",
+    output ? `Output${note}:` : "It printed no output.",
+    ...(output ? ["", fenced(output, "text")] : []),
+  ].join("\n");
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Drops the `^C` the terminal echoes when the command is interrupted. */
+function withoutInterruptEcho(lines: string[]): string[] {
+  let end = lines.length;
+  while (end > 0 && /^\s*\^C\s*$/.test(lines[end - 1])) end--;
+  return trimBlankEdges(lines.slice(0, end));
+}
+
+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;
+  }
+  return -1;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/server/text.ts

@@ -0,0 +1,21 @@
+/** A Markdown fence long enough that no backtick run inside `content` can close it. */
+export function fenced(content: string, lang = ""): string {
+  const longest = Math.max(0, ...(content.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(Math.max(3, longest + 1));
+  return `${fence}${lang}\n${content}\n${fence}`;
+}
+
+/** Removes the run markers the runner prints around command output. */
+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, ""));
+}
+
+export function trimBlankEdges(lines: readonly string[]): string[] {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && !lines[start].trim()) start++;
+  while (end > start && !lines[end - 1].trim()) end--;
+  return lines.slice(start, end).map((line) => line.replace(/\s+$/, ""));
+}

package/shared/code-blocks.ts

@@ -0,0 +1,86 @@
+export interface CodeBlock {
+  lang: string;
+  code: string;
+}
+
+export type Interpreter = "bash" | "zsh" | "fish" | "python3" | "node";
+
+const INTERPRETERS: Record<string, Interpreter> = {
+  bash: "bash",
+  sh: "bash",
+  shell: "bash",
+  shellscript: "bash",
+  console: "bash",
+  "shell-session": "bash",
+  zsh: "zsh",
+  fish: "fish",
+  python: "python3",
+  python3: "python3",
+  py: "python3",
+  javascript: "node",
+  js: "node",
+  mjs: "node",
+  node: "node",
+};
+
+const PROMPT_LANGUAGES = new Set(["console", "shell-session"]);
+const MAX_BLOCK_CHARS = 8_000;
+const MAX_BLOCKS = 20;
+
+export function interpreterFor(lang: string): Interpreter | null {
+  return INTERPRETERS[lang.toLowerCase()] ?? null;
+}
+
+/** Fenced code blocks in Markdown, in order. An unclosed trailing fence is ignored. */
+export function extractCodeBlocks(markdown: string): CodeBlock[] {
+  const blocks: CodeBlock[] = [];
+  let open: { indent: number; fence: string; lang: string; body: string[] } | null = null;
+
+  for (const line of markdown.split(/\r?\n/)) {
+    if (!open) {
+      const match = /^(\s*)(`{3,}|~{3,})(.*)$/.exec(line);
+      if (!match) continue;
+      const [, indent, fence, info] = match;
+      if (fence.startsWith("`") && info.includes("`")) continue;
+      const lang = info.trim().split(/[\s{},]+/)[0] ?? "";
+      open = { indent: indent.length, fence, lang: lang.toLowerCase(), body: [] };
+      continue;
+    }
+    const close = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+    if (close && close[1][0] === open.fence[0] && close[1].length >= open.fence.length) {
+      blocks.push({ lang: open.lang, code: open.body.join("\n") });
+      open = null;
+      continue;
+    }
+    open.body.push(stripIndent(line, open.indent));
+  }
+  return blocks;
+}
+
+/** Code blocks a terminal can run, with shell-session prompts reduced to their commands. */
+export function runnableBlocks(markdown: string): CodeBlock[] {
+  const blocks: CodeBlock[] = [];
+  for (const block of extractCodeBlocks(markdown)) {
+    if (!interpreterFor(block.lang)) continue;
+    const code = normalizeCommand(block).trim();
+    if (!code || code.length > MAX_BLOCK_CHARS) continue;
+    blocks.push({ lang: block.lang, code });
+    if (blocks.length === MAX_BLOCKS) break;
+  }
+  return blocks;
+}
+
+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;
+  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");
+}
+
+function stripIndent(line: string, indent: number): string {
+  let index = 0;
+  while (index < indent && line[index] === " ") index++;
+  return line.slice(index);
+}

package/shared/contracts.ts

@@ -0,0 +1,102 @@
+import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const TERMINAL_NAME = "Agent commands";
+
+export const RUN_CARD_KIND = "terminal-run-card";
+export const RUN_CARD_VERSION = 1;
+
+export const runCardSchema = z.object({
+  cardId: z.string(),
+  blocks: z.array(z.object({ lang: z.string(), code: z.string() })),
+});
+export type RunCardData = z.output<typeof runCardSchema>;
+
+export function runKey(cardId: string, blockIndex: number): string {
+  return `${cardId}:${blockIndex}`;
+}
+
+export const runSnapshotSchema = z.object({
+  runId: z.string(),
+  key: z.string(),
+  status: z.enum(["queued", "running", "done", "canceled", "failed"]),
+  exitCode: z.number().int().nullable(),
+  startedAt: z.number().nullable(),
+  finishedAt: z.number().nullable(),
+  lineCount: z.number().int(),
+  tail: z.array(z.string()),
+  sendOnFinish: z.boolean(),
+  sending: z.boolean(),
+  sent: z.boolean(),
+  error: z.string().nullable(),
+});
+export type RunSnapshot = z.output<typeof runSnapshotSchema>;
+
+export const startRun = defineRpc({
+  name: "run.start",
+  input: z.object({
+    agentId: z.string(),
+    key: z.string(),
+    lang: z.string(),
+    code: z.string().min(1),
+    send: z.boolean(),
+  }),
+  output: runSnapshotSchema,
+});
+
+export const runStatus = defineRpc({
+  name: "run.status",
+  input: z.object({ keys: z.array(z.string()) }),
+  output: z.object({ runs: z.array(runSnapshotSchema) }),
+});
+
+export const cancelRun = defineRpc({
+  name: "run.cancel",
+  input: z.object({ key: z.string() }),
+  output: runSnapshotSchema.nullable(),
+});
+
+export const sendRunOutput = defineRpc({
+  name: "run.send",
+  input: z.object({ key: z.string() }),
+  output: runSnapshotSchema.nullable(),
+});
+
+export const runAdhoc = defineRpc({
+  name: "run.adhoc",
+  input: z.object({ agentId: z.string(), command: z.string().min(1) }),
+  output: z.object({ cardId: z.string() }),
+});
+
+export const scanBlocks = defineRpc({
+  name: "blocks.scan",
+  input: z.object({ agentId: z.string() }),
+  output: z.object({ count: z.number().int() }),
+});
+
+export const searchTerminalOutput = defineRpc({
+  name: "terminals.search",
+  input: z.object({ query: z.string() }),
+  output: z.object({
+    items: z.array(
+      z.object({
+        id: z.string(),
+        identifier: z.string(),
+        title: z.string(),
+        subtitle: z.string().optional(),
+        url: z.string().url(),
+        text: z.string(),
+        resourceType: z.string(),
+      }),
+    ),
+  }),
+});
+
+export const terminalOutputSource = defineAttachmentSource({
+  id: "terminal-output",
+  title: "Terminal output",
+  icon: "SquareTerminal",
+  pickerTitle: "Attach terminal output",
+  searchPlaceholder: "Filter by name or path; add a number for line count (e.g. build 500)",
+  search: searchTerminalOutput,
+});