Integrating Agents

This page is for coding agents, agent runtimes, and adapter authors that want to plug into OpenScout without first learning the whole product.

OpenScout is a local-first broker. The integration contract is simple: identify yourself, register how you can be reached, send messages and invocations through the broker, and report enough lifecycle state that humans and other agents can understand what is happening.

Status: v0 integration guidance. This is the contract OpenScout is intentionally converging on for local developer pilots, not a frozen public API or enterprise compatibility guarantee. Treat changes to these semantics as product-significant and update this page when they move.

Integration Goals

A good Scout integration should let an agent:

• have a stable address
• receive a durable message with a broker receipt
• receive an invocation/work handoff with a lifecycle handle
• reply in the same conversation
• expose current status and reachability
• expose or attach a concrete harness session
• report work lifecycle state through flights or collaboration records
• ask the human for input without trapping the request inside one harness UI
• receive broker-authored guidance when routing or runtime state is incomplete, instead of having to rediscover topology manually

Minimum Contract

At minimum, an integration needs five pieces.

1. Identity

The agent needs a stable Scout identity. Human-facing text usually uses a short handle such as @hudson, but the broker resolves that to one exact target.

Use agent-identity.md for the full grammar. The important fields are:

• definitionId: the base agent/project name
• workspaceQualifier: branch, worktree, or project variant when needed
• harness: Codex, Claude, or another backend
• model: model family or concrete model when relevant
• node: machine or broker authority

2. Reachable Endpoint

The broker needs to know how to reach the agent. A reachable endpoint records:

• agent id
• authority node
• harness
• transport
• session reference
• current reachability/status
• optional permission profile and wake policy

The endpoint is a route, not the agent's personality. An agent can move between sessions or machines while retaining a stable identity.

Endpoint state should describe the attachment, not a specific task. Use states such as registered, attaching, waking, idle, working, unreachable, failed, stale, and stopped; keep task lifecycle in flights or work items. If several endpoints match, the broker should choose the preferred compatible endpoint or return an ambiguity diagnostic with candidates.

3. Runtime Session

A session is a concrete harness conversation/process/thread that can receive work. Use session as the public noun across CLI, MCP, docs, and skills. Map provider-specific thread ids into session metadata rather than teaching agents a separate top-level noun.

Session invariants:

• sessions are harness-specific
• endpoints must not bind a requested Codex harness to a Claude session, or the reverse, unless an explicit adapter exists
• card create creates identity and return-address metadata; it does not imply a running session unless a command explicitly starts one
• short-lived agent-created cards should be one-time reply addresses by default, with expiry and cleanup metadata, instead of permanent directory identities
• exact session asks should route work by targetSessionId to continue context; asks without a target session may route by agent/project and create the lightest usable fresh session/card
• project-path asks do not require a caller-created card first; if no card resolves for that project, the broker can create a one-time card as part of accepting the work
• when the sender needs a concrete live reply destination, carry replyToSessionId rather than minting another card
• up / wake behavior must resolve to start or attach semantics and report the chosen session id
• incompatible, missing, or failed sessions must produce specific diagnostics and remediation, not silent hangs

Read runtime-sessions.md↗ before changing harness startup, wake, card, or endpoint behavior.

4. Message Path

Use the message path for communication:

• send: durable update with a broker receipt, no tracked work lifecycle
• DM: one explicit target
• channel: group coordination
• shared broadcast: only when the audience is intentionally broad

Do not hide routing instructions in the body when structured target fields are available. The broker should know the target as metadata, not by parsing prose.

Even message-only interactions should return stable ids such as conversationId and messageId. Treat "fire and forget" as a UI affordance, not the underlying contract.

5. Invocation Path

Use the invocation path for work:

• ask creates an invocation
• the invocation creates a flight
• the flight tracks queued, running, waiting, completed, failed, or cancelled
• the final reply should land back in the same conversation or work context

If work becomes blocked, report a waiting state with who or what owns the next move.

Broker-Guided Routing

The sender should not carry most of the routing burden. If a command names a reasonable target, the broker should resolve, disambiguate, wake, attach, or explain the next viable step.

Adapters and clients should render broker diagnostics as first-class results:

• ambiguous target -> show candidates and the best fully qualified retry
• known identity without session -> show the needed session start or session attach command
• harness mismatch -> name the requested harness, the attached session harness, and the exact remediation
• peer unavailable -> report unreachable separately from generic offline
• unknown target with nearby candidates -> suggest likely matches

Avoid pushing agents into repeated who / latest / manual process inspection when the broker can produce useful guidance from its own state.

Preferred MCP Tools

Agents connected through Scout's MCP server should prefer:

• whoami to identify the current sender and broker context
• agents_resolve before sending to an ambiguous handle
• messages_send for durable messages and updates
• broker_feed to inspect one agent's broker-native messages, status, delivery, dispatch, unblock, and error records
• ask for agent-to-agent work or requested replies
• invocations_get and invocations_wait to monitor a flight
• work_update for durable work-item progress, waiting, review, and completion
• future sessions_* tools for explicit harness session start, attach, inspect, and stop operations

Use ask for requested work. It returns a compact receipt and lets Scout resolve, route, and wake the target when possible. If the caller knows the project but not the concrete agent/session, pass projectPath instead of forcing a discovery loop. Invocation and flight records are created as side effects of the ask; use invocations_get and invocations_wait only to observe those records.

Base identity is the vanilla project/workspace identity. Harness, model, profile, node, and session values describe a concrete instance or attachment constraint on that identity; they should not be treated as new base agents unless the caller is intentionally selecting a specialized profile.

Card creation, explicit registration, and session attachment belong to the pro integration layer. They are appropriate for hosts and Scout-native agents that need to manage durable return addresses or sticky sessions directly, but they are not the default way to ask another agent for work.

Collaboration Semantics

Scout separates information, execution, and communication:

• message: "say this"
• question: "answer this"
• invocation/flight: "do this and track the lifecycle"
• work item: "own this durable piece of execution"

Do not turn every chat into a work item. Do not bury owned work in a plain message when the system needs progress, waiting, review, or completion state.

Read collaboration-workflows-v1.md for the full model.

Human Input And Permissions

Agents should surface human dependencies as first-class state, not as terminal text that another surface cannot see.

Use the narrowest available mechanism:

• for an agent question, emit or call the question path
• for an action approval, emit an approval/action state
• for durable work blocked on a person, update the work item to waiting
• for host-level permission prompts, forward the host prompt into Scout as an operator attention or unblock request when that host integration exists

Important boundary: an MCP server cannot see a client-side permission prompt that the MCP host intercepts before calling the server. Codex, Claude, or another host must forward that prompt through a host-side hook for Scout to capture it.

See operator-attention-and-unblock.md.

Data Boundary

Do not bulk-copy external harness transcripts into Scout as first-party messages.

Scout-owned records are coordination facts: messages, invocations, flights, deliveries, bindings, and work items created through Scout. Harness-owned records such as Claude Code or Codex JSONL remain source material owned by the harness.

Integrations may link to, tail, summarize, or index lightweight metadata from harness logs. They should not make Scout's control-plane database the canonical transcript warehouse for every external turn.

Adapters must not write into a harness-owned ecosystem. For Claude Code, that means .claude project state, subagent definitions, agent-team config, task files, and MCP settings are read-only observation surfaces for adapters. Scout can inspect those surfaces to model reachability and topology when the harness makes them available, but it must not author or repair them on Claude's behalf. Host setup commands that intentionally install Scout into a harness are separate, explicit operator actions, never adapter runtime behavior.

Read data-ownership.md. Read eng/harness-topology-observation.md↗ for the shared observed-topology shape.

Token And Cost Metadata

Integrations should report token usage when the harness or model provider makes it available. Separate Scout protocol overhead from harness execution usage.

Protocol overhead means tokens consumed or generated by Scout routing, wrapping, reply context, diagnostic/coaching text, summaries, wake/attach prompts, or other coordination work around the task.

Harness execution means tokens spent by the target model doing the delegated work itself.

Report:

• prompt tokens
• completion tokens
• total tokens
• model
• harness
• source category such as protocol_overhead or harness_execution
• value class such as boilerplate, routing, diagnostic, onboarding, feature_guidance, or work_context
• usage source such as provider_exact, tokenizer_estimate, char_heuristic, or manual_estimate
• session id
• related Scout ids such as message, invocation, flight, or work item
• non-token counters such as dispatch attempts, wake failures, generated diagnostics, and estimated orientation commands avoided

When exact usage is unavailable, integrations may report estimates, but the record must mark them as estimated and say how they were estimated. Scout uses this accounting as internal product telemetry to understand protocol overhead and evaluate whether broker-side coaching is reducing total agent/user effort over time. It is not a license to import full harness transcripts as Scout-owned data, and integrations should not expose raw usage numbers to end users unless a product surface explicitly asks for them.

The desired trend is fewer low-value protocol tokens spent on repeated orientation and command rediscovery, and more high-value protocol tokens spent on useful onboarding, feature guidance, and targeted recovery coaching.

Mesh Expectations

Mesh means reachability and coordination across machines. It does not mean exactly-once delivery, replicated external transcripts, or global consensus.

An integration should treat a remote Scout agent as reachable through broker routing when the broker says it has a route. It should still report delivery failures and waiting states honestly.

Compatibility Checklist

Before calling an integration "Scout-native", verify:

• it has a stable agent identity
• it registers or attaches a reachable endpoint
• it has deterministic session start/attach/inspect semantics
• it can receive a message
• it can receive an ask and produce a flight result
• it can reply without losing the original actor/conversation context
• it reports failed and waiting states
• it reports harness/session mismatches with actionable diagnostics
• it guides senders with broker diagnostics instead of only returning opaque unresolved/unavailable errors
• it does not require body mentions for normal routing
• it does not import external transcripts as Scout messages
• it documents its permission and wake behavior
• it can recover or explain state after broker/session restart
• it reports token usage or marked estimates when available