paseo-terminal-integration 0.4.0 → 0.5.1

package/OVERVIEW.md

@@ -0,0 +1,20 @@
+# Terminal integration
+
+Terminal integration connects agent replies to Paseo terminals. Runnable shell, Python, and
+JavaScript code blocks get controls for running them in an interactive workspace terminal or as a
+background process. Command results can be sent back to the agent, while terminal output can also
+be attached manually to a prompt.
+
+Interactive commands run in a regular terminal named "Agent commands" on the daemon host. They can
+accept passwords and confirmations. Background commands have no terminal or input, can run in
+parallel, and retain more output. Commands only run after the user presses a run button or submits
+the `/run` command.
+
+The settings control whether completed output is sent to the agent by default and how many lines
+make a result start collapsed in the timeline. Optional command guidance can be added to newly
+created agents for either a local-daemon or client-server setup. Both supplied instruction templates
+are editable per host.
+
+The plugin requires Paseo 0.10.1 or later and a macOS or Linux daemon host with `bash`. Python and
+Node.js code blocks also require their corresponding interpreter. Plugins are trusted code; this
+plugin starts processes and types commands into terminals on the daemon host.

package/README.md

@@ -17,6 +17,8 @@ the reply finishes. On other Paseo versions a **Run in terminal** card appears u
 - 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.
+- Sent output longer than 20 lines starts collapsed. Change the threshold under
+  **Settings → Plugins → Terminal integration**, or set it to 0 to keep output expanded.
 - **Stop** sends Ctrl-C; **Send output so far** reports a still-running command.
 
 **Terminal beside the chat.** On Paseo builds with the terminal open-location setting, choose
@@ -29,6 +31,22 @@ Terminal runs in one workspace are queued so a command never types into another
 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).

package/client/run-report.tsx

@@ -0,0 +1,143 @@
+import {
+  useSettings,
+  type PluginTimelineItemProps,
+  type PluginTimelineTransformerContribution,
+} from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useMemo, useState } from "react";
+import { Platform, Pressable, ScrollView, Text, View } from "react-native";
+import {
+  parseRunReport,
+  runReportSchema,
+  wrapRunReportOutcome,
+  type RunReportData,
+} from "../shared/run-report";
+import { DEFAULT_COLLAPSE_OUTPUT_AFTER_LINES, preferences } from "../shared/settings";
+
+type UserMessageTransformer = PluginTimelineTransformerContribution<"user_message">["transform"];
+type Theme = PluginTimelineItemProps["theme"];
+
+export const transformRunReport: UserMessageTransformer = ({ item }) => {
+  const data = parseRunReport(item.text);
+  if (!data) return;
+  return {
+    items: [{ type: "plugin", kind: "terminal-run-report", version: 1, data }],
+  };
+};
+
+export { runReportSchema };
+
+export function RunReport({ item, theme, layout }: PluginTimelineItemProps<RunReportData>) {
+  const settings = useSettings(preferences);
+  const threshold =
+    settings.status === "ready"
+      ? settings.values.collapseOutputAfterLines
+      : DEFAULT_COLLAPSE_OUTPUT_AFTER_LINES;
+  const autoCollapsed = threshold > 0 && item.data.outputLineCount > threshold;
+  const [expandedOverride, setExpandedOverride] = useState<boolean | null>(null);
+  const expanded = expandedOverride ?? !autoCollapsed;
+  const styles = useMemo(() => createStyles(theme, layout.compact), [theme, layout.compact]);
+
+  if (!item.data.output) {
+    return (
+      <View style={styles.card}>
+        <Text style={styles.intro}>{item.data.intro}</Text>
+        <CodeBlock text={item.data.code} styles={styles} />
+        <Text style={styles.outputLabel}>{item.data.outputLabel}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={[styles.card, !expanded && styles.collapsedCard]}>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`${expanded ? "Collapse" : "Expand"} terminal output`}
+        accessibilityState={{ expanded }}
+        onPress={() => setExpandedOverride(!expanded)}
+        style={({ pressed }) => [styles.reportHeader, pressed && styles.pressed]}
+      >
+        <Icon
+          name={expanded ? "ChevronDown" : "ChevronRight"}
+          size={16}
+          color={theme.colors.foregroundMuted}
+        />
+        <Text style={styles.reportTitle} numberOfLines={expanded ? undefined : 1}>
+          {expanded ? wrapRunReportOutcome(item.data.intro) : item.data.intro}
+        </Text>
+        <Text style={styles.lineCount}>
+          {item.data.outputLineCount} {item.data.outputLineCount === 1 ? "line" : "lines"}
+        </Text>
+      </Pressable>
+      {expanded ? (
+        <>
+          <CodeBlock text={item.data.code} styles={styles} />
+          <Text style={styles.outputLabel}>{item.data.outputLabel}</Text>
+          <CodeBlock text={item.data.output} styles={styles} />
+        </>
+      ) : null}
+    </View>
+  );
+}
+
+type Styles = ReturnType<typeof createStyles>;
+
+function CodeBlock({ text, styles }: { text: string; styles: Styles }) {
+  return (
+    <ScrollView horizontal style={styles.codeBlock} contentContainerStyle={styles.codeContent}>
+      <Text selectable style={styles.code}>
+        {text}
+      </Text>
+    </ScrollView>
+  );
+}
+
+function createStyles(theme: Theme, compact: boolean) {
+  return {
+    card: {
+      gap: 10,
+      padding: compact ? 12 : 14,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      borderRadius: 12,
+      backgroundColor: theme.colors.surface1,
+    },
+    collapsedCard: { gap: 0, padding: 4 },
+    intro: { color: theme.colors.foreground, fontSize: 14, lineHeight: 20 },
+    reportHeader: {
+      minHeight: 36,
+      flexDirection: "row" as const,
+      alignItems: "center" as const,
+      gap: 6,
+      paddingHorizontal: 8,
+      borderRadius: 6,
+    },
+    pressed: { opacity: 0.7 },
+    reportTitle: {
+      flex: 1,
+      color: theme.colors.foreground,
+      fontSize: 13,
+      lineHeight: 18,
+    },
+    outputLabel: { flexShrink: 1, color: theme.colors.foreground, fontSize: 13 },
+    lineCount: { marginLeft: "auto" as const, color: theme.colors.foregroundMuted, fontSize: 12 },
+    codeBlock: {
+      maxWidth: "100%" as const,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      borderRadius: 8,
+      backgroundColor: theme.colors.surface0,
+    },
+    codeContent: { paddingHorizontal: 10, paddingVertical: 8 },
+    code: {
+      color: theme.colors.foreground,
+      fontSize: 12,
+      lineHeight: 18,
+      fontFamily: Platform.select({
+        ios: "Menlo",
+        android: "monospace",
+        default: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+      }),
+    },
+  };
+}

package/client/settings-screen.tsx

@@ -1,13 +1,23 @@
-import { useSettings, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useSettings, type PluginSurfaceProps, type SettingsState } from "@getpaseo/plugin/client";
 import {
+  ExternalLink,
+  SettingsAction,
   SettingsCard,
+  SettingsInput,
   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 +27,199 @@ 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 [collapseLinesText, setCollapseLinesText] = useState(
+    String(values.collapseOutputAfterLines),
+  );
+  const collapseLines = /^\d+$/.test(collapseLinesText) ? Number(collapseLinesText) : NaN;
+  const collapseLinesError =
+    Number.isInteger(collapseLines) && collapseLines >= 0 && collapseLines <= 5_000
+      ? null
+      : "Enter a whole number from 0 to 5000.";
+  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="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="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={draft.sendToAgent}
+            disabled={settings.saving}
+            error={settings.saveError}
+            onValueChange={(sendToAgent) => setDraft((current) => ({ ...current, sendToAgent }))}
+          />
+          <SettingsInput
+            label="Collapse output after this many lines"
+            hint="Long output sent back to the agent starts collapsed. Set 0 to keep all output expanded."
+            initialValue={collapseLinesText}
+            placeholder="20"
+            disabled={settings.saving}
+            error={collapseLinesError}
+            onChangeText={(text) => {
+              setCollapseLinesText(text);
+              const value = /^\d+$/.test(text) ? Number(text) : NaN;
+              if (Number.isInteger(value) && value >= 0 && value <= 5_000) {
+                setDraft((current) => ({ ...current, collapseOutputAfterLines: value }));
+              }
+            }}
+          />
+          <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 settings">
+        <SettingsCard>
+          <SettingsAction
+            label="Apply changes"
+            hint="Output display changes immediately. Command instructions apply only to newly created agents."
+            error={settings.saveError}
+            actionLabel={settings.saving ? "Saving…" : "Save changes"}
+            disabled={settings.saving || !dirty || collapseLinesError !== null}
+            onPress={() => void settings.save(draft, revision)}
+          />
+        </SettingsCard>
+      </SettingsSection>
+    </>
   );
 }

package/index.client.tsx

@@ -4,10 +4,22 @@ import type { PluginCleanup } from "@getpaseo/plugin";
 import type { InlineActionsClient } from "./client/sdk-compat";
 import { CodeBlockActions } from "./client/code-block-actions";
 import { SettingsScreen } from "./client/settings-screen";
+import { RunReport, runReportSchema, transformRunReport } from "./client/run-report";
 import { RUNNABLE_LANGUAGES } from "./shared/code-blocks";
 import { terminalOutputSource } from "./shared/contracts";
 
 export default function contribute(client: InlineActionsClient): PluginCleanup {
+  client.addTimelineTransformer({
+    id: "terminal-run-report",
+    query: { itemType: "user_message" },
+    transform: transformRunReport,
+  });
+  client.addTimelineRenderer({
+    kind: "terminal-run-report",
+    version: 1,
+    schema: runReportSchema,
+    Component: RunReport,
+  });
   if (typeof client.addCodeBlockActions === "function") {
     client.addCodeBlockActions({
       id: "run",

package/index.server.ts

@@ -1,6 +1,7 @@
 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 {
@@ -16,11 +17,25 @@ 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.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 () => {

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,6 +1,6 @@
 {
   "name": "paseo-terminal-integration",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Run agent code blocks in a Paseo terminal and send the output back to the agent; attach terminal output to prompts",
   "keywords": [
     "agents",
@@ -20,9 +20,11 @@
   },
   "files": [
     "paseo-plugin.json",
+    "OVERVIEW.md",
     "index.client.tsx",
     "index.server.ts",
     "client/",
+    "instructions/",
     "server/",
     "shared/",
     "!**/*.test.ts"

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

@@ -7,7 +7,8 @@ import { StringDecoder } from "node:string_decoder";
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { interpreterFor, type Interpreter } from "../shared/code-blocks";
 import { TERMINAL_NAME, type RunMode, type RunSnapshot } from "../shared/contracts";
-import { fenced, trimBlankEdges } from "../shared/text";
+import { formatRunReport } from "../shared/run-report";
+import { trimBlankEdges } from "../shared/text";
 
 type Paseo = PluginHandlerContext["paseo"];
 type TerminalHandle = ReturnType<Paseo["terminals"]["ref"]>;
@@ -474,14 +475,13 @@ function formatReport(run: Run): string {
     run.mode === "background"
       ? "in the background, with no terminal"
       : `in the Paseo terminal "${TERMINAL_NAME}"`;
-  return [
-    `I ran this ${where} (cwd \`${run.cwd}\`), ${outcome}:`,
-    "",
-    fenced(run.code, run.lang),
-    "",
-    output ? `Output${note}:` : "It printed no output.",
-    ...(output ? ["", fenced(output, "text")] : []),
-  ].join("\n");
+  return formatRunReport({
+    intro: `I ran this ${where} (cwd \`${run.cwd}\`), ${outcome}:`,
+    language: run.lang,
+    code: run.code,
+    outputLabel: output ? `Output${note}:` : "It printed no output.",
+    output,
+  });
 }
 
 function shellQuote(value: string): 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/run-report.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { fenced } from "./text";
+
+export const RUN_REPORT_MARKER = "[paseo-terminal-integration-report]: # (v1)";
+
+export const runReportSchema = z.object({
+  intro: z.string(),
+  language: z.string(),
+  code: z.string(),
+  outputLabel: z.string(),
+  output: z.string(),
+  outputLineCount: z.number().int().nonnegative(),
+});
+
+export type RunReportData = z.output<typeof runReportSchema>;
+
+export function wrapRunReportOutcome(intro: string): string {
+  const splitAt = intro.lastIndexOf("), ");
+  return splitAt < 0 ? intro : `${intro.slice(0, splitAt + 1)}\n${intro.slice(splitAt + 3)}`;
+}
+
+export function formatRunReport(data: Omit<RunReportData, "outputLineCount">): string {
+  return [
+    RUN_REPORT_MARKER,
+    "",
+    data.intro,
+    "",
+    fenced(data.code, data.language),
+    "",
+    data.outputLabel,
+    ...(data.output ? ["", fenced(data.output, "text")] : []),
+  ].join("\n");
+}
+
+export function parseRunReport(text: string): RunReportData | null {
+  const lines = text.split("\n");
+  if (lines[0] !== RUN_REPORT_MARKER) return null;
+
+  let cursor = skipBlankLines(lines, 1);
+  const intro = lines[cursor++];
+  if (!intro) return null;
+
+  cursor = skipBlankLines(lines, cursor);
+  const command = parseFence(lines, cursor);
+  if (!command) return null;
+
+  cursor = skipBlankLines(lines, command.next);
+  const outputLabel = lines[cursor++];
+  if (!outputLabel) return null;
+
+  cursor = skipBlankLines(lines, cursor);
+  let output = "";
+  if (cursor < lines.length) {
+    const outputFence = parseFence(lines, cursor);
+    if (!outputFence || outputFence.language !== "text") return null;
+    output = outputFence.content;
+    cursor = skipBlankLines(lines, outputFence.next);
+  }
+  if (cursor !== lines.length) return null;
+
+  return {
+    intro,
+    language: command.language,
+    code: command.content,
+    outputLabel,
+    output,
+    outputLineCount: output ? output.split("\n").length : 0,
+  };
+}
+
+function skipBlankLines(lines: readonly string[], from: number): number {
+  let cursor = from;
+  while (cursor < lines.length && lines[cursor] === "") cursor++;
+  return cursor;
+}
+
+function parseFence(
+  lines: readonly string[],
+  from: number,
+): { language: string; content: string; next: number } | null {
+  const match = /^(`{3,})([^`]*)$/.exec(lines[from] ?? "");
+  if (!match) return null;
+  const fence = match[1];
+  const language = match[2].trim();
+  const end = lines.indexOf(fence, from + 1);
+  if (end < 0) return null;
+  return { language, content: lines.slice(from + 1, end).join("\n"), next: end + 1 };
+}

package/shared/settings.ts

@@ -1,12 +1,32 @@
 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 DEFAULT_COLLAPSE_OUTPUT_AFTER_LINES = 20;
 
 export const preferences = defineSettings({
   id: "preferences",
   scope: "host",
-  version: 1,
+  version: 3,
   schema: z.object({
     /** Initial state of a code block's "Send output to agent" checkbox. */
     sendToAgent: z.boolean().default(true),
+    /** Automatically collapse a sent run report when its output exceeds this many lines; 0 disables. */
+    collapseOutputAfterLines: z
+      .number()
+      .int()
+      .min(0)
+      .max(5_000)
+      .default(DEFAULT_COLLAPSE_OUTPUT_AFTER_LINES),
+    /** 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;
+  },
 });