b563b12662
## Summary - Add `fusion-plugin-omp-runtime` so Fusion agents can run through operator-installed **Oh My Pi (`omp`)** over the [Agent Client Protocol](https://omp.sh/docs/acp) (`omp acp`). - Wire staged/bundled install, Settings → Authentication card (enable + binary path), model discovery (`omp models` → `omp-cli/*`), and MCP eligibility for runtime id `omp`. - Forward Fusion `systemPrompt` via ACP `session/new` `_meta.systemPromptOverride`. ## How operators use it 1. Install/auth `omp` (credentials under `~/.omp`). 2. Enable **Oh My Pi — via omp ACP** in Settings → Authentication (optional binary path). 3. Set agent **Runtime Source → OMP Runtime** (`runtimeHint: "omp"`), or pick an `omp-cli/*` model when enabled. ## Known v1 gaps - No Grok-style Fusion `fn_*` loopback tool bridge yet (operator MCP is forwarded; in-process custom tools are not). - Model is fixed at spawn (`omp --model … acp`); no mid-session Fusion model switch. ## Test plan - [x] `pnpm --filter @fusion-plugin-examples/omp-runtime test` (unit + live ACP when `omp` is on PATH) - [x] Auth routes: `POST /api/auth/omp-cli`, `GET /api/providers/omp-cli/status` - [x] Engine `runtimeSupportsMcp("omp")` - [ ] Manual: enable card in dashboard, select OMP runtime on an agent, run a short chat turn <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added Oh My Pi (OMP) CLI support as an ACP-backed runtime and model provider, including model discovery and probing. * Added dashboard auth/status controls to enable OMP, check readiness, and configure the local binary path (with validation). * Exposed OMP custom `fn_*` tools via an MCP loopback bridge, plus optional filesystem capabilities and stricter tool permission gating. * **Documentation** * Added/expanded OMP runtime contract and integration docs (including the ACP session/handshake flow). * **Tests** * Added Vitest coverage for settings wiring, provider status, model discovery, runtime sessions, permissions, MCP bridging, and live connectivity. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
105 lines
4.8 KiB
Markdown
105 lines
4.8 KiB
Markdown
# fusion-plugin-omp-runtime
|
||
|
||
Oh My Pi (`omp`) CLI-backed provider/runtime plugin for Fusion. Agent sessions use **native ACP** (`omp acp`) for realtime streaming, tool visibility, and multi-turn reuse.
|
||
|
||
## Install
|
||
|
||
This plugin is staged with Fusion runtime plugins. It shells out to an **operator-installed** `omp` binary on PATH — Fusion never downloads or bundles the CLI itself.
|
||
|
||
### External integration evidence
|
||
|
||
Per `AGENTS.md` (External-integration evidence):
|
||
|
||
- **Canonical upstream repo URL:** https://github.com/can1357/oh-my-pi
|
||
- **Docs / homepage URL:** https://omp.sh/ · https://omp.sh/docs/acp
|
||
- **Release / download URL:** https://github.com/can1357/oh-my-pi/releases · installer `curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh` · npm `@oh-my-pi/pi-coding-agent`
|
||
- **Binary / CLI name:** `omp`
|
||
- **Checksum:** `upstream-pending-verification` (operator-installed binary; Fusion does not pin/download it)
|
||
- **ACP protocol:** https://agentclientprotocol.com · https://github.com/zed-industries/agent-client-protocol
|
||
- **ACP TypeScript SDK:** `@agentclientprotocol/sdk` `0.24.0`
|
||
|
||
## Contract summary
|
||
|
||
| Item | Value |
|
||
| --- | --- |
|
||
| Plugin ID | `fusion-plugin-omp-runtime` |
|
||
| Runtime ID | `omp` |
|
||
| Provider ID | `omp-cli` |
|
||
| Binary probe | `omp --version` |
|
||
| ACP launch | `omp acp` (equiv. `omp --mode acp`) |
|
||
| Optional model | `omp --model <id> acp` |
|
||
| Auth | omp `agent` method — reuses `~/.omp` provider keys / OAuth |
|
||
|
||
## Agent session path — ACP (primary)
|
||
|
||
`OmpRuntimeAdapter` drives omp’s native ACP server with a **vendored** ACP client (copied under `src/acp/`, not imported from `fusion-plugin-acp-runtime`):
|
||
|
||
```bash
|
||
omp acp
|
||
# optional model:
|
||
omp --model claude-sonnet-4 acp
|
||
```
|
||
|
||
- **Realtime streaming** — ACP `session/update` notifications map to Fusion `onText` / `onThinking` / `onToolStart` / `onToolEnd`.
|
||
- **Multi-turn** — one `createSession` keeps the ACP connection; each `promptWithFallback` is a `session/prompt` on the same session.
|
||
- **Permissions** — omp tool calls surface as `session/request_permission` and go through Fusion’s per-category action gate.
|
||
- **Auth** — after `initialize`, Fusion prefers the `agent` auth method (credentials under `~/.omp`). Terminal/TUI login is not preferred for headless Fusion.
|
||
- **Env** — subprocess env is allow-listed (`HOME`/`PATH`/XDG + common provider key names). Full `process.env` is never inherited.
|
||
|
||
See https://omp.sh/docs/acp for the upstream protocol surface (slash commands, `_omp/*` extensions, wire debugging).
|
||
|
||
## Enable in Fusion
|
||
|
||
1. Install & authenticate `omp` (`omp --version`; credentials under `~/.omp`).
|
||
2. Install/enable this plugin (staged bundled runtime).
|
||
3. **Settings → Authentication → Oh My Pi — via omp ACP** → Enable (optional binary path).
|
||
4. Either:
|
||
- Agent → **Runtime Source: Runtime** → **OMP Runtime** (`runtimeHint: "omp"`), or
|
||
- Pick an `omp-cli/*` model when the toggle is on (from `omp models`).
|
||
|
||
## Fusion tools (`fn_*`)
|
||
|
||
Engine `customTools` (board/task/agent tools such as `fn_task_list`) are exposed to
|
||
omp as MCP server **`fusion-custom-tools`**:
|
||
|
||
1. `OmpRuntimeAdapter` starts a **loopback HTTP bridge** holding the in-process
|
||
`ToolDefinition.execute` closures.
|
||
2. Session `session/new.mcpServers` includes a stdio MCP child
|
||
(`mcp-schema-server.cjs`) that implements `tools/list` + `tools/call` and
|
||
POSTs calls to the bridge (`FUSION_OMP_TOOL_BRIDGE_URL`).
|
||
3. Operator-configured MCP servers are forwarded alongside (stdio/http/sse).
|
||
4. System rules tell omp to prefer `fusion-custom-tools` for Fusion board ops.
|
||
|
||
## Known v1 gaps
|
||
|
||
| Gap | Status |
|
||
| --- | --- |
|
||
| Auto-route `omp-cli/*` without explicit Runtime Source | **Partial** — models surface when Enable is on; prefer `runtimeHint: "omp"` for agent lanes |
|
||
| Mid-session Fusion model picker changes | **Not wired** — model is fixed at `omp --model … acp` spawn |
|
||
|
||
## Settings (ACP spawn bag)
|
||
|
||
Built internally by `buildOmpAcpRuntimeSettings`:
|
||
|
||
| Key | Default | Meaning |
|
||
| --- | --- | --- |
|
||
| `acpBinaryPath` | `omp` | Agent binary |
|
||
| `acpArgs` | `["acp"]` | ACP mode args |
|
||
| `acpModel` | `omp/default` | Model id for describeModel / optional `--model` |
|
||
| `acpEnvAllowList` | see `OMP_ACP_ENV_ALLOWLIST` | Env names forwarded |
|
||
| `acpFsRead` / `acpFsWrite` | `false` | Client-side ACP fs capabilities (opt-in) |
|
||
| `acpAllowUnrestricted` | `true` | Operator-selected first-party CLI posture |
|
||
| `acpAuthenticate.preferMethods` | `["agent","terminal"]` | Post-initialize auth |
|
||
|
||
## Development
|
||
|
||
```bash
|
||
pnpm --filter @fusion-plugin-examples/omp-runtime test
|
||
pnpm --filter @fusion-plugin-examples/omp-runtime build
|
||
```
|
||
|
||
## Notes
|
||
|
||
- Do not invent release checksums for the operator’s `omp` binary.
|
||
- Generic multi-agent ACP (any binary) remains `fusion-plugin-acp-runtime`; this plugin is the omp-specific first-class path with sane defaults.
|