paseo-terminal-integration 0.4.0 → 0.5.0

package/README.md

@@ -29,6 +29,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/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="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={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.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.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",
@@ -23,6 +23,7 @@
     "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/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 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;
+  },
 });