Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
A2A — Agent-to-Agent interoperability
MSO implements A2A v1 beside MCP. MCP remains the host tool/data control plane; A2A is the interoperability boundary for delegating an explicit task to another agent or, when the owner opts in, allowing another authenticated agent to delegate a bounded task to MSO.
The implementation has four independent pieces:
Inbound task streams close at terminal state, credential revocation, client disconnect or a five-minute deadline. Admission is bounded to eight streams per profile and sixty-four per process; queued events are bounded too. Resubscribe with valid credentials for a still-running task after the deadline. Revocation closes existing streams as well as refusing new requests.
- Outbound discovery/registry — discover public HTTPS Agent Cards and keep sanitized peer metadata locally.
- Outbound credentials + client — attach a private API-key, Bearer, or OAuth2 access-token profile to a peer and call it over JSON-RPC or HTTP+JSON.
- Streaming — use A2A v1
SendStreamingMessage/ SSE and keep task lifetime independent from an individual stream connection. - Authenticated inbound MSO — optionally publish MSO's Agent Card and JSON-RPC endpoint, guarded by owner-minted
read,write, orexecbearer capabilities.
Public inbound serving is active only when a valid explicit HTTPS OS_PUBLIC_ORIGIN exists; OS_A2A_INBOUND_ENABLED=0 is the kill switch. Without a public HTTPS origin, no public A2A endpoint is advertised.
Trust model
A remote agent is a separate trust domain. MSO keeps that boundary explicit:
- Agent discovery uses
/.well-known/agent-card.jsonand accepts only public HTTPS Agent Card/interface URLs. - Outbound HTTP reuses MSO's SSRF guard: public-address validation, DNS re-resolution with resolved-IP pinning, redirect refusal, and rejection of loopback/private/link-local/metadata targets.
- Exact-loopback discovery additionally requires the current caller to hold
execauthority at card discovery, selected-interface resolution, refresh and credential materialization, even when the deployment enables loopback transport. - Outbound authentication values are removed from returned JSON/SSE keys and values, protocol errors and transport errors if a peer reflects them.
- Remote JSON responses and SSE events are bounded. Normal message text is limited to 24 KiB.
~/.mso/private/a2a-agents.jsonstores sanitized public Agent Card metadata and a local credential-profile pointer, never a secret.- Outbound credential secrets live separately in
~/.mso/private/a2a-credentials.jsonunder owner-only0700/0600storage. List/state APIs return summaries only. - An inbound bearer is shown once when minted. MSO persists only its SHA-256 hash in
~/.mso/private/a2a-inbound-tokens.jsonand compares candidates in constant time. - Inbound task records use
~/.mso/private/a2a-tasks.json, are bounded/rotated, and store only explicit A2A messages, task metadata, status, and result artifacts. - One inbound credential cannot read, cancel, subscribe to, or continue a task owned by another credential.
- Each inbound task also has its own MSO workflow actor, so concurrent tasks from the same peer cannot finish/cancel/status each other's active workflow.
Context and memory isolation
Inbound A2A does not call the normal owner Alfa endpoint. Both surfaces share one provider/model transport, but only the owner assistant performs MSO memory recall.
An inbound A2A turn receives:
- the explicit A2A message for that task;
- the exact
read/write/execcapability assigned to that bearer; - results returned by tools visible at that capability.
It does not receive owner memory, hidden MSO transcript history, raw owner session IDs, owner tool state, or an implicit user profile. The agent_session_* and durable agent_memory_* tool families are removed from the inbound model's tool catalog even for an exec credential.
Outbound handoff follows the same explicit-context rule: objective/context supplied by the caller plus bounded correlation metadata only. Hidden history/memory is not copied to the remote peer.
Permission semantics
Outbound operations initiated through normal MSO CLI/MCP keep the existing owner permission model: registry writes require write; remote execution/cancel/handoff requires exec and therefore follows ask / auto-write / yolo exactly as before.
Inbound is different by design: minting the bearer is the owner's approval boundary. A remote request cannot pause on an interactive ask prompt, so the bearer itself is a delegated capability:
| Inbound scope | Remote agent can use |
|---|---|
read |
read-only MSO tools |
write |
read + write tools; no exec tools |
exec |
read + write + exec tools, except explicitly blocked owner-memory/session families |
Start peers at read. Promote to write or exec only when that remote agent should be allowed to mutate or execute on the host. A scope is enforced both when model-visible tools are selected and again by MCP dispatch.
Enable the inbound server
Public inbound is enabled by default whenever an explicit HTTPS public origin exists. OS_A2A_INBOUND_ENABLED=0 is the kill switch:
OS_A2A_INBOUND_ENABLED=1
OS_PUBLIC_ORIGIN=https://mso.example.com
After rebuild/restart, MSO publishes:
https://mso.example.com/.well-known/agent-card.json
https://mso.example.com/a2a/v1
The Agent Card is public discovery metadata. Protocol calls to /a2a/v1 require HTTP Authorization: Bearer ... before any A2A method is dispatched.
Mint a credential:
mso a2a inbound create research-agent read
The raw mso_a2a_... token is returned once. Copy it into the remote agent's credential store, then discard the plaintext from terminal notes/history as appropriate. Later:
mso a2a inbound list
mso a2a inbound rm <tokenId>
The Settings → A2A panel exposes the same flow, shows the one-time token once, lists/revokes inbound profiles, and surfaces bounded task/audit activity.
A2A skill — provider-neutral workflow trace
The official a2a Agent Skill also exposes an owner-authenticated workflow trace bridge for AI runtimes that are doing work locally through Codex CLI, Claude/Cloud CLI, Antigravity, or another Agent Skills-compatible CLI.
This is intentionally separate from A2A protocol message streaming. Remote A2A remains a trust-domain boundary and does not inherit owner memory. The trace bridge runs only through the normal authenticated MSO owner CLI/MCP session and records concise observable milestones into one durable agent session plus one exact MSO workflow.
Native MCP-capable agents should use workflow_start, agent_session_note, agent_session_flow, and workflow_finish directly. Shell-capable agents can use:
mso a2a trace start --intent "Implement the requested feature" --project my-project --agent codex
mso a2a trace progress --run <run-id> --stage implement --message "Bounded implementation is complete."
mso a2a trace evidence --run <run-id> --stage verify --message "Targeted tests passed."
mso a2a trace context --run <run-id>
mso a2a trace finish --run <run-id> --summary "Implemented and verified." --evidence @evidence.json
The bridge returns the durable session_id, exact workflow_id, a local run_id, and the isolated workspace when MSO created one. The same workflow id is attached to every milestone call, so semantic session flow and workflow receipts remain correlated for later agents.
Allowed trace kinds are plan, progress, action, evidence, blocker, result, and handoff. They are summaries of observable work only. Hidden chain-of-thought, private reasoning, system/developer prompts, complete transcripts, credentials, cookies, and tokens must never be sent as trace events.
Local correlation state lives under ~/.mso/private/a2a-traces with owner-only permissions and contains identifiers/status only. It does not grant access to sessions from another MSO device/principal. workflow_finish still enforces the normal Evidence Receipt rules; streamed progress is context, not verification proof.
Relationship to Workflow and Organization
A2A is a transport boundary, not MSO's visual orchestration graph and not its organization chart.
- Workflow Graph owns repeatable automation topology: triggers, If/Switch, Merge, Loop Over Items, bounded Repeat Until, Execute Workflow/subflow, retry/error routing, and run receipts.
- Organization owns stable unit/seat identity, reporting lines, and the pointer from a seat to its current Project Agent, Local Agent, or remote A2A executor.
- A2A owns discovery, authentication, message/task lifecycle, streaming, cancellation, and the remote trust boundary.
A Workflow agent node may target an orgSeatId. If that seat currently maps to an A2A peer, runtime resolution reaches the existing a2a_handoff path; the saved graph pins the reviewed seat target digest. Changing a shared execution target requires exec; a graph whose target later changes refuses dispatch until explicitly reviewed and saved again. Legacy seat-bound graphs without a digest also require review and resave. Likewise, a saved Session workflow can be called through Execute Workflow or bounded Repeat Until without turning A2A itself into a loop engine. This separation keeps transport credentials and remote task state out of portable workflow definitions and organization metadata.
See Workflow Graph and Organization.
Same-host sessions are native Local Agents, not remote A2A
MSO 1.9 separates live same-host session communication from this remote interoperability protocol. /agents, /message, local /delegate, local inbox delivery, and the local_agent_* MCP tools use a private presence lease + durable mailbox + SSE/event-bus layer. They require no Agent Card, URL, registration, credential, refresh, or restart when another session appears or is renamed.
See Local Agents for lifecycle (ready / idle / busy / offline / ended), short @name handles, foreground receiver observability, durable standby, delivery statuses, storage, TUI commands, tools, and API.
Durable Local Agent standby does not create a second orchestration engine. Once a structured local request is safely claimed, MSO executes it through the same bounded durable-session/A2A task machinery already used by local_agent_request; only the host-local mailbox/listener/claim layer is new. Public A2A keeps its own standard authenticated task lifecycle and trust boundary, but both paths converge on the existing bounded agent execution semantics rather than duplicating a model runtime.
The older mso a2a local ... and loopback virtual-card helpers remain as compatibility/protocol-testing surfaces for one-shot local delegation. They are not the native live-session transport. OS_A2A_ALLOW_LOOPBACK=1 explicitly enables those legacy A2A-over-loopback paths for trusted same-host agents; Local Agents do not require it.
Outbound peers and credentials
Discover/register peers:
mso a2a discover https://agent.example
mso a2a add https://agent.example research
mso a2a list
mso a2a state
Anonymous peers continue to work without a credential. For an authenticated peer:
# interactively prompts for the secret; it is not placed in curl/jq argv
mso a2a auth add research prod bearer
mso a2a auth add research prod-api api-key
mso a2a auth add research oauth-access oauth2
mso a2a auth list research
mso a2a auth use research <credentialId>
mso a2a auth use research none
mso a2a auth rm <credentialId>
MSO sanitizes and stores the public Agent Card security-scheme metadata beside the peer, then binds each credential profile to one declared scheme. Header API-key profiles inherit the exact header name from the Agent Card; HTTP Bearer uses Authorization: Bearer; OAuth2/OIDC profiles use an already acquired access token. MSO 1.8 fails closed for query/cookie API keys, HTTP Basic or other non-Bearer HTTP auth, mTLS, and requirements that need multiple simultaneous schemes. It also does not silently initiate a third-party browser authorization-code flow; a future release can add per-scheme token acquisition/rotation without changing the private profile model.
Credentials are applied at the HTTP transport layer, never inserted into the A2A message payload or Agent Card registry.
Messages, tasks, and streaming
mso a2a send research "Find the latest implementation notes"
mso a2a send research "Do the work" --wait
mso a2a stream research "Do the work and stream progress"
mso a2a task research <taskId>
mso a2a cancel research <taskId>
mso a2a handoff research "Compare the two approaches" "Use these criteria only"
mso a2a rm research
Outbound supports A2A v1:
- JSON-RPC —
SendMessage,SendStreamingMessage,GetTask,CancelTask. - HTTP+JSON —
message:send,message:stream, task read/cancel routes.
The inbound MSO JSON-RPC surface implements:
SendMessageSendStreamingMessageGetTaskListTaskswith bounded pagination tokensCancelTaskSubscribeToTask
Streaming responses use text/event-stream. A SendStreamingMessage begins with the Task, emits status/artifact updates, and ends at a terminal task state. Disconnecting an observer unsubscribes that stream; it does not cancel the task. CancelTask is the explicit cancellation operation.
Inbound task execution is rate-limited by both source IP and bearer profile, and request bodies/results are bounded.
Interactive Agent and MCP
Inside interactive MSO Agent, /agents renders Local session agents and Remote A2A v1 peers as separate groups. /delegate <target> <objective> sends a native local task when a local session matches, then falls back to the explicit remote A2A handoff boundary only when no local target exists. /message is local-only. See Local Agents.
Remote A2A/delegate/handoff intent still loads the A2A tools on demand instead of keeping them in every model turn. The provider-neutral remote A2A MCP catalog remains intentionally generic:
| Tool | Scope | Purpose |
|---|---|---|
a2a_agents_list |
read | List registered public peers |
a2a_agent_discover |
read | Validate/discover a public v1 Agent Card |
a2a_agent_register |
write | Register/refresh public Agent Card metadata |
a2a_agent_remove |
write | Remove local registry metadata |
a2a_message_send |
exec | Send one explicit A2A message |
a2a_task_get |
read | Read a remote A2A task |
a2a_task_cancel |
exec | Request remote task cancellation |
a2a_handoff |
exec | Delegate an explicit objective/context |
Registering a peer does not create dynamic MCP tool names. The target stays data (alias/id/Agent Card URL), keeping the tool schema stable as the peer set changes.
Storage and environment overrides
Defaults:
OS_A2A_STORE=~/.mso/private/a2a-agents.json
OS_A2A_CREDENTIAL_STORE=~/.mso/private/a2a-credentials.json
OS_A2A_INBOUND_TOKEN_STORE=~/.mso/private/a2a-inbound-tokens.json
OS_A2A_TASK_STORE=~/.mso/private/a2a-tasks.json
Private A2A state uses owner-only directories/files, no-follow reads, ownership checks, bounded file size, security-store locking, and atomic replacement.
Deliberately not implicit
This release does not:
- enable inbound serving by default;
- derive an inbound public origin from an untrusted request host;
- expose an unauthenticated execution endpoint;
- copy owner memory/session state into inbound or outbound handoffs;
- let
writecredentials callexectools; - automatically run a remote OAuth browser flow;
- emulate unsupported query/cookie API keys, HTTP Basic, or mTLS;
- enable A2A push callbacks or gRPC.
Those surfaces should be added only with explicit callback validation, credential rotation/revocation UX, and equivalent regression coverage.
Official protocol reference: https://a2a-protocol.org/latest/.