paseo-terminal-integration 0.3.0 → 0.5.0

package/README.md

@@ -2,13 +2,16 @@
 
 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:
+**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 card keeps the last 5,000 lines instead of what fits on a terminal screen. Nothing
+  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
@@ -16,17 +19,32 @@ card under the reply:
   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 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 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.
 
+**Command guidance for agents.** The same settings screen can add command-formatting and execution
+guidance to the system prompt of newly created agents. Turn on **Inject command instructions** and
+choose one topology:
+
+- **Local daemon** tells the agent that Run already executes on the local Paseo daemon host, so it
+  should not add SSH merely to reach that machine.
+- **Client–server** tells the agent that the UI and daemon may be on different devices. Commands for
+  the daemon need no prefix; commands for another machine must include an explicit transport such
+  as SSH, using a destination supplied by the user rather than an invented host.
+
+Both templates are editable and stored per host. The shipped defaults are also available as
+[`local-daemon.md`](instructions/local-daemon.md) and
+[`client-server.md`](instructions/client-server.md), and each editor has a restore-default action.
+Changing or enabling the setting affects only agents created afterward; it does not rewrite the
+system prompt of an existing agent.
+
 **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).
@@ -47,23 +65,29 @@ 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`                                           |
+| 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
 
 - 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.
+- 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

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 });
+}

package/client/run-card.tsx

@@ -188,7 +188,9 @@ function RunStatus({ run, styles }: { run: RunSnapshot; styles: Styles }) {
   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)}`);
+    parts.push(
+      `${run.mode === "background" ? "Running in background" : "Running"} · ${elapsed(run)}`,
+    );
   }
   if (run.status === "done") {
     parts.push(`${run.exitCode === 0 ? "✓" : "✗"} exit ${run.exitCode}`);

package/client/sdk-compat.ts

@@ -0,0 +1,34 @@
+// COMPAT(inlineCodeBlockActions): copies of the inline code-action SDK types until a published
+// @getpaseo/plugin exports them; remove after 2027-04-01.
+import type { ComponentType } from "react";
+import type { PluginCleanup } from "@getpaseo/plugin";
+import type { PluginClientContext, PluginSurfaceProps } from "@getpaseo/plugin/client";
+
+type HostNavigation = NonNullable<PluginSurfaceProps["navigation"]>;
+
+export interface PluginCodeBlockActionsProps extends Omit<PluginSurfaceProps, "navigation"> {
+  readonly navigation?: HostNavigation & {
+    readonly openTerminal?: (input: {
+      readonly workspaceId: string;
+      readonly terminalId: string;
+      readonly serverId?: string;
+    }) => void;
+  };
+  agentId: string;
+  messageId: string;
+  blockIndex: number;
+  code: string;
+  language: string;
+  phase: "streaming" | "complete";
+}
+
+export interface PluginCodeBlockActionsContribution {
+  id: string;
+  languages: readonly string[];
+  Component: ComponentType<PluginCodeBlockActionsProps>;
+}
+
+/** Older clients lack addCodeBlockActions; check for it before calling. */
+export type InlineActionsClient = PluginClientContext & {
+  addCodeBlockActions?: (contribution: PluginCodeBlockActionsContribution) => PluginCleanup;
+};

package/client/settings-screen.tsx

@@ -1,13 +1,22 @@
-import { useSettings, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useSettings, type PluginSurfaceProps, type SettingsState } from "@getpaseo/plugin/client";
 import {
+  ExternalLink,
+  SettingsAction,
   SettingsCard,
   SettingsRow,
   SettingsSection,
+  SettingsSelect,
   SettingsSwitch,
 } from "@getpaseo/plugin/client/ui";
-import { Text } from "react-native";
+import { useMemo, useState } from "react";
+import { Text, TextInput, View } from "react-native";
 import { TERMINAL_NAME } from "../shared/contracts";
-import { preferences } from "../shared/settings";
+import { CLIENT_SERVER_INSTRUCTIONS, LOCAL_DAEMON_INSTRUCTIONS } from "../shared/instructions";
+import { preferences, type InstructionTopology } from "../shared/settings";
+
+const REPOSITORY = "https://github.com/keefeere/paseo-terminal-integration/blob/main";
+
+type ReadySettings = Extract<SettingsState<typeof preferences.schema>, { status: "ready" }>;
 
 export function SettingsScreen({ theme }: PluginSurfaceProps) {
   const settings = useSettings(preferences);
@@ -17,24 +26,178 @@ export function SettingsScreen({ theme }: PluginSurfaceProps) {
       settings.status === "loading" ? "Loading…" : `Settings are unavailable: ${settings.error}`;
     return <Text style={{ color: theme.colors.foregroundMuted }}>{message}</Text>;
   }
+
+  return <ReadySettingsScreen key={settings.revision} settings={settings} theme={theme} />;
+}
+
+function ReadySettingsScreen({
+  settings,
+  theme,
+}: {
+  settings: ReadySettings;
+  theme: PluginSurfaceProps["theme"];
+}) {
   const { values, revision } = settings;
+  const [draft, setDraft] = useState(values);
+  const dirty = useMemo(() => JSON.stringify(draft) !== JSON.stringify(values), [draft, values]);
+  const editorStyle = useMemo(
+    () => ({
+      minHeight: 220,
+      paddingHorizontal: 12,
+      paddingVertical: 10,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      borderRadius: 8,
+      color: theme.colors.foreground,
+      backgroundColor: theme.colors.surface0,
+      fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+      fontSize: 12,
+      lineHeight: 18,
+      textAlignVertical: "top" as const,
+    }),
+    [theme],
+  );
+  const linkStyle = useMemo(() => ({ color: theme.colors.accent, fontSize: 12 }), [theme]);
+
+  const updateTopology = (instructionTopology: InstructionTopology) =>
+    setDraft((current) => ({ ...current, instructionTopology }));
 
   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>
+    <>
+      <SettingsSection title="Code block actions">
+        <SettingsCard>
+          <SettingsSwitch
+            label="Send output to the agent by default"
+            hint={`Initial state of the "Send output to agent" checkbox on each code block.`}
+            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. Choose Main panel or On the side in Settings → Layout → Open location → Terminals. Manually moved tabs keep their location.`}
+          />
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="Agent command instructions">
+        <SettingsCard>
+          <SettingsSwitch
+            label="Inject command instructions"
+            hint="Add the selected guidance to the system prompt of newly created agents. Existing agents are unchanged."
+            value={draft.injectCommandInstructions}
+            disabled={settings.saving}
+            onValueChange={(injectCommandInstructions) =>
+              setDraft((current) => ({ ...current, injectCommandInstructions }))
+            }
+          />
+          <SettingsSelect
+            label="Execution topology"
+            hint="Choose where clicking Run actually executes a command."
+            value={draft.instructionTopology}
+            options={[
+              { label: "Local daemon", value: "local-daemon" },
+              { label: "Client–server", value: "client-server" },
+            ]}
+            disabled={settings.saving}
+            onValueChange={updateTopology}
+          />
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="Local daemon instructions">
+        <SettingsCard>
+          <SettingsRow
+            label="Instruction text"
+            hint="Used when Execution topology is Local daemon. Edit the host-scoped copy below."
+          >
+            <View style={{ gap: 8, width: "100%" }}>
+              <ExternalLink href={`${REPOSITORY}/instructions/local-daemon.md`}>
+                <Text style={linkStyle}>View shipped local-daemon.md</Text>
+              </ExternalLink>
+              <TextInput
+                multiline
+                accessibilityLabel="Local daemon command instructions"
+                value={draft.localDaemonInstructions}
+                editable={!settings.saving}
+                onChangeText={(localDaemonInstructions) =>
+                  setDraft((current) => ({ ...current, localDaemonInstructions }))
+                }
+                style={editorStyle}
+              />
+            </View>
+          </SettingsRow>
+          <SettingsAction
+            label="Restore local template"
+            hint="Replace the draft with the version shipped by the plugin."
+            actionLabel="Restore default"
+            disabled={
+              settings.saving || draft.localDaemonInstructions === LOCAL_DAEMON_INSTRUCTIONS
+            }
+            onPress={() =>
+              setDraft((current) => ({
+                ...current,
+                localDaemonInstructions: LOCAL_DAEMON_INSTRUCTIONS,
+              }))
+            }
+          />
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="Client–server instructions">
+        <SettingsCard>
+          <SettingsRow
+            label="Instruction text"
+            hint="Used when Execution topology is Client–server. Edit the host-scoped copy below."
+          >
+            <View style={{ gap: 8, width: "100%" }}>
+              <ExternalLink href={`${REPOSITORY}/instructions/client-server.md`}>
+                <Text style={linkStyle}>View shipped client-server.md</Text>
+              </ExternalLink>
+              <TextInput
+                multiline
+                accessibilityLabel="Client-server command instructions"
+                value={draft.clientServerInstructions}
+                editable={!settings.saving}
+                onChangeText={(clientServerInstructions) =>
+                  setDraft((current) => ({ ...current, clientServerInstructions }))
+                }
+                style={editorStyle}
+              />
+            </View>
+          </SettingsRow>
+          <SettingsAction
+            label="Restore client–server template"
+            hint="Replace the draft with the version shipped by the plugin."
+            actionLabel="Restore default"
+            disabled={
+              settings.saving || draft.clientServerInstructions === CLIENT_SERVER_INSTRUCTIONS
+            }
+            onPress={() =>
+              setDraft((current) => ({
+                ...current,
+                clientServerInstructions: CLIENT_SERVER_INSTRUCTIONS,
+              }))
+            }
+          />
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="Save instruction settings">
+        <SettingsCard>
+          <SettingsAction
+            label="Apply to newly created agents"
+            hint="Saving does not modify agents that already exist."
+            error={settings.saveError}
+            actionLabel={settings.saving ? "Saving…" : "Save changes"}
+            disabled={settings.saving || !dirty}
+            onPress={() => void settings.save(draft, revision)}
+          />
+        </SettingsCard>
+      </SettingsSection>
+    </>
   );
 }

package/index.client.tsx

@@ -1,66 +1,35 @@
+import { z } from "zod";
+import { contributeLegacy } from "./client/legacy";
 import type { PluginCleanup } from "@getpaseo/plugin";
-import type { PluginClientContext } from "@getpaseo/plugin/client";
-import { RunCard } from "./client/run-card";
+import type { InlineActionsClient } from "./client/sdk-compat";
+import { CodeBlockActions } from "./client/code-block-actions";
 import { SettingsScreen } from "./client/settings-screen";
-import {
-  RUN_CARD_KIND,
-  RUN_CARD_VERSION,
-  runAdhoc,
-  runCardSchema,
-  scanBlocks,
-  terminalOutputSource,
-} from "./shared/contracts";
-
-// 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,
-    schema: runCardSchema,
-    Component: RunCard,
-  });
-
+import { RUNNABLE_LANGUAGES } from "./shared/code-blocks";
+import { terminalOutputSource } from "./shared/contracts";
+
+export default function contribute(client: InlineActionsClient): PluginCleanup {
+  if (typeof client.addCodeBlockActions === "function") {
+    client.addCodeBlockActions({
+      id: "run",
+      languages: RUNNABLE_LANGUAGES,
+      Component: CodeBlockActions,
+    });
+    // COMPAT(legacyRunCards): added in the inline-actions fork, remove after 2027-04-01.
+    client.addTimelineRenderer({
+      kind: "terminal-run-card",
+      version: 1,
+      schema: z.unknown(),
+      Component: () => null,
+    });
+  } else {
+    contributeLegacy(client);
+  }
   client.addSettingsScreen({
     id: "preferences",
     title: "Terminal integration",
     icon: "SquareTerminal",
     Component: SettingsScreen,
   });
-
   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

@@ -1,9 +1,11 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { searchTerminals } from "./server/attachments";
 import { appendCardForTurn, appendRunCard, scanLatestReply } from "./server/cards";
+import { injectCommandInstructions, selectedCommandInstructions } from "./server/instructions";
 import { cleanupScripts, TerminalRunner } from "./server/runner";
 import { preferences } from "./shared/settings";
 import {
+  enableLegacyCards,
   cancelRun,
   runAdhoc,
   runKey,
@@ -15,12 +17,34 @@ import {
 } from "./shared/contracts";
 
 export default function contribute(server: PluginServerContext) {
-  server.registerSettings(preferences);
+  const settings = server.registerSettings(preferences);
   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.before("agent.create", async ({ request }) => {
+    const state = await settings.read();
+    if (state.status !== "ready") return;
+    const instructions = selectedCommandInstructions(state.values);
+    if (!instructions) return;
+    return {
+      ...request,
+      config: {
+        ...request.config,
+        systemPrompt: injectCommandInstructions(request.config.systemPrompt, instructions),
+      },
+    };
+  });
+
+  // COMPAT(legacyRunCards): only old clients opt into scanning; remove after 2027-04-01.
+  let legacyCardsRequested = false;
+  server.handle(enableLegacyCards, async () => {
+    legacyCardsRequested = true;
+    return { enabled: true };
+  });
+  server.on("agent.turn_ended", (event, { paseo }) => {
+    if (legacyCardsRequested) return appendCardForTurn(paseo, event);
+  });
 
   server.handle(startRun, (input, { paseo }) => runnerFor(paseo).start(input));
   server.handle(runStatus, ({ keys }, { paseo }) => ({ runs: runnerFor(paseo).status(keys) }));

package/instructions/client-server.md

@@ -0,0 +1,13 @@
+Paseo Terminal Integration is installed in a client-server setup. The chat UI may be on a different device, but clicking Run never executes on that client device. It executes on this agent's Paseo daemon host, in this agent's working directory, under the daemon user's account.
+
+When you offer commands that the user may want to run:
+
+- Put each directly executable command in a fenced code block tagged with its interpreter, such as bash, sh, python, or node.
+- Keep explanations, alternatives, warnings, and expected output outside executable code blocks.
+- Make each executable block self-contained. Do not include a shell prompt such as "$ ", prose, or sample output in it.
+- State clearly which machine a command targets whenever that may be ambiguous. Never describe Run as executing on the user's phone, browser, or desktop client.
+- A command for the daemon host needs no transport prefix: clicking Run already executes it there.
+- A command for another machine must include the transport explicitly, normally SSH from the daemon host. Use an SSH destination already provided by the user; do not invent a hostname, username, path, or credential. If the destination is unknown, explain what is needed instead of presenting a falsely runnable command.
+- Quote remote commands so that expansion happens on the intended machine. Account for differences between the agent working directory and the remote working directory.
+- Distinguish commands the user may run from commands you already ran. Do not claim that a suggested command has executed.
+- Use Run in the terminal for commands that may need a password, confirmation, or other input. Background runs have no stdin.

package/instructions/local-daemon.md

@@ -0,0 +1,11 @@
+Paseo Terminal Integration is installed on this agent's daemon host.
+
+When you offer commands that the user may want to run:
+
+- Put each directly executable command in a fenced code block tagged with its interpreter, such as bash, sh, python, or node.
+- Keep explanations, alternatives, warnings, and expected output outside executable code blocks.
+- Make each executable block self-contained. Do not include a shell prompt such as "$ ", prose, or sample output in it.
+- Assume that clicking Run executes the block on the same machine as the Paseo daemon, in this agent's working directory, under the daemon user's account.
+- Distinguish commands the user may run from commands you already ran. Do not claim that a suggested command has executed.
+- Use Run in the terminal for commands that may need a password, confirmation, or other input. Background runs have no stdin.
+- Do not add SSH merely to reach the daemon host: the command already runs there.

package/package.json

@@ -1,42 +1,50 @@
 {
   "name": "paseo-terminal-integration",
-  "version": "0.3.0",
+  "version": "0.5.0",
+  "description": "Run agent code blocks in a Paseo terminal and send the output back to the agent; attach terminal output to prompts",
+  "keywords": [
+    "agents",
+    "paseo",
+    "paseo-plugin",
+    "terminal"
+  ],
+  "homepage": "https://github.com/keefeere/paseo-terminal-integration#readme",
+  "bugs": {
+    "url": "https://github.com/keefeere/paseo-terminal-integration/issues"
+  },
+  "license": "MIT",
+  "author": "Chechulin Serhii",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keefeere/paseo-terminal-integration.git"
+  },
   "files": [
     "paseo-plugin.json",
     "index.client.tsx",
     "index.server.ts",
     "client/",
+    "instructions/",
     "server/",
-    "shared/"
+    "shared/",
+    "!**/*.test.ts"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "format": "oxfmt ."
   },
   "devDependencies": {
-    "@getpaseo/plugin": "0.10.1",
+    "@getpaseo/plugin": "0.10.2",
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^26.6.2",
     "@types/react": "~19.2.0",
+    "oxfmt": "0.46.0",
+    "oxlint": "1.61.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"
-  ]
+    "vitest": "^4.1.7",
+    "zod": "4.4.3"
+  }
 }

package/server/attachments.ts

@@ -32,7 +32,9 @@ export async function searchTerminals(
 
   const items = await Promise.all(
     matches.map(async (entry) => {
-      const capture = await paseo.terminals.ref(entry).capture({ start: -lineCount, stripAnsi: true });
+      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);

package/server/instructions.ts

@@ -0,0 +1,28 @@
+import { INSTRUCTION_PROMPT_MARKER } from "../shared/instructions";
+import type { InstructionTopology } from "../shared/settings";
+
+export interface CommandInstructionPreferences {
+  injectCommandInstructions: boolean;
+  instructionTopology: InstructionTopology;
+  localDaemonInstructions: string;
+  clientServerInstructions: string;
+}
+
+export function selectedCommandInstructions(values: CommandInstructionPreferences): string | null {
+  if (!values.injectCommandInstructions) return null;
+  const text =
+    values.instructionTopology === "local-daemon"
+      ? values.localDaemonInstructions
+      : values.clientServerInstructions;
+  return text.trim() || null;
+}
+
+export function injectCommandInstructions(
+  systemPrompt: string | undefined,
+  instructions: string,
+): string {
+  const existing = systemPrompt?.trim() ?? "";
+  if (existing.includes(INSTRUCTION_PROMPT_MARKER)) return existing;
+  const addition = `<${INSTRUCTION_PROMPT_MARKER}>\n${instructions.trim()}\n</${INSTRUCTION_PROMPT_MARKER}>`;
+  return existing ? `${existing}\n\n${addition}` : addition;
+}

package/server/runner.ts

@@ -130,7 +130,9 @@ export class TerminalRunner {
       // 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));
+      const lane = (this.lanes.get(run.workspaceId) ?? Promise.resolve()).then(() =>
+        this.execute(run),
+      );
       this.lanes.set(run.workspaceId, lane);
     }
     return snapshot(run);
@@ -380,6 +382,8 @@ function finishedCleanly(run: Run): boolean {
 function snapshot(run: Run): RunSnapshot {
   return {
     runId: run.id,
+    workspaceId: run.workspaceId,
+    terminalId: run.terminal?.id ?? null,
     key: run.key,
     mode: run.mode,
     status: run.status,
@@ -402,7 +406,8 @@ function snapshot(run: Run): RunSnapshot {
 async function writeScripts(run: Run): Promise<string> {
   const codeFile = await writeCode(run);
   const wrapper = path.join(SCRIPT_DIR, `${run.id}.run.sh`);
-  const shell = run.interpreter === "bash" || run.interpreter === "zsh" || run.interpreter === "fish";
+  const shell =
+    run.interpreter === "bash" || run.interpreter === "zsh" || run.interpreter === "fish";
   const echo = shell
     ? `sed 's/^/$ /' -- ${shellQuote(codeFile)}`
     : `printf '# %s\\n' ${shellQuote(run.interpreter)}; cat -- ${shellQuote(codeFile)}`;
@@ -506,7 +511,10 @@ function signalGroup(child: ChildProcess, signal: NodeJS.Signals): void {
   }
 }
 
+// Terminal output cleaning deliberately matches ANSI and control bytes.
+// oxlint-disable-next-line no-control-regex
 const ANSI_ESCAPE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?|[@-Z\\-_])/g;
+// oxlint-disable-next-line no-control-regex
 const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
 
 /** Program output as a terminal would show it, without colors: `\r` rewrites the current line. */

package/shared/code-blocks.ts

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

package/shared/contracts.ts

@@ -3,6 +3,16 @@ import { z } from "zod";
 
 export const TERMINAL_NAME = "Agent commands";
 
+export function inlineRunKey(
+  hostId: string,
+  agentId: string,
+  messageId: string,
+  blockIndex: number,
+): string {
+  return JSON.stringify([hostId, agentId, messageId, blockIndex]);
+}
+
+// COMPAT(legacyRunCards): added in the inline-actions fork, remove after 2027-04-01.
 export const RUN_CARD_KIND = "terminal-run-card";
 export const RUN_CARD_VERSION = 1;
 
@@ -22,6 +32,8 @@ export type RunMode = (typeof runModes)[number];
 
 export const runSnapshotSchema = z.object({
   runId: z.string(),
+  workspaceId: z.string(),
+  terminalId: z.string().nullable(),
   key: z.string(),
   mode: z.enum(runModes),
   status: z.enum(["queued", "running", "done", "canceled", "failed"]),
@@ -43,7 +55,7 @@ export const startRun = defineRpc({
     agentId: z.string(),
     key: z.string(),
     lang: z.string(),
-    code: z.string().min(1),
+    code: z.string().min(1).max(8_000),
     send: z.boolean(),
     mode: z.enum(runModes),
   }),
@@ -80,6 +92,12 @@ export const scanBlocks = defineRpc({
   output: z.object({ count: z.number().int() }),
 });
 
+export const enableLegacyCards = defineRpc({
+  name: "legacy.cards.enable",
+  input: z.object({}),
+  output: z.object({ enabled: z.boolean() }),
+});
+
 export const searchTerminalOutput = defineRpc({
   name: "terminals.search",
   input: z.object({ query: z.string() }),

package/shared/instructions.ts

@@ -0,0 +1,31 @@
+export const LOCAL_DAEMON_INSTRUCTIONS = `
+Paseo Terminal Integration is installed on this agent's daemon host.
+
+When you offer commands that the user may want to run:
+
+- Put each directly executable command in a fenced code block tagged with its interpreter, such as bash, sh, python, or node.
+- Keep explanations, alternatives, warnings, and expected output outside executable code blocks.
+- Make each executable block self-contained. Do not include a shell prompt such as "$ ", prose, or sample output in it.
+- Assume that clicking Run executes the block on the same machine as the Paseo daemon, in this agent's working directory, under the daemon user's account.
+- Distinguish commands the user may run from commands you already ran. Do not claim that a suggested command has executed.
+- Use Run in the terminal for commands that may need a password, confirmation, or other input. Background runs have no stdin.
+- Do not add SSH merely to reach the daemon host: the command already runs there.
+`.trim();
+
+export const CLIENT_SERVER_INSTRUCTIONS = `
+Paseo Terminal Integration is installed in a client-server setup. The chat UI may be on a different device, but clicking Run never executes on that client device. It executes on this agent's Paseo daemon host, in this agent's working directory, under the daemon user's account.
+
+When you offer commands that the user may want to run:
+
+- Put each directly executable command in a fenced code block tagged with its interpreter, such as bash, sh, python, or node.
+- Keep explanations, alternatives, warnings, and expected output outside executable code blocks.
+- Make each executable block self-contained. Do not include a shell prompt such as "$ ", prose, or sample output in it.
+- State clearly which machine a command targets whenever that may be ambiguous. Never describe Run as executing on the user's phone, browser, or desktop client.
+- A command for the daemon host needs no transport prefix: clicking Run already executes it there.
+- A command for another machine must include the transport explicitly, normally SSH from the daemon host. Use an SSH destination already provided by the user; do not invent a hostname, username, path, or credential. If the destination is unknown, explain what is needed instead of presenting a falsely runnable command.
+- Quote remote commands so that expansion happens on the intended machine. Account for differences between the agent working directory and the remote working directory.
+- Distinguish commands the user may run from commands you already ran. Do not claim that a suggested command has executed.
+- Use Run in the terminal for commands that may need a password, confirmation, or other input. Background runs have no stdin.
+`.trim();
+
+export const INSTRUCTION_PROMPT_MARKER = "paseo-terminal-integration-command-guidance";

package/shared/settings.ts

@@ -1,12 +1,24 @@
 import { defineSettings } from "@getpaseo/plugin";
 import { z } from "zod";
+import { CLIENT_SERVER_INSTRUCTIONS, LOCAL_DAEMON_INSTRUCTIONS } from "./instructions";
+
+export const instructionTopologies = ["local-daemon", "client-server"] as const;
+export type InstructionTopology = (typeof instructionTopologies)[number];
 
 export const preferences = defineSettings({
   id: "preferences",
   scope: "host",
-  version: 1,
+  version: 2,
   schema: z.object({
-    /** Initial state of a run card's "Send output to agent" checkbox. */
+    /** Initial state of a code block's "Send output to agent" checkbox. */
     sendToAgent: z.boolean().default(true),
+    /** Add command-formatting and execution-topology guidance to newly created agents. */
+    injectCommandInstructions: z.boolean().default(false),
+    instructionTopology: z.enum(instructionTopologies).default("client-server"),
+    localDaemonInstructions: z.string().default(LOCAL_DAEMON_INSTRUCTIONS),
+    clientServerInstructions: z.string().default(CLIENT_SERVER_INSTRUCTIONS),
   }),
+  migrate(values) {
+    return values;
+  },
 });