Make local plugins manageable and debuggable (#3446)

* feat(plugins): expose Paseo API to local plugins

Plugin surfaces borrow the selected host connection while subprocess handlers receive an exclusively owned IPC session, so plugins can use normal workspace and agent operations without inventing another transport.

* feat(plugins): reload global enablement safely

Treat the global plugin switch as a live daemon setting and teach plugin automation to inspect it before acting. Enabling remains permission-gated because plugin backend code can access the daemon machine and client contributions execute inside the app.

* feat(plugins): expose plugin logs

Capture plugin stdout and stderr separately from IPC so authors can debug initialization, RPC, cleanup, and crash behavior from the app or CLI. Keep a bounded tail across lifecycle recovery while preserving structured output in the daemon log.

* fix(build): order plugin dependency builds

* test(plugins): align startup and CLI expectations

docs/architecture.md

@@ -92,6 +92,10 @@ facade. App and CLI may import the low-level driver from
 `@getpaseo/client/internal/daemon-client` during migration, while new SDK-shaped
 code imports from `@getpaseo/client`.
 
+`PaseoApi` is the capability-only boundary over workspaces, agents, providers, and config.
+`PaseoClient` adds connection lifecycle. App plugin surfaces borrow an API over their selected
+host's client; plugin subprocesses use the same facade over a host-owned IPC transport.
+
 ### `packages/app` — Mobile + web client (Expo)
 
 Cross-platform React Native app that connects to one or more daemons.

docs/data-model.md

@@ -226,6 +226,8 @@ snapshot so a mixed edit can apply its live subset and still name the paths that
       providers: [{ provider, model?, thinkingOptionId? }]
     }
   },
+  pluginsEnabled: boolean,
+  plugins: Record<pluginId, { source: "directory", path: string, enabled?: boolean }>,
   features: {
     dictation: { enabled, stt: { provider, model, language, confidenceThreshold } },
     voiceMode: { enabled, llm, stt: { provider, model, language }, turnDetection, tts: { provider, model, voice, speakerId, speed } }

docs/plugins.md

@@ -34,7 +34,10 @@ The daemon stores directory sources under the root `plugins` object:
 }
 ```
 
-The plugin system is disabled unless `pluginsEnabled` is `true`.
+The plugin system is disabled unless `pluginsEnabled` is `true`. Changing that root field is
+runtime-safe: run `paseo reload` after editing `config.json`. Enabling starts every configured,
+enabled plugin; disabling tears them all down without restarting the daemon. Plugin source entries
+remain lifecycle-owned and do not reload from manual config edits.
 
 The directory contains an identity-only manifest, one entry point, and local typechecking support:
 
@@ -62,11 +65,21 @@ The config key is the runtime plugin ID. The manifest ID is the default selected
 runtime does not compare the two IDs. The same directory can be installed under several config
 keys.
 
+Never enable plugins on a user's behalf without explicit permission. Before asking, check the
+target daemon's current `pluginsEnabled` value. State that plugins are trusted, unsandboxed code:
+backend code can access the daemon machine, while client contributions run inside the Paseo app.
+
 Source changes are explicit. Run `paseo plugin reload <id>` to stop and fully tear down the old
 plugin before compiling and starting from disk. A failed reload stays failed; Paseo does not restore
 the old code. Use `enable`, `disable`, and `remove` to manage one plugin. Remove deletes only its
 configuration, never its source directory. The global `pluginsEnabled` switch remains available.
 
+Server contributions can write to stdout and stderr with normal Node logging. Inspect the recent
+in-memory tail from the host plugin settings or with `paseo plugin logs <id>`. Reload, disable, and
+process failure retain the tail; removing the plugin clears it. Daemon restarts do not retain the
+tail, but structured copies remain in `$PASEO_HOME/daemon.log`. Plugin output can contain secrets,
+so do not log credentials or tokens.
+
 ## Contribute behavior and UI
 
 Default export one contribution function. Paseo calls it with a plugin-scoped context. The compiler
@@ -77,7 +90,7 @@ resolving dependencies.
 import { Text } from "react-native";
 import { useQuery } from "@tanstack/react-query";
 import { z } from "zod";
-import { defineRpc, type PluginContext, useRpc } from "@paseo/plugin";
+import { defineRpc, type PluginContext, usePaseo, useRpc } from "@paseo/plugin";
 
 const greetRpc = defineRpc({
   name: "greet",
@@ -86,16 +99,36 @@ const greetRpc = defineRpc({
 });
 
 function Greeting() {
+  const paseo = usePaseo();
   const greet = useRpc(greetRpc);
   const query = useQuery({
     queryKey: ["greeting", "Paseo"],
     queryFn: () => greet({ name: "Paseo" }),
   });
-  return <Text>{query.data?.message}</Text>;
+  const createWorkspace = () =>
+    paseo.workspaces
+      .create({
+        source: {
+          kind: "worktree",
+          cwd: "/absolute/path/to/project",
+          action: "checkout",
+          checkoutSource: { kind: "change_request", forge: "github", number: 42 },
+        },
+      })
+      .then((workspace) =>
+        workspace.agents.create({
+          config: { provider: "codex/gpt-5" },
+          prompt: "Review PR #42",
+        }),
+      );
+  return <Text onPress={() => void createWorkspace()}>{query.data?.message}</Text>;
 }
 
 export default function contribute(plugin: PluginContext) {
-  plugin.handle(greetRpc, async ({ name }) => ({ message: `Hello, ${name}` }));
+  plugin.handle(greetRpc, async ({ name }, { paseo }) => {
+    const { config } = await paseo.config.get();
+    return { message: `${name}: ${config.pluginsEnabled ? "enabled" : "disabled"}` };
+  });
   plugin.addSurface("main", Greeting);
   plugin.addSidebarItem({
     id: "main",
@@ -107,10 +140,11 @@ export default function contribute(plugin: PluginContext) {
 }
 ```
 
-The contribution function must return cleanup. Paseo invokes it once when the plugin is reloaded,
-disabled, removed, disconnected, or shut down. Cleanup is for resources created by plugin code.
-Paseo removes registered contributions, unmounts surfaces, clears query state, rejects pending RPCs,
-and stops the subprocess. Cleanup errors are logged and do not interrupt host teardown.
+The contribution function must return cleanup. Server cleanup may be async; Paseo waits for it when
+the plugin is reloaded, disabled, removed, disconnected, or shut down. Cleanup is for resources
+created by plugin code. Paseo removes registered contributions, unmounts surfaces, clears query
+state, rejects pending RPCs, closes the plugin's daemon session, and stops the subprocess. Cleanup
+errors are logged and do not interrupt host teardown.
 
 Paseo owns the route, screen header, Lucide icon validation, close action, theme DTO, layout facts,
 and render error boundary. The contributed component owns the complete body below the header.
@@ -119,6 +153,19 @@ RPC contracts validate inputs and outputs in both the app and plugin subprocess.
 typed async function. Use the host-provided `@tanstack/react-query` for request state and caching;
 Paseo gives each plugin installation its own query client.
 
+`usePaseo()` and the handler's `{ paseo }` context expose the same `PaseoApi`: workspaces, agents,
+providers, and daemon config. They do not expose connection lifecycle. A surface borrows the
+selected host's existing connection; switching the screen's host changes both `usePaseo()` and
+`useRpc()` to that host. An offline selected host fails there and never falls through to another
+installation. A server handler owns an IPC-backed daemon session for the life of its subprocess.
+Use plugin RPC for plugin-specific backend behavior that is not a normal Paseo operation.
+
+Each subprocess gets an exclusively owned `plugin:<id>` session. That identity is reserved from
+normal clients, never resumes another session, and is cleaned immediately on exit without reconnect
+grace. During daemon startup, plugin sessions may connect while application WebSockets remain
+paused; the daemon accepts clients only after configured plugins have settled and the initial
+catalog is complete.
+
 When the same plugin contribution exists on multiple hosts, Paseo shows it once in the sidebar and
 adds a host picker to the screen header. The selected host supplies the bundle, RPC transport, and
 query cache. Plugin code cannot address another host.

docs/terminal-performance.md

@@ -24,6 +24,7 @@ Terminal frames share the daemon main event loop with all agent traffic. The `ev
 - **Coalesced output carries the LAST chunk's revision.** Snapshot replay dedup (`replayTerminalOutputAfterSnapshot`) skips buffered output with `revision <= replayRevision`; a merged batch with a lower revision would be wrongly skipped (lost output).
 - **The input-mode tracker runs once per process boundary, not per hop.** The worker owns the authoritative tracker; the daemon caches the replay preamble from `getTerminalState` responses and `snapshotReady` messages. Do not reintroduce a per-chunk `feed()` on the daemon main loop.
 - **Snapshot catch-up is backpressure-gated.** A stream falls back to a full snapshot only when `outputBytesSinceSnapshot > MAX_TERMINAL_OUTPUT_FRAME_BYTES` (256KB) **and** the client transport reports `bufferedAmount > MAX_CLIENT_BUFFERED_BYTES` (4MB). A client that keeps draining streams continuously, no matter how much output is produced. Before this gate existed, every 256KB of build output dropped a frame and forced a full JSON cell-grid snapshot (~200k objects across IPC) — the historical source of spiky lag and GC hitches.
+- **Plugin daemon sessions report IPC queue bytes.** Their virtual socket increments `bufferedAmount` before `process.send` and decrements it only in the send callback. Text and binary frames share that ordered queue, so the normal snapshot catch-up and physical high-water gates remain valid for server-side plugin SDK traffic.
 - **Client output writes are not serialized per frame.** The emulator runtime drains contiguous plain writes straight into xterm (which buffers internally). Only barrier ops (`clear`, `snapshot`, `suppressInput` writes) wait — behind a zero-length sentinel write — so resets can't interleave with in-flight output.
 - **Terminal size has one daemon-owned claimant.** Focus and direct interaction send a `claim`; later geometry changes from that connection send `update`. A claim transfers ownership even when the dimensions are unchanged, while an update from any other connection is ignored. This lets an owning pane follow splits and keyboard insets without allowing an idle phone or browser to steal the PTY size.