Repository navigation
Harnesses
Kabmo can run a chat on more than omp. The agent behind a session is its harness, and it is a first-class idea: it appears in the composer's model dropdown as a tab, beside the session name in the sidebar, and as a section in Settings.
The full measured design — every capability per agent, the frame mapper, the
data model, the build order — lives in docs/milestones/M17-harnesses-design.md
and docs/milestones/M16-harnesses-research.md.
This page is the map of how the shipped code is arranged, and why.
| Harness | Transport | Why |
|---|---|---|
omp |
RPC --mode rpc-ui (unchanged) |
the DEFAULT. The only path that reports todos, subagents, host tools, stats and compaction |
omp-acp |
ACP over stdio (omp acp) |
a second tab for the same agent: it proves the adapter against a known agent, and gives a slimmer surface |
opencode |
ACP over stdio (opencode acp) |
the 1.x CLI: measured 102 models |
opencode2 |
— |
retired. The 2.x preview is now a 47-byte shim that execs opencode: measured on this machine, both report v2.2.5 and the shim's body is exec "$(dirname "$0")/opencode" "$@". One binary means one tab, not two. |
command-code |
ACP over stdio (cmd acp) |
Command Code's own agent. Measured: 0.77 s handshake, 43 ms session/new, 96 models · 4 thought levels, list/resume/close advertised. Needs cmd login; todos are off until cmd mods enable todos -g
|
antigravity |
ACP over stdio (agy acp) |
Google's agent, replacing the retired gemini. Sign in once with agy (or agy acp --login); one process serves one project |
zcode |
ACP over stdio (zcode-acp-server) |
Z.ai's agent. The vendor CLI has no acp subcommand, so the launch line is the community bridge that spawns zcode app-server --stdio. Measured through Kabmo's own client on 0.82.3: 1 model · 3 thought levels · 5 modes, list/resume/fork advertised, steering supported. A chat needs a ZCode runtime: the desktop app, or zcode-app-cli on PATH (ZCODE_BIN for a custom install). Custom providers live in ~/.zcode/v2/provider_config.json; ZCODE_BIN/ZCODE_HOME still decide which install and data root the bridge drives |
grok |
ACP over stdio (grok agent stdio) |
xAI's Grok Build CLI. It ships its own ACP server (grok agent stdio), driven without --always-approve so tool approvals still arrive as session/request_permission and Kabmo's access tiers decide. Measured on 1.0.77: loadSession: true, sessionCapabilities list/resume/close, mcpCapabilities stdio+http+sse, authMethods: grok.com (a signed-out handshake answers session/new with "Authentication required"). Sessions return standard configOptions plus a models block (currentModelId + availableModels). grok login is needed once for xAI's own models, while a BYOK [model.<name>] table in ~/.grok/config.toml (base_url + api_key) runs without a login — measured end to end: currentModelId: "kenari", prompt returned end_turn on deepseek-v4-1-flash (11 787 in / 3 out) with text hello. By contrast, GROK_MODELS_BASE_URL + XAI_API_KEY alone still answered "Not signed in" |
jcode |
ACP over stdio (jcode acp) |
The Rust agent from jcode.sh ships its own ACP adapter (src/cli/acp.rs), backed by the Jcode daemon; session/load and session/resume are implemented, session/fork is not. Configure a provider once in ~/.jcode/config.toml (jcode provider add …; API keys go to ~/Library/Application Support/jcode/ on macOS, ~/.config/jcode/ on Linux) |
hermes |
ACP over stdio (hermes acp) |
Nous Research's Hermes Agent ships the adapter in-tree (acp_adapter/), but the stock install does not include it: the acp extra must be synced once (cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)"), which is what enables hermes acp and hermes-acp. The adapter logs to stderr and reserves stdout for JSON-RPC. Its initialize advertises loadSession: true, image prompts, and sessionCapabilities list/resume/fork; fork_session(cwd, session_id) takes no anchor, so the fork is whole-chat. Providers live in ~/.hermes/config.yaml (providers.<name> → api, api_key or key_env, transport, models), written by hermes model and its dashboard — Kabmo reads that table, never writes it |
omo |
ACP over stdio (pi-acp) |
Oh My OpenAgent's standalone omo command. The CLI ships no ACP server (measured against 5.1.x: no acp subcommand), so the launch line is the pi-acp adapter with PI_ACP_PI_COMMAND=omo; OmO Native is a senpi (pi fork) engine, so the adapter's --mode rpc surface applies. Measured through Kabmo's own client on 5.1.9: initialize + session/new answered, 69 models · 3 thought levels, list/delete advertised. Providers live in ~/.omo/agent/models.json (same providers.<id> shape as pi); run omo setup (or /login) once before a turn succeeds |
| every other | ACP over stdio | measured: all of them ship it, so one adapter covers them all |
gemini is gone; antigravity holds its slot. Google deprecated Gemini CLI
in favour of Antigravity CLI, and the two are one product line's ancestor and
successor — listing both would offer a dead agent beside its replacement and
split one Google account across two tabs. The harness COUNT did not grow: exactly
one Google adapter is advertised, asserted by catalog.test.ts.
Standard ACP has no fork point: ForkSessionRequest carries only
sessionId/cwd/mcpServers/additionalDirectories/configOptions/systemPrompt,
and the session-fork RFD lists a message id as a future extension. Two
JetBrains-maintained adapters implement it today as the AIR extension
_meta.jetbrains.air.fork = {version: 1, messageId} (gate: none). Everything
else forks the whole session, so Kabmo refuses an anchored request there
(anchor_unsupported) instead of silently handing back the tip.
| Harness | session/fork |
Fork point | Transcript store | Kabmo path |
|---|---|---|---|---|
omp-rpc / omp-acp
|
yes (omp-acp 18.18.8) | any turn | ~/.omp/agent/sessions/<project>/<ts>_<id>.jsonl |
file cut (cutIndexFor + buildTruncatedBody) |
claude |
yes (0.106.0) | assistant message |
~/.claude/projects/<slug>/<session-id>.jsonl (parentUuid chain, sidechains) |
AIR _meta |
codex |
yes (adapter advertises fork: {}) |
the turn holding the message |
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl (session_meta + items) |
AIR _meta |
opencode |
yes (1.19.5) |
REST only: session.fork {before|through}; the ACP adapter calls it with no boundary |
SQLite ~/.local/share/opencode/opencode.db (session/message/part) |
whole over ACP; an anchor would need the REST server, which Kabmo does not run |
zcode |
yes (0.83.3) |
target: {kind: "latestCheckpoint"} only |
~/.zcode/cli/db/db.sqlite + rollout/model-io-*.jsonl
|
whole / latest checkpoint |
minimax |
yes | runtime has assistantDisplayMessageId; the ACP handler passes none |
~/.minimax/v2/sqlite/runtime-state.sqlite |
whole over ACP |
kimi |
no — ACP fork_session raises NotImplementedError
|
CLI-only file fork (wire.jsonl/context.jsonl truncated at a turn index) |
~/.kimi/.../wire.jsonl |
none over ACP |
qwen |
no session/fork in the ACP agent (only subagent forks) |
— | ~/.qwen/sessions |
none |
dsh |
no (measured: close/list/resume only) |
— | ~/.dsh/sessions/<project>/<id>/session.v4.jsonl.zstd |
none |
antigravity |
no (measured 1.5.3: forkSession: false) |
— | not inspected | none |
pi |
no (probe blocked; research: list/delete only) |
— | ~/.pi/agent |
none |
command-code |
no (research: list/resume/close) |
— | not inspected | none |
cursor |
unknown (closed source, not installed) | — | ~/.cursor/projects |
none |
jcode |
no — ACP server implements load/resume only |
— | not inspected | none |
grok |
no (measured 1.0.77: sessionCapabilities = list/resume/close, no fork; the CLI has an x.ai/session/fork extension) |
— |
~/.grok/ session store |
none |
hermes |
yes — advertises SessionForkCapabilities(), and fork_session(cwd, session_id) takes no message id |
— | its own session DB (SessionDB under ~/.hermes/) |
whole over ACP |
omo |
no (pi-acp advertises list/delete only) |
— | ~/.omo/agent/sessions |
none |
File surgery on claude/codex is possible in principle — both stores are JSONL —
but the adapters' own fork reads the same store and handles sidechains/turns, so
a second implementation would drift. kimi is the one agent whose CLI fork IS
file surgery (turn-index truncation), but its ACP surface does not expose it.
The button follows the same fact. forkCapability(harness)
(shared/lib/harness/fork.ts) is the one model: message (omp, claude, codex),
tip (opencode, minimax, zcode) or none (qwen, dsh, antigravity, pi,
command-code, jcode, grok, omo). canForkAt(harness, role) gates the row's Fork control — omp on
a user turn and on the run footer, claude/codex on the run footer only, and
tip/none on neither. The whole-chat fork is the session menu's Fork chat
(canForkChat, probe-authoritative: an agent that does not advertise
session/fork gets no item), which opens the same pending composer with no
anchor — that is the only fork entry point for a tip harness. MessageList
passes the session's harness down to ChatMessageItem and RunFooter, so the
control cannot appear on a row the send path would refuse
(anchor_unsupported).
omp over RPC is the default and is not a CHOICE, so catalog.ts marks it
builtIn: true. Three surfaces read that flag:
- Settings → Harnesses leaves it out (there is nothing to install or configure);
- the composer's tab strip never treats it as blocked — see below;
-
/api/harnessREFUSES to probe it, and reportsbuiltIn, so no probe record can ever exist for it.
It stays in the CATALOG — a session row still has to name the transport that ran it — and it stays in the tab strip, which names the list on screen.
A probe must never mark the default harness blocked. Before the guard, a
?probe=omp-rpc produced the only answer probeHarness has for a harness with
no launch line — capabilities.blocked: "No launch command is configured for this harness" — cached it for 30 minutes, and the tab strip reads blocked as both a
⚠ AND disabled. Measured: the omp tab rendered omp⚠ with
disabled="true", so the harness every session actually runs on could not be
selected. The flag is now honoured in the route (no probe record, and probing it
answers 400 builtin_not_probeable) AND in the client
(harnessBlockedReason returns null for a built-in, so a cache written by an
older build cannot resurrect the mark).
The RPC path is untouched. Adding harnesses did not generalise omp's RPC mode into an abstraction; the ACP adapter is a second driver behind the same per-session seam.
| Concern | Module |
|---|---|
| the catalog (ids, labels, glyphs, transport) | src/shared/lib/harness/catalog.ts |
| brand colours for the marks | src/shared/lib/harness/brand-color.ts |
| the mark itself | src/client/components/common/harness-glyph/ |
| which models a tab shows | src/client/components/workspace/model-dropdown/harness-models.ts |
| the tab strip | src/client/components/workspace/model-dropdown/HarnessTabs.tsx |
| the picker's measured size | src/client/components/workspace/model-dropdown/popover-metrics.ts |
| the phone placement | src/client/components/workspace/model-dropdown/Fullscreen.tsx |
| launch table + session spawn |
src/server/lib/harness/launch.ts, spawn.server.ts
|
| capability model | src/server/lib/harness/capabilities.ts |
| the ACP client | src/server/lib/harness/acp/ |
| the open chat's harness + the pending pick | src/client/hooks/chat/timeline/session-harness.ts |
| the harness a spawn answered (before the sidebar row) | src/client/hooks/chat/timeline/spawn-harness.ts |
| the mark on a run (indicator + answer footer) | src/client/components/workspace/chat-timeline/RunMark.tsx |
| discovery + probe route | src/server/routes/harness/root.ts |
| availability, the config-aware probe, the boot pass | src/server/lib/harness/auto-probe.server.ts |
| which parts an update moves (pure) | src/shared/lib/harness/update-plan.ts |
| the background job: start, record, settle, repoint |
src/server/lib/harness/update-job.server.ts, update-job-store.ts, update-worker.ts
|
| the record's wire shape + guard |
src/shared/types/harness-update.ts, src/shared/lib/harness/update-job.ts
|
| the dialog's start-and-follow hook | src/client/hooks/models/use-harness-update.ts |
| the shared catalog store + its one read | src/client/hooks/models/harness-catalog.ts |
the useHarnesses() controller |
src/client/hooks/models/use-harnesses.ts |
| registry writes, in refresh order | src/server/lib/models/registry-refresh.server.ts |
| which harnesses read a registry file |
harnessesSharingRegistry in src/server/lib/harness/provider-sources.server.ts
|
| Settings → Harnesses | src/client/components/settings/categories/HarnessSettings.tsx |
omp's list is Kabmo's /api/models (omp's registry, with favorites, recents
and provider plates), returned untouched. Every other harness replaces
it with its own configOptions[model]. A merge would offer rows the active
agent cannot run, which fail at the first prompt; and an unprobed harness
reports unprobed rather than showing omp's list as a stand-in.
A LIVE chat outranks the probe. There are three sources, ranked:
omp-rpc → /api/models; an ACP harness with an open session → the selectors
that session itself published (get_state → configOptions, served on
/api/chat/:id as harness + liveModels); an ACP harness with no session →
its probe. A probe is one throwaway spawn and can be REFUSED while the running
chat lists models — measured with codex: the probe answered "Authentication
required" beside rows the chat was already offering. The loader publishes the
live lists once per session read (publishLiveModels guards a no-op update),
and harnessModels(..., live) reads them first, so no "Authentication
required" banner sits beside a usable list.
Measured sizes: omp 221, omp (ACP) 221, claude 5 (default, opus,
claude-fable-5[1m], sonnet, haiku), opencode 102, dsh 1.
Before liveModels, an ACP harness's JSONL branch returned without the live
fields at all: the picker could only ever show a probe snapshot, and the
composer named the file's last model instead of the one in force.
Pinned by harness-models.test.ts (the merge is refused, the omp list survives
identically, a live chat outranks a refused probe, an unprobed harness yields
unprobed) and session-load.test.ts (a session payload publishes its live
lists to the harness store).
popover-metrics.ts computes the box from the trigger's own rect, the space
above it, and the visual viewport. A constant width is what makes a picker look
right at 1440px and clip at 900px. popover-metrics.test.ts pins the cases that
matter: a short window shrinks the height before the width, a narrow panel
shrinks the width, and the box never exceeds the trigger's panel.
fullscreen-picker.ts decides. The shell's own isMobile verdict wins when the
picker is given one (App.tsx already answered it from the user agent, the
pointer and a landscape-phone height test); otherwise it reads
(pointer: coarse) first and width second — a 900px touch window is still a
phone surface, a 600px mouse window is still a desktop.
Fullscreen.tsx renders the SAME card content as a 100dvh overlay and
portals to <body>, for the reason the composer rule states: the composer
card can become a containing block for position: fixed through
backdrop-filter, transform or contain: layout.
The sheet that came first is gone, and the measurements are why: on a 390x844
phone an 86dvh sheet showed ~7 model rows and left 344px of dead canvas above
it; the full screen shows ~18. The full screen also drops the popover's
keyboard-hint footer (↑ ↓ navigate, Tab switch agent) — a phone has no
keyboard to press them on.
This is the bug that made a phone picker look broken. A portalled overlay is
outside the picker's containerRef by construction, so an armed
useOnClickOutside sees the press that was meant to trigger a row as an outside
press and closes the picker on mousedown — before click reaches the row.
useOnClickOutside(ref, handler, enabled) now takes an enabled flag and the
picker passes !fullscreen.
Pinned by on-click-outside.test.ts (armed closes on an outside press and
ignores an inside one; disabled listens to neither pointer type) and
placement.test.tsx (the frame portals to <body>, not into the composer).
popover-metrics.ts takes anchorLeft (the trigger's left edge, where the card
starts) and containerRight (the composer card's right edge, read from
[data-composer-style]), with a ResizeObserver on both elements.
Two earlier forms were wrong, each in a different direction:
| Budget | Failure, measured |
|---|---|
| the TRIGGER's width | a 259px chip inside a 712px composer produced a 275px card; every model name rendered Agn…
|
| the PANEL's width | a 437px card hung 29px past a 421px composer — the card starts 13px inside the panel and that overhang was never subtracted |
Desktop caps: 512 x 460. The width went 384 → 512 because the row (two
marks, the name, a context figure, a thinking chip, a star) cut the name at 384;
measured scrollWidth 139 / clientWidth 0. The height went to 620 and came
back to 460 — at 620 the card stood ~14 rows tall on a 1200px window and read as
a panel over the conversation rather than a menu beside it.
Two older measured bugs the pure arithmetic also pins:
- The popover's measured
widthwas applied to the card inside the phone frame, so a 390px frame held a 292px card and every name truncated toA.. -
vhsizing put the last row under the browser chrome;dvhplusenv(safe-area-inset-*)does not.
HarnessGlyph returns null for an unknown harness — but the wrapper span that
owns the 6px gap (mr-1.5) stays behind, shifting every pre-harness and MOCK
row's title right by 6px while the page still looks plausible. So each row
writes {harness && (<span…>)}, in all three layouts: SessionItem (classic),
common/session-row (modern), and mobile-session-sidebar/SessionRow.
The mark reads its id from harness_sessions, the table a spawn writes and
sidebar-data.server.ts reads. Before it existed the field was filled from
DEFAULT_HARNESS_ID for EVERY row, so the mark said omp for a chat that ran on
opencode2 — decoration, not information. Two consequences of that table:
- an ACP chat is now LISTED at all. Its agent writes no session file, so omp's
JSONL discovery cannot see it: the chat existed in the registry and in no list,
and disappeared from the sidebar when its tab closed.
acp-rows.server.tsbuilds those rows from the record, filed by resolving each chat's own cwd to a project root — the same resolution the scan applies. - the merged list is sorted as ONE sequence. Appending the ACP rows after omp's already-sorted bucket put a chat just spawned below 240 older ones, behind "Show more" (measured).
An omp row is persisted too (its resume id lives there), which is why the ACP
listing carries harness <> 'omp-rpc' in its SQL. That is a cheap PRE-FILTER,
not the rule: omp-acp is omp over the Agent Client Protocol — the same binary,
writing the same JSONL store — so its chats are found by the scan and recorded
in this table, and the filter let both through. Measured on a real id
(01a1af9c-…): two sidebar rows, Halo from the scan and Untitled from the
record. One chat, one row is enforced where the two lists MERGE
(sidebar-data.server.ts): a recorded row whose id the scan already listed is
dropped, keeping the scan's row because it carries the real title and
timestamps. That rule holds for any future agent that writes a session file.
The client's placeholder id (__new__<uuid>) is never persisted: it is an alias
in the live registry, not a session, and storing it listed the chat twice.
acpRowsFor used to write a literal title: 'Untitled' for every row it built,
on the argument that an ACP agent publishes no title of its own and inventing one
would put words in its mouth. The argument was right for a chat with no content
and wrong for every chat that has any: measured an hour after a claude chat's
first prompt, its row still read Untitled — while the placeholder row it
replaced (the client's titleHint) had shown the user's own words all along, so
the real row was a visible REGRESSION of the placeholder.
Two sources now, and harness_sessions.title holds whichever arrived:
| Order | Source | Written by |
|---|---|---|
| 1 | the first prompt |
notePromptTitle, from dispatchCommand's prompt case — the ONE place every ACP prompt passes (a new chat's first send, a live send, a queue delivery) |
| 2 | the agent's own title (session_info_update) |
noteAgentTitle (see the note on the turn gate below) |
The DISPLAY rule is the omp row's, unchanged: deriveSessionTitle (shared/lib/omp/session/sidebar.ts) is name → first message → a New Session - <created>
stamp, and sessionTitleFor now calls the same function — two copies of that
precedence is how one row source starts saying Untitled where the other says
the first prompt. The stamp comes from the row's created_at, never new Date(), so a revalidation cannot re-stamp the title.
saveHarnessSessionTitleIfEmpty is the contract that makes a first prompt safe
to record from a path that sees EVERY prompt: a steering message, a retry or a
queued follow-up reaches the same call with its own text and must not rename the
chat. The agent's own title uses the unconditional writer, because it outranks
Kabmo's guess — and the writer's inequality guard keeps an agent that re-sends
the same title from republishing the sidebar's whole structure.
Pinned by harness/session-title.server.test.ts (the two writers, the
empty-title no-op, one publish per change) and the three title cases in
sidebar-data.harness.test.ts, which read the row the sidebar actually draws.
The mark sits between the leading slot and the name, at 12px compact / 13px
touch. Measured geometry in a running build, all three layouts:
slot x=12, gap x=28, mark x=36, title x=54.
Pinned by harness-mark.test.tsx — including the spacer assertion, which is the
one the text-only test missed.
harness_sessions is the sidebar row of an ACP chat, so the delete flow has to
purge it — it only purged Kabmo's own tables. Measured against the delete route:
| Chat | Before | Visible result |
|---|---|---|
opencode (no JSONL) |
404 {"error":"Session not found","code":"not_found"} |
row stayed forever |
omp-acp (JSONL and record) |
200 {"success":true,"fileRemoved":true} |
row came straight back from the record |
| an ARCHIVED ACP chat |
200, and the purge ran archived_sessions before answering |
row returned unarchived — read as "delete undoes Archive" |
purgeSessionData now deletes harness_sessions, harness_goal_state and
harness_usage_state with the other session-keyed rows, and found is true for
an ACP chat that only ever had a record. After the fix the same calls answer
200 and the next sidebar build has no row.
The process half is the harness-AGNOSTIC registry, not getRpcSession: an ACP
session is not an AgentSessionWrapper, so the omp-only lookup answered "nothing
live" for every non-omp chat and the delete removed rows under a running agent.
removeSession now uses getLiveSession — busy → 409 session_busy, idle →
destroyAndWait() before the purge.
Pinned by routes/sessions/delete-acp.test.ts (record-only delete, goal/usage
rows, the archived case, omp-acp not re-listed, busy refusal, idle teardown).
Purging Kabmo's rows is not a deletion for a chat that ran on another agent: the
conversation lives in that agent's store, and the next import (session/list)
copies it straight back. Measured on this machine: bun run dev auto-imported
615 sessions from opencode and dsh; deleting one removed the row and the
next pass restored it. dsh's 337 imported rows had no title, so the sidebar
drew them as New Session - <timestamp> — the "hundreds of New Session rows"
report.
removeSession now asks the agent before any Kabmo row goes
(lib/harness/session-delete.server.ts):
-
Live child first.
deleteAgentSession()returnsfalsewhen the agent advertises nosession/delete, and THROWS on a real failure (it used to log and swallow, which is how a failed delete still answered200). - No live child (an imported row, a closed tab, an exited child): one fresh child per harness, reused for the whole batch — 300 rows on one harness must boot that agent once, not 300 times.
-
dshhas no verb to call. 0.2.2-rc.1 advertisessessionCapabilities.listonly, so its<DSH_HOME|~/.dsh>/sessions/<project>/<id>/directory is removed directly, without spawning it. The project level is scanned rather than re-encoding a cwd the row may no longer have. -
omp-rpc/omp-acpkeep no second copy: the JSONL the purge removes IS the agent's store. -
A refusal is the answer.
502 agent_session_not_removedwith the agent's own words; the row stays, because purging it would only bring it back and the user would believe the chat was gone. -
The purge writes a tombstone.
purgeSessionDatainserts the id intodeleted_sessions(lib/sessions/deleted-sessions.server.ts), and both the import and the sidebar skip it. The agent's store is the source an import copies from, so removing Kabmo's rows alone is not a deletion: measured, a deleted imported row returned on the next pass. The tombstone is durable — it outlives the process, a reload and a second instance — and it is written with the purge rather than by the route, so a future caller cannot skip it.
Pinned by lib/harness/session-delete.server.test.ts (the id on the wire is the
AGENT's, an agent without the verb refuses, the dsh directory goes without a
spawn, omp needs no second store) and the dsh/refusal cases in
routes/sessions/delete-acp.test.ts.
The omp wrapper has always ended its child after a quiet window
(IdleReaper, IDLE_REAP_MS = 10 min). The ACP transport had no clock at all,
and nothing else ends a child it is not actively driving — so an omp acp
spawned for a chat the user had not touched stayed resident indefinitely.
Measured on this machine: omp acp (pid 29716) still alive 3 h 43 m after its
chat's last command, under a server that had been up 20 h.
AcpSession now owns the same IdleReaper (acp/session-idle.ts): start()
arms it after the handshake, every dispatched command and every incoming frame
defers it, and a destroy stops it. A session that is running or parked on an
approval dialog answers false, so the reaper re-arms instead of killing the
question the user is still reading.
One exception is deliberate: a child whose agent cannot session/load is never
reclaimed. resumeRecordedHarnessSession refuses to start a fresh agent under a
chat's id, so reclaiming one would leave a chat that can never take another
prompt. omp-acp is reclaimed regardless of its advertised loadSession
(measured true) because it writes a session file Kabmo resumes over RPC.
Pinned by acp/session-reaper.test.ts (decision + wiring) and smoke-tested
against a real omp acp: idleDestroyMs: 1500 reclaimed the child 1.5 s after
the handshake and isAlive() went false.
Opening a new chat used to pay the agent's boot on the first prompt. omp's RPC
child had a prewarm pool; every ACP agent had none, so picking claude from the
composer's tab strip and typing was followed by a cold spawn.
Two pools now exist (routes/agent/prewarm.ts picks one by harness), and the
client fires the request at the earliest moment each fact is known: the sidebar's
New Session click warms omp, a New Chat card opened from an ACP chat warms THAT
agent, and pending-warmup.ts re-fires when the composer's harness or Plan pick
moves (the server recycles an entry that can no longer serve the request).
The ACP pool warms a process and stops at initialize. Measured on
omp-acp: ~1 ms spawn, ~100 ms initialize, ~80-120 ms session/new. Warming
through session/new was tried and reverted — omp-acp writes its session JSONL
at that moment, Kabmo's sidebar scans that directory, and a warm child nobody
claimed appeared as an empty chat row (measured: the file lands before any
prompt and outlives the child). So the claim adopts the process and the session
that owns it runs the same session/new and config writes a cold spawn does.
Why it can be warmer than omp's pool: omp's modes ride the spawn ENVIRONMENT and
are read once, so an entry whose selection differs is killed. ACP applies model,
thinking, mode and the approval tier after session/new, so ONE warm process
serves any pick. Smoke-tested against a real omp acp with an isolated DB:
prewarm settled in 99 ms with zero session files; startAcpSession with
claimPrewarmed adopted that same child in 89 ms (cold: 208 ms) and landed
mode: plan plus accessMode: yolo on it.
The pool is keyed by harness + cwd, replaces a candidate the operator left (one
pending chat runs one agent), and disposes an unclaimed entry after IDLE_REAP_MS
— restartPrewarmedAcpSessions disposes them on an engine reload/update too.
Pinned by acp/prewarm.test.ts (single adoption, dead child, failed-spawn retry,
sibling replacement, recycle).
About used to answer "which product am I running?" for two products. It now runs
a chat on a dozen agents, so the card carries an Agents strip: one row per
harness, its real state (ready / needs setup / not installed / not probed
from harness/status.ts), and a link to that harness's settings page.
- the rows come from the SAME shared
useHarnesses()store the composer's tab strip and Settings read, so a probe made anywhere appears here with no reload; - a row is a LINK, never an editor — editing lives on the harness's own page, and About is where you learn which page to open;
- the built-in transport gets no row: nothing to install or probe, so listing it would inflate the count with the one entry nobody decides about.
Layout: the sheet went from max-w-[340px] in one column — which could not hold
the strip at all — to 720px, two panes at md (agents on the wide side,
updates and links on a 260px column), scrolling as ONE page so the close control
never sits over a pane still moving. Measured on a 390x844 phone: 358px wide,
743px tall, two 151px columns, scrollable.
Two columns also fixed a truncation: three cells inside a ~380px pane cut
command-code to command-c…, and no label truncates at two.
Pinned by HarnessStrip.test.tsx — the real state per row, the binary named in a
missing-install title, no row and no count for the built-in transport, and a row
opening harness:<id> while the footer opens harness-index.
Every harness page in the Settings drawer carries the agent's OWN logo
(HarnessGlyph, 14px), because the rest of the app already identifies an agent by
its mark — a session row, the composer's tab strip, a model row — and a generic
Waypoints glyph beside the word "claude" asked the reader to learn a second
vocabulary for the same fact.
Two exceptions, both deliberate:
- the overview keeps a lucide glyph. It is not an agent, so a brand mark would claim it were one.
-
the mark sits in a FIXED-WIDTH slot (
w-[14px]). The marks have different viewBoxes — omp is 64x64, the rest 24x24 — so an unstyled inline svg makes every label beside it shift. Measured: with the slot, labels in the HARNESSES group and the rest of the menu all land at the samex.
Pinned by settings/harness-icons.test.tsx: every harness row draws a branded
svg, the overview draws none, the generic glyph is GONE (not merely accompanied),
opencode and opencode2 share one vendor key, and the slot is what holds the
column.
A harness tab draws no label. Three to five tabs share one strip, and the names
(claude, deepseek-harness, omp (ACP)) spent the strip's width restating what
the vendor's own mark already says. The consequence is that the mark now carries
the accessible name (aria-label is the harness's label), the reason a tab is
unavailable moved into title + aria-description — see the next section, which
is where that turned out to be broken — and a blocked tab is dimmed with OPACITY,
because the colour mode paints it a brand hue that no text-ink/35 can outrank:
a hue-only mute left an unavailable agent looking as ready as the one beside it.
HARNESS_GLYPH_SIZE is { compact: 12, touch: 13, tab: 18 }. The tab gets its
own entry rather than reusing touch: reusing it would mean growing the sidebar
silently shrinks the composer's tabs, and the two are not the same kind of
surface — a session row is a dense list, the tab strip is a primary control whose
mark IS the target.
size is measured against the INK, not the source viewport. Reported as "the
icons look different sizes". They were: every mark is drawn at one size, but a
brand's viewport is not a brand's mark. Measured with getBBox() across the
twelve shipped marks — omp draws a 36x40 mark inside its 64x64 art (62.5% of
the height) while codex, command-code and qwen fill all of 24x24. At an 18px
tab that was 11px of omp ink beside 18px of codex. So HarnessBrandGlyph
carries the measured ink box and HarnessGlyph renders viewBox={ink}: one
size now paints the same mark height for every brand (measured after: omp
16.2x18 ink, codex 18x18, claude 18x11.3 — same nominal height, each brand's
own shape kept by preserveAspectRatio). The box is measured, never derived, and
harness-glyph.test.ts pins three of them.
One brand, two surfaces, two colours. omp publishes one logo, and
HARNESS_BRAND_COLORS is keyed by it — so omp-rpc and omp-acp drew the same
purple. That was correct while the word "omp (ACP)" sat beside the mark and is a
defect the moment the mark is the whole tab: two identical glyphs naming two
different transports. The glyph therefore also carries data-harness-id (the
harness) beside data-harness (the brand), and
HARNESS_SURFACE_COLORS paints the id: purple #9b4dff for RPC, red #dc2626
for ACP. The surface rules are emitted AFTER the brand rows — same specificity, so
order is what lets the override win — and both values go through legiblePair so
each variant clears the 3:1 non-text floor on every shipped palette.
Pinned by harness-tabs.test.tsx (empty textContent, aria-label carries the
name, 18px mark, dimmed blocked tab), harness-glyph.test.ts (the measured
viewBox crop and data-harness-id on the svg), icon-paint-harness.test.ts
(the two surfaces differ, the surface rule follows the brand rows, the tab strip
keeps both hues in monochrome) and brand-color.test.ts (both variants clear the
floor).
Four measured defects, three of which made the reason unreachable:
-
disabledswallows the tooltip and the click. In Chromium a<button disabled>never shows itstitle— the one thing a blocked tab exists to say — and never delivers a click, soonFixcould not fire either (elementFromPointon the tab answered the tab, and the handler ran 0 times). The tab therefore usesaria-disabled, stays focusable, and keeps its handler. -
A nested
titlewins.HarnessGlyphsetstitle="Session runs on claude"on its own<span>, and that span is INSIDE the tab button — the browser shows the innermost title, so a locked tab announced the generic sentence and never the explanation one level up. That is the reported "tooltip tidak informatif". Inside a named control the mark is drawn withdecorative: notitle, norole="img", noaria-label. -
cursor-helpis a QUESTION MARK. Reported as "kenapa ada icon tanda tanya ketika hover" — on macOS the help cursor is an arrow with a?, which read as a stray icon over an icon-only tab. Three states now, each earned:pointerwhere a press selects (or opens that agent's settings),not-allowedwhere the chat already runs on another agent and a press cannot switch anything (the state most tabs are in once a transcript exists — reported from use as "kasih tanda larangan"), anddefaulton the current selection, which is not a refusal. -
A missing install was blamed for an auth failure. Measured in the running
picker:
codexwas blocked withAuthentication requiredand the tab appendednpm i -g @agentclientprotocol/codex-acp— advising a user to install a program that had just replied.harnessBlock()now separates the REASON from the FIX: a probe refusal carries no install hint (the binary ran, and its own sentence names the command), while a harness that never launched carries one. Pressing a blocked tab opens THAT agent's settings page (omp:open-settingswithharnessCategoryId), because login and install are both fixed there; it used to re-probe andconsole.warnthe answer into devtools.
The sentence itself names the OWNER. "Start a new chat to use claude" was true and useless — it never said which agent already held the chat, so a lock could not be told from a mistake:
- blocked →
<label>: <agent's words>(+— install: …only when nothing launched); - chat already started →
Cannot switch to <label>: this chat already started on <owner>. Start a new chat to use <label>.; - the tab IS the owner →
<label> is the agent this chat already started on.; - otherwise →
<label> · <agent name> <version>from the probe.
The same sentence is the accessible one: title for the pointer and
aria-description for the keyboard path, so screen readers cannot hear "claude,
tab, dimmed" with no reason. Both come from one call, so they cannot drift.
Reported as "I sent with the opencode harness and it was processed by omp".
Two independent gaps, and both had to be closed for one click to work:
-
The composer was never handed the harness.
PendingChatViewandEmptyWorkspacePrompt— the branch everynew-…chat renders through — had noharness/onSelectHarnessprops at all, soModelDropdown's tab strip changed only its OWNviewHarnessstate.pendingHarnessRefstayed null,send.tsomitted the field, androutes/agent/new.tsfell back to its documented default:'omp-rpc'. The tab LOOKED switched, which is what made it read as the server ignoring the pick. -
The pick lived only in a ref. Even once wired, a ref cannot re-render, so
the strip could not show the choice it had just recorded.
useSessionHarnessnow keeps the pick in state as well, keyed by the chat it was made on (a secondnew-…chat must not inherit the first one's harness), and writes the ref in the same call.
The tab strip's own view is deliberately NOT the source: harness is a SPAWN
property that decides the transport, the model list and every capability, so it
has one owner per chat — the sidebar row once spawned, the pick before that.
The composer's access chip drew omp's three tiers on every harness and stored
one global value (omp_access_mode). Two things were wrong with that:
-
The same three words are a different control on ACP. omp's tier IS the
approval gate (
--approval-modeover RPC,tools.approvalModeover ACP). Another agent decides which calls it asks about (session/request_permission) and Kabmo's tier only decides which of those arrive as a dialog (acp/permissions.ts→autoApproval). It can loosen the agent's own policy and never tighten it, andtools.restrictedFoldersdoes not exist there — so the omp copy ("except a restricted folder, which always asks") was a promise this transport cannot keep. -
The value leaked across a harness switch.
Full bypasspicked on omp followed the operator toclaude, whose approvals were then auto-answered — a grant nobody made for that agent.
access-mode.ts now keeps the pick per harness (harness_access_modes), with
omp's own entry mirrored into omp_access_mode because the server reads that
key as its spawn-time default for the paths that carry no explicit pick (a
scheduled task, a child spawn, a held prompt). Every other harness starts at
always-ask until the operator picks one FOR IT. accessLevelCopy(harness)
switches the descriptions and adds the disclaimer under the list. Measured in
the browser: Full bypass on claude, switch to omp → Always ask, switch
back → Full bypass; the stored map read
{"omp-rpc":"always-ask","claude":"yolo"}.
The generating indicator and the AI answer footer both hardcoded lucide's Bot.
On an opencode or claude chat that is a false claim in the one row the user
watches while waiting, so both now draw the harness's own brand mark through one
component (RunMark.tsx); an unknown or absent harness still falls back to the
robot rather than an empty badge.
The source is the sidebar row, which is written at spawn — so a fresh chat has
no harness for the first seconds. spawn-harness.ts records what the SERVER
answered with (new.ts returns harness on the ACP branch and omits it for
RPC, which means omp), and useSessionHarness reads it in that window. The
answer is used rather than the request, so a pick the server refused can never
be reported as the agent running the chat.
The badge is an INVERTED surface (bg-ink + text-canvas), so the mark passes
inherit and the colour mode's .bg-ink svg[data-harness] { color: currentColor } rule keeps it on that foreground. Without it an opencode mark
(brand #000000) or a claude one (#D97757) painted its brand hue on a fill
that already IS the palette's foreground — invisible in one of the two themes.
The mark's colour comes from HARNESS_BRAND_COLORS, painted through the fourth
family in the one color: rule:
svg.lucide, svg[data-provider], svg[data-file-brand], svg[data-harness].
legiblePair derives the dark variant from the brand's own hex, so a harness
with no published colour stays ink instead of inventing a hue.
HARNESS_SURFACE_COLORS is the layer above it, keyed by data-harness-id, for
the one case the brand table structurally cannot express: a vendor whose two
harnesses share one logo. See "A tab is the MARK" for the measured reason.
use-harnesses.ts holds module state, not per-call useState. Two surfaces
read /api/harness at once — the composer's tab strip and Settings → Harnesses —
and with one state each, a probe lived in whichever instance ran it: pressing
Check status on opencode2 wrote the 96 models into the SETTINGS copy while
the picker still said "This harness has not reported its models yet". Measured
in a browser: probe in Settings, open the picker, 0 rows; reload the page,
96 rows — the answer only looked fresh because the server had cached it and the
reload re-read the cache. probe() now pushes to every subscriber.
Pinned by use-harnesses.test.ts: two mounts share ONE catalog read, a probe
from one is visible from the other with no reload, a late mount still sees the
catalog, and a failed read reports instead of claiming "none installed".
A models frame during the mount's own read must re-run it. The topic
routinely lands while the first GET /api/harness is still in flight, so a
re-read that merely cleared the "loaded" flag joined that same promise and kept
the PRE-write answer — the picker showed the old probe until a manual reload.
invalidateCatalog() bumps a generation; a read that finishes with a stale
generation starts another instead of settling. Pinned by
use-harnesses-signal.test.ts, which publishes the frame against a real socket
and asserts a third read (mount, subscription snapshot, post-write).
The catalog also follows the models topic. A provider import, add or
bespoke write refreshes the server's probes on its way to republishing models
(invalidateModelsCaches), so the cached catalog is stale in exactly the way the
composer's model list is — and the picker showed pre-write probes until a
reload. The hook's effect now subscribes through subscribeModelsUpdated and
drops loaded before re-reading /api/harness; announceProviderWrite already
refreshes the affected probes, and the topic carries the same fact to every
other surface and tab.
Measured cost, and why it is paid: realtimeClient.subscribe delivers the
CURRENT value of a topic when the subscription opens, indistinguishable from a
change, so mounting the hook reads the catalog twice (its own read plus the
snapshot-triggered one). The second answer is the same catalog. use-harnesses-signal.test.ts
pins both halves: baseline probe is null after 2 reads on a topic that
never changed, and one publish with a probe now available takes a third read and
renders the models.
models.yml is loaded by the pooled omp utility child when it is SPAWNED, and
get_available_models only awaits an in-flight refresh — it never compares the
file's mtime. Dropping Kabmo's cache alone therefore left /api/models
answering the OLD registry from that child: measured, adding a provider only
appeared after omp was restarted.
refreshModelRegistryAfterWrite (src/server/lib/models/registry-refresh.server.ts)
is the one path every settings write and the import route use, and its order is
the contract: recycle the pooled readers → forget the probes that measured the
old file → re-probe when asked → invalidate the caches LAST (the models topic
resolver reads through loadModelsWithCache; invalidating first would publish
and cache the pre-write answer for another minute).
The relation is the FILE, not a pair of ids. harnessesSharingRegistry(path)
maps whatever file a harness reads to every harness that reads it — omp-rpc
and omp-acp are two transports over the same models.yml, so a provider added
on either tab invalidates both pickers. A per-model override passes
probes: false: it changes a row's metadata, not which models exist, so the
stored probe stays valid and the ACP picker does not blank out.
Pinned by registry-refresh.server.test.ts (the injected side effects run in
that order; a restart that throws drops no cache) and
provider-sources.server.test.ts (both transports share one file; a harness
with its own file names only itself; a file no harness reads invalidates
nothing).
The card draws a single table — one row per harness carrying its STATE, its running VERSION and the one ACTION that moves it. It used to draw the same fourteen agents twice (a status grid, then a version table below it), which is why it had grown to 760x920 and why a reader asking "is this working, and is it current?" read the same names twice for two halves of one question. Measured after the merge: 680x640, one list, three aligned columns, no name truncated.
Column widths are the design, and they were wrong first: a 9rem action column left
the NAME column narrow enough to cut command-code and deepseek-harness while
their action cells had room to spare. The name takes the slack (it is what a
reader scans) and the widest installer command ellipsizes with its full text in
title.
Two measurement traps, both hit here:
- a stale stylesheet.
bun run buildwrote the new utilities, the server served the old sheet, andgetComputedStylereported the arbitrarygrid-cols-[...]as one 350px track. Restart the server after a build before trusting a layout measurement. -
measure the row, not its container. The first probe read the outer
two-pane grid (
grid-cols-[1fr_260px]) and reported the merge as broken.
Desktop: a wide two-column card that never scrolls — 880x718 measured, three
columns per row pair, the harness list in TWO columns.
The tally and Open Settings → Harnesses sit on the heading's row at the right
edge (both are ABOUT the section), and the strip under the list is one stacked
column: update controls, then the links in ONE centred row under them.
Phone: ONE centered card with 12px gutters — 366x820 measured at 390x844 — one
column, and one scroller. It used to be the whole screen (h-full w-full, no
gutter, box [0,0,500,913]): the header sat at the viewport's top edge, which a
viewport-fit: cover surface draws UNDER the phone's status bar, so the wordmark
and half the close button were unreachable. The scrim now carries
safeAreaPadding() (shared/lib/ui/safe-area.ts) — max(0.75rem, env(safe-area-inset-*)),
the same rule the shared Modal shell states — and the card caps at the model
picker's own 512px instead of the screen width.
The card is also the ONLY scroller on a phone. Two scroll traps were measured:
the harness list capped itself at 46vh and scrolled while the card had most of
the screen empty below it, and the phone card had a second overflow-y-auto on
its own body — so a drag near the bottom moved the container, not the table. The
list is now plain flow and the body holds min-h-0 flex-1 overflow-y-auto;
measured listScrolls: false, cardScrolls: true with the whole 13-row list laid
out below the fold.
The phone tracks are their own pair, because the desktop pair starves the name:
minmax(0,1fr) 7rem 1.75rem measured 168 / 112 / 28 px at 324px of content
width — 9.5rem stays for md. An arbitrary grid-cols-[…] utility is
compiled by the BUILD, so a dev server started before the edit serves the old
sheet and getComputedStyle reports no track at all; restart before measuring
(the same stale-stylesheet trap the desktop table hit).
Three layout mistakes were measured and undone on the way here:
- a right rail for the update controls squeezed each row's three cells into 280px while the rail held two short blocks — the content paid for the sidebar;
- a two-column bottom strip put "check for updates" beside the links, making a reader pick a column for a control that has nothing to do with them;
- a
border-ton the wrapper doubledUpdateSection's ownborder-y, two rules 16px apart reading as a mistake; - a
md:w-autocard, which is sized by its CONTENT: shrinking the action column to an icon collapsed the whole dialog. The width is now fixed (md:w-[880px]) and the action column keeps its own track, so the card cannot be resized by a change inside a row.
The state mark sits beside the name, inline. Two earlier shapes were wrong, and both looked plausible in the markup:
- as a trailing child of the row it claimed a column of its own, so every agent name lost ~14px to a 6px dot;
-
absolute right-0inside theflex-1wrapper anchored it to the column's edge, which put it beside the VERSION cell — it read as a marker on the version.
inline-flex max-w-full hugging the text is what makes it a mark on the name, and
it still truncates.
Column widths are taken from what each cell must SHOW. Both earlier guesses
starved the version: the action column held 7rem for a single icon, and the
version held 4rem — 64px cannot show a current → latest pair, so the number
truncated while the action cell sat mostly empty. The tracks are now
minmax(0,1fr) 7.5rem 1.75rem, measured as 239 / 120 / 28 px: the pair reads
0.100.0 → 0.101.0 in full, the button gets one 24px square, and the name keeps
the slack.
The action cell is an icon, only when a newer version exists. A permanent
"Update" label claims work that does not exist, and a copy chip for every vendor
command turned the column into prose — so the label moved to aria-label/title
and the row goes quiet otherwise. The glyph is lucide-download: the press
installs something, and ArrowUpRight read as "open this elsewhere".
"I updated, but the Update button is still there." The versions store skipped
its own reload: loadVersions(false) returned early when loaded was already
true, so the refresh an update asks for did nothing. refresh() is now a DISTINCT
operation from reload(force):
-
refreshre-reads the rows — an update already knows the number it installed; -
reload(true)also bypasses the server's registry cache, which costs one request pernpmharness and belongs to the explicit Check button.
Measured after a real install: the row's Update disappeared and its version went
to —, because a successful install also FORGETS the probe (the running adapter
is still the previous process).
"An Update button appears where there is no newer version." Two causes, both fixed by removing a claim Kabmo cannot support:
- the
selfbranch drew an unconditional Update button, so a CLI that was already current still offered one. Kabmo cannot even READ a self-updating CLI's latest version (it lives with the vendor, not in a registry we query), so the row offers the vendor's command instead; -
opencode2was pointed at theopencode-aipackage, whose 1.19.5 was compared against the preview binary'sv0.0.0-beta-18743. Measured:opencode2is a SEPARATE binary on its own beta line, so that comparison was fabricated on every refresh. It now readsownwith no package and no action.
"Harnesses I never installed show an Update." The versions route reported
kind, command and latest for every harness in the CATALOG, not for the ones
on this machine. A row now carries installed (the launch command resolves), and
an absent harness gets kind: null, latest: null, command: null and a note
that says "Not installed on this machine — nothing to update". Measured on this
install: six catalog entries have no action at all now.
The card now carries Versions below the two panes: one row per harness — running version, and the action that moves it. Three kinds, and the kind decides what the row may say:
| Kind | Meaning | Row shows |
|---|---|---|
npm |
published on npm; the number IS the install target |
current → latest + a download icon |
self |
the CLI updates itself (opencode upgrade, cmd update) |
the command, copyable — Kabmo must not install behind the vendor's launcher |
own |
a vendor installer owns it (agy, cursor-agent) |
the command; the route REFUSES to run it |
A row shows the CLI's version, and the adapter's beside it. claude --version
answers 2.1.318 (Claude Code) while the ACP adapter answers 0.101.0 — two real
numbers for two real things. Reporting only the adapter read as "why is my 2.x
showing 0.100?", so the row leads with the CLI's number (read from its own
--version, cached 10 minutes) and states adapter 0.100.0 → 0.101.0 underneath.
Two shapes were wrong first, both from adding a FOURTH grid child: the row shifted one track and the action button fell onto its own line. The adapter note belongs inside the version cell.
The arrow may only point between the SAME number line. With the CLI's 2.1.318
leading, the package in latest is the ADAPTER's — 2.1.318 → 0.101.0 is a
fabricated comparison. The pair is shown on the adapter's own line instead.
The package must be the one the probe reports. The first table pointed
claude at @anthropic-ai/claude-code while the probe reports
@agentclientprotocol/claude-agent-acp — measured as "0.100.0 → 2.1.318" with an
Update button, a comparison across two unrelated number lines. Numbers that look
comparable but are not are worse than a dash.
claude is not one package: it is the npm ACP adapter
(@agentclientprotocol/claude-agent-acp, the number initialize reports) sitting
on top of the claude CLI (its own --version, its own claude update). The two
move independently — measured on this machine: adapter 0.100.0 under CLI
2.1.318 — so the route reports them separately and the update decides per part:
-
agent— the adapter's probe version and its package's latest; -
cli— the CLI's--versionand the latest of its own npm package, which the facts table names (cli.pkg). Without that package the CLI line can only report what is installed, because Kabmo has no registry number to compare — and the planner then never plans it. Onlyclaudecarries both (claude updateplus@anthropic-ai/claude-code);codexandpiname no CLI updater, so their CLI line is report-only.
planHarnessUpdate (src/shared/lib/harness/update-plan.ts) is the decision, kept
pure so it can be tested without spawning:
| State | Commands run |
|---|---|
| both behind |
npm install -g <adapter>@<latest> then claude update
|
| only the CLI behind | claude update |
| only the adapter behind | the npm install alone |
| neither | nothing — the answer is "already up to date" |
The first shape ran BOTH unconditionally, which reinstalled an adapter that was already current and reported "updated to 0.101.0" about a version that never moved. A part whose latest version Kabmo cannot read is never planned: it cannot claim the part is behind. A row with no probe still plans the adapter install — a press there means "make this install current" — and the outcome says plainly that nothing could be compared instead of claiming it is current.
updateAvailable on the row is the UNION of the parts, so the button appears when
either half can move; the accessible name names each part and its target
(Update claude to adapter 0.102.0 + Claude Code 2.1.400), because one press
running two installs must not read as one. The action icon is a download
(lucide-download); it used to be ArrowUpRight, which reads as "open this
elsewhere" next to a version number.
After a successful run the cached probe AND the cached CLI --version are
forgotten (forgetProbe, forgetCliVersion), and the server probes the
harness again by itself — otherwise the row keeps quoting the pre-update number
until the reader opens Settings and presses Check status, which is what "updated"
next to the OLD version looked like. Forgetting alone was the bug: it only
dropped the stale answer.
The re-probe is probeWithConfig (the same call the boot pass uses, so the user's
command/env override is honoured), and it is NOT awaited by the install's report —
it spawns an agent that may take a minute. So the record carries probe: 'pending' and the dialog's poll (and the queue ticker) keep going on jobMoving
until it turns 'done'; the client then drops the cached version rows
(invalidateHarnessVersions) and the row reads the new number. A probe that
fails, or a run that failed, still writes 'done'/null rather than leaving the
row polling forever, and a successful probe names what it found in the record's
message (— it now reports 0.103.0) — a version claimed only because the agent
answered it. A probe left pending by a server that died mid-flight is kicked
again by the next pass. Opening About also re-reads the rows without forcing the
registry, because a run may have settled while the card was closed.
A CLI part with no number must not hide the adapter's. The row leads with the
CLI only when its --version read SUCCEEDED. Carrying the empty part as the lead
rendered — over a number the probe had already reported — measured on zcode
(adapter 0.82.3 probed while no zcode runtime was on PATH) and claude
(claude --version answered claude native binary not installed while the
adapter answered 0.100.0). The part that has a number leads; the adapter …
line is drawn only when BOTH numbers exist and differ.
npm i -g writes PATH; a pinned npx launch never reads it. The launch table
starts claude, codex, pi and zcode as npx -y pkg@x.y.z, while the update
installs the package globally. Measured: global
@agentclientprotocol/claude-agent-acp was 0.101.0 while every launch requested
0.100.0, so the press reported success and the row stayed behind forever. A
successful adapter install now repoints the harness's command at the binary the
install wrote (facts.agentBin: claude-agent-acp, codex-acp, pi-acp,
zcode-acp-server) unless the user already configured a command of their own.
repointAdapterLaunch is the pure decision; the route only does the I/O.
The update runs in a BACKGROUND worker, because a killed npm install -g is a corrupt install. The route used to hold the POST open and run every step inside it. Three properties of that shape were measured failure modes:
-
the request was the run's lifetime. Closing About or reloading the page did not stop it, but a
bun --hotreload or a server restart dropped the only record of it, so the dialog came back showing nothing while npm was still writing. -
the five-minute child timeout killed the installer mid-write. A 147 MB native package measured 33 s on this machine's link and 67 s for the full
npm i -g; a slower link crosses five minutes, and SIGTERM there leaves a half-replaced package tree — the corruption the press was blamed for. -
nothing serialized two presses. The old route had no single-flight at all: a reload re-enabled the button (the console's "in flight" flag is JavaScript), and two
npm install -gover the same prefix is the classic way an npm tree is destroyed.
So one press now spawns a detached worker (src/server/lib/harness/update-worker.ts) that owns the steps and writes a record the server reads. One install at a time, but a second harness is QUEUED rather than refused — see below.
| File | Role |
|---|---|
<data>/run/harness-update.<id>.spec.json |
what to run: the planned argv, from planHarnessUpdate
|
<data>/run/harness-update.<id>.json |
that harness's record: steps + states, streamed output, pid, queuedAt, finishedAt, ok, message
|
<data>/run/harness-update.lock |
flock, held for the run — the kernel releases it if the worker dies. ONE lock for every harness, because the installs share the global npm prefix |
-
POST /api/harness/updateanswers202 {started, queued, job}in milliseconds. A second press for the SAME harness is a409naming its record; a press for a DIFFERENT harness is202withqueued: true, and the record carriesqueuedAtinstead of a pid. The decision is read from disk, so a second tab and a second server instance agree. -
GET /api/harness/update/statusanswers{jobs}— one record per harness, an empty array for "nothing ever ran" (never a 404). It runs the same pass the ticker runs: settle a run that died, apply the post-install side effects once (forgetProbe,forgetCliVersion, the launch-line repoint,applied: trueas the marker), then start the oldest WAITING record when nothing is installing. -
update-queue.server.tsowns the queue and its clock. The ticker (2 s,globalThis-anchored,unref'd) exists only while a record is unfinished, so a queued run starts with the About card CLOSED and after a server restart (runAfterListenTaskspumps once at boot). Every read-decide-write over the records goes through one promise chain — two presses arriving together are one decision, not two "nothing is running" reads that both spawn. -
A QUEUED record is never "dead".
jobQueuedisfinishedAt: null && pid: null && queuedAt != null; the dead-run settlement skips it, because nothing was ever spawned for it. The worker clearsqueuedAtwhen it takes the record over. -
The worker's kill bound is 30 minutes PER STEP, not five for the whole run, and it stops at the first failure. Output is appended as it arrives (throttled to 400 ms), so the dialog can name the step it is on (
adapter, thenClaude Code). -
A record whose pid is gone is settled by the next read, not polled forever:
finishedAtis written withok: falseand the message says the install may still have completed, because a dead reporter is not proof the command failed. The first 15 s afterstartedAtare exempt — that is the window between the record and the worker's pid handshake. -
A settled run is not necessarily
done:probe: 'pending'keeps both the ticker and the dialog's poll alive until the post-install probe answers (see the paragraph above), sojobMoving— notfinishedAtalone — is what "keep following" means. -
The rows show it: the installing row says
Installing <step>…, the waiting row saysQueued — starts when the install running now finishes, both keepView logfor their OWN record, and pressing a row that is waiting is disabled rather than a second refusal (measured in Chromium: both lines on screen at once).
The install passes --allow-scripts=<package>, per package. npm 11 blocks lifecycle scripts by default, and @anthropic-ai/claude-code needs its postinstall to unpack the native binary — measured on this machine: bin/claude.exe was left as a 500-byte stub printing Error: claude native binary not installed., and claude update then failed with update_apply_native_binary_missing (recorded in ~/.claude/.last-update-result.json). Blanket script execution is not the fix; the flag names the one package whose vendor scripts this install is for.
Pinned by update-job-store.test.ts (atomic replace, a foreign JSON file reads as "no job", live pid vs dead pid, the start grace, a queued record neither in flight nor dead, and a settled run left alone), update-queue.test.ts (the refusal is per harness; a press while another installs writes a waiting record and starts nothing; the oldest waiting record goes next; the waiting run is handed to a real worker once the run ahead settles — the worker is detached, so its own record is the only way to observe it), update-worker.test.ts (runs the real worker in a child process: every step in order, the first failure ends the run, a held lock refuses the second install), update.test.ts (the refusals: unknown harness, vendor-managed, same-harness in flight, same-harness already queued, and the two-record status payload) and use-harness-update.test.ts (a 202 starts following, a second harness is accepted as queued and BOTH settles are reported once each, a 409 is a refusal, an in-flight run is adopted on open, a finished record is history).
The probe's agent version is not always the package version. dsh answers
deepseek-harness-acp 0.0.1 from initialize while dsh --version is
0.2.2-rc.1. Comparing 0.0.1 against @deepseek-ai/dsh 0.2.2 planned an install
of the version already on disk on every press. The CLI is the part that carries
the package and the comparison; the agent line is report-only. An npm CLI with no
vendor updater now plans npm install -g <cli.pkg>@<latest>.
"Installed" is the same question the catalog asks. The versions read used to
resolve the build's launch table directly, so it called a zcode with no runtime
installed and refused a harness whose binary is only reachable through its
configured launch line. It now uses commandAvailable (user command + the
bridge's required runtime), which is the rule the spawn and the status card use.
A dash is a real answer. updateAvailable needs BOTH numbers; one missing
shows — with the reason, never "up to date". A row with no probe has no running
version, and claiming otherwise would be fabricating a fact.
An install FORGETS the probe (forgetProbe): measured after a real
npm install -g, the row still read 0.100.0 while npm had 0.101.0 on disk,
because the running adapter was the previous process. The message says so —
"check its status to read the new version".
Routes: GET /api/harness/versions?force=1 (one registry read per npm harness,
cached 10 min), POST /api/harness/update (starts the background job, 202), and
GET /api/harness/update/status (the job record). All three are registered as
their OWN static paths, never under a /api/harness/:id parameter route.
Layout, measured: the table is three columns and at 260px the label collapsed to
nothing while installer commands ran past the card — so it sits at the card's
FULL width below the panes, scrolls inside its own section, and the card grew to
min(92vh, 980px) / 760px wide. max-w utilities silently did not apply on a
stale build for one round of checks; the class was present in the stylesheet and
the browser had an older sheet — restart the server after bun run build before
trusting a layout measurement.
harness_probes (one row per harness) holds each probe; the Map on
globalThis is only the fast layer in front of it.
Memory alone was a reported bug: press Check status, watch the card turn
ready, restart Kabmo — or let bun --hot reload during development, which is
every edit — and every harness read not probed again. A probe is a fact about the
installed binary, not about the process that asked, so the record belongs on
disk. The spawn had the same symptom one layer down: it resolves a harness's
configured default model against the probed model list, and after a restart that
list was empty, so the default silently fell through to the agent's own
preference.
probedAt AGES a probe; it must not DELETE it. A row older than PROBE_TTL_MS
(30 min) used to be read as absent, which reproduced the same reported bug by a
second route: probe a harness, come back an hour later, and the card said
not probed while harness_probes still held the answer. Measured on a cold
process against the real database — omp-acp at 17 minutes answered, claude
at 61 minutes read as absent — so "re-probe after every restart" was still the
user's experience even though the row had survived the restart.
A stored record is now always returned and carries stale: true once it is past
the TTL. The card shows the answer WITH its age (ready (aged), "checked 1h
ago · re-check for a current version") instead of forgetting it.
The two gates differ on purpose, and that split is the point:
- showing an old answer is honest, so the catalog returns it;
-
acting on one is not, so
harnessProbeModels— the read the SPAWN uses to resolve a configured default model — still refuses a record past the TTL. A model the agent dropped in the meantime would fail at the first prompt.
The real invalidators are the ones that change what was measured: a launch line
or env edit (forgetProbe via probeInvalidatedBy) and an install
(routes/harness/update.ts).
Pinned by probe-cache.server.test.ts, whose cases empty the memory map to
simulate a restart (the only thing a restart changes): the record survives, the
catalog is read back in one call, the spawn still finds its models, forgetProbe
really deletes, an aged record is returned and labelled, an aged record is NOT
used to pick a spawn model, and a re-probe replaces rather than piles up.
opencode 2.x activates "Location plugins" asynchronously per directory and guards
every request that needs them with a HARD five-second wait. Measured on 2.2.5
against a real config: the first session/new answered at +6 s with
Internal error: Internal service failure: {"errorName":"ServiceUnavailableError"}
(a 5 s gate that expired just before a 6 s request timeout), plugin installs
finished at ~30 s and 72–82 s, and the SAME process then answered a real session.
The probe read that first refusal as final, so the card showed opencode blocked
while the agent was still booting — and the composer could not start it either.
newSessionAfterActivation (acp/activation.ts) retries on that error name
alone, up to 150 s (headroom over the measured 82 s), sleeping 3 s between
attempts. Three properties are deliberate:
-
the same process. Activation is per-process state, so the retry re-sends
session/newto the running agent. Respawning would restart the clock. -
opencode only. Every other harness's first refusal (
Authentication required) is final; retrying would hide it behind a two-minute wait. -
bounded, and it says why. A plugin that never settles ends in the agent's
own words plus
plugin activation did not finish within 150s, instead of a bare opaque error.
Both owners of session/new go through it: probeHarness and
handshakeAcpSession (including its load path). Pinned by activation.test.ts;
measured end to end against a stub ACP agent that emits the real error frame —
two refusals, then ses_stub after three attempts — and against a real opencode
2.2.5 process (89 models probed in 1.3 s once activation was warm).
startHarnessAutoProbe() runs from runAfterListenTasks (lifecycle/after-listen.ts),
after the listener is up. It reads the roster (omp_harness_disabled), keeps the
switchable entries the user has not hidden, drops anything whose launch command is
not resolvable, and probes the rest one at a time, writing each answer through
rememberProbe.
Measured on a mocked boot with a temp data dir: the log line
[harness] probed on boot: claude, codex, pi, zcode appears after
listening on …, without delaying the listener. The pass is not awaited on
purpose — a probe can take a minute (an agent that has to authenticate, a wrapper
that resolves a container) and boot must not wait for it.
The guard is the PID on globalThis, not a module flag. bun --hot
re-evaluates the entry, and probing spawns agents: without the guard every edit
during development would start one process per enabled harness. A real restart is
a new PID and therefore runs the pass again, which is the requirement. The
built-in omp-rpc is skipped because there is no agent to spawn, and a missing
binary is skipped for the same measured reason as the toggle route — the card
already says "not installed", and spawning it can only repeat that fact.
Pinned by auto-probe.server.test.ts: a switched-off harness and the built-in
transport never reach the availability check, an unresolvable command is skipped,
every target's answer is stored, and one failing probe does not stop the pass.
A login-entry launch hands the server a minimal PATH. Measured on this machine:
~/Library/LaunchAgents/dev.kabmo.tray.plist carries no EnvironmentVariables,
so launchctl print gui/$UID/dev.kabmo.tray reports
default environment PATH => /usr/bin:/bin:/usr/sbin:/sbin. Under that PATH
Bun.which('npx') and Bun.which('omp') both answer null while
/opt/homebrew/bin/npx and ~/.bun/bin/omp are installed — so the first boot
after login logged [harness] probed on boot: omp-acp (omp survived only through
resolveOmpBin's own fallback list) and every npx-launched harness read
not installed. Starting Kabmo from a terminal inherited the shell's PATH and
probed the whole roster; a restart spawned BY the launchd-started server
inherited the same minimal PATH and did not repair it.
The spawn side was already repaired (withToolchainPath in the ACP stdio
transport), which is why "not installed" and "runs fine" could both be true. The
resolution side now uses the same repair: whichOnToolchainPath
(src/server/lib/fs/toolchain-path.ts) is the one lookup commandAvailable,
harnessRequirementMet/resolvable, resolveOmpBin, the update queue's agent
check and cliVersion all use. cliVersion executes the RESOLVED absolute path,
because a bare name that passes the check still fails the spawn under a minimal
PATH. Verified end to end: env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin bun src/cli/kabmo.js serve --prod logged
[harness] probed on boot: omp-acp, claude, codex, opencode, dsh, antigravity, pi, zcode, jcode.
Pinned by toolchain-path.test.ts (a binary that exists only in ~/.bun/bin is
found while the inherited PATH cannot see it).
GET /api/harness answers from the cache (30 min TTL before a record is labelled
stale, memory on globalThis over the disk row for the bun --hot reason);
?probe=<id> spawns exactly one, switching an agent ON does so when its launch
command is resolvable, and the server's own boot pass does the whole ON roster
once per process (previous section). The page has an explicit Check status
button, which is also what makes the capability rows honest: they render FROM the
probe, never from a hardcoded table.
The sidebar's HARNESSES group holds an overview (harness-index) followed by one
entry per agent. Ids are DYNAMIC — harness:claude, from
shared/lib/harness/menu.ts — not twelve more members of the
SettingsCategoryId union: the catalog decides which agents exist, and a union
member per adapter would need a build-time edit for every agent added at runtime.
The union accepts `harness:${string}` for that reason.
A single-harness page renders the SAME card the overview draws, with
HarnessSettings only={id}. A second renderer for one agent is how the two views
start disagreeing about what that agent can do.
The overview is a ROSTER, not twelve cards. It used to be one full card per
agent — capabilities, config form, provider panel each — which turned "which
agents do I run here?" into a page you scroll. It is now one row per agent with a
switch, its live status, a Check button when it is on, and a link to its page.
omp_harness_disabled (one app_settings row) holds the SWITCHED-OFF ids:
- the DISABLED list is stored, not the enabled one. An adapter added by a later Kabmo update must arrive ON. Storing "what the user had enabled" would freeze the roster on the day they first opened Settings, and a new agent would silently never appear.
- an empty list is the default, so the row is DELETED when nothing is off — same rule as an all-empty harness config.
-
the built-in transport has no switch:
ompover RPC is the path this app IS, and a build with it off could run no chat. Refused with a 400, not silently ignored. - a switched-off agent leaves the DRAWER and the composer's model PICKER, but not the All Harnesses page — that page always lists every agent, because it is the only place one can be switched back on. It also keeps its catalog entry, since a session row must still say which transport ran it.
-
the agent owning an open chat is never removed from the picker, so an
existing conversation can still name the harness that produced it
(
pickerHarnesses).
Switching ON is a roster decision and ALWAYS succeeds — including for an
agent that is not installed. The user may want the tab present before installing
the binary; refusing made the switch look broken (reported). The probe is
therefore a BONUS with two guards: it runs only when the launch command is
actually resolvable (commandAvailable — no spawn for a missing binary), and a
failure for any other reason is caught so it cannot undo a roster write the
database already holds. The response says probed: false when nothing was
measured, so the UI can tell "on, not checked" from "on, and here is its answer".
Pinned by menu.test.ts (the id round-trip, the overview first, no page for the
built-in transport, and every menu entry present in SETTINGS_CATEGORIES),
groups.test.tsx (a switched-off harness has no drawer row and comes back when
re-enabled, while its neighbours stay), enabled.test.ts /
enabled.server.test.ts (the stored list, the retired-id drop, the built-in
refusal, deletion when empty), toggle.test.ts (enable succeeds with the binary
absent and spawns nothing), and harness-models.test.ts (pickerHarnesses).
shared/lib/harness/provider-facts.ts is the table, and it is MEASURED against
each vendor's own reference and, where possible, the installed binary:
| Harness | File | Pointer | Format |
|---|---|---|---|
| omp / omp-acp | ~/.omp/agent/models.yml |
providers |
YAML |
| opencode and opencode2 | $XDG_CONFIG_HOME/opencode/opencode.json |
provider |
JSON |
| codex | ~/.codex/config.toml |
model_providers |
TOML |
| pi | ~/.pi/agent/models.json |
providers |
JSON |
| kimi |
~/.kimi-code/config.toml (kimi-code; KIMI_CODE_HOME moves it) |
providers + models
|
TOML |
| qwen | ~/.qwen/settings.json |
modelProviders |
JSON (array per protocol) |
| command-code | ~/.commandcode/providers.json |
providers |
agent-managed, read-only |
| zcode |
~/.zcode/v2/provider_config.json (personal rules; config.json is the app's legacy map and is never written) |
config.providerConfigRules.providerRules + config.modelConfigRules
|
JSON rules, writable |
| minimax |
mcode's own BYOK store |
— | agent-managed, read-only |
| claude / antigravity | environment | — |
ANTHROPIC_BASE_URL / GOOGLE_GEMINI_BASE_URL
|
The first version of this table GUESSED and was wrong three times, which is why
the corrections are pinned by provider-facts.test.ts:
-
opencode2reads the sameopencode.jsonas 1.x — verified by writing a provider and watching both binaries list it. That entry is now GONE rather than merged: the preview became a shim foropencode, so there is one binary and one tab. -
codex HAS a registry (
[model_providers.<id>]), so calling it "no registry" sent the reader to the wrong page. - pi, kimi and qwen each have one, in three different formats.
Two formats store a VARIABLE NAME, never the secret: codex's env_key and qwen's
envKey. The form says so, and the writer never puts a key in those files.
A dialect the target cannot speak is REFUSED. codex has OpenAI's two wire
formats only, so importing an Anthropic endpoint throws with the reason instead of
writing wire_api = "chat" at a gateway that never agreed to that protocol —
measured on a real import, where the mislabelled entry would have failed the first
request.
ZCode's registry is a RULE GRAPH, not a map (provider-zcode.server.ts).
3.12+ writes user-added providers to ~/.zcode/v2/provider_config.json; the
legacy config.json map stopped syncing and belongs to the app, so Kabmo never
rewrites it. Two measured consequences: a provider rule alone is INVISIBLE (the
bridge builds its dropdown from modelConfigRules), so the writer emits one model
rule per id; and a new model rule WITHOUT an explicit reasoning map inherits a
catalog family rule — a qwen3-… id got enable_thinking + thinking +
reasoning_effort and a Kenari gateway answered every turn with 400. The writer
emits the catalog's generic { "reasoningLevel": { "values": ["disabled", "enabled"], "map": "{}" } }, and the same prompt then reached the gateway with no
reasoning parameters and returned ok. The write takes a .kabmo.lock lease
because the runtime's own writer locks a DIRECTORY at <file>.lock; a file there
would look like a lock it must reclaim. A chat also needs a ZCode runtime — the
desktop app, or zcode-app-cli on PATH (ZCODE_BIN for a custom install).
provider-write.server.ts is one writer per FORMAT, dispatched by the same table.
Every format merges rather than rewrites (these files hold plugins, agents, MCP,
approval policy), refuses an unparseable file untouched, keeps a stored credential
and the user's own dialect on update, and writes 0600 because the file can hold a
key.
Under bun test, a write outside KABMO_TEST_HOME is refused. That guard
exists because a verification run of this feature wrote into the developer's real
~/.codex/config.toml, ~/.pi/agent/models.json, ~/.kimi/config.toml,
~/.qwen/settings.json and ~/.omp/agent/models.yml — a script with HOME
reassigned was fine, while a real server started for a browser check was not. The
damage was reverted by removing exactly the injected entries; the guard is at the
one place that writes.
Two actions on one landing path (routes/harness/import-action.ts → applyProvider):
| Action | Where the endpoint comes from | Where the key comes from |
|---|---|---|
| import | another agent's registry row | the SOURCE file, read in the request that writes |
| add | typed into the card | typed into the card |
Everything after that is shared, so "copy" and "type" cannot drift:
-
The endpoint is PROBED first (
provider-probe.server.ts) — one unauthenticated request per protocol. An empty JSON body is enough because every one of these APIs rejects a body it cannot parse before it looks at a credential:/v1/messages→ 400invalid Anthropic request JSON,/v1/chat/completions→ 400invalid JSON: missing field model,/v1/responses→ 400,/v1beta/models→ 200 list. 404/405 and an HTML error page mean the route is absent. Measured onkenari.id: chat + responses + anthropic answer, the Gemini listing is a 404 HTML page. -
The protocol is chosen from the measurement, not the declaration. Measured: omp's
models.ymlcallskenariopenai-completions, and the same host answers Anthropic Messages — which is the whole reason "import kenari from omp into Claude Code" works and writing its declared dialect there would fail every request. - A protocol neither side has is REFUSED by name, including what the endpoint answered. A probe that reached the host is EVIDENCE: when it answers nothing the target speaks, the answer is no — an earlier version fell back to "the target has only one protocol, so use it" and would have written a Chat gateway into Responses-only codex.
-
The write lands where that agent reads it: the registry (with its own dialect spelling) or, for an
environmentharness, the vendor variables at the host root — measured,ANTHROPIC_BASE_URL=https://kenari.id/v1made Claude Code request/v1/v1/messagesand answer an empty turn.
CUSTOM only, in both directions. shared/lib/models/provider/vendors.ts is the census (omp 18.3.0's KnownProvider plus each agent's reserved ids), the list filters with it and the writer refuses anyway: copying anthropic into codex writes an override of codex's OWN built-in provider instead of adding a gateway.
Per-provider credential variable names. codex's env_key and qwen's envKey hold a NAME. A fixed OPENAI_API_KEY meant two providers added to qwen both wrote it, so the second silently re-pointed the first at a different key; the name is now derived from the provider id (KENARI_ID_API_KEY) and the value is written into the harness env (or qwen's env block) — measured: two gateways, two names, two values.
A provider with no models SAYS so. Measured: omp serves zero rows from an entry with no models and no discovery, and prints no warning. The write answers with a note instead of a bare success, and the form's hint says empty ids are only for an endpoint override.
The display name survives. omp keys a provider by slug and prints the slug, so a card read ui-gateway after the form said "UI Gateway". The entry now carries name (accepted by omp), and both the harness reader and omp's own native reader prefer it.
The card lists what the agent already holds (configured, custom only). Without it an add that wrote correctly and one that silently wrote nothing rendered the same card; it is re-read from the server after a write, because the file is the only proof.
The card used to draw the same six fields for every agent, and two of them were lies on most of them. The probe the card already reads answers it:
| Harness |
probe.models values |
Providers | Fields shown |
|---|---|---|---|
omp-acp |
kenari/agnes-2-5-flash:free, … (221) |
kenari, kenari-jatis, aihub-brisnets-jatis
|
launch, Provider, model, thinking, mode, env |
claude |
default, opus, sonnet, haiku, claude-fable-5[1m] (5) |
none | launch, model, env |
codex (unauthenticated) |
none published | none | launch, model, env |
shared/lib/harness/config-fields.ts is the rule, pure and probe-injected:
-
The Provider field exists only where the agent publishes
provider/modelselectors.claudepublishes bare names, so its picker could never populate and its model list never narrowed by it. A provider already STORED keeps the field visible even with no probe — hiding a value the config holds is how a form silently rewrites it. - Thinking and mode appear only when the probe published a ladder. The old free-text fallback invited a value the agent rejects, and "Empty leaves the agent on its own effort" was shown on agents that have no such selector at all.
-
The Environment box speaks the agent's OWN variables. Claude Code gets
ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL, plus oneANTHROPIC_DEFAULT_<FAMILY>_MODELper picker alias (opus,sonnet,haiku,fable); Antigravity getsGOOGLE_GEMINI_BASE_URL/GEMINI_API_KEY. It used to hintGEMINI_API_KEYon a Claude Code card — an instruction that cannot work. A registry harness says where its providers actually live (.codex/config.toml), andcursorsays the launch line is the whole surface. -
An unpinned alias fails against a gateway. Measured with the SDK's own
binary (2.1.318):
--model sonnetagainst a gateway that listsclaude-sonnet-5-5still sends the vendor's id, and a gateway that does not serve it answers400 model not found; withANTHROPIC_DEFAULT_SONNET_MODEL=<gateway id>the same turn succeeds. -
A gateway must accept a
role: "system"entry inmessages. Measured on Claude Code 2.1.316's captured request body: the Environment block travels as{"role":"system","content":"# Environment …"}insidemessages, not in the top-levelsystemarray. A gateway that forwards that role to an upstream which only accepts user/assistant answers400 the model's provider rejected the requeston EVERY turn — measured on kenari:qwen3-8-27b:freerefused it,agnes-2-5-flash:freeanswered 200. The model, not the env form, is the variable. -
The launch hint names that agent's own install line, and the model
placeholder is
provider/modelonly where selectors are the shape.
Verified in the browser at 1440: claude renders launch / model / env with the
ANTHROPIC names and no provider picker; omp-acp (probed, 221 models) renders
launch / Provider (commandcode) / model / thinking ("7 levels") / mode
("2 modes") / env, plus its registry panel.
Each ACP card carries a form (harness-settings/ConfigForm.tsx) with six fields,
all optional — empty means the build's table, stated in the field's own hint
rather than implied:
| Field | What it is actually for |
|---|---|
| Launch command | The binary is not on PATH, or needs a wrapper that signs in first. Quoted paths survive (/Users/me/My Tools/agy acp) |
| Provider | Which of the agent's providers a new chat starts on. ACP publishes each model as provider/model, so this is a FILTER over that list |
| Default model / thinking / mode | The selectors a spawn writes after session/new, so the first prompt does not run on whatever the agent prefers |
| Environment |
KEY=VALUE lines. This is the provider/credential switch an ACP agent actually honours (GEMINI_API_KEY, GOOGLE_GEMINI_BASE_URL, CODEX_PATH) |
Storage is one app_settings key per harness (omp_harness_config:<id>), not a
blob: a blob would let two instances writing different harnesses clobber each
other, the same defect session_ui_state avoids by keying on the session. Saving
an all-empty form DELETES the row, so a reset leaves nothing stale behind.
A default model only applies if the agent still lists it. resolveDefaultModel
matches against what the probe published, so a model the agent dropped falls
through to the provider's first model rather than being written and failing the
first prompt. command and env overrides are what make this a real provider
setting: there is no Kabmo-side model routing for an ACP agent.
Only a changed command or env invalidates the cached probe.
probeInvalidatedBy is the single rule, used by the route and its test. The first
version dropped the probe on EVERY save, which collapsed the provider/model
pickers back into free-text fields the moment a default was stored — measured:
probe command-code (96 models, dropdown populated), press Save, dropdowns gone.
Three separate defects made the Stop button do nothing on an ACP harness, and each one was invisible in a different way:
-
session/cancelwas never sent. It is a JSON-RPC notification, so nothing awaits it and a failure to write it is silent.AcpProcess.cancelpassedthis.notify— a plain method — intoverbs.cancel, which loses the receiver: the throw wasundefined is not an object (evaluating 'this.write')and the route answered500while the turn kept running.notifyis now an arrow field, likecallbeside it, andclient.test.tsasserts the frame on a real pipe (an echoing child) rather than a stubbedwrite, which would have hidden exactly this. -
A failed abort counted as a stop.
stopAgentSessionreturnedtruefor any HTTP answer, so the 500 above suppressed theforce_resetescalation it exists to trigger. It now requiresres.ok; a failed or dropped request escalates. -
The turn's flags were cleared by hand, and only half of them. The abort
branch set
isPromptRunning = falseand leftisStreamingup, so a session whose agent never answered stayed "already processing" forever.cancelTurnnow closes the turn itself (finishTurn({stopReason:'cancelled'})): the open message is flushed, abandoned tool cards are failed, and the terminalagent_endis emitted once — by that close, not by a hand-built frame beside it.
omp does answer the cancel (measured with a raw stdio client: session/cancel
4.3 s into a turn → {"stopReason":"cancelled"} immediately). What is easy to get
wrong afterwards is the next turn: ACP has no queue, and a second
session/prompt while one is open cancels the first. Kabmo sent it 1 s after the
stop and the agent persisted the new user row and never answered it — every later
send then failed as "already processing". Turns are now chained behind the
outstanding request, and abandonPrompt settles it locally, because the agent's
own reply is not something the next turn can wait for.
Frames are also dropped when no turn is open (openTurn === null): after a stop,
omp keeps emitting chunks for work nobody is watching, and forwarding them
reopened the assistant message the client had already finalized.
Verified end to end against a scripted ACP agent over a real pipe: turn 1
end_turn; stop mid-turn → exactly one terminal cancelled frame, isRunning()
false, zero frames afterwards; turn 3 streams normally. A deliberate
destroyAndWait no longer reports itself as "the agent exited" (closing), since
force_reset is now the user-requested path.
ACP v1 makes messageId optional on agent_message_chunk, and antigravity
1.5.3 sends none: every chunk was exactly {sessionUpdate, content}
(measured on a 500-word answer — 25 chunks over ~10 s, none with an id).
AcpFrameMapper.snapshot() only wrote id when the agent supplied one. With no
id, toChatMessage minted msg-<Date.now()>-ai per frame, so the client's
onMessageUpdate found no existing row and appended: chunk 2, chunk 3 … and the
final message_end each became a separate bubble. One assistant turn rendered as
N duplicate rows that grew in length, and the answer looked like it was not
streaming because only the first frame ever filled the placeholder.
The mapper now synthesizes one identity per turn (acp-<uuid>) the first time a
snapshot is built, including a tool_call that precedes the first text chunk.
reset() and closeMessage() clear it, so the next turn gets a fresh id. The
same id reaches message_end, which is what makes the client replace the
streamed row in place instead of appending the completed answer beside it.
Pinned by frames.test.ts (id-less chunks share one id, message_end carries it,
a tool-first turn shares it, reset() gives a new one). A short answer still
arrives in a burst because agy finishes generating it first; that is the
agent's cadence, not a transport defect.
initialize used to send clientCapabilities: {}. That is legal, but it told
every agent that this client could not read or write a file, so an adapter that
routes edits through the client had to refuse them. The advertisement is now
client-capabilities.ts:
| Advertised | Why |
|---|---|
fs.readTextFile / fs.writeTextFile
|
client-fs.ts serves both against the session's workspace |
session.notices |
AcpFrameMapper already renders notice, and the turn gate was moved so a notice sent between turns is not dropped |
Everything else is deliberately absent, and each omission is a promise Kabmo
cannot keep: terminal (no bridge surfaces a terminal's live output in the
timeline), elicitation (no form/URL dialog), auth.terminal (Kabmo does not
reproduce the agent's launch line interactively), session.configOptions.boolean
(the selector UI is select-only) and session.compaction (no renderer). An
advertised capability the client cannot serve parks a turn on a call nobody
answers — the same failure the explicit refusal exists to prevent.
Two details are load-bearing:
-
Containment, not string prefixes. Every fs path must be absolute and must
survive
pathHolds(session.cwd, path), which canonicalizes symlinks and the nearest existing ancestor. A symlink inside the workspace that points at/etc/hostsis outside and gets-32602; a missing file gets-32002.line/limitare 1-based, and a write creates the file and its parents. -
A refusal carries the spec's code. An unimplemented method answers
-32601, not-32603: an agent decides from the code whether to fall back.
assertProtocolVersion accepts 1 and 2 and refuses anything else by name; the
connection is not parsed as v1 when the peer says v3.
Verified with a scripted ACP agent over a real pipe (the agent echoed the
received clientCapabilities, then read a file through fs/read_text_file and
got its contents back), and with a real omp 18.18.6 initialize + session/new
against the new advertisement.
The protocol is one document per surface. This is the state of each, so a future change knows whether it is filling a hole or re-deciding a choice:
| Page | State |
|---|---|
| Overview / Transports | stdio, newline-delimited JSON-RPC. Non-JSON stdout lines are skipped (measured: opencode acp prints plugin-boot logs first). |
| Initialization | Major version checked; client advertises fs + session.notices, nothing it cannot answer. |
| Authentication |
authMethods are read into the probe (the blocked card names them), but there is no login control yet; authenticate / logout are not called. |
| Session Setup |
new, load and resume are capability-gated. session/close exists but is not called (Kabmo kills the process); additionalDirectories, systemPrompt and MCP servers are never sent. |
| Session List |
listAllSessions follows nextCursor; Settings → Harnesses → Import sessions copies the agent's own history into harness_sessions, and the Auto import switch runs the same pass at boot and every 15 minutes. The request carries NO cwd (codex's cwd-filtered list exits the adapter 3/3 before answering, on 2.5.0 and 2.7.0), so rows are filed locally by their own cwd. |
| Session Delete |
session/delete runs for every recorded harness — on the live child when there is one, else on one fresh child reused for the whole batch. dsh advertises no delete (0.2.2-rc.1: list only), so its own <DSH_HOME>/sessions/<project>/<id>/ directory is removed. A failure refuses the delete (502 agent_session_not_removed) instead of leaving a row that returns on the next import. |
| Prompt Turn | Chunks, usage and notices; stop reasons forwarded. Compaction updates are not advertised, so a spec-compliant agent falls back to a normal message. |
| Content | Prompts carry text and, when the agent advertised image, images. Tool output and chunks expose embedded-resource text and name resource links. Audio is never sent. |
| Tool Calls |
tool_call_update merges as a PATCH; diff blocks become the Edit panel; permission requests park and are answered (or cancelled on Stop). Embedded terminal content is not rendered because terminals are not advertised. |
| Elicitation | Not advertised: no form/URL dialog exists, and advertising it would park the agent on a question nobody draws. |
| File System | Both methods served inside the session root. |
| Cancellation |
session/cancel answers every parked approval with cancelled; $/cancel_request answers the named one; an agent's -32800 answer closes the turn as cancelled rather than as an error. |
| Terminals | Not advertised: there is no bridge from an ACP terminal to the timeline, and advertising one would route shell work into a terminal the user cannot see. |
| Agent Plan |
plan entries feed the Todos topic through buildAcpTodos. |
| Session Modes | A mode config selector when published; otherwise the legacy modes list is synthesized into the same selector and writes go to session/set_mode. The composer offers the whole ladder in a dropdown (except omp-acp, which keeps the Plan toggle for its default/plan pair); a pick POSTs set_mode, flips optimistically, rolls back on refusal, and mode_changed/config_changed re-reads the authoritative value. An agent-initiated change also updates the persisted plan flag. |
| Session Config Options | Select options are adopted as published. boolean is not advertised because the selector UI is select-only, and an agent must not send a type the client cannot render. |
| Slash Commands |
available_commands_update feeds the composer's / pool; a command is sent as ordinary prompt text, exactly as the spec defines. |
| Extensibility |
_meta.steering is read at the result root; unknown methods answer -32601; unknown notifications are ignored. |
| Security Considerations | fs paths are canonicalized and root-checked; agent-authored text is rendered through the app's existing Markdown surface; no agent-supplied URI is fetched. |
| Errors | Codes survive as AcpRequestError; refusals to the agent use -32601, -32602, -32002, -32603. |
| Schema | Only the fields Kabmo reads are typed (protocol.ts), deliberately, so an adapter's newest field is not a compile error. |
Kabmo sends protocolVersion: 2 as its latest version, but the request also
carries the v1 field names (clientCapabilities, clientInfo). Migration says a
v1 agent reads a v2 request WITHOUT those fields and loses the client's file
system support, so carrying both is what lets a v1 peer answer 1 and still see
what it understands; a v2 peer ignores the v1 names as unknown fields. A strict
v1 peer that rejects version 2 gets one clean v1 retry — allowed because the
connection is still uninitialized — and no retry happens for a dead process or a
timeout.
Internally the model stays v1-shaped; v2.ts translates at the process
boundary:
-
initialize — role-agnostic
info/capabilitiesbecomeagentInfo/agentCapabilities; object support markers become booleans;capabilities.sessionimplies list/resume/close;session.deleteandadditionalDirectorieskeep their markers;authMethods.methodIdbecomesid.capabilities._metais merged where steering is read. -
session setup —
configId/groupIdbecomeid/group; initialavailableCommandsare adopted; v2 restore callssession/resumeand neversession/load(removed in v2), keeping the chat's agent id. -
updates — whole-message
agent_message/agent_thoughtupserts andtool_call_content_chunkare applied to the same accumulator; v2's singletool_call_updatecreates on first sight;pausedstays open andcancelledis final;plan_updatefeeds the same Todos topic;state_updategoes to the turn machine instead of the mapper; terminal/compaction updates are ignored (no renderer). -
prompt lifecycle —
AcpTurns.completion = 'state': thesession/promptresponse only acknowledges insertion (messageId), and an idlestate_updateends the turn. An idlestopReason: "error"becomes the failed outcome with the agent's message;-32800before insertion is a failure, after insertion it cannot be returned. v2 does not infer failure from an idle without a stop reason, so the v1 "silent answer is a failure" verdict is gated tocompletion === 'response'. -
permissions — the required
titleplus atool_call/commandsubjectare normalized into the v1toolCallthe approval queue and access tiers already understand. -
config writes —
session/set_config_optionadds v2's requiredtype: "id" | "boolean";session/set_modeis never called on v2 because modes are config options there. -
client APIs — v2 removed
fs/*andterminal/*; the v2 advertisement iscapabilities: {}, so nothing is promised that v2 does not define.
Verified with a scripted v2 agent over a real pipe: v2 negotiated, initial
config/commands adopted, streaming message + tool + plan produced the same frame
types as v1, and state_update idle closed the turn with end_turn. A real
omp 18.18.6 still negotiates 1 through the same hybrid request and keeps
session/load.
Deliberately outside this adapter, because the surface does not exist yet:
elicitation (elicitation/create), auth/login/auth/logout (auth methods are
normalized for the probe but no login control), Agent-owned terminal rendering
(terminal_update/terminal_output_chunk are ignored), compaction rendering,
and session/close (Kabmo kills the process). v2 background activity that keeps
updating after idle is also dropped by the turn gate: Kabmo's timeline has no
open message to attach it to, and pretending it were foreground would resurrect
a finished turn. session/cancel answers every parked approval, including one
v2 would keep open because it belongs to listed background work; the background
list is not tracked.
The page is one section per harness: the mark, the transport, the probed version, and the capability rows it actually published.
shared/lib/harness/status.ts derives one of five states from facts the card
already has, and the chip, the sentence under it and the disabled-reason on the
button all read that single derivation:
| State | Chip | Says |
|---|---|---|
ready (probed) |
ready |
claude answered as version 0.100.0. |
ready (built-in) |
built in |
Kabmo runs this transport itself — nothing to install or probe. |
not-installed |
not installed |
cursor: cursor-agent was not found on PATH, so it cannot be launched. + the install line |
needs-setup |
needs setup |
the AGENT's own refusal, quoted (Authentication required: …) |
unprobed |
not probed |
… has not answered yet — press Check status … |
The word blocked covered four of those at once while the fix differed in every
one of them: install a package, run a login, press a button, do nothing. Two
details are load-bearing and each was a wrong instruction before:
-
the sentence names the BINARY, not the harness id —
minimaxis launched bymcodeandcursorbycursor-agent, so "minimax is not installed" sends the reader looking for a package that does not exist; -
the install line belongs to
not-installedonly — telling a signed-out agent to install a package it already has is a wrong instruction.
Precedence is stated, not implied: a missing binary outranks a stale refusal (there is nothing to authenticate against with no binary on disk), and a refusal outranks "not probed" (something did answer). The state also drives SHAPE, not only colour: a filled dot, a slashed package, a warning circle or an empty ring, so a reader who cannot separate two low-contrast tones still sees a difference.
Pinned by status.test.ts — every state's words, the binary-name rule, the
precedence, and the shipped defect as an assertion: no state may render the bare
word blocked. What it deliberately
does not do is duplicate omp's own settings — Providers, Models, Agent and
Behavior stay omp-specific, and two write paths to one config file is the defect.
The sidebar files it under HARNESSES, a group of its own rather than a member of OMP. omp's group is one engine's own config (engine state, providers, agents, behavior, commands, MCP); this group holds OTHER agents entirely — a different transport, a different config file, one section per agent. Filed under OMP, the drawer read as "omp settings" followed by seven pages that are not omp.
SETTINGS_SECTIONS (src/shared/lib/settings/sections.ts) is the ONE list of
groups, imported by both the section type and the render loop. It used to be
written twice — the union and an array beside the drawer — so a group added to
one and forgotten in the other rendered nothing under it: no error, no empty
state, just every category filed there missing from the settings drawer.
Pinned by settings/groups.test.tsx: every category's group is drawn, the
headings equal the declared order (one per non-empty group), and every declared
category label is reachable — a count, because the bug this prevents dropped a
whole group and a spot check on one category would have passed.
A chat that was born in a terminal has no harness_sessions row and no omp
JSONL, so it cannot appear in the sidebar. Import sessions (Settings →
Harnesses → one agent) asks the agent itself through session/list, writes one
row per reported session, and emits sidebar-structure.
Measured rules:
-
No
cwdonsession/list. codex tears its app-server down before answering a cwd-filtered list (exit 0, 3/3 on 2.5.0; 2.7.0 fails without a cwd too). The rows carrycwd; Kabmo resolves each to a workspace folder and reports the rest as "outside your workspaces". -
Both ids are the dedupe key. A resumed chat whose load forked keeps
Kabmo's id in
session_idand the agent's inagent_session_id; checking onlysession_idimported a second row for one conversation (measured). -
The row is marked
origin = 'imported'. That marker decides restore eligibility. It no longer exempts Delete: an imported chat is removed from the agent's own history too (see "Delete removes the AGENT's copy too"), because forgetting only Kabmo's row made the next import restore it. -
The agent may shut down while listing. A first
session/listhas answeredACP agent exited (code 0)before any frame; the import retries once with a fresh process and never retries a real refusal (auth, launch). -
codex execsessions are invisible. The adapter'ssourceKindsexcludesexec; TUI (cli) and adapter-created (vscode) sessions are listed.
A spawn per installed harness on sidebar load is not a read — the same reason probing never runs there. The automatic pass therefore has its own clock and its own per-harness switch:
-
ON by default. The switch turns it OFF for one harness; the stored value
is the EXCLUSION list (
app_settings.harness_auto_import_disabled), so a harness added later arrives ON with no migration. A build from the first cut stored the ENABLED ids underharness_auto_import; that row is migrated once. - Switching it back ON imports once immediately. A switch whose effect appears a quarter-hour later reads as broken; the counts land beside it.
-
Boot, every 15 minutes, and when the sidebar is opened. The boot tick
runs immediately AFTER the probe pass finishes: its cache is what says which
agents answer
list, and sequencing avoids two agents per harness competing. The sidebar route triggers a pass at most once every 30 s, so a terminal chat followed by a reload appears without waiting for the clock. One clock per PROCESS (globalThis),unref'd, with an in-flight guard so a slow pass cannot overlap the next. -
A target must be: not switched off, roster on, launchable, and its cached
probe must advertise
list. A spawn that can only fail is not a discovery.omp-acpis skipped — it writes omp's JSONL, which the scan already lists. - Sequential, and one failed agent does not stop the others. The log names the harness and the agent's own error.
-
A session with no transcript is not imported, and not listed. An agent
reports every session it CREATED, not the ones that were used: measured on
this machine, 114 of opencode's 131 sessions held zero messages, and the
sidebar drew them as
New session - <timestamp>rows that open an empty chat.sessionsWithoutTranscript(lib/harness/session-transcript.server.ts) reads the store Kabmo can name — opencode's SQLite (message/session_message), zcode's SQLite (message), antigravity's per-conversation SQLite (steps), dsh'ssession.v4.jsonl.zstd, claude's project.jsonl, codex's rollout — and answers "provably empty" only for those. A non-empty file is not a transcript: dsh writes a header plus its setup events (permission/preset,sandbox/mode,approval/policy) before the first prompt, so the dsh check decompresses the zstd JSONL and looks for aturn/startor a message event — measured, every dsh session on this machine held those four lines and nothing else. A harness with no readable store (pi,qwen,minimax,grok,hermes,kimi,cursor,command-code,jcode) yields no verdict and its rows are kept: hiding a real chat is worse than listing an empty one. The same rule filters omp's own scan (messageCount > 0— 208 of 1793 files on this machine carried a header and no message), and the import result reports the skipped count asempty. - The pass never DELETES rows: a terminal session removed in the agent's store
stays in Kabmo until the user archives or deletes it. A DELETE writes a
tombstone (
deleted_sessions), and the pass skips every id in it — so a chat the user deleted does not return even when the agent still lists it.
Pinned by auto-import.server.test.ts (switch round-trip, built-in/omp-acp
refusals, one failure does not stop the pass), session-transcript.server.test.ts
(each store's empty/present verdict, and the no-verdict case), and the card's DOM
test (the switch renders the server's state and names its harness; the manual
button reports the counts).
The sidebar row is not a transcript. A v2 agent replays retained history only
when session/resume carries replayFrom: { type: 'start' }; without it the
open tab is empty. Measured on codex 0.169.0 through codex-acp@2.5.0: 8 frames
(user message + chunk, assistant message + chunk, title, usage, idle) in 3.7 s,
no duplicate thread.
Two gates dropped those frames and both were correct for a live turn:
- the turn gate (
acceptingFrames) has no open turn during a resume; - the mapper treats
user_messageas a receipt for a bubble the composer already drew, so every replayed question vanished.
AcpReplay opens a bounded window (closed by state_update: idle, or 1.5 s),
buffers the frames, and AcpFrameMapper.setReplaying(true) materializes user
turns. transcriptFromReplay reduces the last snapshot per message id into
ChatMessageData, and the restore command persists it to chat_sessions once.
Every later open is an ordinary read: no agent, no auth, no second replay.
A blocked probe no longer refuses a restore: codex answered "Authentication
required" before login, and that stale record locked a chat that could already
resume. The gate now ignores capabilities.blocked.
The restore path assumed every chat Kabmo spawned had a client-written
transcript. An orchestration worker (or a CLI child) has no tab, so nothing
wrote chat_sessions: measured on a real antigravity worker, the row was
messages='[]', harness_sessions.origin='', session_relations.parent_session_id
named the coordinator, and session_answers held the final report — the
conversation existed only in the agent's store, and the open tab was empty.
Two halves fix it:
-
AcpTranscriptRecorder(lib/harness/acp/session-transcript.server.ts) is attached instartAcpSessionand folds the frames the driver already receives (user_turn,message_*,tool_execution_*) intoacp_transcripts. It hydrates from the newer ofacp_transcriptsandchat_sessionson a resume, merges by message id (a user turn by its text, because the composer's optimistic id is local to the tab), and writeschat_sessionsonly when its copy is AHEAD — so an open tab's richer row (attachment chips, notices) is never replaced. A restore session is skipped: it persists its own replay. -
The loader reads
acp_transcriptswhenchat_sessionshas no assistant row, and the restore gate is now the LOCAL TRANSCRIPT, notorigin: a spawned child with no answer is eligible for the samesession/loadreplay an imported chat uses. A user-only row is a prompt whose tab closed, not a transcript.
Pinned by session-transcript.server.test.ts (prompt/answer, tool pairing,
resume hydration, notice preservation), the loader's child cases in
routes/chat/session.test.ts, and restoreEligible in
routes/agent/harness-command.test.ts.
session/resume on a Codex thread that another client owns (the TUI, the app,
an IDE) answers thread_active_writer and starts nothing. That is the normal
case right after using the terminal, and it left the imported chat empty.
codex/transcript.server.ts reads the rollout file (CODEX_HOME or
~/.codex/sessions/**/rollout-*.jsonl) for DISPLAY only: the sidebar row still
comes from session/list. It drops Codex's own developer turns and the
<environment_context> user turn, pairs function_call with its output, and
returns the same ChatMessageData rows the timeline reads. The loader uses it
only when the imported chat has no local transcript, and then it does not
ask for a restore — so the conversation is visible while the TUI still holds the
lock. Continuing still needs that client closed; the agent's own message says
so.
A v2 peer validates the list strictly: every entry is tagged (type: 'stdio')
and a stdio command must be ABSOLUTE. Kabmo sent the v1 shape, and both codex
and claude answered Invalid params — no session at all, on every spawn/resume
with an MCP server configured. toAcpV2McpServers converts after initialize
(the first point the negotiated major is known), resolves a bare binary on the
toolchain PATH, and skips an unresolvable server with a log line rather than
failing the chat.
POST /api/agent/:id is Kabmo's one lazy-spawn path, and it used to have exactly
one resume: the .jsonl locator. That is omp's store, so a chat on any other
harness had no resume at all — measured on a claude chat after a restart, whose
row was in the sidebar: both prompt and get_state answered
{"error":"Session not found"}, because resolveSessionPathOr404 found no file
to hand omp --resume.
resumeRecordedHarnessSession (routes/agent/command.ts) now reads the harness
out of harness_sessions and respawns a non-omp chat on its OWN agent, passing
the id the AGENT reported so session/load can restore the conversation.
Measured after the fix, from a second instance (so nothing was live): the same
prompt answered {"success":true,"data":{"agentInvoked":true}} and spawned
@agentclientprotocol/claude-agent-acp as a child of that server.
Three rules the code owes:
- an id no catalog harness claims spawns NOTHING. A retired adapter must not be guessed at from a stale row, so the old 404 stands.
-
an EMPTY
agent_session_idmeans "the same as ours" (saveHarnessSessionwrites it blank in exactly that case, when the agent's id equals Kabmo's), so the row's own id is the value to send. Passing''starts a FRESH agent session under this chat's id and throws the conversation away silently. -
omp-acpis excluded even though ACP is what it speaks. It writes a session file, so the locator resumes it in place — same chat, same id, one row.session/loadon omp FORKS (measured: a load for01a1b49f-…answered id01a1b4cc-…), and a forked id is a second record: a second sidebar row for one conversation, which is exactly what the merge rule prevents. The recorded mark is rewritten toomp-rpcon that path, which is truthful — RPC is then the transport that ran it. -
a non-omp load forks too, and the record FOLLOWS the chat. Measured on a
resumed
claudechat: the agent answered340f24a3-…for5c5e776e-…, and the spawn's own record of that id drew an empty twin row beside the conversation.repointHarnessSessiontherefore moves the chat's row onto the agent's id and drops the twin — the chat keeps the id the tab, the transcript and the layout name, and the nextsession/loadsends the id the agent actually resumed into.
A harness whose probe advertises neither session/load nor
sessionCapabilities.resume is refused in words, because the only alternative is
a fresh agent session under an old chat's id. When loadSession is absent but
resume is present, the handshake calls session/resume instead: it replays
nothing and creates nothing, so the chat keeps the agent id and only the config
state the reply carries is adopted.
Pinned by the two cases in routes/agent/command.test.ts: a retired id keeps its
404 and spawns nothing, and a recorded non-omp chat reaches its OWN launch line
(the failure names the configured command, not "Session not found").
The composer used to draw Plan and Goal on every chat. For a non-omp ACP agent
that is a button whose only outcome is a refusal: there is no /kabmo-mode
extension on the wire, and its own mode selector is the only place plan can
live. Measured: press Plan on a claude chat and the extension prompt reached
the MODEL as prose, which then refused the next mode command as "already
processing".
modeAvailability (client/hooks/chat/timeline/modes.ts) is the pure rule, and
it is injected with the two facts it needs:
| Harness | Plan | Goal | Why |
|---|---|---|---|
omp-rpc |
shown | shown | omp carries the extension AND the RPC goal driver |
omp-acp |
shown | shown | Plan is the agent's selector; Goal is Kabmo-owned with the ACP driver |
another ACP agent that publishes a plan mode value |
shown | shown |
applyHarnessMode maps Plan to the agent's own mode selector; Goal is Kabmo-owned |
| another ACP agent without one | hidden | shown | nothing can express Plan; Goal needs no agent mode |
| unknown (no row, no spawn record, no pick yet) | shown | shown | the row may simply not have arrived |
The value comes from the CALLER, never re-derived: chat-timeline/index.tsx
already holds useSessionHarness's answer (sidebar row → spawn record → pending
PICK) and passes it in. A second resolution inside the timeline hook read only
the first two, so a pending claude chat — picked in the tab strip, not yet
spawned — still offered Goal, and arming it did nothing: harnessModeSelection
forwards plan on that path and silently drops a goal. A pick the composer
renders must be the same pick every consumer reads.
applyHarnessMode (routes/agent/command.ts) is the other half: for a live
non-omp session a mode command becomes set_mode('plan') / set_mode('default')
where the agent publishes plan, and is refused in words where it does not
(<label> has no plan mode, <label> has no goal mode). Pinned by
mode-availability.test.ts and the mode cases in command.test.ts.
Goal on ACP is Kabmo-owned. The agent has no /kabmo-mode extension (and
omp-acp's extension writes to a transcript this transport cannot rely on), so
acp-goal.server.ts stores the record in harness_goal_state, the turn-end
driver audits the closed message, and it opens the next turn itself. The AUDIT
runs on the same harness, not omp RPC: acp-audit.server.ts opens a disposable
ACP session with the same launch command/env (and therefore the harness's own
tools/MCP setup), applies the chat's own model (runModel), sends the shared
classification prompt, and reads the JSON verdict. No omp -p is spawned and
the omp goalAuditModel setting is not applied to an ACP chat. Markers travel as
extension_ui_request / notify frames on the session stream, which the
composer's fold already parses. ACP reports context tokens (not spend), so the
goal budget is enforced on the summed per-turn peak used; tokensUsed on the
strip is that figure. The continuation is a normal prompt, not a hidden custom
message. A GUIDED goal is approximated as a create whose objective is the
operator's message: a real interview ends with the model calling a goal tool to
write the objective, and an ACP agent without that extension cannot do it. Plan
mode is still the agent's own selector.
-
Thinking.
probe.thinkingis the agent'sthought_levelladder and is a SESSION selector, so every ACP model row carries it (harness-models.ts). Without that the composer disabled the picker even thoughset_thinking_level→session/set_config_optionis implemented. -
Plan state survives a reload.
GET /api/sessions/:id/modesused to answer 404 for every non-omp ACP chat (no omp transcript), so a plan mode the user turned on came back OFF. The route now asks the live session's ownmodeselector (applyHarnessMode(…, {scope:'plan', action:'state'})). -
Selector IDs, not categories.
session/set_config_optionkeys on the option'sid; the category only classifies it. The writes used the literalmodel/thinking/mode, which worked only on agents whose ids happened to use those words. Every write now passesoption.id, measured against a fake agent publishingsel-model/sel-thinking/sel-mode. -
Model identity on reopen. A non-omp ACP chat has no JSONL.
/api/chat/:idnow answers the live session'sget_statemodel/thinking, falling back to the last run'ssession_stream_staterow after a restart. Before it, the composer matched the session id against omp's registry, never found it, and displayed an omp model over a chat running a different agent. -
A model pick must reach the footer, three ways.
set_modelis a config write, not a respawn: the session adopts the reply list (or the requested value when a harness returns{}), renames the livesession_stream_staterow, and emitsmodel_changedso/api/chat/:idis re-read. In addition everymessage_update/message_endis stamped with the session'srunModel, which is whatRunFooterwas designed to read; before it every ACP footer fell back to the SESSION's model and an idle chat kept showing the first pick forever. Verified against a fake agent that answerssession/set_config_optionwith{}:runModelmovedfirst → second, themessage_endcarried{model:"second", provider:"p"}, and amodel_changedframe arrived. -
A silent turn is a REPORTED error, not an empty bubble. pi-acp answers
session/promptwith{}and sends no frames on a provider failure; the ACP driver turns that (and a whitespace-only chunk) intoprompt_error. The client used to log it and leave the optimistic row blank. It now attaches the reason to that row —MessageItemalready rendersmsg.erroras its error alert — and consumes the placeholder so a late frame cannot fill it. A failed prompt emits the agent's error ONCE:finishno longer appends its generic "no answer" verdict on top. Warning/error ACPnoticeupdates also become notice rows instead of console lines. -
Slash commands are the AGENT's.
/api/settings/commands?sessionId=returns the agent'sget_commandslist even when empty; falling through to omp's utility catalog offered commands from a different agent./api/settings/skillsreturns none for a live non-omp chat for the same reason. The client's TUI-only refusal is scoped toomp-rpc/omp-acp— claude publishes/clearand/statusitself, and the omp table used to refuse them before they left the composer. -
@agents are omp's. The@pool drops the omp subagent rows on a non-omp harness (loadComposerItems(..., { includeAgents:false })) andbuildPromptTextleaves the token as typed: the rewrite names omp'stasktool, which those agents do not have. File mentions still translate to@path, which remains agent-dependent — ACP'sresource_linkis the standard form and is not sent yet. -
The
@harness:<id>:model tail completes from that harness's catalogue. Before this, the popup saidNo matching files or agentsfor the model the hint told the user to type.detectComposerTriggernow returns amodelphase whosereplaceFromsits AFTER the second colon, so a row inserts only the--modelvalue (provider/idfor omp, the bare ACP value) and the typed mention survives. The rows areharnessModels— the same list the model dropdown's tab shows, live session before probe — and the id is resolved throughharnessIdForName, one table shared withparseHarnessMentions, so@harness:omp:scopes toomp-rpc. Measured in the browser: omp listed 319 registry models, claude its 5 selectors, and Enter left@harness:claude:claude/opusin the draft with the popup closed. -
Tool output and renderer key. ACP nests text as
{type:"content", content:{type:"text"}};acpToolOutputflattens it ontotool_execution_start/update/end, and the shared fold prefers thatoutputover re-walking the raw envelope. The transport's ownkind(execute→ bash,search→ grep) rides the message block astoolType, so a vendor name still draws the right panel. Atool_callannounced alreadycompletedis closed immediately — leaving it open made turn-end report a success as an error. -
Panels. A
{type:"diff"}content block becomesdetails.diff/pathfor the Edit card.planupdates become the Todos payload, andusage_updatefeeds the Context ring/panel (contextUsage, cost, user/assistant counts) through the telemetry topic. A turn end republishessession-data-dirty, and the last snapshot is persisted (harness_usage_state) so a reopened chat's ring still fills after the process is gone. -
Queue. The stored model snapshot is best-effort per command: a harness with
no model/thinking selector used to make
set_modelthrow, which aborted the delivery and re-queued the user's message forever. -
Undo/Retry work on BOTH omp transports, and refuse on the other ACP
agents. The action calls the omp JSONL rewind endpoint, so the rule is a
capability, not a transport:
harnessSupportsRewind(shared/lib/harness/rewind.ts) allowsomp-rpcandomp-acp—omp-acpwrites the SAME session file, and the endpoint destroys its live child first (that child holds the old context and is the only other writer), then truncates. The next prompt resumes the truncated file over RPC, becausesession/loadon omp forks andresumeRecordedHarnessSessionexcludesomp-acpfor exactly that reason. Another ACP agent (claude, codex, opencode, …) keeps its history in its own store and ACP defines no truncation (session/loadreplays it, a fork copies it), so it is refused in words BEFORE its child is touched rather than truncating a file it does not read. The endpoint refuses a live non-rewindable harness withharness_not_rewindable; the client reports the same sentence. -
A subagent that outlives its turn is recovered from
session/load. antigravity ends the turn right afterinvoke_subagent(the tool call is markedcompleted, the agent sends a holding sentence,session/promptanswersstopReason:"end_turn") and holds the subagent's completion until the next request — upstream google-antigravity/antigravity-cli#1461, measured on 1.5.3: zero frames for 60 s, while the transcript already held the answer. Kabmo starts asession/loadprobe for a closed message carryinginvoke_subagent/spawn_subagent; the replay is swallowed (it repeats the whole chat) and the text past the holding answer is emitted as a follow-up run only once two replays repeat it, because a single replay can be a prefix while the model is still writing. Measured end to end: holding answer at 15.3 s, image and final answer delivered at 51.8 s. An emptysession/promptis refused (-32602 Empty prompt), andsession/resumeneither replays nor subscribes;session/loadis the only request that surfaces the held frames. -
Not built:
@file:mentions travel as@pathtext, not ACPresource_linkblocks (agent-dependent); Kabmo's own subagent roster and compaction controls remain RPC-only (an agent's INTERNAL background subagent is recovered by the probe above).
-
A harness is a row, not a build.
custom_harnessesholds{ id, label, initial, command, env, note };src/server/lib/harness/custom.server.tsloads it into a process-wide registry and publishes a descriptor to the shared catalog. The ACP transport was already generic — a launch line is a command vector, the handshake is one implementation, and the settings page reads/api/harness— so nothing in the session path is per-agent. -
HarnessIdis open, the built-in tables are not.HarnessId = BuiltinHarnessId | (string & {})keeps autocomplete and typo errors for the shipped ids while letting a runtime id through. Tables that must be COMPLETE (HARNESS_CATALOG,HARNESS_MCP_FACTS) are keyed byBuiltinHarnessId; tables that may be partial (HARNESS_LAUNCH, provider/update facts) stayPartial<Record<HarnessId, …>>. -
Every fact has a fallback, and each one is a decision. MCP delivery →
acp(the only transport the add form offers); provider facts →kind: 'none'(no registry editor); update facts → none (no Update button); fork →none(the probe is still authoritative forsession/fork); local transcript →false(no rewind, no message-anchored fork). A custom harness therefore gets the generic ACP behaviour instead of a crash on an undefined table entry. -
Launch resolution reads the registry.
launchFromConfig/resolveLaunch/commandAvailableuseHARNESS_LAUNCH[id] ?? customLaunch(id), andopenAcpSessionawaitsensureCustomHarnesses()before asking — the resolver is synchronous, the row is not. The boot loads the registry before any probe or spawn. -
A removed harness is still named.
knownHarnesskeeps any well-formed id even when no descriptor exists, so a chat that ran on a deleted harness reports that id and the resume path refuses with "No launch command is configured for X" instead of silently rewriting the chat toomp-rpc. Removal deletes the definition, its config key, its probe row and its disabled entry; it does NOT deleteharness_sessions. -
The UI is roster-driven.
/api/harnessreturnscustom: trueandinitial; the client registers the descriptors before rendering,HarnessGlyphdraws the initial when there is no vendor mark, and the settings sidebar rebuilds its HARNESSES section from the live roster (settingsCategoriesFor) rather than the build's static list. Settings → Harnesses → Add an ACP harness is the only writer.
-
harness_eventspersistence — needed bydsh, which has noloadSession. - The discover dialog with a count preview.
- Hosting an agent's terminal auth flow in Kabmo's own PTY.
omp holds a per-session lease on ~/.omp/run/session-owners/<id>.lock for the
life of the process that opened the session; a second process that resumes a
held session forks itself (reason: "open-elsewhere"), which is the duplicate
sidebar row a user sees. Kabmo asks "is it held" itself
(src/server/lib/omp/session/lease-probe.server.ts) so it can refuse before
spawning and relay to the owning instance instead.
Linux keeps flock(2) and record locks in separate spaces, so the primitive
has to match the one omp takes. omp 19.0.1 moved Linux from an abstract socket
to an open-file-description lock (F_OFD_SETLK on the .lock file). A
flock-based probe — what this module was until that pin — acquires a lease
another omp is holding and answers "free", so the guard silently stopped
working on the platform where it now had a file to look at. Measured in a Linux
container (bun 1.4.4, 2026-11-20) with a second process holding the write lock:
flock says held? false
ofd getlk l_type: 1 => held? true # F_WRLCK
free: flock held? false ofd l_type: 2 # F_UNLCK
The module is lease-probe.server.ts (it is no longer flock-only): flock
with LOCK_EX|LOCK_NB on macOS, F_OFD_GETLK on Linux — a query, so the probe
never takes the lock it asks about. holdLeaseForTest takes the same primitive
per platform, so the detached-holder test in ownership.server.test.ts holds a
lease omp would recognise, and lease-probe.server.test.ts pins the Linux half
against a lock it takes with fcntl directly (a regression to flock fails it
rather than passing tautologically — verified by reverting the branch).
A 32-bit Linux struct flock is a different layout (16 bytes, not 32) and is
refused as null ("cannot answer") instead of guessed at; a null is not
"free", and ownership.server.ts falls back to the instance registry.
Using Kabmo
How it is built
- Architecture
- Runtime and toolchain
- App shell and layout
- Chat stream and tools
- omp engine and settings
- Plugins, skills and automation
- Desktop integration
- Workspace panels
- Providers
- Harnesses
- Tool panels
Shipping it
History