paseo-terminal-integration 0.5.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

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

@@ -3,6 +3,7 @@ import {
   ExternalLink,
   SettingsAction,
   SettingsCard,
+  SettingsInput,
   SettingsRow,
   SettingsSection,
   SettingsSelect,
@@ -39,6 +40,14 @@ function ReadySettingsScreen({
 }) {
   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(
     () => ({
@@ -69,12 +78,25 @@ function ReadySettingsScreen({
           <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}
+            value={draft.sendToAgent}
             disabled={settings.saving}
             error={settings.saveError}
-            onValueChange={(sendToAgent) =>
-              void settings.save({ ...values, sendToAgent }, revision)
-            }
+            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"
@@ -186,14 +208,14 @@ function ReadySettingsScreen({
         </SettingsCard>
       </SettingsSection>
 
-      <SettingsSection title="Save instruction settings">
+      <SettingsSection title="Save settings">
         <SettingsCard>
           <SettingsAction
-            label="Apply to newly created agents"
-            hint="Saving does not modify agents that already exist."
+            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}
+            disabled={settings.saving || !dirty || collapseLinesError !== null}
             onPress={() => void settings.save(draft, revision)}
           />
         </SettingsCard>

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-terminal-integration",
-  "version": "0.5.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,6 +20,7 @@
   },
   "files": [
     "paseo-plugin.json",
+    "OVERVIEW.md",
     "index.client.tsx",
     "index.server.ts",
     "client/",

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/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

@@ -4,14 +4,22 @@ import { CLIENT_SERVER_INSTRUCTIONS, LOCAL_DAEMON_INSTRUCTIONS } from "./instruc
 
 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: 2,
+  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"),