Paseo OMP plugin

Community OMP integration for Paseo. The plugin registers the distinct omp-plugin provider plus named profile providers and coexists with Paseo's bundled omp provider.

Stable: see Support for supported versions and known limitations, and review release notes for any migration requirements before upgrading.

Demo

https://github.com/user-attachments/assets/6d7eff94-cd63-43e1-83ad-642b1b8f75b4

Screenshots

Both PNGs come from the plugin's isolated Paseo development daemon at 2× pixel density. Browser DevTools rewrites local filesystem paths and verifies that no private organization names remain before capture.

Native plugin manager

Typed OMP configuration

Quick start

Requirements: Paseo ^0.12.0, OMP 18.1.15 or newer, and OMP RPC protocol v2. Workspace discovery passes includeBackground, which throws on hosts that do not advertise features.backgroundWorkspaces (new in 0.12), so older hosts are not supported.

paseo plugin install npm:@omercnet/paseo-omp@<version>
paseo plugin ls paseo-omp

Open the OMP sidebar to review the provider-profile contract, choose which composer pills appear, browse and edit native scalar settings, manage OMP-native plugins, verify runtime health, and generate a bounded support report under Help. The same tabs are available in the workspace OMP panel, except for the global Composer preference tab. Then create an agent and select OMP Plugin. Its optional MCP composer control runs OMP-native management commands in the current session; setup questions and authorization stay in that chat timeline, where OAuth can open in a workspace-scoped Paseo Browser or on the current device. Composer pill preferences are shared by clients connected to the same host; normal use requires no other plugin-specific settings.

Install, update, rollback, and local development
Configuration and every provider option
Compatibility, limitations, and support
Test matrix and release verification
Core-provider issue and parity audit
Release checklist

The plugin uses public Paseo 0.12 provider and client contracts and registers distinct omp-plugin and omp-plugin-<profile> identities; it does not modify the bundled omp provider.

Named OMP profiles

At startup the plugin discovers directory names under ~/.omp/profiles/ (or PI_CONFIG_DIR) and registers OMP · for each valid lowercase name. Select that provider when creating a profile-backed agent. Discovery, launch, recovery and persisted session listing share its fixed profile and session root. Matching command wrappers, including Doppler, remain supported; conflicting profile or session-directory overrides fail before launch. Plain env NAME=value omp wrappers are supported, but environment-control flags such as env -i and env -u are rejected because they can discard the selected store. Profile-specific XDG roots cannot be overridden by per-launch environment values. Reload the plugin after adding a profile.

Separate provider identities let the model picker request the correct profile catalog before an agent exists. Existing omp-plugin and bundled omp agents retain their provider; they are not migrated automatically. Profile names use OMP's lowercase grammar, including dotted names such as team.prod.

The OMP sidebar and memory panel expose an explicit store selector. Settings, plugins, quota, history, memory and diagnostics use that selection, and profile-agent popovers derive it from the provider ID. OMP-compatible XDG data and state roots are honored when a migrated profile uses them. Default-provider views are labelled Daemon default store; changing providerOptions.command on the default provider does not make those views profile-aware. Workspace configuration remains project-scoped, with the selected profile supplying inherited settings. Hub records are daemon-wide. The RPCs also accept an explicit absolute store.agentDir for custom stores; it is mutually exclusive with store.profile.

Profile selection is request-local: concurrent clients cannot change each other's process environment or cached results. Settings edits affect the selected store immediately.

Paseo provider SDK coverage

The capability inventory is pinned to @getpaseo/plugin 0.12.0, with nightly compatibility checks against the latest and beta channels. Provider capability scoring covers all 17 entries in the SDK's PROVIDER_CAPABILITIES; the separate provider/client SDK table below also tracks the registration, screen, and sidebar APIs introduced in 0.11. This measures strict SDK surface coverage, not general product quality.

Provider capability completeness: 61.8%. The provider advertises 11 of 17 capabilities (64.7%); ten are complete and session.configure is partial.

Scoring is deliberately mechanical so releases remain comparable:

100%: advertised, implemented end to end, and covered by automated provider tests.
50%: advertised with a meaningful subset, but at least one material SDK operation is rejected.
0%: not advertised; requests are rejected rather than silently approximated.
Overall completeness is the unweighted arithmetic mean of all 17 SDK capability rows.

SDK capability	Completeness	Support and gap
`prompt.message`	100%	Text, structured attachments, optimistic correlation, streaming, and terminal outcomes map to native OMP prompts. Matching terminal request IDs remain authoritative; released OMP builds without them use the ordered compatibility policy described below.
`prompt.command`	100%	Native command discovery plus structured `compact`, `autocompact`, `handoff`, `steer`, and `follow-up` dispatch. Individual commands can still fail when their documented OMP prerequisites are absent.
`prompt.image`	100%	Native image blocks for capable models; private bounded temporary files with cleanup for text-only models.
`prompt.output_schema`	0%	Not advertised. OMP has no equivalent structured-output contract; `outputSchema` fails visibly.
`prompt.steer`	100%	Native steering with turn ownership, user-message correlation, stale-target rejection, and terminal race handling.
`session.archive`	0%	Not advertised. Paseo may archive its agent record, but OMP has no native transcript archive operation.
`session.configure`	50%	Live model and thinking changes commit and republish native state. Live approval-mode changes require a new session, and non-empty SDK `settings` are rejected.
`session.list`	100%	Bounded host-wide and cwd-scoped discovery, search, previews, profile-specific session roots, and cleanup-reservation guards.
`session.persistence`	100%	Versioned opaque handles, exact resume, import, replay-before-ready, runtime recovery, and cleanup quarantine. Archived agents whose recorded workspace has been removed load read-only from their authorized transcript when Paseo opens them with its `history` purpose, without spawning OMP or connecting MCP servers; interactive create and resume still require the workspace.
`session.revert.both`	0%	Not advertised because OMP cannot atomically rewind conversation and workspace files.
`session.revert.conversation`	100%	Native branch-based conversation rewind, replay deduplication, ownership transfer, and failure quarantine.
`session.revert.files`	0%	Not advertised because OMP does not expose a native file-only rewind contract.
`session.subsession`	100%	Direct and nested OMP subagents become Paseo child sessions with lifecycle, ancestry, progress, and replay.
`session.unarchive`	0%	Not advertised; there is no native OMP archive state to reverse.
`permission`	100%	Typed tool permissions when negotiated, with a bounded generic interaction fallback for OMP 18.1.15. Allow, deny, cancel, timeout, and interruption are covered.
`permission.tool_policy`	0%	Not advertised. Exact MCP preapproval policy cannot be preserved through OMP `set_host_tools`, so the plugin fails closed instead of broadening access.
`timeline.plugin`	100%	Negotiated OMP MCP authorization requests render as interactive, schema-validated cards that can open a workspace-scoped Paseo Browser tab, with an on-device and built-in-notification fallback.

Provider functionality outside the capability flags is tracked separately:

Provider SDK surface	Completeness	Implementation
Registration metadata and sanitized SVG icon	100%	Stable `omp-plugin` identity, label, description, and bundled icon.
Strict `providerOptionsSchema`	100%	Command, literal environment, names-only profile inherited environment, output-redaction mode, session directory, RPC timeout, and role-model options are validated and normalized. Host-wide inherited names are separately persisted and merged at launch.
Availability diagnostics	50%	The plugin implements a `checkAvailability` hook with bounded checks that distinguish missing, unrunnable, incompatible, and available OMP runtimes, but Paseo 0.12 does not call it. The host uses the `status()` hook below instead, which reuses this probe for the default launch.
Catalog cache identity	100%	Hash includes effective options, merged host/profile inherited-environment names, settings, scope, cwd, and default command, but never resolves or fingerprints inherited values.
Models, modes, and thinking catalog	100%	Native catalog is mapped to opaque public model IDs with committed defaults and permission-gated modes.
Connection `send` / `onEvent` / `close` lifecycle	100%	Request correlation, multi-session ownership, process recovery, teardown, and provider reload/removal are covered.
Session launch: cwd, env, system prompt, title, and persistence	100%	Complete launch configuration is bounded, validated, forwarded, and re-read on recovery; selected host and profile daemon environment values are resolved only when catalog and session children spawn.
MCP server forwarding and host tools	100%	Configured MCP tools are discovered, namespaced, labeled, executed, canceled, and bounded. Forwarded tools are namespaced `mcpx__<server>_<tool>`: OMP treats `mcp__` as its own MCP manager's namespace and deletes that whole namespace from the session registry on every `refreshMCPTools`, so a forwarded tool registered under it is accepted and then dropped. Registration races OMP's deferred MCP discovery on every supported release; from 18.9.0 the ordering is deterministic and the tools were always lost. An OMP approval policy or inline-docs glob keyed on the old `mcp__<server>_<tool>` spelling must be re-keyed to `mcpx__<server>_<tool>`; OMP matches approval entries by exact tool name. Caller-scoped Paseo orchestration tools retain their native names, such as `create_agent` and `list_profiles`, so OMP skills can invoke them directly. The MCP composer control delegates native server management to OMP instead of duplicating its profile and workspace precedence. Exact `toolPolicy` remains the separate 0% capability above.
Denied native tools	100%	`disallowedTools` becomes an explicit OMP allow-list; unknown names fail closed.
Commands and committed session state events	100%	Publishes `session.commands`, `session.opened`, `session.config`, `session.ready`, and request completion in protocol order.
Built-in timeline snapshots	100%	Assistant, reasoning, tools, todos, notifications, errors, compaction, and friendly MCP labels use stable IDs and complete snapshots. OMP emits client-safe PNG/JPEG when possible; validated legacy WebP images render on capable clients with an explicit per-image fallback elsewhere.
Usage reporting	100%	Periodic, post-compaction, fallback, terminal, timeout, and recovered-runtime samples publish `session.usage`.
0.11 provider `status()`	75%	Registered for the plugin-owned default launch (`OMP_COMMAND` or `omp`, plus the fixed `--profile` wrapper for profile providers), using the bounded `--version`/`--help` probe. Only a missing executable reports `available: false`; slow, failing, or unrecognized probes stay available with a diagnostic. An unexpected internal probe error is not caught here, so the host reports it as unavailable. Available results are shared for 30 seconds; an unavailable result is never remembered, so installing `omp` takes effect on the next host call. The request carries only an optional daemon `launch` and never `providerOptions`, so a per-agent `providerOptions.command` or `env` is invisible. Breaking since 0.11: the host gates create, resume, and draft commands/features on this status, so a missing default executable blocks them all, including agents configured with an otherwise valid custom command. Any request `launch` is ignored.
0.11 provider `command` and daemon launch	0%	Deliberately not declared. Declaring `command` makes the daemon resolve it against its own `PATH` and reject every `connect` when the default binary is missing. The resulting `launch.env` is the daemon's entire process environment plus overrides, indistinguishable from configured values, so adopting it would defeat names-only `inheritEnv` and the fixed profile store environment. The host never supplies `launch` without a declared `command`; `connect` and `getCatalogCacheKey` do not read it, each pinned by `tests/provider-catalog.test.ts`. Revisit if the host stops gating on the default binary or exposes configured `env` separately from the daemon environment.
0.11 screens and sidebar items	100%	The global config surface migrates to `addScreen({ id: "config" })`, preserving legacy links and encoding profile selection in screen params. The Hub status row uses `addSidebarHeaderItem` + `SidebarRow`, lists processes and tails logs in a reusable popover. The legacy static config row and surface were removed with the 0.11 floor.
0.11 usage source	0%	Not registered. `server/quota.ts` reads OMP's recorded `usage_history`, not live quota, so there is no live fetcher to register. Upstream Claude and Codex sources fetch live quota for the Anthropic and Codex OAuth credentials in the daemon's default or `OMP_PROFILE` store; other providers and named profiles remain covered only by this plugin's historical quota pill.

Tracking rules:

On every @getpaseo/plugin upgrade, diff the SDK's exported PROVIDER_CAPABILITIES list and add every new capability here at 0% before claiming support.
Raise a row only when the provider advertises the capability and an observable contract test covers its success and failure boundaries.
Keep native-agent limitations at less than 100% even when the adapter itself is complete; do not count undocumented fallbacks as support.
Keep the detailed evidence and regression locations in TESTING.md; this README is the public progress ledger.

Compatibility and coexistence

The plugin always remains a separate provider. It registers omp-plugin and omp-plugin-<profile> identities; it never registers, overrides, removes, or migrates Paseo's bundled omp provider. Both identities may be enabled on the same daemon and selected independently per agent.

Existing agents whose provider is omp remain owned by the bundled provider. New plugin agents persist under their selected omp-plugin or omp-plugin-<profile> identity with the plugin's versioned opaque handle. The plugin can list and import OMP-native sessions through its own provider flow, but it performs no implicit conversion of bundled-provider records.

OMP 18.1.15 is the oldest version tested end to end. The direct provider's hard compatibility gate is rpc-ui protocol v2: metadata-free legacy ready frames and v1-only runtimes are rejected before a provider session opens because they cannot support the advertised persistence and conversation-rewind capabilities. Typed tool approvals remain capability-gated and fall back as described above. For terminal completion, a matching agent_end.requestId is authoritative and mismatches are ignored before state changes. Released OMP 18.2.x builds that omit that field use an ordered fallback requiring a fresh correlated native user entry followed by current-turn assistant activity, an idle non-compacting runtime, and no conflicting permission, tool, steer, or child-session work. Ambiguous events while OMP is active are ignored; unresolved ambiguity after confirmed idle fails only the Paseo turn. This trades a bounded residual same-agent stale-event risk for compatibility with released OMP instead of terminating and lazily restarting the runtime after every later prompt. Paseo clients, including mobile clients inside reconnect grace, do not own or terminate the daemon-managed OMP session.

Paseo 0.12 is the minimum supported release. The controlled Docker canary is pinned to official 0.12.0; nightly SDK checks cover the latest and beta channels. The canary preserves nested provider-subagent ancestry and spawning-tool links, and validates npm-managed plugin sources, platform-owned external URL opening, and whole-item timeline transforms before Overview grouping.

Install, update, disable, or remove paseo-omp independently of the bundled provider. Verify the provider snapshot contains omp-plugin after installation; a bundled omp entry may remain present and is not modified by this plugin.

Output and credential boundary

The plugin validates OMP protocol data and bounds public strings and structured values. It does not heuristically redact or rewrite content produced by native OMP, models, or tools. Do not put credentials in prompts or tool output, because that content may be published unchanged after validation and bounding.

providerOptions.outputRedaction defaults to none, preserving native content subject to those bounds. configured-values provides best-effort literal replacement for explicitly supplied credential values and every non-empty daemon value selected through host or profile inheritEnv, regardless of its name. It does not detect generated secrets or encoded, transformed, or independently streamed fragments of configured values. Centralized Paseo policy is required when a deployment needs redaction guarantees.

Unexpected or internal launch failures use fixed fallback messages rather than serializing the launch configuration. Explicit public validation errors may include caller-supplied configuration names or values. Deployments that require host-wide content redaction should implement it in a dedicated host or plugin layer rather than this protocol adapter.

Testing and development

The repeatable Docker canary and every validation command are documented in TESTING.md. It covers discovery, modes, text, images, tools, MCP, permissions, steering, interruption, persistence, host-wide and scoped session listing, import, resume, subagents, Hub, usage, plugin RPCs, and conversation rewind.

Use Deterministic Canary for picker-label assertions. The optional local Ollama model is exploratory and nondeterministic.

Support

See SUPPORT.md for ownership, escalation boundaries, supported versions, security reporting, and the repeatable OMP RPC compatibility intake process.

paseo-omp

Gallery

Install