Agent protocol services
Agent protocol services form the native bridge between coding-agent clients and Impeccable. They expose managed agent configuration through a remote service and add local capabilities for asset transfer, browser use, sign-in recovery, and agent presence. The bridge keeps agent processes on a line-based MCP protocol while protecting local files, credentials, and browser access.
MCP client boundary
Stdio MCP session
The MCP session is the client-facing entry point for an agent. Each agent starts one local impeccable mcp process over standard input and output. The process forwards service requests while keeping protocol frames on stdout and diagnostics on stderr.
The session presents one stable tool boundary even when a capability is local. It forwards normal requests to the account service, replaces the service asset tool with a local-file form, and adds browser tools only when the local browser relay is available.
The main request path is shown below.
flowchart LR
Agent[External coding agent] --> MCP[Local MCP session]
MCP --> Local[Local tools]
MCP --> Account[Account service MCP]
Local --> Reply[Tool result]
Account --> Reply
Reply --> Agent
References: crates/…/lib.rs• L1-18 crates/…/lib.rs• L63-75 crates/…/lib.rs• L98-185
Service requests
The account service remains the source for remote agent operations. The local session uses the CLI's stored sign-in and sends the MCP request to the account service without asking the agent to manage a token. This keeps service access consistent across agents on the same machine.
When a call needs authentication, the session can hold the call while the person signs in through the browser. It retries the call once after a successful sign-in. On a headless or SSH session it returns a direct instruction to run impeccable login instead.
Only one sign-in runs on a machine at a time. A second agent waits for the first sign-in result rather than opening another authorization flow.
References: crates/…/lib.rs• L28-60 crates/…/lib.rs• L321-359 crates/…/lib.rs• L389-455 crates/…/lib.rs• L486-525
Local capability services
Asset transfer
The asset tool lets an agent give an artifact a local file without sending the file bytes through the model. The session reads a supported regular file, checks its size and type, hashes its bytes, and asks the account service to reserve the matching content key.
If the workspace already has that content, the agent receives the key at once. Otherwise the service returns a short-lived upload address and the local session sends the bytes directly to it. The agent receives only the content key.
This flow separates file selection from remote storage and makes repeated uploads idempotent by content digest.
References: crates/…/asset.rs• L1-11 crates/…/asset.rs• L33-43 crates/…/asset.rs• L53-83 crates/…/lib.rs• L218-259 crates/…/lib.rs• L376-387
Browser control
The browser service lets an agent drive the person's signed-in Chrome through the Impeccable extension. It is local: the extension chooses which sites the person allows, and the remote service never reaches the browser relay.
Chrome starts a native-messaging host that accepts only approved Impeccable extension origins. The host relays framed JSON through a user-only Unix socket. One agent owns the browser session at a time; other agents receive a busy result until that session ends.
The browser tools cover page navigation, interaction, page inspection, and session end. A browser session can return an accessibility tree, images, styles, or other page views so an agent can inspect the result of its actions.
References: crates/…/browser.rs• L1-11 crates/…/browser.rs• L18-31 crates/…/browser.rs• L74-92 crates/…/browser.rs• L200-239 crates/…/lib.rs• L103-185
Browser host registration
Browser registration connects Chrome to the local relay. Installation writes one stable launcher and a native-messaging manifest for each supported Chromium browser profile that is present on the machine.
The launcher selects the newest verified local engine at run time. This lets engine updates take effect without changing each browser manifest. Sandboxed browser packages are reported when they cannot start the host outside their sandbox.
Registration is limited to macOS and Linux. It does not register a host until a verified engine is available, and it leaves an existing host with a different path unchanged.
References: crates/…/host_setup.rs• L1-7 crates/…/host_setup.rs• L16-45 crates/…/host_setup.rs• L121-145 crates/…/host_setup.rs• L138-193
Agent presence
The presence service gives the local CLI a view of active coding-agent sessions. A connected MCP session writes a short-lived record when it initializes and removes the record when it ends. The record links the session to its harness, process start time, working folder, and repository label.
The reader checks both process identity and process start time. It removes records from crashed sessions and scans for harness processes that do not use the MCP entry point. Those processes appear as seen but not connected, so the view distinguishes an active protocol session from an agent that is only visible in the process list.
The from value supplied by a needs-you request becomes the session's display name when present. Names are cleaned before they are stored or shown to the user.
References: crates/…/presence.rs• L1-7 crates/…/presence.rs• L106-175 crates/…/presence.rs• L193-253 crates/…/lib.rs• L108-150
Managed agent resources
Target files
Targets are derived from the request rather than supplied as arbitrary paths. Hooks select the harness settings files. Instructions select the harness rule file. Codex approval changes select its existing config.toml.
| Harness | Hook targets | Instruction target | Approval target |
|---|---|---|---|
| Claude Code | settings.json | CLAUDE.md | Not supported |
| Codex | hooks.json and config.toml | AGENTS.md | Existing server table in config.toml |
This fixed target model limits the service to known agent integration points and gives status and undo a stable view of what the request can affect.
References: crates/…/targets.rs• L5-23 crates/…/cli.rs• L81-114
Resource records
A resource is one independently tracked part of an installation. Examples include a hook entry, an instruction block, the Codex hooks setting, a Codex MCP approval, or an MCP server. Records keep the last value written, the prior value when known, and the installations that claim the resource.
Reapply updates the last written value while keeping the original baseline from the first install. This lets status check the current desired part and lets undo restore the correct earlier value after a staged change.
This model allows status to check the managed part instead of treating every unrelated edit in the same settings file as drift. It also lets undo preserve user content and release shared resources in the correct order.
References: crates/…/lib.rs• L213-260 crates/…/resources.rs• L252-424 crates/…/tests.rs• L1234-1247
Installation lifecycle
JSON protocol
The service accepts one JSON specification for one owner, harness, and account root. The command boundary validates that request, selects an operation, and returns a versioned JSON result or a structured error. The supported operations are capabilities, list, plan, apply, undo, status, and recover.
The protocol keeps the client independent from the details of either coding-agent harness. A client can inspect the supported scope first, preview changes without writing, apply or remove an installation, and inspect drift later.
References: crates/…/cli.rs• L4-66 crates/…/cli.rs• L68-121 crates/…/lib.rs• L18-54
In-process access
The service also exposes the same validated operations to native callers that already build a Spec in code. These callers can run a plan, apply, status, or undo operation without crossing the command-line boundary. They can also list the installations owned by one owner and recover an interrupted installation.
This access path reads committed and pending state from the service journal. It therefore lets a caller undo or recover what was installed earlier instead of reconstructing that state from the current environment.
References: crates/…/lib.rs• L504-510 crates/…/lib.rs• L512-561 crates/…/lib.rs• L564-568
Request scope
Each request names an owner and a harness. The harness is either Claude Code or Codex. The account root is an absolute path that identifies the user installation to change. Hooks, instructions, MCP servers, and Codex approval modes are optional parts of the same desired state.
The service stores its private state outside the account root. This lets several owners or account roots share a physical resource while keeping each installation claim separate.
References: crates/…/lib.rs• L39-59 crates/…/lib.rs• L105-114 crates/…/cli.rs• L123-146
Change planning
Planning compares the requested state with the current files and harness state. It reports whether each target will be created, updated, or left unchanged. It also reports MCP server changes and whether an existing JSON file would be reformatted. Planning does not write the target or the journal.
References: crates/…/targets.rs• L25-87 crates/…/tests.rs• L667-686
Change application
Application first checks for changes made outside the service. It also refuses to replace an instruction block that a person edited. It then renders the requested content, writes the files, updates MCP settings through the selected harness, and records the result. The journal is the source for later status checks and undo operations.
On a reapply, the service keeps the original baseline when only its own earlier write changed the resource. An outside edit changes the cleanup path to a surgical update, so undo does not restore over the person’s change.
The main lifecycle is shown below.
flowchart LR
Client[Agent client] --> Request[JSON specification]
Request --> Validate[Validate scope]
Validate --> Plan[Plan targets and resources]
Plan --> Apply[Apply file and MCP changes]
Apply --> Journal[Record claims and written state]
Journal --> Result[Versioned JSON result]
Apply --> Recover[Pending transaction]
Recover --> Result
References: crates/…/resources.rs• L3-57 crates/…/resources.rs• L58-250 crates/…/render.rs• L105-132 crates/…/tests.rs• L1356-1373 crates/…/tests.rs• L1417-1457
Change removal
Undo removes only content that the installation owns. It restores original bytes when the service still controls the whole file. When a person or another installation changed the resource, it removes only the owned part when that is safe. Otherwise it reports a conflict and leaves the changed content in place.
Undo uses the journaled installation state rather than only the caller’s current request. If the journal is missing while the installation’s marker or exact hook remains on disk, the service reports the missing state instead of claiming that removal succeeded.
References: crates/…/resources.rs• L577-688 crates/…/render.rs• L77-103 crates/…/tests.rs• L1375-1388 crates/…/cli.rs• L148-168
Harness integration
Configuration rendering
Rendering adds the requested agent behavior to the harness format while preserving unrelated content. JSON settings reject invalid or duplicate-key input. Codex TOML keeps existing keys, comments, and line endings while changing only the features or approval data that the request owns.
Instruction text uses an owner marker in CLAUDE.md or AGENTS.md. The marker gives the service a clear boundary for later updates and removal. Ambiguous markers or edits inside the owned block stop replacement or removal rather than risk deleting user text.
Codex approval changes apply only to an existing standard MCP server table. The service changes the approval value or removes the line later without creating or rewriting a different table form.
References: crates/…/render.rs• L8-75 crates/…/render.rs• L105-161 crates/…/render.rs• L544-645 crates/…/render.rs• L737-802 crates/…/tests.rs• L131-216 crates/…/tests.rs• L952-1019
Hook behavior
Hooks are expressed once in the request and mapped to the shape expected by the selected harness. Claude Code stores them in user settings. Codex stores them in its hook file and enables the Codex hook feature when that feature is not already set.
The service does not take ownership of an explicit Codex choice to disable hooks. It asks for that setting to be enabled first, so a request cannot silently change the user’s safety choice.
Undo can remove an unchanged managed hook while keeping a personal hook in the same event. If a person changes the managed hook’s options, the service leaves that entry in place and reports the specific hook as a conflict.
References: crates/…/lib.rs• L60-103 crates/…/render.rs• L34-63 crates/…/render.rs• L163-193 crates/…/render.rs• L268-339 crates/…/tests.rs• L1392-1414 crates/…/tests.rs• L1501-1532
MCP integration
MCP server state
MCP, or Model Context Protocol, servers are named external tools that a coding-agent harness can start or use. The service manages these servers through the Claude Code or Codex command-line interface. It reads back the installed configuration after an add and compares that observation with the requested value.
The service treats an existing name as a real resource. A foreign configuration causes a collision. Identical claims can be shared, and the server is removed only after the last claim is released.
References: crates/…/mcp.rs• L3-49 crates/…/mcp.rs• L51-117 crates/…/mcp.rs• L222-328 crates/…/resources.rs• L10-19 crates/…/resources.rs• L397-424
Codex approvals
Codex approval modes control how a configured MCP server is allowed to run. The service changes only the approval line in an existing standard server table. It records the prior mode so undo can restore it without changing other Codex settings.
An absent server or an unsupported table form is rejected. A person’s later change to the approval mode is treated as drift, not as permission for the service to set the old mode again. Status checks each approval against its own server, so a matching mode on another server cannot hide drift.
References: crates/…/render.rs• L556-645 crates/…/render.rs• L647-666 crates/…/resources.rs• L21-42 crates/…/targets.rs• L158-168 crates/…/tests.rs• L1202-1247
Safe state changes
File ownership
File writes protect the user’s account and the service’s ownership boundary. The service accepts regular files and user-owned target locations, follows an existing symlink without replacing the link, and refuses unsafe or ambiguous targets.
Before and after a write or delete, the service checks that the target still has the expected identity and content. It writes through a temporary file and verifies the final result. A concurrent change therefore becomes an explicit conflict instead of an overwrite.
References: crates/…/fs_writer.rs• L17-135 crates/…/fs_writer.rs• L153-248 crates/…/tests.rs• L217-240
Shared claims
Several installations may claim the same physical file or MCP server. The service permits this only when the desired values agree. An undo keeps a shared resource for remaining claims and restores it after the final claim is released.
This claim model is important for symlinked account roots and for Codex settings shared by multiple installations. A different desired value is refused before it can replace another owner’s configuration. A shared Codex configuration can still remove one owner’s approval when no other owner claims that server.
References: crates/…/resources.rs• L109-143 crates/…/resources.rs• L465-575 crates/…/resources.rs• L600-633 crates/…/tests.rs• L474-510 crates/…/tests.rs• L1166-1200
Recovery and visibility
Interrupted transactions
Application records a pending transaction before it changes files or MCP state. If the process stops before the journal commit, recover compares the current state with the intended and prior state. It rolls back only changes that still match the transaction and reports a conflict when another change prevents a safe rollback.
The same journal also protects against a newer or invalid state format. Such state is rejected instead of being guessed at or overwritten.
References: crates/…/lib.rs• L275-382 crates/…/resources.rs• L159-186 crates/…/tests.rs• L242-336
Status reports
Status reports whether an installation exists, whether its managed resources still match, and whether Codex needs a manual action such as hook approval or folder trust. The list operation summarizes all readable installations without exposing account roots or hook commands. Resources that need a harness CLI to check can be marked unchecked when that CLI is not available.
Status evaluates each owned resource separately. Unrelated file edits remain acceptable, while an edited hook, instruction block, MCP server, or approval becomes a conflict. Invalid or newer journals do not hide other readable installations from the list report.
References: crates/…/targets.rs• L89-186 crates/…/cli.rs• L182-240 crates/…/tests.rs• L688-727 crates/…/tests.rs• L1281-1343
Runtime relationships
Native runtime links
This page describes the agent-service boundary used by the native runtime, CLI, and external coding-agent clients. For the surrounding process model, read Native runtime and CLI and Rust CLI runtime. For account and paid-service boundaries, read Account and Pro services. For workflows that create agent behavior, read Design seed generation and Component composition operations. For the design rules that guide those workflows, read Design foundations and taste.
References: crates/…/lib.rs• L1-18 crates/…/lib.rs• L1-35 crates/…/cli.rs• L4-58
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the MCP tool list, local tool interception, and
tools/list_changedbehavior aligned when a local capability is added or removed. - Keep account-service request forwarding, sign-in retry rules, progress messages, and headless-browser errors aligned when authentication behavior changes.
- Keep asset file checks, digest reservation, upload expiry handling, and returned-key semantics aligned across local and remote sides.
- Keep browser extension origins, native-host manifests, socket permissions, frame size limits, and one-agent ownership rules aligned.
- Keep presence record identity, process start-time checks, display-name rules, and the connected versus seen distinction aligned.
- Keep target selection, rendering, resource recording, status checks, and undo logic aligned when a new managed resource is added.
- Preserve the pending-transaction and journal contract when changing apply order or recovery behavior.
- Recheck shared-claim and last-undo behavior when changing resource identity or installation identity.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The account sign-in is missing or lacks a needed scope | The call waits for approval or returns a login instruction | One browser sign-in is held and the call is retried once |
| A local upload is missing, empty, too large, unsupported, or a symlink | No asset reservation or upload occurs | The file type, size, identity, and byte count are checked |
| An upload address is expired or rejected | The asset tool returns an error and no key is claimed as complete | The upload response is checked and the agent must call the asset tool again |
| A browser host has an unverified engine or an unapproved extension origin | Chrome cannot start the browser relay | Host registration requires a verified engine and fixed extension origins |
| Another agent owns the browser relay | The caller receives a busy result | The relay assigns one driver and tracks pending calls by connection |
| The browser relay or extension closes during a call | The tool returns a browser-gone error and the next call reconnects | Socket identity and framed-call failures are checked |
| A presence record outlives its process or its PID is reused | A stale session could appear connected | The reader compares the recorded process start time |
| Another installation wants a different value for a shared file or MCP name | The requested change is refused | Shared claims are checked before writing |
| A person changes a managed hook, instruction block, MCP server, or approval | Apply or undo reports drift or conflict and preserves the change | Last-written values and prior values are recorded |
| The process stops during a file or MCP change | A pending transaction remains | recover rolls back matching changes or reports the blocking conflict |
| The journal is missing while managed content remains on disk | Undo refuses to claim success | The service checks for the owner marker and exact hook entries |
Key files
| File | Why to read it |
|---|---|
| crates/…/lib.rs | Defines the local MCP session, service forwarding, sign-in recovery, and tool interception. |
| crates/…/asset.rs | Defines safe local asset selection, hashing, reservation parsing, and the key-only result. |
| crates/…/browser.rs | Defines browser tools, framed relay messages, local socket access, and single-agent ownership. |
| crates/…/host_setup.rs | Defines Chrome native-host registration and verified-engine launch behavior. |
| crates/…/presence.rs | Defines connected-session records and the local running-agent view. |
| crates/…/Cargo.toml | Shows that the native MCP layer depends on the common and account services and handles asset hashing. |
| crates/…/cli.rs | Defines the external agent-service command boundary, validation, verbs, and result shape. |
| crates/…/lib.rs | Defines request types, journal state, locking, and recovery boundaries. |
| crates/…/targets.rs | Shows which harness files are in scope and how status checks managed resources. |
| crates/…/resources.rs | Explains apply, undo, resource claims, and shared-resource behavior. |
| crates/…/render.rs | Shows how hooks, instructions, Codex features, and approvals map into harness files. |
| crates/…/fs_writer.rs | Defines the safety boundary for file writes, deletes, symlinks, and concurrent edits. |
| crates/…/mcp.rs | Defines MCP server discovery, synchronization, verification, and collision handling. |
| crates/…/tests.rs | Demonstrates the end-to-end guarantees for rendering, recovery, sharing, status, drift, and undo. |
| crates/…/mcp.rs | Demonstrates MCP collision, sharing, drift, verification, and removal behavior. |