paseo-smart-session 3.5.0 → 3.6.1

package/server/install.ts

@@ -14,12 +14,15 @@
  *
  * The rules that make that acceptable:
  *
- *   - **Own only our own.** An entry is ours when its command points at a
- *     `hooks/*.mjs` in this repository. Nothing else in the file is read for
- *     meaning, reordered or rewritten.
- *   - **Never write a path that does not exist.** The plugin directory comes from
- *     Paseo's own `config.json` and is then checked for the scripts themselves. A
- *     hook command pointing at a missing file fails on every turn of every session.
+ *   - **Own only our own.** An entry is ours when its command points at one of our
+ *     `hooks/*.mjs` scripts: the stable shim in Smart Session's data directory, or
+ *     (from older versions, migrated on the next load) an install's own `hooks/`.
+ *     Nothing else in the file is read for meaning, reordered or rewritten.
+ *   - **Never name an install directory.** Paseo deletes the old one on every update,
+ *     so the commands run shims in the fixed data directory (`server/hook-path.ts`),
+ *     each guarded so that a missing shim is a silent no-op. The shims are written, and
+ *     their pointer checked against the scripts themselves, before any command naming
+ *     them is.
  *   - **Write only on a real change.** Reconciling to identical JSON writes nothing,
  *     so the common case — every reload after the first — touches no files.
  *   - **Be reversible.** One backup, kept from the first modification, and turning
@@ -28,11 +31,13 @@
 
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
-import { access, copyFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
+import { PLUGIN_VERSION } from "../shared/version.ts";
+import { complete, pointerHealthy, pointShimsAt } from "./hook-path.ts";
 import { readSettings } from "./settings.ts";
 
 const execFileAsync = promisify(execFile);
@@ -94,16 +99,55 @@ async function exists(path: string): Promise<boolean> {
   }
 }
 
+interface Candidate {
+  readonly dir: string;
+  /** Explicitly named (SMART_SESSION_PLUGIN_DIR): taken as is, whatever its version. */
+  readonly explicit?: boolean;
+}
+
+/** Every install directory under `$PASEO_HOME/plugins/<id>/<install>/`, newest first. */
+async function scanInstalls(home: string): Promise<string[]> {
+  const root = join(home, "plugins");
+  const found: { dir: string; mtime: number }[] = [];
+  for (const id of await readdir(root).catch(() => [] as string[])) {
+    for (const install of await readdir(join(root, id)).catch(() => [] as string[])) {
+      // npm installs land in node_modules/<package>, Git installs in checkout/.
+      for (const dir of [join(root, id, install, "node_modules", "paseo-smart-session"), join(root, id, install, "checkout")]) {
+        const info = await stat(dir).catch(() => null);
+        if (info?.isDirectory()) found.push({ dir, mtime: info.mtimeMs });
+      }
+    }
+  }
+  return found.sort((a, b) => b.mtime - a.mtime).map(({ dir }) => dir);
+}
+
+async function packageVersion(dir: string): Promise<string | null> {
+  try {
+    const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
+    return pkg.name === "paseo-smart-session" && typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Where this plugin's files live, according to Paseo.
+ * Where the running plugin's files live.
  *
- * Read from the host's own `config.json` rather than derived from the module's
- * location: Paseo compiles `index.server.ts` into a bundle whose path is an
- * implementation detail, and `import.meta` is not safe to rely on across that
- * compilation. Every configured plugin is checked rather than just `smart-session`,
- * because a second install under `--id something-else` is a supported thing to do.
+ * Paseo evaluates the server bundle from a string and hands it no directory, so
+ * `import.meta.url` and `__dirname` say nothing. What the bundle does carry is its own
+ * version, and the install it came from carries the same one in `package.json`. That is
+ * the first test, because `config.json` is not trustworthy during an update: on
+ * 2026-11-09 it still named the previous install when this ran, the hooks were written
+ * against it, and Paseo deleted it seconds later.
+ *
+ * Candidates are `SMART_SESSION_PLUGIN_DIR` (taken as is), every plugin `config.json`
+ * names (a second install under `--id something-else` is supported), then every install
+ * directory under `$PASEO_HOME/plugins`, newest first. Only a directory holding the
+ * scripts counts. The first whose version is the running one wins; failing that, the
+ * first complete one, which is what this did before it knew its version.
  */
-export async function resolvePluginDir(): Promise<string | null> {
+export async function resolvePluginDir(options: { version?: string } = {}): Promise<string | null> {
+  const version = options.version ?? PLUGIN_VERSION;
   const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
   let configured: string[] = [];
   try {
@@ -114,21 +158,28 @@ export async function resolvePluginDir(): Promise<string | null> {
       .map((entry) => entry.path)
       .filter((path): path is string => typeof path === "string" && path !== "");
   } catch {
-    // No config, or one we cannot read. Fall through to the environment.
+    // No config, or one we cannot read. Fall through to the environment and the scan.
   }
 
   const fromEnv = process.env.SMART_SESSION_PLUGIN_DIR;
-  const candidates = fromEnv !== undefined && fromEnv !== "" ? [fromEnv, ...configured] : configured;
-
-  for (const candidate of candidates) {
+  const candidates: Candidate[] = [
+    ...(fromEnv !== undefined && fromEnv !== "" ? [{ dir: fromEnv, explicit: true }] : []),
+    ...configured.map((dir) => ({ dir })),
+    ...(await scanInstalls(home)).map((dir) => ({ dir })),
+  ];
+
+  let fallback: string | null = null;
+  const seen = new Set<string>();
+  for (const { dir, explicit } of candidates) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
     // The scripts themselves are the proof. A directory that merely has the right
     // name would still produce hook commands that fail on every turn.
-    const complete = await Promise.all(
-      OUR_SCRIPTS.map((script) => exists(join(candidate, "hooks", script))),
-    );
-    if (complete.every(Boolean)) return candidate;
+    if (!(await complete(dir))) continue;
+    if (explicit === true || (await packageVersion(dir)) === version) return dir;
+    fallback ??= dir;
   }
-  return null;
+  return fallback;
 }
 
 /** Whether a hook command is one of ours, wherever it was installed from. */
@@ -137,8 +188,18 @@ function isOurs(command: unknown): boolean {
   return OUR_SCRIPTS.some((script) => command.includes(`hooks/${script}`));
 }
 
-function commandFor(pluginDir: string, script: string): string {
-  return `node ${join(pluginDir, "hooks", script)}`;
+/** A shell word, single-quoted. */
+function quote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * The command for one hook: the stable shim, guarded, so a missing shim is a silent
+ * no-op rather than a failing hook on every turn of every session.
+ */
+export function commandFor(shims: string, script: string): string {
+  const path = quote(join(shims, script));
+  return `if [ -f ${path} ]; then node ${path}; fi`;
 }
 
 /**
@@ -148,7 +209,7 @@ function commandFor(pluginDir: string, script: string): string {
  * directory or renamed a script leaves nothing stale behind — and so the manual
  * entries an early adopter added by hand are adopted rather than duplicated.
  */
-export function reconcile(existing: HookMap, pluginDir: string | null): HookMap {
+export function reconcile(existing: HookMap, shims: string | null): HookMap {
   const next: HookMap = {};
 
   for (const [event, groups] of Object.entries(existing)) {
@@ -162,13 +223,13 @@ export function reconcile(existing: HookMap, pluginDir: string | null): HookMap
     if (kept.length > 0) next[event] = kept;
   }
 
-  if (pluginDir === null) return next;
+  if (shims === null) return next;
 
   for (const { event, matcher, script } of MANAGED) {
     const groups = next[event] ?? [];
     const entry: HookEntry = {
       type: "command",
-      command: commandFor(pluginDir, script),
+      command: commandFor(shims, script),
       timeout: HOOK_TIMEOUT_SECONDS,
     };
     const group = groups.find((candidate) => (candidate.matcher ?? "") === matcher);
@@ -226,8 +287,8 @@ const currentRuntime = (): McpRuntime => ({
  * 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")];
+export function mcpDefinition(pluginDir: string, runtime: McpRuntime = currentRuntime(), script?: string): McpDefinition {
+  const args = [script ?? join(pluginDir, "mcp.mjs")];
   if (runtime.electron === undefined) return { type: "stdio", command: "node", args };
   return {
     type: "stdio",
@@ -303,7 +364,25 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
   return serialize(async () => {
     const path = settingsPath();
     const settings = await readSettings();
-    const pluginDir = settings.installHooks ? await resolvePluginDir() : null;
+    // Resolved and pointed at whether or not hooks are installed: the stdio MCP server
+    // and the bridge the asks name run through the same shims.
+    const resolved = await resolvePluginDir();
+    let shims: string | null = null;
+    if (resolved !== null) {
+      try {
+        shims = (await pointShimsAt(resolved)).dir;
+      } catch (error) {
+        return {
+          pluginDir: resolved,
+          settingsPath: path,
+          changed: false,
+          hooks: [],
+          mcp: "skipped",
+          error: `Could not write the hook shims into Smart Session's data directory (${(error as NodeJS.ErrnoException).code ?? "error"}), so no hooks were installed.`,
+        };
+      }
+    }
+    const pluginDir = settings.installHooks ? resolved : null;
 
     if (settings.installHooks && pluginDir === null) {
       return {
@@ -339,7 +418,7 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
     }
 
     const before = (parsed.hooks ?? {}) as HookMap;
-    const after = reconcile(before, pluginDir);
+    const after = reconcile(before, pluginDir === null ? null : shims);
     const merged = { ...parsed, hooks: after };
     if (Object.keys(after).length === 0) delete (merged as { hooks?: unknown }).hooks;
 
@@ -364,3 +443,20 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
     };
   });
 }
+
+/**
+ * Points the shims at the running install, if they do not already point at one that
+ * still exists. Cheap enough for a timer: when the pointer is healthy it stats a handful
+ * of files and writes nothing. When it moves, the hooks are reconciled too (which writes
+ * `settings.json` only if that changes anything). Returns whether the pointer moved.
+ */
+export async function refreshPointer(): Promise<boolean> {
+  // The load-time install() already pointed the shims at the running version; this only
+  // repairs a pointer whose target has since gone (or a shim someone deleted).
+  if (await pointerHealthy()) return false;
+  const dir = await resolvePluginDir();
+  if (dir === null) return false;
+  const { moved } = await pointShimsAt(dir);
+  if (moved) await install();
+  return moved;
+}

package/server/mcp-registrations.ts

@@ -0,0 +1,126 @@
+import { execFile } from "node:child_process";
+import { chmod, copyFile, readFile, readdir, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { promisify } from "node:util";
+
+/**
+ * Smart Session's agent tools are attached per launch (natively on Paseo 0.15+, or as a per-launch
+ * stdio server), so a user-scope "smart-session" MCP entry left by an older version only makes every
+ * Claude or Codex session on the machine, Paseo's or not, start its own `node mcp.mjs` — or fail to,
+ * when it points at an install directory a later update removed. This removes such entries from
+ * every Claude and Codex home Paseo launches agents with, backing each file up first.
+ *
+ * An entry is ours only when it runs this plugin's `mcp.mjs`. `.claude.json` holds credentials, so
+ * it is read but never written here: `claude mcp remove` does that, under Claude Code's own lock,
+ * with `CLAUDE_CONFIG_DIR` pointing at the home in question.
+ */
+export type Unregistered = { path: string; status: "removed" | "absent" | "foreign" | "unavailable" | "error"; error?: string };
+const NAME = "smart-session";
+const BACKUP = ".smart-session-unregister.bak";
+const OURS = /(?:^|[\\/])(?:paseo-smart-session|smart-session)[\\/](?:.*[\\/])?mcp\.mjs$/;
+const execFileAsync = promisify(execFile);
+
+/** Every Claude global config (.claude.json) and Codex config.toml Paseo may launch an agent with. */
+export async function agentHomes(env: NodeJS.ProcessEnv = process.env, paseoHome = env.PASEO_HOME ?? join(homedir(), ".paseo"), home = homedir()): Promise<{ claude: string[]; codex: string[] }> {
+  const claudeDirs = new Set<string>([env.CLAUDE_CONFIG_DIR?.trim() || home, home]);
+  const codexDirs = new Set<string>([env.CODEX_HOME?.trim() || join(home, ".codex"), join(home, ".codex")]);
+  // Homes set in Paseo's provider settings (agents.providers.<id>.env).
+  try {
+    const config = JSON.parse(await readFile(join(paseoHome, "config.json"), "utf8"));
+    for (const provider of Object.values(config?.agents?.providers ?? {}) as { env?: Record<string, string> }[]) {
+      if (provider?.env?.CLAUDE_CONFIG_DIR) claudeDirs.add(provider.env.CLAUDE_CONFIG_DIR);
+      if (provider?.env?.CODEX_HOME) codexDirs.add(provider.env.CODEX_HOME);
+    }
+  } catch { /* No config: the defaults. */ }
+  // Homes ZeroSub creates per account (~/.paseo/zerosub/homes/<id>/), Claude and Codex alike. ZeroSub
+  // seeds them from the main .claude.json, which is in the list above, so the entry does not come back.
+  const zerosub = join(paseoHome, "zerosub", "homes");
+  for (const entry of await readdir(zerosub, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isDirectory()) continue;
+    claudeDirs.add(join(zerosub, entry.name)); codexDirs.add(join(zerosub, entry.name));
+  }
+  const existing = async (paths: string[]) => [...new Set((await Promise.all(paths.map(async (p) => (await stat(p).catch(() => null))?.isFile() ? await realpath(p) : null))).filter((p): p is string => !!p))];
+  return {
+    claude: await existing([...claudeDirs].map((dir) => join(resolve(dir), ".claude.json"))),
+    codex: await existing([...codexDirs].map((dir) => join(resolve(dir), "config.toml"))),
+  };
+}
+
+const ours = (server: unknown) => {
+  const entry = server as { command?: unknown; args?: unknown } | null;
+  return [entry?.command, ...(Array.isArray(entry?.args) ? entry.args : [])].some((part) => typeof part === "string" && OURS.test(part));
+};
+
+async function backup(path: string): Promise<void> {
+  await copyFile(path, path + BACKUP, 1).catch((error) => { if (error.code !== "EEXIST") throw error; });
+  await chmod(path + BACKUP, (await stat(path)).mode & 0o777);
+}
+
+export type RunClaude = (args: string[], env: NodeJS.ProcessEnv) => Promise<unknown>;
+const runClaude: RunClaude = (args, env) => execFileAsync("claude", args, { env, timeout: 30_000, maxBuffer: 1024 * 1024 });
+
+export async function unregisterClaude(path: string, run: RunClaude = runClaude, home = homedir()): Promise<Unregistered> {
+  try {
+    const entry = JSON.parse(await readFile(path, "utf8"))?.mcpServers?.[NAME];
+    if (!entry) return { path, status: "absent" };
+    if (!ours(entry)) return { path, status: "foreign" };
+    await backup(path);
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    // ~/.claude.json is the default home's; any other directory is a CLAUDE_CONFIG_DIR.
+    if (dirname(path) === await realpath(home).catch(() => resolve(home))) delete env.CLAUDE_CONFIG_DIR; else env.CLAUDE_CONFIG_DIR = dirname(path);
+    try { await run(["mcp", "remove", NAME, "--scope", "user"], env); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { path, status: "unavailable" };
+      throw error;
+    }
+    const after = JSON.parse(await readFile(path, "utf8"))?.mcpServers?.[NAME];
+    return after ? { path, status: "error", error: "still registered after claude mcp remove" } : { path, status: "removed" };
+  } catch (error) { return { path, status: "error", error: (error as Error).message }; }
+}
+
+/** Removes [mcp_servers.smart-session] and its sub-tables when they run our mcp.mjs, keeping everything else verbatim. */
+export function withoutCodexEntry(text: string): string | null {
+  const lines = text.split("\n");
+  const header = (line: string) => /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(line)?.[1].replace(/["']/g, "") ?? null;
+  const mine = (name: string | null) => name === `mcp_servers.${NAME}` || name?.startsWith(`mcp_servers.${NAME}.`);
+  const tables: { start: number; end: number }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!mine(header(lines[i]!))) continue;
+    let end = i + 1;
+    while (end < lines.length && header(lines[end]!) === null) end++;
+    // Comments and blank lines just above the next table belong to it.
+    while (end > i + 1 && /^\s*(#.*)?$/.test(lines[end - 1]!)) end--;
+    tables.push({ start: i, end }); i = end - 1;
+  }
+  if (!tables.length) return null;
+  const body = tables.map((t) => lines.slice(t.start, t.end).join("\n")).join("\n");
+  const strings = [...body.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]!);
+  if (!strings.some((value) => OURS.test(value))) return text;
+  const keep = lines.filter((_, i) => !tables.some((t) => i >= t.start && i < t.end));
+  return keep.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export async function unregisterCodex(path: string): Promise<Unregistered> {
+  try {
+    const text = await readFile(path, "utf8");
+    const next = withoutCodexEntry(text);
+    if (next === null) return { path, status: "absent" };
+    if (next === text) return { path, status: "foreign" };
+    await backup(path);
+    const temporary = `${path}.smart-session.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(temporary, next, { mode: (await stat(path)).mode & 0o777 });
+    await rename(temporary, path);
+    return { path, status: "removed" };
+  } catch (error) { return { path, status: "error", error: (error as Error).message }; }
+}
+
+/** Removes Smart Session's own global registrations from every known home. Never throws. */
+export async function removeGlobalRegistrations(homes?: { claude: string[]; codex: string[] }, run: RunClaude = runClaude, home = homedir()): Promise<Unregistered[]> {
+  const found = homes ?? await agentHomes().catch(() => ({ claude: [], codex: [] }));
+  // One at a time: `claude mcp remove` is a whole CLI process, and they would share the main file's lock.
+  const results: Unregistered[] = [];
+  for (const path of found.claude) results.push(await unregisterClaude(path, run, home));
+  for (const path of found.codex) results.push(await unregisterCodex(path));
+  return results;
+}

package/server/native-tools.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import type { AgentToolContext, AgentToolDefinition, PluginSessionOpenRequest } from "@getpaseo/plugin/server";
+import { TOOL_SHAPES, agentTools, named } from "./agent-tools.mjs";
+
+/**
+ * Smart Session's agent tools served natively (Paseo 0.15+). At `agent.session_open` they go on
+ * `request.tools`, and the daemon lists them on the agent's own Paseo MCP server and routes each
+ * call here over IPC. No process per agent, and the caller's id comes from the daemon's per-agent
+ * endpoint rather than an environment variable. `mcp.mjs` stays as the per-launch fallback where
+ * the host doesn't serve plugin tools (`nativeToolsAvailable`).
+ *
+ * Names carry a `smart_` prefix: plugin tools share one namespace with Paseo's own, and a
+ * collision fails the agent's whole Paseo tool list.
+ */
+export const PREFIX = "smart_";
+
+type PaseoConfig = {
+  daemon?: { mcp?: { enabled?: boolean; injectIntoAgents?: boolean } };
+  agents?: { providers?: Record<string, { paseoTools?: { enabled?: boolean; disabledTools?: string[] } }> };
+};
+
+/** Whether this host serves plugin tools to this agent: `request.tools` exists, the daemon injects its MCP, and the provider's Paseo tools aren't off. */
+export function nativeToolsAvailable(request: Pick<PluginSessionOpenRequest, "provider"> & { tools?: unknown }, config: PaseoConfig | null): boolean {
+  if (!Array.isArray(request.tools)) return false;
+  if (config?.daemon?.mcp?.enabled === false || config?.daemon?.mcp?.injectIntoAgents === false) return false;
+  const policy = config?.agents?.providers?.[request.provider]?.paseoTools;
+  if (policy?.enabled === false) return false;
+  return !policy?.disabledTools?.some((name) => name.startsWith(PREFIX));
+}
+
+/** Calls one of this plugin's RPCs in-process, as the stdio server would over the daemon. */
+export type Invoke = (method: string, input: unknown, context: AgentToolContext) => Promise<unknown>;
+
+const fromJSONSchema = (schema: unknown): z.ZodType =>
+  (z as unknown as { fromJSONSchema: (schema: unknown) => z.ZodType }).fromJSONSchema(schema);
+
+/** The tool definitions for one session. The same text and rules as `mcp.mjs`, run in this process. */
+export function nativeTools(invoke: Invoke): AgentToolDefinition[] {
+  // Built once per worker: the definitions hold no per-session state (the caller comes with each call).
+  const cached = built.get(invoke);
+  if (cached) return cached;
+  const tools = TOOL_SHAPES.map((shape) => ({
+    name: PREFIX + shape.name,
+    description: named(shape.description, true),
+    input: fromJSONSchema(shape.inputSchema),
+    async execute(input: unknown, context: AgentToolContext) {
+      try {
+        const tools = agentTools({ agentId: context.agent.id, call: (method, payload) => invoke(method, payload, context) });
+        const text = await tools[shape.name as keyof typeof tools].run((input ?? {}) as Record<string, unknown>);
+        return { text: named(text, true) };
+      } catch (error) {
+        // A tool result, not a protocol error, so the model reads it, as in mcp.mjs.
+        return { isError: true, text: `Failed: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    },
+  }));
+  built.set(invoke, tools);
+  return tools;
+}
+const built = new WeakMap<Invoke, AgentToolDefinition[]>();

package/server/session-mcp.ts

@@ -1,26 +1,67 @@
-import type { PluginServerContext } from "@getpaseo/plugin/server";
+import type { PluginServerContext, PluginSessionOpenRequest } from "@getpaseo/plugin/server";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { readPointer, shimFor } from "./hook-path.ts";
 import { mcpDefinition, resolvePluginDir } from "./install.ts";
+import { type Invoke, nativeTools, nativeToolsAvailable } from "./native-tools.ts";
 import { readSettings } from "./settings.ts";
 
-/** MCP is a launch contribution, so it never writes global provider settings. */
-export function contributeSessionMcp(server: PluginServerContext) {
+const paseoHome = () => process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+
+async function paseoConfig(): Promise<Record<string, any> | null> {
+  try { return JSON.parse(await readFile(join(paseoHome(), "config.json"), "utf8")); } catch { return null; }
+}
+
+/** Providers whose sessions get the tools. A test harness may widen it to its fixture provider. */
+const providers = () => (process.env.SMART_SESSION_TOOL_PROVIDERS ?? "claude,codex").split(",").map((name) => name.trim());
+
+/**
+ * The agent tools are a launch contribution, so nothing global is written. On Paseo 0.15+ they go
+ * on `request.tools` and the daemon serves them through the agent's own Paseo MCP; otherwise this
+ * launch alone gets `mcp.mjs` as a stdio server. `SMART_SESSION_TOOLS` tells the hooks which names
+ * the agent has (`smart_checkpoint` or `checkpoint`).
+ */
+export function contributeSessionMcp(server: PluginServerContext, invoke: Invoke) {
+  // A reload or update detaches native tools from open sessions until each reopens. This worker's instance, and the
+  // instance that attached each session, let the hooks tell a detached session how to reach the tools meanwhile
+  // (hooks/context.mjs toolsMode). Written synchronously, before any session can open.
+  const instance = randomUUID();
+  const data = join(paseoHome(), "plugin-data", "smart-session");
+  try {
+    mkdirSync(join(data, "tools"), { recursive: true });
+    writeFileSync(join(data, `tools-instance.json.${instance}`), JSON.stringify({ instance }));
+    renameSync(join(data, `tools-instance.json.${instance}`), join(data, "tools-instance.json"));
+  } catch { /* Without it the hooks assume the tools are attached. */ }
   return server.before("agent.session_open", async ({ request }) => {
-    if (request.purpose !== "interactive" || !["claude", "codex"].includes(request.provider)
+    if (request.purpose !== "interactive" || !providers().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 } : {}),
-      } } },
-    };
+    if (process.env.SMART_SESSION_FORCE_STDIO !== "1" && nativeToolsAvailable(request, await paseoConfig())) {
+      await writeFile(join(data, "tools", `native-${request.agentId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`), JSON.stringify({ instance })).catch(() => undefined);
+      return { ...request, env: { ...request.env, SMART_SESSION_TOOLS: "native" }, tools: [...request.tools, ...nativeTools(invoke)] };
+    }
+    return withStdio(request);
   });
 }
+
+async function withStdio(request: PluginSessionOpenRequest): Promise<PluginSessionOpenRequest | void> {
+  const directory = await resolvePluginDir();
+  if (!directory) return;
+  // Through the stable shim when it is in place, so a session opened just before an
+  // update does not hold a path Paseo is about to delete.
+  const shim = shimFor("mcp.mjs");
+  const definition = mcpDefinition(directory, undefined, (await readPointer()) === directory && existsSync(shim) ? shim : undefined);
+  return {
+    ...request,
+    env: { ...request.env, SMART_SESSION_TOOLS: "stdio" },
+    mcpServers: { ...request.mcpServers, "smart-session": { ...definition, env: {
+      ...definition.env, PASEO_AGENT_ID: request.agentId,
+      PASEO_HOME: paseoHome(), 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/chat.ts

@@ -31,9 +31,13 @@ export const PromptCardSchema = z.object({
 });
 export type PromptCard = z.infer<typeof PromptCardSchema>;
 
-/** Claude records mcp__smart-session__context_status; Codex records smart-session.context_status. */
+/**
+ * Claude records mcp__smart-session__context_status and Codex smart-session.context_status from the
+ * stdio server; served natively through Paseo's MCP they are mcp__paseo__smart_context_status and
+ * paseo.smart_context_status.
+ */
 export function smartSessionTool(name: string): SmartSessionTool | null {
-  const match = /^(?:mcp__)?smart-session(?:__|\.|\/|:)([a-z_]+)$/.exec(name);
+  const match = /^(?:mcp__)?(?:smart-session(?:__|\.|\/|:)|paseo(?:__|\.|\/|:)smart_)([a-z_]+)$/.exec(name);
   return match && (SMART_SESSION_TOOLS as readonly string[]).includes(match[1]!) ? (match[1] as SmartSessionTool) : null;
 }
 

package/shared/version.ts

@@ -0,0 +1,10 @@
+/**
+ * This plugin's version, compiled into the bundle.
+ *
+ * Paseo evaluates the server bundle from a string, so the running code has no
+ * `import.meta.url` or `__dirname` to say which install directory it came from. Its
+ * version is the one thing it carries that the directory on disk also carries
+ * (`package.json`), which is how `resolvePluginDir()` tells the install that is running
+ * from a stale one during an update. `version.test.ts` keeps it equal to `package.json`.
+ */
+export const PLUGIN_VERSION = "3.6.1";