paseo-smart-session 1.2.5 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/paseo-smart-session?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-smart-session)
 [![npm downloads](https://img.shields.io/npm/dm/paseo-smart-session?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-smart-session)
-[![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.8.0-8A63D2?style=for-the-badge)](https://paseo.sh)
+[![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.14.0-8A63D2?style=for-the-badge)](https://paseo.sh)
 [![License](https://img.shields.io/github/license/tomgrin10/paseo-smart-session?style=for-the-badge&color=2563eb)](LICENSE)
 
 Give Paseo agents a safe way to manage long-running work.
@@ -11,6 +11,22 @@ Smart Session lets an agent see how full its context is, save durable task state
 
 ![A Smart Session compaction handoff: the requested compact preserves the task state, then the resumed session is told to re-read its state file and continue](docs/screenshots/smart-compact-handoff.png)
 
+## Install
+
+Install from npm using the latest Paseo release:
+
+```sh
+paseo plugin install paseo-smart-session
+```
+
+```sh
+paseo plugin ls                    # confirm it is running
+paseo plugin update smart-session
+paseo plugin remove smart-session
+```
+
+On first load, Smart Session registers its Claude Code hooks. Its MCP server is attached by Paseo when an interactive session opens. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
+
 ## What it does
 
 ### Lets agents compact themselves
@@ -32,28 +48,6 @@ Smart Session keeps a local history of:
 
 That history remains useful after an individual session ends or a provider cache changes.
 
-## Install
-
-Install from npm on Paseo 0.9.0 or newer:
-
-```sh
-paseo plugin install npm:paseo-smart-session@1.2.5
-```
-
-Paseo 0.8 can install the same plugin from Git:
-
-```sh
-paseo plugin add tomgrin10/paseo-smart-session --ref v1.2.5
-```
-
-```sh
-paseo plugin ls                    # confirm it is running
-paseo plugin update smart-session
-paseo plugin remove smart-session
-```
-
-On first load, Smart Session registers its Claude Code hooks and MCP server. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
-
 ## How an agent uses it
 
 Smart Session exposes these MCP tools to Paseo agents:
@@ -141,7 +135,7 @@ When the Paseo daemon requires a password, Smart Session resolves it in this ord
 
 The secret is used only to connect to the daemon. It is never written or logged.
 
-## Develop locally
+## Development
 
 ```sh
 git clone https://github.com/tomgrin10/paseo-smart-session.git
@@ -162,16 +156,37 @@ Reloading the plugin is enough. Do not restart the Paseo daemon: that interrupts
 
 ## Data and privacy
 
-Smart Session reads local Claude Code usage information and communicates with the local Paseo daemon. Its usage history, settings, and task state stay under `$PASEO_HOME`. Apart from narrowly maintaining its own Claude Code hook and MCP entries, it does not modify user configuration.
+Smart Session reads local Claude Code usage information and communicates with the local Paseo daemon. Its usage history, settings, and task state stay under `$PASEO_HOME`. Apart from narrowly maintaining its own Claude Code hook entries, it does not modify user configuration. MCP attachment is local to each Paseo session.
 
-## More Paseo plugins
+## License
 
-Also available from [Tom Gringauz](https://github.com/tomgrin10):
+[MIT](LICENSE) © 2026 Tom Gringauz.
 
-- [Defer](https://www.npmjs.com/package/paseo-defer) — Schedule messages to agents for later delivery.
-- [Graphite](https://www.npmjs.com/package/paseo-graphite) — Monitor Graphite stacks and PR action state.
-- [Vitals](https://www.npmjs.com/package/paseo-vitals) — Host, Paseo, agent, and Docker health in one dashboard.
+## Navigation and display
 
-## License
+Open this plugin from Command-K or its sidebar entry. **Overview** and **Display settings** link the main view and settings directly, without opening the Plugins settings page. Hiding a sidebar entry keeps Command-K available.
 
-[MIT](LICENSE) © 2026 Tom Gringauz.
+Display settings can also hide this plugin's workspace header or composer buttons independently. Hidden buttons stay hidden for newly opened workspaces; restoring them retains the latest button status.
+
+## Paseo 0.14 agent integration
+
+The Smart Session MCP attaches automatically when an interactive Claude or Codex session opens, including resume, refresh and import. Normal plugin startup no longer registers a global Claude MCP. Existing global entries are preserved; usage history and checkpoints remain in place. The bridge also respects a custom daemon listen address.
+
+Requires Paseo **0.14.0 or newer**. Agent tools are scoped to interactive Claude
+and Codex sessions; history-only opens receive none. They become available on
+the next idle session open after install or reload. The agent label
+`plugin-tools/enabled: "false"` opts a session out. Existing plugin data and
+settings are retained.
+
+## Other plugins
+
+- [Defer](https://github.com/tomgrin10/paseo-defer) — Schedule messages for later delivery.
+- [Graphite](https://github.com/tomgrin10/paseo-graphite) — Graphite stacks and PR status.
+- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, agent, and Docker health.
+- [Session Guard](https://github.com/tomgrin10/paseo-session-guard) — Pause at session limits and continue after reset.
+- [Transfer](https://github.com/tomgrin10/paseo-transfer) — Copy or move workspaces between hosts.
+- [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search conversations across connected hosts.
+- [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) — Send GitHub and Graphite PRs to Paseo from Chrome.
+- [Dispatch](https://github.com/tomgrin10/paseo-dispatch) — Route tasks to existing workspaces (development preview).
+
+- [Follow-up](https://github.com/tomgrin10/paseo-follow-up) — Track workspace PRs, remaining tasks and completion.

package/client/button-visibility.ts

@@ -0,0 +1,32 @@
+import type { PluginClientContext, PluginButtonRegistration } from "@getpaseo/plugin/client";
+import { subscribeDisplay } from "./display";
+
+export function withButtonVisibility(client: PluginClientContext) {
+  const entries = new Set<{ reconcile(): void; remove(): void }>();
+  let enableHeader = true;
+  let enableComposer = true;
+  function gated<K extends "addHeaderButton" | "addComposerPill">(method: K, input: Parameters<PluginClientContext[K]>[0]): PluginButtonRegistration {
+    let descriptor = input.button;
+    let registration: PluginButtonRegistration | undefined;
+    const entry = {
+      reconcile() {
+        const enabled = method === "addHeaderButton" ? enableHeader : enableComposer;
+        if (enabled && !registration) registration = (client[method] as (value: typeof input) => PluginButtonRegistration)({ ...input, button: descriptor });
+        if (!enabled && registration) { registration.remove(); registration = undefined; }
+      },
+      remove() { registration?.remove(); registration = undefined; entries.delete(entry); },
+    };
+    entries.add(entry);
+    entry.reconcile();
+    return { remove: entry.remove, update(patch) { descriptor = { ...descriptor, ...patch }; registration?.update(patch); } };
+  }
+  const buttons = Object.create(client) as PluginClientContext;
+  buttons.addHeaderButton = input => gated("addHeaderButton", input);
+  buttons.addComposerPill = input => gated("addComposerPill", input);
+  const unsubscribe = subscribeDisplay(values => {
+    
+    enableComposer = values.enable_composer_button;
+    for (const entry of entries) entry.reconcile();
+  });
+  return { client: buttons, dispose() { unsubscribe(); for (const entry of [...entries]) entry.remove(); } };
+}

package/client/display.tsx

@@ -0,0 +1,102 @@
+import type { PluginClientContext, PluginSidebarContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useSettings } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { useEffect } from "react";
+import { ActivityIndicator, ScrollView, Text, View } from "react-native";
+import { displayPreferences, displayRpc } from "../shared/display";
+import { withNavigation } from "./navigation";
+import { sidebarVisibility } from "./sidebar-visibility";
+
+type Display = import("zod").infer<typeof displayPreferences.schema>;
+const listeners = new Set<(values: Display) => void>();
+export function subscribeDisplay(listener: (values: Display) => void) { listeners.add(listener); return () => { listeners.delete(listener); }; }
+
+function DisplaySettings({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(displayPreferences);
+  const values = settings.status === "ready" ? settings.values : undefined;
+  useEffect(() => {
+    if (values !== undefined) for (const listener of listeners) listener(values);
+  }, [values]);
+
+  if (settings.status === "loading") return <ActivityIndicator accessibilityLabel="Loading display settings" color={theme.colors.foregroundMuted} />;
+  if (settings.status !== "ready") return (
+    <View style={{ gap: 12 }}>
+      <Text style={{ color: theme.colors.statusDanger }}>{settings.error}</Text>
+      <SettingsCard>
+        <SettingsAction label="Try loading the saved settings again" actionLabel="Retry" onPress={() => void settings.reload()} />
+        {settings.status === "invalid" && <SettingsAction label="Replace invalid display settings with defaults" actionLabel="Reset" disabled={settings.saving} onPress={() => void settings.reset()} />}
+
+      </SettingsCard>
+      {settings.saveError && <Text style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
+    </View>
+  );
+
+  return (
+    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
+    <SettingsSection title="Navigation">
+      <SettingsCard>
+        <SettingsSwitch
+          label="Show in sidebar"
+          hint="Open this plugin from Command-K (Ctrl-K on Windows and Linux) while viewing a workspace or plugin on this host."
+          value={settings.values.showSidebar}
+          disabled={settings.saving}
+          onValueChange={(showSidebar) => void settings.save({ ...settings.values, showSidebar }, settings.revision)}
+        />
+
+        <SettingsSwitch label="Show composer button" hint="Command-K and the sidebar remain available when this button is hidden." value={settings.values.enable_composer_button} disabled={settings.saving} onValueChange={(enable_composer_button) => void settings.save({ ...settings.values, enable_composer_button }, settings.revision)} />
+      </SettingsCard>
+      {settings.saveError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
+    </SettingsSection>
+    </ScrollView>
+  );
+}
+
+/** Settings notifications reach mounted screens; poll for changes made on other clients. */
+export function contributeDisplay(client: PluginClientContext, item: PluginSidebarContribution) {
+  const sidebar = sidebarVisibility(() => client.addSidebarItem(item));
+  // Paseo 0.10.1 memoizes sidebar route resolution when an installation mounts.
+  // Register synchronously, then reconcile the saved preference, so that an
+  // already-open sidebar route can resolve its surface during that first render.
+  sidebar.set(true);
+  const Settings = withNavigation(DisplaySettings, client, item.surface, "display");
+  const removeSurface = client.addSurface("display-settings", Settings);
+  const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: Settings });
+  const removeCommand = client.addCommandCenterItem({
+    id: "display-settings",
+    title: `${item.title}: display settings`,
+    icon: "PanelLeft",
+    keywords: [item.title, "sidebar", "show", "hide", "display", "settings"],
+    context: "global",
+    onSelect({ openSurface }) { openSurface("display-settings"); },
+  });
+  let disposed = false;
+  let pending = false;
+  let generation = 0;
+  const update = (values: Display) => { generation += 1; sidebar.set(values.showSidebar); };
+  listeners.add(update);
+  const refresh = async () => {
+    if (disposed || pending) return;
+    pending = true;
+    const currentGeneration = generation;
+    try {
+      const result = await client.rpc(displayRpc.read, {});
+      if (!disposed && generation === currentGeneration && result.status === "ready") {
+        const parsed = displayPreferences.schema.safeParse(result.values);
+        if (parsed.success) { sidebar.set(parsed.data.showSidebar); for (const listener of listeners) listener(parsed.data); }
+      }
+    } catch {
+      // Retain the last valid preference through temporary disconnects.
+    } finally { pending = false; }
+  };
+  void refresh();
+  const timer = setInterval(() => void refresh(), 5000);
+  return () => {
+    disposed = true;
+    clearInterval(timer);
+    listeners.delete(update);
+    sidebar.dispose();
+    removeSurface();
+    removeSettings();
+    removeCommand();
+  };
+}

package/client/navigation.tsx

@@ -0,0 +1,14 @@
+import type { ComponentType } from "react";
+import type { PluginClientContext, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { Pressable, Text, View } from "react-native";
+
+export function withNavigation<P extends PluginSurfaceProps>(Component: ComponentType<P>, client: PluginClientContext, home: string, active = "overview") {
+  return function PluginView(props: P) {
+    return <View style={{ flex: 1, backgroundColor: props.theme.colors.surface0 }}>
+      <View accessibilityRole="toolbar" style={{ flexDirection: "row", flexWrap: "wrap", gap: 4, padding: 8, borderBottomWidth: 1, borderColor: props.theme.colors.border }}>
+        {[{ id: "overview", title: "Overview", target: home }, { id: "display", title: "Display settings", target: "display-settings" }].map(item => <Pressable key={item.id} accessibilityRole="button" accessibilityState={{ selected: active === item.id }} onPress={() => client.openSurface(item.target)} style={({ pressed }) => ({ minHeight: 44, paddingHorizontal: 12, justifyContent: "center", borderRadius: 6, backgroundColor: pressed || active === item.id ? props.theme.colors.surface2 : "transparent" })}><Text style={{ color: active === item.id ? props.theme.colors.foreground : props.theme.colors.foregroundMuted, fontSize: 13, fontWeight: active === item.id ? "600" : "400" }}>{item.title}</Text></Pressable>)}
+      </View>
+      <Component {...props} />
+    </View>;
+  };
+}

package/client/sidebar-visibility.ts

@@ -0,0 +1,21 @@
+/** Own one sidebar registration; late reads cannot register after teardown. */
+export function sidebarVisibility(register: () => (() => void) | void) {
+  let disposed = false;
+  let remove: (() => void) | undefined;
+  return {
+    set(visible: boolean) {
+      if (disposed) return;
+      if (visible && !remove) remove = register() ?? (() => {});
+      if (!visible && remove) {
+        remove();
+        remove = undefined;
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      remove?.();
+      remove = undefined;
+    },
+  };
+}

package/client/surface.tsx

@@ -536,7 +536,7 @@ export function SmartSessionSurface({ theme, layout }: PluginSurfaceProps) {
                     : install.pluginDir === null
                       ? "Not registered. Nothing will ask a session to compact itself."
                       : `Registered: ${install.hooks.join(", ")}. Only entries pointing at this plugin are touched; the MCP server is ${
-                          install.mcp === "unavailable" ? "not registered — the claude CLI was not reachable" : "registered"
+                          install.mcp === "session" ? "attached when a Paseo session opens" : install.mcp === "unavailable" ? "not registered — the claude CLI was not reachable" : "registered"
                         }.`
               }
               onPress={toggleInstallHooks}

package/docs/navigation-verification.md

@@ -0,0 +1,11 @@
+# Navigation verification
+
+Verified the actual plugin in an isolated Paseo 0.12.0 daemon with synthetic workspace and provider data, using the app web runtime at 1440×1000 and 390×844.
+
+- Sidebar main view → Display settings → Overview opens the plugin surfaces directly.
+- Compact settings have no horizontal overflow and preserve accessible native switches.
+- Existing saved sidebar preferences retain their values. Button-bearing plugins expose independent positive enable_ preferences; hiding a button does not stop its feature.
+- Graphite and Transfer header hiding/restoration were exercised through the UI; Transfer settings remained reachable from Command-K while its sidebar was hidden. Follow-up's choice survived a full page reload.
+- Button lifecycle regressions cover registrations discovered while hidden, retaining the latest descriptor, duplicate prevention, restoration and teardown.
+
+Screenshots: [desktop](screenshots/display-settings-desktop.png), [compact](screenshots/display-settings-mobile.png). Screenshots contain synthetic data. No main daemon restart or real-agent messages were used.

package/index.client.tsx

@@ -1,3 +1,6 @@
+import { withButtonVisibility } from "./client/button-visibility";
+import { contributeDisplay } from "./client/display";
+import { withNavigation } from "./client/navigation";
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 
 import { contributeClient, refreshPills } from "./client/pill";
@@ -5,9 +8,11 @@ import { SmartSessionSurface } from "./client/surface";
 import { enrolmentState } from "./shared/governor";
 import { getSettings, setSettings } from "./shared/smart-session";
 
-export default function contribute(client: PluginClientContext) {
-  client.addSurface("overview", SmartSessionSurface);
-  client.addSidebarItem({
+export default function contribute(host: PluginClientContext) {
+  const visibility = withButtonVisibility(host);
+  const client = visibility.client;
+  client.addSurface("overview", withNavigation(SmartSessionSurface, client, "overview"));
+  const removeDisplay = contributeDisplay(client, {
     id: "smart-session",
     title: "Smart Session",
     icon: "Gauge",
@@ -38,5 +43,6 @@ export default function contribute(client: PluginClientContext) {
     },
   });
 
-  return contributeClient(client);
+  const removeClient = contributeClient(client);
+  return () => { visibility.dispose(); removeDisplay(); return removeClient(); };
 }

package/index.server.ts

@@ -1,3 +1,5 @@
+import { contributeSessionMcp } from "./server/session-mcp.ts";
+import { displayPreferences } from "./shared/display";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 
 import { readAgents, withDaemon } from "./server/daemon.ts";
@@ -38,6 +40,8 @@ import { queue } from "./server/governor.ts";
 import "./server/install-on-load.ts";
 
 export default function contribute(server: PluginServerContext) {
+  const removeSessionMcp = contributeSessionMcp(server);
+  server.registerSettings(displayPreferences);
   server.handle(budgetStatus, async () => {
     try {
       const since = Date.now() - 14 * 24 * 60 * 60 * 1000;
@@ -189,6 +193,7 @@ export default function contribute(server: PluginServerContext) {
   // The recorder and governor register their timers in this shared lifecycle.
   // Paseo waits for this cleanup before stopping the plugin subprocess.
   return async () => {
+    removeSessionMcp();
     const teardowns = lifecycle.teardowns.splice(0);
     for (const teardown of teardowns) await teardown();
   };

package/mcp.mjs

@@ -71,6 +71,12 @@ const log = (...args) => console.error("[smart-session mcp]", ...args);
  * installed. On a managed Git install the fallback instead finds the `paseo` CLI
  * on `PATH` and resolves the client from its own installed dependencies — the
  * same package the running daemon was built with.
+ *
+ * The desktop app is the exception. Its client lives inside `app.asar`, which
+ * only Electron can read, and its `paseo` is a shell wrapper with no
+ * `node_modules` beside it. `server/install.ts` therefore registers this server
+ * to run on the app's own Electron runtime in node mode, and from there the
+ * client resolves through `process.resourcesPath`.
  */
 let daemonClientModule = null;
 
@@ -78,22 +84,38 @@ const CLIENT_SPECIFIER = ["@getpaseo", "client", "internal", "daemon-client"].jo
 
 async function loadDaemonClient() {
   if (daemonClientModule !== null) return daemonClientModule;
-  try {
-    daemonClientModule = await import(CLIENT_SPECIFIER);
-    return daemonClientModule;
-  } catch (directError) {
-    const cliPath = findPaseoCli();
-    if (cliPath === null) throw directError;
+  const failures = [];
+  for (const { label, resolve } of clientCandidates()) {
     try {
-      const resolved = createRequire(cliPath).resolve(CLIENT_SPECIFIER);
-      daemonClientModule = await import(pathToFileURL(resolved).href);
+      daemonClientModule = await import(resolve());
       return daemonClientModule;
-    } catch (viaCliError) {
-      throw new Error(
-        `Cannot resolve ${CLIENT_SPECIFIER} directly (${directError.message}) or via the paseo CLI at ${cliPath} (${viaCliError.message})`,
-      );
+    } catch (error) {
+      failures.push(`${label} (${error.message})`);
     }
   }
+  throw new Error(`Cannot resolve ${CLIENT_SPECIFIER} ${failures.join(" or ")}${desktopHint()}`);
+}
+
+/** Every place the client can come from, cheapest first. */
+function clientCandidates() {
+  const fromEntry = (entry) => () => pathToFileURL(createRequire(entry).resolve(CLIENT_SPECIFIER)).href;
+  const candidates = [{ label: "directly", resolve: () => CLIENT_SPECIFIER }];
+  // Set only under Electron, where the bundled CLI inside app.asar is readable.
+  if (typeof process.resourcesPath === "string") {
+    const entry = join(process.resourcesPath, "app.asar", "node_modules", "@getpaseo", "cli", "dist", "index.js");
+    candidates.push({ label: `from the Paseo app bundle at ${process.resourcesPath}`, resolve: fromEntry(entry) });
+  }
+  const cliPath = findPaseoCli();
+  if (cliPath !== null) candidates.push({ label: `via the paseo CLI at ${cliPath}`, resolve: fromEntry(cliPath) });
+  return candidates;
+}
+
+/** Explains the one failure a person can fix without reading the code. */
+function desktopHint() {
+  if (process.versions.electron !== undefined) return "";
+  const cliPath = findPaseoCli();
+  if (cliPath === null || !existsSync(join(dirname(cliPath), "..", "app.asar"))) return "";
+  return ". The paseo CLI is the desktop app's, whose client only its own runtime can load: reload the smart-session plugin so it re-registers this MCP server on that runtime, then restart the Claude Code session";
 }
 
 /** Finds `paseo` on PATH and resolves symlinks, the way a shell's `which` would. */
@@ -112,11 +134,21 @@ function findPaseoCli() {
   return null;
 }
 
+function daemonUrl() {
+  if (process.env.PASEO_DAEMON_URL) return process.env.PASEO_DAEMON_URL;
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  try {
+    const config = JSON.parse(readFileSync(join(home, "config.json"), "utf8"));
+    if (typeof config.daemon?.listen === "string") return `ws://${config.daemon.listen}/ws`;
+  } catch { /* Use the documented default when configuration is absent. */ }
+  return "ws://127.0.0.1:6767/ws";
+}
+
 async function callPlugin(method, input) {
   const { DaemonClient } = await loadDaemonClient();
   const password = await resolveDaemonPassword();
   const client = new DaemonClient({
-    url: process.env.PASEO_DAEMON_URL ?? "ws://127.0.0.1:6767/ws",
+    url: daemonUrl(),
     clientId: "smart-session-mcp",
     clientType: "cli",
     reconnect: { enabled: false },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "1.2.5",
+  "version": "2.0.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {
@@ -33,13 +33,13 @@
     "typecheck": "tsc --noEmit",
     "test": "node --test --experimental-strip-types *.test.ts",
     "check": "node check-bundles.mjs && node check-gitinstall.mjs && node check-teardown.mjs && node check-mcp-resolve.mjs",
-    "verify": "npm run typecheck && npm run test && npm run check"
+    "verify": "npm run typecheck && npm run test && npm run check && node --test button-visibility.test.mjs"
   },
   "devDependencies": {
     "@babel/parser": "^8.0.4",
-    "@getpaseo/client": "0.8.0-beta.1",
-    "@getpaseo/plugin": "0.8.0-beta.1",
-    "@getpaseo/protocol": "0.8.0-beta.1",
+    "@getpaseo/client": "0.14.0",
+    "@getpaseo/plugin": "0.14.0",
+    "@getpaseo/protocol": "0.14.0",
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^22.10.2",
     "@types/react": "~19.2.0",

package/paseo-plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "smart-session",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.14.0"
   }
 }

package/server/install.ts

@@ -7,10 +7,10 @@
  * feature was off for anyone who skimmed, and off in a way that looked like it was
  * working — the surface said "on", and nothing ever happened.
  *
- * Paseo cannot do this for us. Its plugin API contributes UI, commands, timeline
- * renderers and RPCs, and explicitly nothing about agent configuration — there is
- * no hook contribution and no way to set an agent's environment. So the plugin
- * reconciles the entries itself, in `~/.claude/settings.json`.
+ * Paseo 0.14 attaches MCP servers at session open. Claude Code's provider hooks
+ * still need reconciliation in `~/.claude/settings.json`; this module owns only
+ * those hooks during normal load. Global MCP registration is an explicit legacy
+ * compatibility operation, never the default.
  *
  * The rules that make that acceptable:
  *
@@ -78,7 +78,7 @@ export interface InstallReport {
   readonly changed: boolean;
   /** One line per managed event, for the surface to show. */
   readonly hooks: string[];
-  readonly mcp: "present" | "added" | "updated" | "unavailable" | "skipped";
+  readonly mcp: "present" | "added" | "updated" | "unavailable" | "skipped" | "session";
   readonly error: string | null;
 }
 
@@ -198,6 +198,45 @@ async function writeAtomic(path: string, text: string): Promise<void> {
   await rename(temp, path);
 }
 
+export interface McpDefinition {
+  type: "stdio";
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
+export interface McpRuntime {
+  electron: string | undefined;
+  execPath: string;
+  appImage: string | undefined;
+}
+
+const currentRuntime = (): McpRuntime => ({
+  electron: process.versions.electron,
+  execPath: process.execPath,
+  appImage: process.env.APPIMAGE,
+});
+
+/**
+ * How Claude Code should launch `mcp.mjs`.
+ *
+ * `node` from `PATH`, except under the desktop app. There the daemon client lives
+ * inside `app.asar`, which plain Node cannot read, so the server runs on the
+ * runtime this plugin is itself running on — Electron in node mode, the same way
+ * the app launches its bundled `paseo` CLI. An AppImage mounts at a fresh path on
+ * every launch, so its stable `$APPIMAGE` stands in for the mounted executable.
+ */
+export function mcpDefinition(pluginDir: string, runtime: McpRuntime = currentRuntime()): McpDefinition {
+  const args = [join(pluginDir, "mcp.mjs")];
+  if (runtime.electron === undefined) return { type: "stdio", command: "node", args };
+  return {
+    type: "stdio",
+    command: runtime.appImage ?? runtime.execPath,
+    args,
+    env: { ELECTRON_RUN_AS_NODE: "1" },
+  };
+}
+
 /**
  * Registers the agent-facing MCP server, through Claude Code's own CLI.
  *
@@ -208,34 +247,31 @@ async function writeAtomic(path: string, text: string): Promise<void> {
  * install into a new directory, so an entry can exist while its script no longer
  * does.
  */
-export function mcpPointsAtPlugin(output: string, pluginDir: string): boolean {
+export function mcpPointsAtPlugin(output: string, definition: McpDefinition): boolean {
   const lines = output.split(/\r?\n/).map((line) => line.trim());
   return lines.includes("Scope: User config (available in all your projects)")
-    && lines.includes("Command: node")
-    && lines.includes(`Args: ${join(pluginDir, "mcp.mjs")}`);
+    && lines.includes(`Command: ${definition.command}`)
+    && lines.includes(`Args: ${definition.args.join(" ")}`)
+    && Object.entries(definition.env ?? {}).every(([key, value]) => lines.includes(`${key}=${value}`));
 }
 
 async function ensureMcp(pluginDir: string): Promise<InstallReport["mcp"]> {
   const run = (args: string[]): Promise<{ stdout: string }> =>
     execFileAsync("claude", args, { timeout: 20_000, maxBuffer: 1024 * 1024 });
+  const definition = mcpDefinition(pluginDir);
 
   let existing = false;
   try {
     const { stdout } = await run(["mcp", "get", "smart-session"]);
-    if (mcpPointsAtPlugin(stdout, pluginDir)) return "present";
+    if (mcpPointsAtPlugin(stdout, definition)) return "present";
     existing = true;
   } catch {
     // Absent, or no `claude` on PATH. The add below tells the two apart.
   }
 
-  const definition = JSON.stringify({
-    type: "stdio",
-    command: "node",
-    args: [join(pluginDir, "mcp.mjs")],
-  });
   try {
     if (existing) await run(["mcp", "remove", "smart-session", "--scope", "user"]);
-    await run(["mcp", "add-json", "--scope", "user", "smart-session", definition]);
+    await run(["mcp", "add-json", "--scope", "user", "smart-session", JSON.stringify(definition)]);
     return existing ? "updated" : "added";
   } catch {
     // No `claude` binary on the daemon's PATH is the usual reason, and it is not
@@ -263,7 +299,7 @@ function serialize<T>(work: () => Promise<T>): Promise<T> {
  * reads two files and writes none.
  */
 export function install(options: { registerMcp?: boolean } = {}): Promise<InstallReport> {
-  const registerMcp = options.registerMcp !== false;
+  const registerMcp = options.registerMcp === true;
   return serialize(async () => {
     const path = settingsPath();
     const settings = await readSettings();
@@ -323,7 +359,7 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
       settingsPath: path,
       changed,
       hooks: lines,
-      mcp: pluginDir === null || !registerMcp ? "skipped" : await ensureMcp(pluginDir),
+      mcp: pluginDir === null ? "skipped" : !registerMcp ? "session" : await ensureMcp(pluginDir),
       error: null,
     };
   });

package/server/session-mcp.ts

@@ -0,0 +1,26 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mcpDefinition, resolvePluginDir } from "./install.ts";
+import { readSettings } from "./settings.ts";
+
+/** MCP is a launch contribution, so it never writes global provider settings. */
+export function contributeSessionMcp(server: PluginServerContext) {
+  return server.before("agent.session_open", async ({ request }) => {
+    if (request.purpose !== "interactive" || !["claude", "codex"].includes(request.provider)
+      || request.labels["plugin-tools/enabled"] === "false" || !(await readSettings()).enabled) return;
+    const directory = await resolvePluginDir();
+    if (!directory) return;
+    const definition = mcpDefinition(directory);
+    return {
+      ...request,
+      mcpServers: { ...request.mcpServers, "smart-session": { ...definition, env: {
+        ...definition.env, PASEO_AGENT_ID: request.agentId,
+        PASEO_HOME: process.env.PASEO_HOME ?? join(homedir(), ".paseo"), SMART_SESSION_MCP_SCOPE: "paseo",
+        ...(process.env.PASEO_DAEMON_URL ? { PASEO_DAEMON_URL: process.env.PASEO_DAEMON_URL } : {}),
+        ...(process.env.PASEO_PASSWORD ? { PASEO_PASSWORD: process.env.PASEO_PASSWORD } : {}),
+        ...(process.env.PASEO_PASSWORD_FILE ? { PASEO_PASSWORD_FILE: process.env.PASEO_PASSWORD_FILE } : {}),
+      } } },
+    };
+  });
+}

package/shared/display.ts

@@ -0,0 +1,11 @@
+import { defineSettings, settingsRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const displayPreferences = defineSettings({
+  id: "display",
+  scope: "host",
+  version: 1,
+  schema: z.object({ enable_composer_button: z.boolean().default(true), showSidebar: z.boolean().default(true) }),
+});
+
+export const displayRpc = settingsRpc(displayPreferences.id);

package/shared/smart-session.ts

@@ -109,7 +109,7 @@ export const InstallReportSchema = z.object({
   settingsPath: z.string(),
   changed: z.boolean(),
   hooks: z.array(z.string()),
-  mcp: z.enum(["present", "added", "updated", "unavailable", "skipped"]),
+  mcp: z.enum(["present", "added", "updated", "unavailable", "skipped", "session"]),
   error: z.string().nullable(),
 });