paseo-terminal-integration 0.2.0 → 0.4.0

package/README.md

@@ -2,31 +2,32 @@
 
 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 in side terminal** runs the block in the workspace terminal "Agent commands" and shows it in
-  the side panel; **Run silently** runs it without showing anything.
-- With **Send 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.
+**Agent → terminal.** Runnable fenced code blocks in the agent's reply (`bash`, `sh`, `shell`,
+`console`, `zsh`, `fish`, `python`, `js`/`node`) get run controls. On Paseo builds with inline code
+block actions ([getpaseo/paseo#5874](https://github.com/getpaseo/paseo/pull/5874)) the controls sit
+directly under each block, including in older messages as history loads, and become available when
+the reply finishes. On other Paseo versions a **Run in terminal** card appears under the reply.
+
+- **Run** runs the block in the workspace terminal "Agent commands", a regular Paseo terminal tab.
+  With inline controls, Run also opens that tab.
+- **Run in background** runs it as a hidden process in the agent's working directory: no terminal
+  tab, and the runner 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.
 
-**Terminal panel.** The side panel (Explorer) shows "Agent commands" as a full terminal: the same
-xterm.js renderer and live stream as Paseo's terminal tabs, with colors, the cursor, full-screen
-programs, and keyboard input. Click it and type to answer `sudo` passwords, `y/n` questions, or
-npm's "Press ENTER" without leaving the chat. Ctrl-C copies while text is selected and otherwise
-goes to the shell; Ctrl-Shift-C and Ctrl-Shift-V always copy and paste. Web links open in the
-browser when clicked. The card's **Terminal** button opens the panel without running anything. On
-phones the panel is a plain-text copy with an input line and Enter, Ctrl-C, Ctrl-D, and Tab keys,
-in a tab that opens only when you ask. **Settings → Plugins → Terminal integration** switches the
-panel to a workspace tab and sets the checkbox's default.
-
-Paseo gives every workspace terminal its own tab, so "Agent commands" also appears in the tab bar
-(in the background). Closing that tab ends the terminal; the next run starts a new one. 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.** On Paseo builds with the terminal open-location setting, choose
+**Settings → Layout → Open location → Opening a terminal → On the side** and "Agent commands"
+opens beside the chat. Elsewhere, drag the tab onto the right or bottom edge of the chat to split
+the workspace. A tab you moved stays where you put it while the terminal is open. Background runs
+never change the layout.
+
+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
@@ -39,36 +40,38 @@ Requires Paseo 0.10.1 or later and a macOS or Linux daemon host with `bash` (plu
 
 ```bash
 paseo plugin install npm:paseo-terminal-integration
+# or from GitHub
+paseo plugin install github:keefeere/paseo-terminal-integration
 ```
 
-Install from npm: GitHub installs skip npm dependencies, which the terminal panel needs.
-
 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`                                           |
-| ⌘K / Ctrl+K → "Terminal: show … in the side panel" | Open the terminal panel in the Explorer                  |
+| 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`                                      |
+
+The commands are available on Paseo versions without inline code block actions.
 
 ## 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).
-- The live panel opens its own connection to the daemon on the plugin host, using the address in
-  `$PASEO_HOME/paseo.pid` and the local credential, as the `paseo` CLI does. A daemon listening on
-  a Unix socket gets the plain-text panel instead.
-- Opening or resizing the panel resizes the PTY to fit it, as focusing a terminal tab does.
+- Run state lives in the plugin process; reloading the plugin forgets it. Controls and cards stay,
+  and nothing is re-run.
 - A command that has not started within 20 seconds fails, for example when something else is
   running in "Agent commands".
 
 ## Develop
 
+The inline code block action types are not in a published `@getpaseo/plugin` yet, so
+`client/sdk-compat.ts` declares them. Delete it once the SDK exports them. Use npm 11 for
+`npm install`: npm 10 crashes on this dependency tree.
+
 ```bash
 npm install
 npm run typecheck
@@ -77,6 +80,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/code-block-actions.tsx

@@ -0,0 +1,367 @@
+import { useRpc, useSettings } from "@getpaseo/plugin/client";
+import type { PluginCodeBlockActionsProps } from "./sdk-compat";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { Platform, Pressable, Text, View, type TextStyle } from "react-native";
+import {
+  cancelRun,
+  inlineRunKey,
+  runStatus,
+  sendRunOutput,
+  startRun,
+  type RunMode,
+  type RunSnapshot,
+} from "../shared/contracts";
+import { runnableBlock } from "../shared/code-blocks";
+import { preferences } from "../shared/settings";
+import { revealStartedRun } from "./reveal-run";
+
+type Theme = PluginCodeBlockActionsProps["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",
+});
+interface Controls {
+  pending: boolean;
+  send: boolean | null;
+  error: string | null;
+}
+const INITIAL_CONTROLS: Controls = { pending: false, send: null, error: null };
+function isActive(run: RunSnapshot): boolean {
+  return run.status === "queued" || run.status === "running" || run.sending;
+}
+export function CodeBlockActions(props: PluginCodeBlockActionsProps) {
+  const block = runnableBlock(props.code, props.language);
+  if (!block) return null;
+  return <RunnableActions {...props} command={block.code} />;
+}
+function RunnableActions({
+  agentId,
+  messageId,
+  blockIndex,
+  host,
+  theme,
+  layout,
+  language,
+  phase,
+  navigation,
+  command,
+}: PluginCodeBlockActionsProps & { command: string }) {
+  const key = inlineRunKey(host.id, agentId, messageId, blockIndex);
+  const queryKey = useMemo(() => ["terminal-run-status", key], [key]);
+  const controlsKey = useMemo(() => ["terminal-run-controls", key], [key]);
+  const styles = useMemo(() => createStyles(theme, layout.compact), [theme, layout.compact]);
+  const queryClient = useQueryClient();
+  const fetchStatus = useRpc(runStatus);
+  const start = useRpc(startRun);
+  const cancel = useRpc(cancelRun);
+  const send = useRpc(sendRunOutput);
+  const settings = useSettings(preferences);
+  const { data: controls = INITIAL_CONTROLS } = useQuery<Controls>({
+    queryKey: controlsKey,
+    queryFn: () => INITIAL_CONTROLS,
+    initialData: INITIAL_CONTROLS,
+    enabled: false,
+    gcTime: Infinity,
+  });
+  const updateControls = (patch: Partial<Controls>) =>
+    queryClient.setQueryData<Controls>(controlsKey, (previous) => ({
+      ...INITIAL_CONTROLS,
+      ...previous,
+      ...patch,
+    }));
+  const sendToAgent =
+    controls.send ?? (settings.status === "ready" ? settings.values.sendToAgent : true);
+  const status = useQuery({
+    queryKey,
+    queryFn: () => fetchStatus({ keys: [key] }),
+    refetchInterval: (query) => (query.state.data?.runs.some(isActive) ? POLL_MS : false),
+  });
+  const run = status.data?.runs[0];
+  const running = run?.status === "queued" || run?.status === "running";
+  const disabled = controls.pending || (!!run && isActive(run)) || phase !== "complete";
+  async function act(action: () => Promise<unknown>) {
+    if (queryClient.getQueryData<Controls>(controlsKey)?.pending) return;
+    updateControls({ pending: true, error: null });
+    try {
+      await action();
+      await queryClient.invalidateQueries({ queryKey });
+    } catch (error) {
+      updateControls({ error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      updateControls({ pending: false });
+    }
+  }
+  function runBlock(mode: RunMode) {
+    if (disabled) return;
+    void act(async () => {
+      const started = await start({
+        agentId,
+        key,
+        lang: language,
+        code: command,
+        send: sendToAgent,
+        mode,
+      });
+      queryClient.setQueryData(queryKey, { runs: [started] });
+      // Owned by this click, not by rendering or polling: remounts cannot steal focus.
+      void revealStartedRun(started, navigation?.openTerminal, fetchStatus).catch((error) =>
+        updateControls({ error: error instanceof Error ? error.message : String(error) }),
+      );
+    });
+  }
+  return (
+    <View style={styles.card}>
+      <View style={styles.actions}>
+        {running ? (
+          <ActionButton
+            styles={styles}
+            theme={theme}
+            icon="Square"
+            label="Stop"
+            tone="danger"
+            disabled={controls.pending}
+            onPress={() => void act(() => cancel({ key }))}
+          />
+        ) : (
+          <>
+            <ActionButton
+              styles={styles}
+              theme={theme}
+              icon="Play"
+              label="Run"
+              tone="primary"
+              disabled={disabled}
+              onPress={() => runBlock("terminal")}
+            />
+            <ActionButton
+              styles={styles}
+              theme={theme}
+              icon="EyeOff"
+              label="Run in background"
+              disabled={disabled}
+              onPress={() => runBlock("background")}
+            />
+          </>
+        )}
+        <Checkbox
+          styles={styles}
+          theme={theme}
+          label="Send output to agent"
+          checked={sendToAgent}
+          onChange={(value) => updateControls({ send: value })}
+        />
+        {run && !run.sent && !run.sending && (!running || !run.sendOnFinish) ? (
+          <ActionButton
+            styles={styles}
+            theme={theme}
+            icon="Send"
+            label={running ? "Send output so far" : "Send output"}
+            disabled={controls.pending}
+            onPress={() => void act(() => send({ key }))}
+          />
+        ) : null}
+      </View>
+      {phase !== "complete" ? (
+        <Text style={styles.muted}>Available when the response finishes</Text>
+      ) : null}
+      {controls.error ? <Text style={styles.danger}>{controls.error}</Text> : null}
+      {status.error ? <Text style={styles.danger}>{status.error.message}</Text> : null}
+      {run ? <RunStatus run={run} styles={styles} /> : null}
+    </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(
+      `${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;
+  }
+  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 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,
+  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,
+      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 },
+    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/client/legacy.tsx

@@ -0,0 +1,60 @@
+import type { PluginCleanup } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { RunCard } from "./run-card";
+import {
+  enableLegacyCards,
+  RUN_CARD_KIND,
+  RUN_CARD_VERSION,
+  runAdhoc,
+  runCardSchema,
+  scanBlocks,
+} from "../shared/contracts";
+
+// A function declaration: the host reads the default export before the module body has run.
+export function contributeLegacy(client: PluginClientContext): PluginCleanup {
+  // COMPAT(legacyRunCards): added in the inline-actions fork, remove after 2027-04-01.
+  void client
+    .rpc(enableLegacyCards, {})
+    .catch((error) => console.error("Could not enable legacy terminal cards", error));
+  client.addTimelineRenderer({
+    kind: RUN_CARD_KIND,
+    version: RUN_CARD_VERSION,
+    schema: runCardSchema,
+    Component: RunCard,
+  });
+
+  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/client/reveal-run.ts

@@ -0,0 +1,24 @@
+import type { PluginCodeBlockActionsProps } from "./sdk-compat";
+import type { RunSnapshot } from "../shared/contracts";
+
+type OpenTerminal = NonNullable<PluginCodeBlockActionsProps["navigation"]>["openTerminal"];
+/** Called only by the initiating click; history mounts never acquire navigation intent. */
+export async function revealStartedRun(
+  started: RunSnapshot,
+  openTerminal: OpenTerminal,
+  status: (input: { keys: string[] }) => Promise<{ runs: RunSnapshot[] }>,
+): Promise<void> {
+  if (started.mode !== "terminal") return;
+  if (!openTerminal)
+    throw new Error("Command started. Update Paseo to open its terminal automatically.");
+  let run = started;
+  while (!run.terminalId) {
+    if (run.status !== "queued" && run.status !== "running") return;
+    await new Promise((resolve) => setTimeout(resolve, 700));
+    const current = (await status({ keys: [run.key] })).runs[0];
+    if (!current || current.runId !== started.runId) return;
+    run = current;
+  }
+  if (run.status === "canceled" || run.status === "failed") return;
+  openTerminal({ workspaceId: run.workspaceId, terminalId: run.terminalId });
+}