@omercnet/paseo-omp 0.2.1-next.72.1

package/client/quota-state.ts

@@ -0,0 +1,140 @@
+import type { OmpQuota } from "../shared/quota";
+import { isOmpProvider } from "./omp-store-state";
+
+const PROVIDER_LABELS: Record<string, string> = {
+  anthropic: "Anthropic",
+  cursor: "Cursor",
+  "google-antigravity": "Google",
+  "openai-codex": "OpenAI",
+};
+
+// Paseo's own provider brand icons (@getpaseo/protocol names such as "claude" or "omp") are
+// host-internal: passing one as a button `icon` string fails host validation, and rendering it
+// through `Icon` draws nothing. Plugin icons resolve Lucide names only, so each provider maps
+// to the Lucide vector closest to its mark.
+const PROVIDER_ICON_NAMES: Record<string, string> = {
+  anthropic: "Asterisk",
+  azure: "Cloud",
+  cursor: "MousePointer2",
+  "google-antigravity": "Gem",
+  openai: "Atom",
+  "openai-codex": "Atom",
+};
+
+export function quotaProviderIconName(provider: string | null): string {
+  return (provider ? PROVIDER_ICON_NAMES[provider] : undefined) ?? "Gauge";
+}
+
+export type QuotaSeverity = "ok" | "warning" | "danger" | "unknown";
+
+export function quotaSeverityFromFraction(fraction: number | null): QuotaSeverity {
+  if (fraction === null) return "unknown";
+  if (fraction >= 0.9) return "danger";
+  if (fraction >= 0.7) return "warning";
+  return "ok";
+}
+export function quotaProviderFromSession(
+  provider: string,
+  model: string | null = null,
+): string | null {
+  const [runtime, modelProvider] = provider.split("/");
+  if (!isOmpProvider(runtime)) return null;
+  if (modelProvider) return modelProvider;
+  return model?.includes("/") ? model.split("/")[0] : null;
+}
+
+export function quotaProviderLabel(provider: string | null): string {
+  return provider
+    ? (PROVIDER_LABELS[provider] ?? `${provider.slice(0, 1).toUpperCase()}${provider.slice(1)}`)
+    : "Provider";
+}
+
+export function quotasForProvider(
+  quotas: readonly OmpQuota[],
+  provider: string | null,
+  includeAll = false,
+): OmpQuota[] {
+  return provider
+    ? quotas.filter((quota) => quota.provider === provider)
+    : includeAll
+      ? [...quotas]
+      : [];
+}
+
+export function quotaSummaryForProvider(
+  quotas: readonly OmpQuota[],
+  provider: string | null,
+  includeAll = false,
+): { visible: boolean; label: string } {
+  const matching = quotasForProvider(quotas, provider, includeAll);
+  const label = provider ? quotaProviderLabel(provider) : "Quotas";
+  const used = matching.flatMap((quota) =>
+    quota.usedFraction === null ? [] : [quota.usedFraction],
+  );
+  if (used.length === 0) {
+    return provider
+      ? { visible: true, label: `${quotaProviderLabel(provider)} · —` }
+      : { visible: includeAll, label: "Quotas · —" };
+  }
+  const peak = Math.round(Math.max(...used) * 100);
+  return { visible: true, label: `${label} · ${peak}%` };
+}
+
+export function quotaSeverityForProvider(
+  quotas: readonly OmpQuota[],
+  provider: string | null,
+  includeAll = false,
+): QuotaSeverity {
+  const used = quotasForProvider(quotas, provider, includeAll).flatMap((quota) =>
+    quota.usedFraction === null ? [] : [quota.usedFraction],
+  );
+  return used.length === 0 ? "unknown" : quotaSeverityFromFraction(Math.max(...used));
+}
+
+export type QuotaProviderGroup = {
+  provider: string;
+  quotas: OmpQuota[];
+  peakFraction: number | null;
+  severity: QuotaSeverity;
+};
+
+/** Groups every recorded provider (not just the active session's) so a popover can show the
+ * full comparison a user needs to decide which provider to switch to. The active session's
+ * provider always sorts first; the rest fall back to worst-quota-first. */
+export function quotaProviderGroups(
+  quotas: readonly OmpQuota[],
+  currentProvider: string | null,
+): QuotaProviderGroup[] {
+  const byProvider = new Map<string, OmpQuota[]>();
+  for (const quota of quotas) {
+    const group = byProvider.get(quota.provider);
+    if (group) group.push(quota);
+    else byProvider.set(quota.provider, [quota]);
+  }
+  const groups = [...byProvider.entries()].map(([provider, providerQuotas]) => {
+    const used = providerQuotas.flatMap((quota) =>
+      quota.usedFraction === null ? [] : [quota.usedFraction],
+    );
+    const peakFraction = used.length === 0 ? null : Math.max(...used);
+    return {
+      provider,
+      quotas: [...providerQuotas].sort((a, b) => (b.usedFraction ?? -1) - (a.usedFraction ?? -1)),
+      peakFraction,
+      severity: quotaSeverityFromFraction(peakFraction),
+    };
+  });
+  groups.sort((a, b) => {
+    if (a.provider === currentProvider) return -1;
+    if (b.provider === currentProvider) return 1;
+    return (b.peakFraction ?? -1) - (a.peakFraction ?? -1);
+  });
+  return groups;
+}
+
+export function quotaResetLabel(resetsAtMs: number | null, nowMs: number = Date.now()): string {
+  if (resetsAtMs === null) return "";
+  const remainingMs = Math.max(0, resetsAtMs - nowMs);
+  const hours = Math.floor(remainingMs / 3_600_000);
+  const minutes = Math.floor((remainingMs % 3_600_000) / 60_000);
+  return hours > 0 ? `resets ${hours}h ${minutes}m` : `resets ${minutes}m`;
+}

package/client/sessions-popover.tsx

@@ -0,0 +1,78 @@
+import { type PluginButtonContentProps, useAgent, useRpc } from "@getpaseo/plugin/client";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { ScrollView, Text, View } from "react-native";
+import { storeForProvider, storeLabel } from "../shared/omp-store";
+import { listOmpSessions } from "../shared/sessions";
+import { ompStoreKey } from "./omp-store-state";
+
+const SESSIONS_POLL_MS = 20_000;
+const PREVIEW_LIMIT = 20;
+
+function age(epochSeconds: number): string {
+  const seconds = Math.max(0, Math.floor(Date.now() / 1_000 - epochSeconds));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export function SessionsPopover(props: PluginButtonContentProps) {
+  const { theme, layout } = props;
+  const agentId = props.context === "agent" ? props.agentId : "";
+  const agent = useAgent(agentId, ({ cwd, provider }) => ({ cwd, provider }));
+  const cwd = agent?.cwd ?? "";
+  const store = storeForProvider(agent?.provider);
+  const loadSessions = useRpc(listOmpSessions);
+  const sessions = useQuery({
+    queryKey: ["paseo-omp", "sessions", ompStoreKey(store), cwd],
+    queryFn: () => loadSessions({ cwd, store }),
+    enabled: cwd.length > 0,
+    refetchInterval: SESSIONS_POLL_MS,
+  });
+  const styles = useMemo(
+    () => ({
+      root: { gap: 8, padding: 4, maxHeight: 360, width: 320 },
+      muted: { color: theme.colors.foregroundMuted, fontSize: 13 },
+      error: { color: theme.colors.statusDanger, fontSize: 13 },
+      row: {
+        gap: 2,
+        padding: layout.compact ? 8 : 10,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 8,
+        backgroundColor: theme.colors.surface1,
+      },
+      title: { color: theme.colors.foreground, fontSize: 13, fontWeight: "600" as const },
+      prompt: { color: theme.colors.foreground, fontSize: 13 },
+      detail: { color: theme.colors.foregroundMuted, fontSize: 11 },
+    }),
+    [layout.compact, theme],
+  );
+
+  if (sessions.isLoading) return <Text style={styles.muted}>Loading omp history…</Text>;
+  if (sessions.error) return <Text style={styles.error}>Could not read omp history.</Text>;
+  const items = sessions.data?.sessions ?? [];
+  if (items.length === 0)
+    return <Text style={styles.muted}>No omp prompts for this directory.</Text>;
+
+  return (
+    <ScrollView contentContainerStyle={styles.root}>
+      <Text style={styles.muted}>{storeLabel(store)}</Text>
+      {items.slice(0, PREVIEW_LIMIT).map((entry) => (
+        <View key={entry.id} style={styles.row}>
+          {entry.title ? <Text style={styles.title}>{entry.title}</Text> : null}
+          <Text style={styles.prompt} numberOfLines={3}>
+            {`${entry.prompt}${entry.truncated ? "…" : ""}`}
+          </Text>
+          <Text style={styles.detail}>{age(entry.createdAt)}</Text>
+        </View>
+      ))}
+      {items.length > PREVIEW_LIMIT ? (
+        <Text style={styles.muted}>{`Showing ${PREVIEW_LIMIT} of ${items.length}`}</Text>
+      ) : null}
+    </ScrollView>
+  );
+}

package/docs/alpha-release-checklist.md

@@ -0,0 +1,68 @@
+# Alpha release checklist
+
+This checklist prepares `paseo-omp-v0.1.0-alpha.1`. It does not authorize publication. A maintainer must explicitly approve the tested package before any push, tag, GitHub release, or npm publication.
+
+## Release identity
+
+- [ ] Release Please proposes `0.1.0-alpha.1` from manifest version `0.0.0`.
+- [ ] Package and tag names are `@omercnet/paseo-omp` and `paseo-omp-v0.1.0-alpha.1`.
+- [ ] Provider identity remains `omp-plugin`; bundled `omp` remains independent and enabled or disabled by the user.
+- [ ] Paseo requirement remains an official released range, currently `^0.8.0`.
+- [ ] Minimum tested OMP version, checksum, CI job, README, SUPPORT, and TESTING agree.
+
+## Required gates
+
+- [ ] `npm run check`
+- [ ] `npm run typecheck`
+- [ ] `npm run test:coverage`; aggregate loaded-source coverage meets the configured threshold.
+- [ ] Real installed OMP regression against the documented minimum version.
+- [ ] `npm run test:integration:install`
+- [ ] `npm run test:integration:docker`
+- [ ] Windows/WSL host ownership job passes in CI.
+- [ ] Docker canary matrix passes on the exact release candidate.
+- [ ] GitHub Actions syntax and release-configuration schemas pass.
+
+## Required manual acceptance
+
+- [ ] Maintainer installs the exact `npm pack` candidate into the controlled official-Paseo Docker canary.
+- [ ] Maintainer verifies catalog, prompt, tools, configured MCP, permissions, steer, interrupt, import/resume, subagents, rewind, usage, Hub, and plugin surfaces.
+- [ ] Maintainer confirms the known limitations are acceptable for alpha.
+- [ ] Maintainer explicitly authorizes publication after testing. Silence or prior approval for development is not release authorization.
+
+## Alpha blocker
+
+- [x] `omp-audit.1`: incomplete or compacted `agent_end` frames recover success, failure, or native cancellation from complete streamed `message_end` evidence, or from bounded history whose entry IDs correlate with the streamed turn. Idle state is confirmed before and after retrieval, and concurrent interrupts remain authoritative. Missing, unavailable, non-correlatable, or conflicting terminal evidence fails closed with content-free count diagnostics.
+
+## Accepted alpha limitations
+
+These may remain only when called out in `SUPPORT.md`, `CHANGELOG.md`, and the GitHub prerelease notes:
+
+- Native Fast mode is not exposed.
+- No first-class plan mode; `/handoff` depends on native OMP prerequisites not reproduced by the deterministic canary.
+- Terminal-started OMP sessions are importable but are not registered automatically.
+- Large skill-body presentation has no dedicated provider regression.
+- OMP RPC stdout contamination is structurally mitigated but requires upstream channel purity.
+- `omp` and `omp-plugin` do not share ownership, configuration, or persisted handles.
+- The deterministic model does not implement OMP compaction summarization; protocol fixtures cover compaction behavior.
+- The tiny Ollama model is exploratory and is not a deterministic oracle.
+
+## Non-blocking post-alpha cleanup
+
+- [ ] `omp-maintenance.1`: remove `ProviderRegistrationCompat`, both `ProviderCatalogOptionsCompat` declarations, and `parseProviderInputCompat` after the published `@getpaseo/plugin` types natively expose the registration hooks and request fields they bridge. The required upstream surface is `providerOptionsSchema`, `getCatalogCacheKey`, `checkAvailability`, catalog/session-list `providerOptions` plus `settings`, and session-open `deniedTools`. This is type/compatibility cleanup only; it must not change provider behavior and does not block alpha.
+
+## Release notes
+
+The prerelease notes must include:
+
+1. Alpha support statement and compatibility range.
+2. Permanent side-by-side `omp-plugin` identity.
+3. Provider SDK capability percentage and link to the README matrix.
+4. Link to the deduplicated [core-provider issue audit](core-provider-issue-audit.md).
+5. Verification totals from the exact release commit.
+6. Known limitations above, including the distinction between supported MCP host tools, unsupported exact `toolPolicy`, and native-only `disallowedTools`.
+7. Install, upgrade, rollback, support, and security-reporting links.
+8. Artifact provenance verification command.
+
+## Publication boundary
+
+Release Please may prepare metadata. Publication must use npm trusted publishing from the immutable release commit. Never retag an alpha commit as stable.

package/docs/configuration.md

@@ -0,0 +1,126 @@
+# Configuration
+
+Open the global **OMP** sidebar to browse and edit machine-wide state, or open the workspace **OMP** panel from the workspace tab or Explorer to manage project-scoped state. Scalar edits in the global surface use OMP's native `config set` and `config reset` commands. Workspace edits create validated overrides in `<workspace>/.omp/config.yml`; removing an override restores the effective global or default value. Arrays, records, and credentials remain read-only in both surfaces.
+
+The **Plugin** tab documents the supported `omp-plugin` launch options, including names-only inherited environment configuration. Paseo's public plugin API does not expose the effective provider options for active launches, so the tab does not claim profile values are active. Choose **OMP Plugin** when creating an agent. Model, mode, thinking level, system prompt, persistence, MCP servers, workspace, and agent environment use Paseo's standard provider controls.
+
+## Optional provider profile overrides
+
+Advanced launch overrides belong in an `omp-plugin` provider profile. The provider options schema is strict; unknown fields fail validation.
+
+```json
+{
+  "provider": "omp-plugin",
+  "providerOptions": {
+    "command": ["/opt/omp/bin/omp"],
+    "params": {
+      "sessionDir": "/var/lib/omp/sessions",
+      "rpcTimeoutMs": 60000,
+      "smolModel": "openai/gpt-5-mini",
+      "slowModel": "anthropic/claude-opus-5",
+      "planModel": "openai/gpt-5.4"
+    }
+  }
+}
+```
+
+| Option | Purpose |
+| --- | --- |
+| `command` | Complete OMP executable and argument prefix. |
+| `env` | Non-secret process overrides applied below the session launch environment. |
+| `inheritEnv` | Daemon environment variable names copied only when OMP starts. Values are never stored in the profile or displayed in the sidebar. |
+| `outputRedaction` | `none` (default) preserves native output. `configured-values` performs best-effort literal replacement only for explicitly supplied configured credential values from profile/session credential environment fields and configured MCP headers or environment. |
+| `params.sessionDir` | Native OMP session directory supplied through `--session-dir`. Used consistently by discovery, import, resume, and launch. |
+| `params.rpcTimeoutMs` | Startup, request, catalog, and availability timeout, from 1 ms through 10 minutes. |
+| `params.smolModel` | Native selector supplied through `--smol`. |
+| `params.slowModel` | Native selector supplied through `--slow`. |
+| `params.planModel` | Native selector supplied through `--plan`. |
+
+Paseo's generic provider profile fields remain available:
+
+| Profile field | Behavior |
+| --- | --- |
+| `models` | Replaces the discovered model list. |
+| `additionalModels` | Extends the discovered model list. |
+| `disallowedTools` | Restricts only the known native OMP built-ins accepted by this plugin. It becomes an explicit OMP allow-list; unknown names fail closed rather than being ignored. It does not filter MCP host tools. |
+| `paseoTools` | Enables or restricts which caller-scoped Paseo orchestration tools the daemon includes before they reach OMP as MCP host tools. |
+
+These options cover every plugin-specific launch value. Values that belong to an individual agent, including model, mode, thinking level, title, system prompt, MCP servers, persistence, and cwd, remain standard Paseo session fields rather than duplicate plugin options.
+
+## OMP-native plugins
+
+Open **OMP → OMP plugins** globally for user-scoped management, or use the workspace **OMP** panel to include project-scoped installations and effective project overrides. The manager uses OMP's documented singular `omp plugin` CLI and supports install, enable, disable, upgrade, and uninstall operations. Every state-changing action requires explicit confirmation; already-running OMP sessions are unchanged.
+
+Project-scoped lifecycle commands run from the selected workspace and use `--scope project`. Duplicate path installations that share one npm package identity remain read-only because OMP's lifecycle CLI addresses npm plugins by package name rather than installation path. Plugin configuration exposes schema metadata without returning current or default values. Non-secret scalar plugin settings can be set or deleted through write-only controls. Secret settings are presence-only and delete-only because OMP's CLI would otherwise expose a new secret through process arguments.
+
+The Configuration view links to the official OMP settings reference, value parsing and precedence guides, relevant category sections, and a small curated set of setting-specific anchors.
+
+
+## MCP tools, management, and policy boundary
+
+Configured MCP servers and Paseo's caller-scoped MCP tools are supported. The plugin discovers their schemas, assigns collision-safe OMP names, binds them before `session.ready`, forwards progress and terminal results, propagates cancellation, and renders calls with friendly labels.
+
+Use the **MCP** control beside the composer on an **OMP Plugin** agent to run OMP's native list, add, reload, test, authorize, enable, disable, resource, and prompt commands. The control is agent-scoped because OMP MCP discovery depends on both the active profile and the workspace directory. The global OMP sidebar remains a host-level health and settings surface; a separate workspace manager would duplicate OMP's own discovery and precedence rules.
+
+Command output, setup questions, and OAuth prompts appear in the agent timeline. OAuth URLs render as an interactive card and always retain the full provider authorization URL, never substituting OMP's daemon-local `/launch` shortcut. **Open in Paseo Browser** calls the current agent's caller-scoped `browser_new_tab` tool, so the authorization page becomes a browser tab in the same workspace; it requires Paseo tools to be injected into the agent, browser tools to be enabled, and a connected Paseo desktop browser host. **Open on this device** remains available when no browser host is connected. For a loopback callback to complete automatically, the chosen browser host must run on the daemon machine. Otherwise, finish authorization in either browser, copy the final redirect URL or authorization code, and submit it in the OMP authorization prompt. Tokens and refresh material are stored by OMP on the daemon (or its configured auth broker), never in the Paseo client or plugin timeline.
+
+Paseo's exact session `toolPolicy` preapproval grants are not equivalent to OMP's `set_host_tools` contract. The plugin cannot preserve that policy exactly, so any non-empty `toolPolicy` rejects session startup. It never converts exact grants into broader access. `disallowedTools` is separate: it controls only recognized native OMP built-ins and rejects unknown names.
+
+## Credentials and environment
+
+The plugin is deny-by-default. It inherits only its fixed built-in allowlist of core provider authentication variables plus exact names that an operator selects with `providerOptions.inheritEnv`; it does not discover or inherit arbitrary credential-shaped names. Prefer OMP's native credential store or auth broker whenever possible.
+
+For example:
+
+```json
+{
+  "provider": "omp-plugin",
+  "providerOptions": {
+    "inheritEnv": ["ACME_OMP_API_KEY"],
+    "outputRedaction": "configured-values",
+    "env": {
+      "ACME_OMP_REGION": "us-east-1"
+    }
+  }
+}
+```
+
+`inheritEnv` accepts an array of at most 256 names matching `[A-Za-z_][A-Za-z0-9_]{0,127}`. Selecting a name is an operator trust decision: its daemon-owned value becomes available to the OMP child and anything OMP launches. The plugin resolves selected values from the Paseo daemon environment immediately before each catalog or session launch. Unselected variables remain absent. Explicit `providerOptions.env` and per-session `env` overlays win over inherited values with the same name.
+
+Profiles, persistence, errors, and catalog cache identity contain only the configured `inheritEnv` names, never resolved values or secret-derived hashes. A selected variable that is present and not shadowed by explicit `env` must contain at least 4 UTF-8 bytes. The existing 64 KiB per-value and 1 MiB total environment bounds still apply; shadowed daemon values are neither validated nor counted.
+
+Process-control variables are always rejected case-insensitively, even when explicitly selected. The blocked prefix families are `BUN_INSTALL*`, `DYLD_*`, `GIT_CONFIG*`, `LD_*`, and `NPM_CONFIG_*`. The blocked exact names are:
+
+```text
+BASH_ENV, BUN_OPTIONS, CLASSPATH, CLAUDE_BASH_NO_CI, CLAUDE_BASH_NO_LOGIN,
+CLAUDE_CODE_SHELL_PREFIX, EDITOR, ELECTRON_RUN_AS_NODE, ENV, GEM_HOME, GEM_PATH,
+GIT_SSH_COMMAND, HOME, JAVA_TOOL_OPTIONS, NODE_OPTIONS, NODE_PATH,
+OMP_AUTORESEARCH_DB_DIR, OMP_COMMAND, OMP_GITHUB_CACHE_DB, OMP_PROFILE,
+OMP_WORKTREE_DIR, PATH, PATHEXT, PERL5LIB, PERL5OPT, PI_BASH_NO_CI,
+PI_BASH_NO_LOGIN, PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR,
+PI_CONFIG_DIR, PI_CONFIG_FILES, PI_GIT_COMMON_DIR, PI_PACKAGE_DIR, PI_PROFILE,
+PI_PROJECT_DIR, PI_SESSION_ID, PI_SHELL_PREFIX, PI_SUBPROCESS_CMD,
+PI_WORKTREE_DIR, PWD, PYTHONHOME, PYTHONINSPECT, PYTHONPATH, PYTHONSTARTUP,
+RUBYLIB, RUBYOPT, SHELL, SYSTEMROOT, USERPROFILE, VISUAL, XDG_CACHE_HOME,
+XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR, XDG_STATE_HOME, _JAVA_OPTIONS
+```
+
+Unlike `inheritEnv`, `providerOptions.env` stores its literal values in the provider profile/configuration. Use it only for deliberate non-secret overrides. If configuration contains sensitive values anyway, restrict `<paseo-home>/config.json` to the daemon account (`chmod 600` on POSIX), protect backups, and never attach it to an issue.
+
+The plugin validates and bounds native protocol data, but it does not heuristically detect, redact, or rewrite credentials in OMP, model, or tool content. Never put credentials in prompts or tool output. With `outputRedaction: "configured-values"`, every non-empty value selected through `inheritEnv` is treated as sensitive regardless of its name, alongside the existing explicitly configured credential values. Exact configured literals are replaced on a best-effort basis; generated secrets and encoded, transformed, or independently streamed fragments are not detected. With the default `none`, inherited values are not rewritten in output. Centralized Paseo policy is required for redaction guarantees. Unexpected or internal launch failures use fixed fallback messages rather than serializing the launch configuration, while explicit public validation errors may include caller-supplied configuration names or values.
+
+## Modes and permissions
+
+- `full` is always available.
+- `write` and `ask` appear when Paseo negotiates provider permission support.
+- Typed OMP approval frames become Paseo tool permissions when both sides negotiate `typedToolApprovals: 1`.
+- OMP 18.1.15 uses the bounded generic interaction fallback.
+- Changing approval mode requires a new session. Live model and thinking changes are supported.
+
+## Persistence and images
+
+Non-persisted sessions use `--no-session`. Persistent sessions keep a versioned native handle, replay before becoming ready, and recover with the effective launch configuration.
+
+For text-only models, image inputs are written to a private bounded temporary directory shared with the local OMP child and removed after the turn, session, or failed launch.
+
+Every OMP process launched by the plugin receives provider-owned `OMP_NO_WEBP=1` compatibility mode after caller environment validation, so generated and resized images use PNG or JPEG across Paseo clients without reducing the configured environment limits. Persisted or upstream WebP blocks are still retained: capable clients render them directly, while an unsupported client shows a per-image fallback instead of failing the timeline item.

package/docs/core-provider-issue-audit.md

@@ -0,0 +1,108 @@
+# Core OMP provider issue audit
+
+This audit compares reports in `getpaseo/paseo` with the community `omp-plugin` provider. It was refreshed on 2026-09-12 from GitHub issue titles and bodies containing `OMP`, `oh-my-pi`, or `rpc-ui`, OMP-related pull requests, and materially equivalent Pi/RPC reports. GitHub Discussions were also inspected; the repository had no OMP-related discussion.
+
+Issue and pull-request pairs are consolidated by root cause. A closed upstream issue does not prove the plugin implements the behavior, and an open upstream issue does not imply the plugin is affected.
+
+Status meanings:
+
+- **Verified**: the plugin has implementation and focused automated evidence for the consumer-visible behavior.
+- **Mitigated**: the plugin bounds or rejects the failure, but an upstream or host condition remains.
+- **Gap**: behavior is missing or only partially supported by the plugin.
+- **Host-owned**: the report concerns Paseo behavior outside the provider boundary.
+
+## Lifecycle, turns, and recovery
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#3838](https://github.com/getpaseo/paseo/issues/3838), [PR #3839](https://github.com/getpaseo/paseo/pull/3839) | **Verified** | A dead OMP subprocess invalidates its generation. A later write lazily resumes the same native session. Process-tree cleanup, recovery, and registry replacement are covered. |
+| [#3252](https://github.com/getpaseo/paseo/issues/3252), equivalent Pi [#3496](https://github.com/getpaseo/paseo/issues/3496), [PR #3258](https://github.com/getpaseo/paseo/pull/3258) | **Verified** | Hidden and custom notices do not terminalize a turn before the native user echo and terminal evidence. |
+| [#2260](https://github.com/getpaseo/paseo/issues/2260), [PR #2261](https://github.com/getpaseo/paseo/pull/2261) | **Verified** | Incomplete or compacted `agent_end` frames use complete streamed `message_end` evidence or bounded history correlated by entry ID, with idle state confirmed before and after retrieval. Success, failure, native cancellation, and concurrent interrupts are preserved; missing, unavailable, non-correlatable, or conflicting terminal evidence fails closed with content-free count diagnostics. |
+| [#2281](https://github.com/getpaseo/paseo/issues/2281), [PR #2282](https://github.com/getpaseo/paseo/pull/2282) | **Verified** | Local-only prompt results and structured commands have explicit terminal ownership. |
+| [#3654](https://github.com/getpaseo/paseo/issues/3654), [#3998](https://github.com/getpaseo/paseo/issues/3998), [PR #3667](https://github.com/getpaseo/paseo/pull/3667) | **Verified** | Post-`agent_end` state reconciliation is bounded. Stale or unavailable `get_state` cannot leave a turn running forever. |
+| [#3999](https://github.com/getpaseo/paseo/issues/3999), [#4000](https://github.com/getpaseo/paseo/issues/4000), [#4039](https://github.com/getpaseo/paseo/issues/4039), [PR #3772](https://github.com/getpaseo/paseo/pull/3772), [PR #4217](https://github.com/getpaseo/paseo/pull/4217) | **Verified** | `prompt.steer` is negotiated and implemented with expected-turn checks, acknowledgement ordering, duplicate correlation, and interrupt/terminal race coverage. |
+| Shared RPC cancellation [#3540](https://github.com/getpaseo/paseo/issues/3540), Pi [#3749](https://github.com/getpaseo/paseo/issues/3749) | **Verified in provider** | Native abort, exactly-one terminal event, permission cleanup, descendant cleanup, and uncertain-cleanup quarantine are tested. UI keyboard delivery remains host-owned. |
+| [#3218](https://github.com/getpaseo/paseo/issues/3218) | **Verified at provider boundary** | Session close owns and awaits OMP process cleanup. Whether every archive UI route invokes provider close is a host concern. |
+
+## Persistence, import, and subagents
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#2006](https://github.com/getpaseo/paseo/issues/2006), [PR #2004](https://github.com/getpaseo/paseo/pull/2004), [PR #2131](https://github.com/getpaseo/paseo/pull/2131) | **Verified** | Descriptor parsing accepts bounded leading title/session metadata. |
+| [#2727](https://github.com/getpaseo/paseo/issues/2727), [PR #4416](https://github.com/getpaseo/paseo/pull/4416) | **Verified** | Import resolves opaque native identity and preserves model and thinking selection. |
+| [#2796](https://github.com/getpaseo/paseo/issues/2796), [PR #2065](https://github.com/getpaseo/paseo/pull/2065), [PR #2265](https://github.com/getpaseo/paseo/pull/2265) | **Verified** | Host-wide discovery is supported when `cwd` is omitted; scoped listing still enforces absolute workspace ownership. This also prevents the previously observed import-sheet crash path. |
+| [#2232](https://github.com/getpaseo/paseo/issues/2232), equivalent Pi [#3160](https://github.com/getpaseo/paseo/issues/3160), [PR #2052](https://github.com/getpaseo/paseo/pull/2052), [PR #2245](https://github.com/getpaseo/paseo/pull/2245), [PR #3371](https://github.com/getpaseo/paseo/pull/3371) | **Verified** | Native child lifecycle, progress, nested timelines, replay, active-child gating, and parent-terminal deferral use `session.subsession`. |
+| Pi lifecycle variants [#3845](https://github.com/getpaseo/paseo/issues/3845), [#3847](https://github.com/getpaseo/paseo/issues/3847), [#4309](https://github.com/getpaseo/paseo/issues/4309) | **Verified by the same model** | Child activity and terminal ownership are explicit rather than inferred from one provider event. |
+| [#2728](https://github.com/getpaseo/paseo/issues/2728) | **Gap** | Listing and import work, but the plugin does not install an OMP terminal hook that automatically creates a Paseo agent for terminal-started sessions. |
+| [#2574](https://github.com/getpaseo/paseo/issues/2574) | **Mitigated** | Recursive bounded transcript discovery covers OMP files. Generic archived-agent and registry visibility remain host-owned. |
+| [#4707](https://github.com/getpaseo/paseo/issues/4707) | **Host-owned** | Plugin reservations reject conflicting live ownership; archived-agent workspace re-homing policy belongs to Paseo. |
+
+## Transport and startup
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#2548](https://github.com/getpaseo/paseo/issues/2548), [#2966](https://github.com/getpaseo/paseo/issues/2966), [PR #3038](https://github.com/getpaseo/paseo/pull/3038), [PR #3184](https://github.com/getpaseo/paseo/pull/3184) | **Verified** | RPC protocol v2 is required. Chunk assembly, frame byte counts, deadlines, malformed frames, and oversized frames are tested. |
+| [#2473](https://github.com/getpaseo/paseo/issues/2473) | **Mitigated** | Strict frame schemas, request correlation, session identity, and bounds prevent ordinary stdout JSON from becoming a valid response. OMP should still keep non-protocol output off RPC stdout. |
+| [#4047](https://github.com/getpaseo/paseo/issues/4047), [PR #4048](https://github.com/getpaseo/paseo/pull/4048) | **Verified** | Stdin EPIPE and stream closure fail pending calls and enter bounded cleanup/recovery rather than crashing the daemon. |
+| [#1657](https://github.com/getpaseo/paseo/issues/1657), [#1730](https://github.com/getpaseo/paseo/issues/1730), [#2226](https://github.com/getpaseo/paseo/issues/2226), [#4142](https://github.com/getpaseo/paseo/issues/4142), [PR #4008](https://github.com/getpaseo/paseo/pull/4008), [PR #4143](https://github.com/getpaseo/paseo/pull/4143) | **Verified** | Availability and ready probes use bounded configurable timeouts and distinguish missing, unrunnable, incompatible, and available binaries. |
+| [#1446](https://github.com/getpaseo/paseo/issues/1446), [#2456](https://github.com/getpaseo/paseo/issues/2456) | **Mitigated / host-owned** | Plugin discovery and cache identity are bounded. Provider snapshot scheduling and stale host snapshots remain Paseo behavior. |
+| [#2610](https://github.com/getpaseo/paseo/issues/2610) | **Mitigated / host-owned** | OMP input frames, replay, and retained state are bounded; final daemon-to-client WebSocket buffering is owned by Paseo. |
+
+## Models, modes, commands, and usage
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#1692](https://github.com/getpaseo/paseo/issues/1692), [PR #1698](https://github.com/getpaseo/paseo/pull/1698), [PR #2539](https://github.com/getpaseo/paseo/pull/2539) | **Verified** | The plugin uses `get_available_commands`, publishes aliases, and fails slash dispatch closed when discovery is unavailable. |
+| [#2080](https://github.com/getpaseo/paseo/issues/2080), Pi [#2117](https://github.com/getpaseo/paseo/issues/2117), [PR #2171](https://github.com/getpaseo/paseo/pull/2171), [PR #2191](https://github.com/getpaseo/paseo/pull/2191) | **Verified** | Thinking options and defaults are model-specific; unsupported levels fail closed. |
+| Pi [#2663](https://github.com/getpaseo/paseo/issues/2663), [#4382](https://github.com/getpaseo/paseo/issues/4382) | **Verified** | Model and thinking changes are committed only after re-reading native state. |
+| [#2405](https://github.com/getpaseo/paseo/issues/2405), [PR #2406](https://github.com/getpaseo/paseo/pull/2406) | **Verified** | Nullable context windows remain valid catalog entries. |
+| [#2544](https://github.com/getpaseo/paseo/issues/2544), [PR #2865](https://github.com/getpaseo/paseo/pull/2865) | **Verified** | Strict provider options expose command prefix, environment, session directory, timeout, role models, model overlays, and denied tools. |
+| [#2857](https://github.com/getpaseo/paseo/issues/2857), [PR #2859](https://github.com/getpaseo/paseo/pull/2859) | **Verified** | Native compact requests use no ordinary RPC request timeout; provider-level compaction state owns completion, cancellation, and usage refresh. |
+| [#4073](https://github.com/getpaseo/paseo/issues/4073), [PR #4074](https://github.com/getpaseo/paseo/pull/4074) | **Verified** | Fallback and model/thinking events trigger committed runtime-state refresh rather than trusting event labels as final state. |
+| [#1888](https://github.com/getpaseo/paseo/issues/1888), [PR #1882](https://github.com/getpaseo/paseo/pull/1882), [PR #2503](https://github.com/getpaseo/paseo/pull/2503) | **Verified** | Active, terminal, post-compaction, fallback, and recovery sampling publish `session.usage`. |
+| [#4437](https://github.com/getpaseo/paseo/issues/4437), [PR #4449](https://github.com/getpaseo/paseo/pull/4449) | **Gap** | The plugin advertises `full`, `write`, and `ask`; it does not expose a distinct native Fast mode. |
+| [#3627](https://github.com/getpaseo/paseo/issues/3627), [PR #4205](https://github.com/getpaseo/paseo/pull/4205) | **Partial** | Plan role-model configuration and `/handoff` exist. There is no first-class `plan` mode, and the controlled canary does not satisfy the native handoff workflow prerequisites. |
+
+## Timeline, media, and questions
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#4509](https://github.com/getpaseo/paseo/issues/4509), equivalent Pi [#2803](https://github.com/getpaseo/paseo/issues/2803), [PR #4510](https://github.com/getpaseo/paseo/pull/4510) | **Verified** | `contentIndex` participates in stable reasoning identity, preserving interleaved live blocks and replay shape. |
+| [#3244](https://github.com/getpaseo/paseo/issues/3244), [PR #3245](https://github.com/getpaseo/paseo/pull/3245) | **Verified** | Tool-result and assistant images are validated, bounded, retained, packaged, and rendered through the plugin transformer. |
+| [#3527](https://github.com/getpaseo/paseo/issues/3527), [PR #3628](https://github.com/getpaseo/paseo/pull/3628) | **Verified** | Positional `optionDetails.description` metadata is preserved in Paseo permission questions. |
+| [#1726](https://github.com/getpaseo/paseo/issues/1726), [PR #1879](https://github.com/getpaseo/paseo/pull/1879) | **Partial** | Structured user questions are supported. Dedicated collapsing/presentation for very large skill bodies is not demonstrated. |
+| [#2264](https://github.com/getpaseo/paseo/issues/2264), equivalent Pi [#2674](https://github.com/getpaseo/paseo/issues/2674), [PR #2280](https://github.com/getpaseo/paseo/pull/2280) | **Verified** | `display:false` custom messages remain hidden. |
+| [#2266](https://github.com/getpaseo/paseo/issues/2266), [PR #2284](https://github.com/getpaseo/paseo/pull/2284) | **Verified** | Manual and automatic compaction lifecycle and recap data map to stable timeline operations. |
+| Pi [#3121](https://github.com/getpaseo/paseo/issues/3121), [PR #4497](https://github.com/getpaseo/paseo/pull/4497) | **Verified** | Todo events map to Paseo's native todo item; the plugin does not add a second timeline-card renderer. |
+| [#3850](https://github.com/getpaseo/paseo/issues/3850) | **Verified by avoidance** | The inherited environment allowlist does not pass `TERM_PROGRAM`; the plugin never advertises Kitty graphics support. |
+
+## MCP, tools, and host behavior
+
+| Reports | Status | Plugin comparison |
+| --- | --- | --- |
+| [#2060](https://github.com/getpaseo/paseo/issues/2060), [PR #2418](https://github.com/getpaseo/paseo/pull/2418), [PR #3820](https://github.com/getpaseo/paseo/pull/3820), [PR #3449](https://github.com/getpaseo/paseo/pull/3449) | **Verified** | Configured and caller-scoped MCP tools are discovered, policy-filtered, bound before readiness, canceled, and bounded. Docker exercises a configured stdio MCP tool. |
+| Pi [#3004](https://github.com/getpaseo/paseo/issues/3004) | **Verified structurally** | Host-tool setup completes before `session.ready`; capability-registration races cannot expose a partially bound catalog. |
+| Pi [#3666](https://github.com/getpaseo/paseo/issues/3666) | **Verified** | Exact preapproval is validated. If policy cannot be represented, startup fails closed instead of broadening access. |
+| [#1892](https://github.com/getpaseo/paseo/issues/1892) | **Host-owned gap** | Paseo decides global voice-mode eligibility. The plugin does not synthesize a missing speak tool. |
+| [#3762](https://github.com/getpaseo/paseo/issues/3762), Pi [#2815](https://github.com/getpaseo/paseo/issues/2815) | **Host-owned** | The plugin preserves and validates the received tool catalog but does not redefine Paseo's own MCP schemas. |
+| [#3178](https://github.com/getpaseo/paseo/issues/3178) | **Avoided** | The plugin permanently registers `omp-plugin`, never the built-in `omp` identity. |
+| [#3217](https://github.com/getpaseo/paseo/issues/3217) | **Host-owned** | Draft submission and agent creation multiplicity occur before provider-session behavior. |
+
+## Origin records, not regressions
+
+[#1176](https://github.com/getpaseo/paseo/issues/1176), [#1189](https://github.com/getpaseo/paseo/issues/1189), [PR #1177](https://github.com/getpaseo/paseo/pull/1177), [PR #1388](https://github.com/getpaseo/paseo/pull/1388), and [PR #2067](https://github.com/getpaseo/paseo/pull/2067) requested or introduced first-class OMP support. The plugin satisfies that product goal independently under `omp-plugin`; it does not replace or migrate bundled `omp` agents.
+
+## Release blockers and tracked gaps
+
+Before moving from alpha toward stable, track these separately:
+
+1. Decide whether native Fast mode can be represented honestly through the public provider SDK.
+2. Decide whether a first-class plan mode is possible; separately make `/handoff` reproducible in the controlled canary.
+3. Decide whether terminal-started automatic registration belongs in this plugin or requires a generic Paseo hook.
+4. Add an explicit large-skill presentation regression or document it as host-owned.
+5. Keep stdout contamination defenses, and pursue upstream OMP protocol-channel purity.
+6. Keep host-owned issues visibly separated: provider snapshot refresh, voice eligibility, MCP schemas, WebSocket buffering, archive routing, and draft/agent creation.
+
+## Maintenance rule
+
+Refresh this audit before each release candidate. New OMP or materially shared Pi/RPC reports must be added, deduplicated by root cause, and classified with a concrete test, an explicit limitation, or a linked host/upstream issue. Never infer that a plugin is fixed merely because the corresponding core issue is closed.

package/docs/installation.md

@@ -0,0 +1,67 @@
+# Install and update
+
+Paseo plugins are trusted, unsandboxed code. Review this plugin and its production dependencies before installing it on the daemon host.
+
+## Requirements
+
+- Paseo daemon and apps: `^0.8.0`
+- OMP: `18.1.15` or newer is the supported floor
+- OMP RPC: protocol v2 must negotiate successfully
+
+The first public build is an alpha. Alpha releases are compatibility previews and may require deleting and re-importing agents created by an earlier preview.
+
+## Install a release
+
+Install an exact published version from npm:
+
+```bash
+paseo plugin install npm:@omercnet/paseo-omp@<version>
+paseo plugin ls paseo-omp
+```
+
+Alternatively, install the matching reviewed Git tag:
+
+```bash
+paseo plugin add omercnet/paseo-plugins:paseo-omp --ref paseo-omp-v<version>
+paseo plugin ls paseo-omp
+```
+
+A Git tag-pinned installation does not advance through `paseo plugin update`. To upgrade, record the current installation, then replace it with the new tag in one maintenance window:
+
+```bash
+paseo plugin ls paseo-omp --json > paseo-omp-before-update.json
+paseo plugin remove paseo-omp
+paseo plugin add omercnet/paseo-plugins:paseo-omp --ref paseo-omp-v<new-version>
+```
+
+Removal deletes plugin-scoped settings and briefly makes `omp-plugin` unavailable. It does not modify Paseo's bundled `omp` provider or native OMP transcripts. Roll back by repeating the remove/add sequence with the recorded tag or commit.
+
+## Install a local checkout
+
+```bash
+git clone https://github.com/omercnet/paseo-plugins.git
+cd paseo-plugins/paseo-omp
+npm ci --ignore-scripts
+paseo plugin install "$PWD"
+```
+
+After editing a directory installation:
+
+```bash
+npm run check
+npm run typecheck
+paseo plugin reload paseo-omp
+paseo plugin ls paseo-omp
+```
+
+## Track a branch
+
+Tracking `main` executes future dependency and plugin updates with the daemon user's privileges. Record the installed commit before each update:
+
+```bash
+paseo plugin add omercnet/paseo-plugins:paseo-omp --ref main
+paseo plugin ls paseo-omp --json > paseo-omp-before-update.json
+paseo plugin update paseo-omp
+```
+
+A failed Git build or incompatible update leaves the previous revision active. Remove and re-add the recorded commit to roll back.