can1357
d7261bcbeb
- Added typed event listeners and granular event handling for all RPC notification types. - Added set_todos RPC command and todoPhases session state field for todo phase management. - Added RpcClient initialization parameters (thinking, tools, no_session, rpc_defaults) for startup configuration. - Added install_headless_ui() method and todo management methods (get_todos, set_todos, clear_todos). - Added TodoItem and TodoPhase dataclasses with parser functions for structured todo representation. - Added RPC mode behavior: disables session title generation by default and resets workflow settings to built-in defaults.
132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
# omp-rpc
|
|
|
|
Typed Python bindings for the `omp --mode rpc` protocol used by the coding agent.
|
|
|
|
This package wraps the newline-delimited JSON RPC transport exposed by the CLI and
|
|
provides:
|
|
|
|
- typed command methods for the stable RPC surface
|
|
- typed startup options for common `omp --mode rpc` flags such as thinking level,
|
|
tool selection, prompt appends, provider session IDs, and headless session toggles
|
|
- typed protocol models for state, bash results, compaction, and session stats
|
|
- a process-backed client that manages request correlation over stdio
|
|
- typed per-event listeners plus a typed catch-all notification hook
|
|
- helpers for collecting prompt runs and handling extension UI requests in manual or headless mode
|
|
|
|
## Basic Usage
|
|
|
|
```python
|
|
from omp_rpc import RpcClient
|
|
|
|
with RpcClient(provider="anthropic", model="claude-sonnet-4-5") as client:
|
|
state = client.get_state()
|
|
print(state.model.id if state.model else "no model")
|
|
|
|
turn = client.prompt_and_wait("Reply with just the word hello")
|
|
print(turn.require_assistant_text())
|
|
```
|
|
|
|
The wrapper also exposes the common RPC startup flags directly, so scripts do not
|
|
need to build `extra_args` by hand:
|
|
|
|
```python
|
|
from omp_rpc import RpcClient
|
|
|
|
with RpcClient(
|
|
model="openrouter/anthropic/claude-sonnet-4.6",
|
|
thinking="high",
|
|
no_session=True,
|
|
no_skills=True,
|
|
no_rules=True,
|
|
tools=("read", "edit", "write"),
|
|
append_system_prompt="Focus on reproducible benchmark behavior.",
|
|
) as client:
|
|
print(client.get_state().thinking_level)
|
|
```
|
|
|
|
For orchestration hosts, the wrapper also exposes typed event hooks and a simple
|
|
way to seed todos before the first prompt:
|
|
|
|
```python
|
|
from omp_rpc import MessageUpdateEvent, RpcClient
|
|
|
|
def on_message_update(event: MessageUpdateEvent) -> None:
|
|
assistant_event = event.assistant_message_event
|
|
if assistant_event.get("type") == "text_delta":
|
|
print(assistant_event["delta"], end="", flush=True)
|
|
|
|
with RpcClient(model="openrouter/anthropic/claude-sonnet-4.6", no_session=True) as client:
|
|
client.on_message_update(on_message_update)
|
|
client.set_todos(
|
|
[
|
|
"Map the read and edit tool surface.",
|
|
"Exercise the supported edit paths.",
|
|
"Write concrete findings and gaps.",
|
|
]
|
|
)
|
|
client.prompt_and_wait("Evaluate the current tool behavior.")
|
|
```
|
|
|
|
`set_todos()` accepts either a flat list of todo strings/items or explicit
|
|
phases, and `get_state().todo_phases` returns the typed current todo state.
|
|
|
|
By default the client runs:
|
|
|
|
```bash
|
|
omp --mode rpc
|
|
```
|
|
|
|
You can also point it at a custom command, which is useful inside this repo while
|
|
developing against the Bun entrypoint:
|
|
|
|
```python
|
|
from omp_rpc import RpcClient
|
|
|
|
with RpcClient(
|
|
command=[
|
|
"bun",
|
|
"packages/coding-agent/src/cli.ts",
|
|
"--mode",
|
|
"rpc",
|
|
"--provider",
|
|
"anthropic",
|
|
"--model",
|
|
"claude-sonnet-4-5",
|
|
],
|
|
) as client:
|
|
print(client.get_state().session_id)
|
|
```
|
|
|
|
## Extension UI Requests
|
|
|
|
Extensions in RPC mode can ask the host for input. Those requests are available as
|
|
typed `ExtensionUiRequest` instances:
|
|
|
|
```python
|
|
request = client.next_ui_request(timeout=5.0)
|
|
|
|
if request.method == "confirm":
|
|
client.send_ui_confirmation(request.id, True)
|
|
elif request.method in {"input", "editor"}:
|
|
client.send_ui_value(request.id, "approved")
|
|
```
|
|
|
|
For non-interactive scripts, you can install a default headless policy instead of
|
|
handling every request manually:
|
|
|
|
```python
|
|
with RpcClient(model="anthropic/claude-sonnet-4-5") as client:
|
|
client.install_headless_ui()
|
|
turn = client.prompt_and_wait("needs ui-safe automation")
|
|
print(turn.assistant_text)
|
|
```
|
|
|
|
That helper ignores passive UI notifications (`notify`, `setStatus`, `setWidget`,
|
|
`setTitle`, `set_editor_text`), answers `confirm` with `False`, and cancels
|
|
`select`/`input`/`editor` requests unless you provide explicit values.
|
|
|
|
## Protocol Reference
|
|
|
|
The canonical wire protocol still lives in the repo at
|
|
[`docs/rpc.md`](../../docs/rpc.md).
|