* Agents can show local images in chat: show_image, and Markdown images in replies
show_image {path} (Zeron MCP) copies a PNG/JPEG/WebP/GIF into uploads and
publishes the image part Codex's generated images use, so every client
already renders it and it outlives the file.
An agent reply's  now draws the image in place, read live by the
chat's host through ReadChatImageChunk: strictly inside that chat's folder,
no link followed, no URL fetched, extension and bytes checked, decoded within
the shared raster limits. Anything refused keeps today's link.
* Chat image folder tests: refuse the filesystem root portably
On Windows `/` isn't absolute, so it was refused as "not an absolute
path" instead of as the root. Test the root of the temp dir's own path
(`/`, or a drive like `C:\`) instead.
* Retrigger CI: cursor_shim frame timeout on the Windows runner
* Reply images: right-click copies the original, and narrow columns scale them whole
Rebased onto main (Origin's new side_chats_only in the show_image test).
- A Markdown image in a reply now opens the shared Copy path / Copy image
menu, like generated images and tool previews. Copy image reads the
original through ReadChatImageChunk under that chat's jail, not the wider
ReadAttachmentChunk, and not the downscaled preview.
- The image row keeps its aspect ratio when the column is narrower than the
image, instead of keeping its height and letterboxing.
- docs/image-preview.md: the menu, the sizing, and what the cache means for a
Markdown image whose file changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
---------
Co-authored-by: Wing <44917547+wingleeio@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
26 KiB
Zeron MCP server
zeron mcp serves the Model Context Protocol on stdin/stdout and proxies every
tool into the running engine's localhost IPC (ws://127.0.0.1:$ZERON_IPC_PORT,
default 27654) — the same zeron_rpc surface the headed app and zeron sync
dial. It is a subcommand of the one zeron binary: no Node runtime, no extra
install, a few MB resident.
Crate: crates/mcp (zeron-mcp). The protocol layer is hand-rolled
(initialize, ping, tools/list, tools/call; newline-delimited JSON-RPC
2.0) — the repo already owns JSON-RPC framing for the Codex and ACP drivers and
the stdio tool-server subset is tiny, so no SDK dependency was taken.
Identity
The engine can inject this server into a harness's MCP config with the originating chat in the environment:
| Variable | Meaning |
|---|---|
ZERON_IPC_PORT |
Engine to proxy (default 27654). |
ZERON_IPC_TOKEN_FILE |
The engine's IPC bearer file (see below). |
ZERON_CHAT_ID |
The chat whose agent spawned this server. |
ZERON_DEVICE_ID |
That chat's host device. |
ZERON_SIDE_CHATS_ONLY |
1: the agent has no subagent tools of its own (below). |
ZERON_SIDE_CHATS_ONLY=1: the host device turned the provider's native
subagents off (Settings → Providers), so initialize tells the agent to
delegate with create_chats. Never set for a chat that has a parent, nor
for one whose host doesn't know its parent yet.
IPC authentication
The IPC port is loopback-only, but loopback is not an identity: any local
process could otherwise drive the engine (start agents, broker Cloud vault
grants). Every engine start that binds the port mints a fresh 32-byte token
and writes it to {data_dir}/ipc-token (owner-only 0600, atomic replace;
on Windows the file inherits %LOCALAPPDATA%\Zeron's per-user ACL). The
WebSocket handshake must carry Authorization: Bearer <token> (compared in
constant time) and is refused with 401 otherwise; the browser Origin
rejection (403) still applies on top. In-process (in-memory) transports are
unaffected.
Clients resolve the token at every dial — $ZERON_IPC_TOKEN, then the file
named by $ZERON_IPC_TOKEN_FILE, then {ZERON_DATA_DIR or ~/.zeron}/ipc-token
(zeron_rpc::connect_ipc) — so they follow the rotation across engine
restarts. The engine hands injected servers the file PATH
(ZERON_IPC_TOKEN_FILE), never the token itself: Claude receives this env on
its command line (--mcp-config <inline json>), which other local users can
read with ps. A client run against a different data dir (e.g. a viewport on
a daemon's port) sets ZERON_IPC_TOKEN_FILE to the daemon's file.
When ZERON_CHAT_ID is set, every send_message is prefixed with a
[Message from Zeron chat <title> (<id8>) …] line so the receiving agent and the
human reading that transcript can tell an agent-to-agent message from a typed
one, and the server refuses to message its own chat. The transcript renders
this routing header as “Message from chat name”, keeping the full routing
instructions in the stored prompt for agents.
Parent links
create_chat and each request in create_chats accept kind:
| Input | Placement |
|---|---|
kind: "chat" |
Standalone session, visible in the left Sessions sidebar; no parentChatId is written. |
kind: "side" |
Child of the explicit parent or origin chat. Requires one of those. |
| Kind omitted, origin or parent supplied | Child, preserving the previous default. |
| Kind omitted, no origin or parent | Standalone, preserving terminal usage. |
kind: "chat" with a nonempty parent, kind: "side" without an origin/parent,
and unknown kinds fail before any writes. Empty parent uses the default.
The creation result includes the effective kind, chatId, deviceId,
project and parentChatId. Kind is derived from the parent; it is not persisted.
Children record Chat.parent_chat_id (proto) ⇄ parentChatId on the registry
row (Mutate createChat { parentChatId? }). Any chat may delegate to any provider.
Delegation is one level deep: a chat that has a parent creates no chats at all,
and a new chat's parent (the origin, or an explicit parent) must be top-level.
Standalone sessions have no parent.
cloud: true runs the child on a Cloud machine of its own (Codex or Claude
Code), cloning the project's GitHub repository; from a Cloud chat, the parent's
repository. Without it, a child of a Cloud chat shares the parent's machine. A
Cloud machine starts children only for the chat it runs, and sees and manages
only those children (docs/design/cloud-device.md, "Delegation").
For children, parent (id, prefix, or title) overrides the origin (ZERON_CHAT_ID).
list_chats { parent } returns children, and chat summaries carry parentChatId.
Rows from older engines read as parentless; a dangling parent id is tolerated.
The left sidebar hides chats that have a parent: AppState::visible_chats
(the Sessions list, project tabs, jump slots) and the Archived section both
require parent_chat_id == None. Children remain addressable by id, deep
link, and every MCP tool; list_chats { parent } is how an orchestrator
finds them.
Injection
The host engine stamps this server onto every run it drives
(RunRequest.mcp, additive): the same zeron binary with args: ["mcp"]
and the variables above, pointed at the port the engine itself serves
(never a port it lost the bind race for). Each driver spells it in its own
dialect and leaves the user's configured servers alone:
| Harness | Where |
|---|---|
| Claude | --mcp-config <inline json> (no --strict-mcp-config) |
| ACP (Devin, Grok, Hermes, Antigravity) | session/new and session/load → mcpServers: [{name, command, args, env}] |
| Pi | Per-run --extension bridges stdio MCP into Pi tools in the native RPC process |
| OpenCode | Child-only OPENCODE_CONFIG_CONTENT: mcp.zeron on 1.x, mcp.servers.zeron on 2.x |
| Codex | thread/start config overrides mcp_servers.zeron.{command,args,env} |
| Cursor | SDK Agent.create / Agent.resume → inline mcpServers.zeron, plus local.settingSources: ["user", "team", "mdm", "plugins"] so ~/.cursor/mcp.json and plugin servers load (not project: the SDK skips MCP approvals, so repo-defined servers would run unprompted) |
OpenCode preserves inherited inline configuration and other servers. Its config
shape follows the installed binary's major version. Cursor uses the SDK's
inline MCP configuration; OpenCode's
1.x config layer and
2.x MCP format differ.
Pi's temporary extension lives only for the native RPC process lifetime;
user settings, extensions, and session arguments remain intact. The bridge
registers zeron_<tool> tools, propagates cancellation and errors, and closes
the MCP child when the Pi session shuts down.
Title runs never carry it. A run with no served port (embedded engine that lost the bind) gets no Zeron tools rather than a dead server.
Forks and the session card
ForkSideChat { chatId, sourceChatId, parentChatId? } copies a chat's
history through its latest completed response into a new chat and appends
a fork part (a system entry: sourceChatId, sourceTitle) as the seam;
the transcript draws it as "This chat was forked from