Repository navigation
Omp Engine and Settings
-
src/client/data/settings/omp-schema.jsonis GENERATED, never hand-edited.bun run omp:schema(scripts/omp-schema.mjs) importsorderedSettings()from the installed@oh-my-pi/pi-coding-agentandSETTING_TABS/TAB_METADATAfrompi-tui, and writes the panel's tab/group/label/editor metadata from that.bun run omp:schema:checkregenerates in memory and exits non-zero when the file is stale, so a stale schema is a CI failure rather than a shipped panel — that gate is theSettings schemajob in.github/workflows/gates.yml(called byci.yml), deliberately separate fromchecksbecause the generator imports the INSTALLED package (this repo does not depend on@oh-my-pi/pi-coding-agent) and a cold Bun global install would otherwise sit in front of every other check. The gate installs the PIN in.github/scripts/install-omp.sh, so the schema and that pin are bumped TOGETHER — a schema generated from a newer omp than the pin is reported stale by CI, and a pin newer than the schema is the same failure in reverse (measured twice:948f9e4refreshed the schema from a local 18.10.3 with the pin at 18.10.0, and the pin then stayed at 18.10.3 while 18.11.0 was installed, so CI stayed green over two rowsomp config setrefuses). It was documented here before it existed: no workflow called the script until 2026-10-12, which is how the file drifted 9 rows behind omp 18.9.2 unnoticed (as of omp 18.16.0: 438 upstream entries,10 tabs / 582 settings, and 0 of Kabmo's 461 merged keys rejected byomp config list --json). The JSON sat frozen from the Remix→Elysia migration (2026-09-18) until this existed: 157 live settings had no row at all (everytitle.*,tui.renderSvg,tui.autoGraph,task.completionProbe,skills.*,ida.*,searxng.*,gc.*,memories.*,compaction.v2RetainedMessageBudget,browser.tern,stream.serverUrl,telemetry.otlpExportEnabled), and 12 rows Kabmo still offered were rejected byomp config getwithUnknown setting:—stt.modelName,providers.tts,tts.localModel,providers.webSearchOrder,irc.timeoutMs,providers.autoThinkingModel,providers.imageOrder,providers.memoryModel,providers.tinyModel,providers.unexpectedStopModel,providers.webSearchExclude,providers.webSearchGeminiModel— an editor whose write was guaranteed to fail. The generator reads the PACKAGE, not the binary, and now pins it to the script's own version.ompcan self-update its compiled binary (omp update) while~/.bun/install/global/node_modules/@oh-my-pi/pi-coding-agentstays behind — measured at 18.17.0:omp --versionansweredomp/18.17.0while the package still said 18.16.0, andbun run omp:schemaregenerated the OLD 438-row file. A candidate is now used only when itspackage.jsonversion equalsOMP_VERSIONin.github/scripts/install-omp.sh; an explicitOMP_SCHEMA_PACKAGE_DIRwith the wrong version is an error. A machine whose onlyompis the standalone binary has no global package, so a miss underOMP_SCHEMA_PACKAGE_DIR/ reponode_modules/ Bun's global install provisions@oh-my-pi/pi-coding-agent@<pin>into$XDG_CACHE_HOME/kabmo/omp-schema/<pin>and generates from there. That cache is outside PATH, so Bun'sbinlink cannot collide with the standalone binary (EEXIST) and no secondompcommand appears. CI is unchanged:install-omp.shinstalls the pin globally and the generator finds it first. -
The generator reads omp's own source, not its bundle. The published package ships
src/besidedist/, and the definitions live insrc;dist/cli.jsis minified, so itsre({…})calls only partially evaluate (the enum anduishape survive, an expression-valued default does not). A setting with nouiblock has no row in omp's own panel either, so it is deliberately not carried — andschema-extras.tsstill supplies Kabmo's documented extras, which never shadow an upstream entry (asserted byschema.test.ts). -
The credential marker is
credential, notisCredential.orderedSettings()yieldsSettinginstances, but the generator destructures{ definition }— the rawSettingDefinition— sodefinition.isCredential(a getter on the instance) was alwaysundefinedand NO row ever carriedcredential: true. Every credential row therefore rendered in plain text, includinglive.apiKeywhen omp 18.22.1 added it. The generator now readsdefinition.credential === true || definition.ui?.secret === true, the same rule as omp's ownSetting.isCredential; four rows mask (live.apiKey,mnemopi.embeddingApiKey,mnemopi.llmApiKey,hindsight.apiToken), asserted inschema-releases.test.ts. -
task.completionProbereplacedtask.completionProbeMsin omp 18.5.0 (0→ off, any period → on), so the old key is gone from the schema and offering it would write a key the binary rejects.
-
A role row is a MODEL PICKER, not a text field.
modelRolesholds aprovider/modelselector, which a user cannot type reliably and which fails silently when mistyped — omp falls back to its own resolution and the role runs on a different model than the panel shows.RoleRow.tsxrenders a<select>grouped by provider (native type-ahead, keyboard and screen-reader semantics for free), and the stored value is always an option even when the catalog no longer lists it (a model removed from models.yml, a provider that lost its credential, a catalog read that failed): dropping it would make the select display a model config.yml does not hold, and the next edit would write that one over it. -
The candidates come from
omp models --json --kind all, not fromget_available_models. The RPC answers CHAT models only (modelRegistry.getAvailable()defaults to kindchat), so the five kind roles would have offered nothing; the CLI lists every kind (~1.3 s, cached 60 s onglobalThis). The cache is dropped byinvalidateModelsCaches— the same signal every provider/model mutation already emits — because a model that disappeared must leave the role pickers too. A catalog failure is REPORTED (candidatesError) rather than thrown: the roles live in config.yml and stay editable without it, and an empty dropdown with no explanation reads as "no models exist". -
The role table is ONE shared module (
src/shared/lib/omp/config/model-roles.ts), read by the editor, the pickers and the tests. It mirrors omp'sMODEL_ROLESat 18.12.6 — includingwidget("Job widgets"), which this panel had omitted, making it the one role unreachable from the console. Each role's upstreamacceptspredicate is flattened into a catalog-kind list;webadditionally admits a chat model declaring a grounding transport, which the CLI's JSON does not carry, so that one case is awebCapableflag androleAcceptsCandidateis the single predicate. -
A preset is Kabmo's own record, in
model_role_presets(src/server/lib/model-roles/{schema,store}.server.ts). omp has the same idea upstream (modelPresets.<name>driven by/modelpreset), but that surface is TUI-only and Kabmo does not own that key — a second writer on a file omp rewrites is how a config gets clobbered. The preset's whole map is one JSON column: it is applied as a UNIT, which is the only operation that exists.nameisCOLLATE NOCASE UNIQUE, and a collision is reported as a sentence ("A preset named “cheap” already exists") rather than the SQLite constraint text. -
Role ids are NOT narrowed to the built-ins.
modelRolesaccepts custom role ids and omp adds them to its own role list, so filtering a preset's keys would silently delete a custom role the moment it was applied — the map is written whole, and a filtered copy is an edit of the live config. Only keys that cannot be a role name (and empty selectors) are dropped. -
PUT /api/model-roleswrites the whole map; that one verb serves both a single row edit and applying a preset. config.yml holds the map whole either way, and two writers is how a preset and a row edit end up disagreeing. The client adopts the server's echo, and a REFUSED write restores the previous map (useModelRoles) — leaving the optimistic draft on screen after config.yml rejected it shows an assignment that does not exist, and the next edit builds on it. -
The selected preset and "in use" are two different facts.
in useis derived by comparing the live map with the preset, so there is no stored "last applied" flag to go stale. The SELECTION is not: tying it to the comparison madeUpdateunreachable in the exact flow it exists for — pick a preset, tweak one role, save the tweak back into it — because the edit moved the picker toCustomand disabled the button. The picker therefore readspreset · modifiedwhile they differ,in useonly while they agree, andUpdate/Deletealways target the selected preset (disabled only with no selection). Delete confirms inline;Save as…names a new preset. -
The first open snapshots the roles an install already had into ONE preset (
seedPresetFromCurrentRoles, called from theGETloader). A machine that has been running omp for months has a fullmodelRolesmap and an empty preset table, so the picker would offer nothing until the user hand-saves what it is already running. Three cases step aside and still spend the one run: an EMPTY map (a fresh install has nothing to snapshot), a table that already holds a preset, and MOCK mode (a demo must not write rows into a real database). The name isDefault— what it is, not a strategy claim the seeder cannot make — and theapp_settingsmarkermodel_role_presets_seededis written on EVERY deciding path, the same ruleworkspace_sync_ranfollows: "the table is empty" cannot separate never-seeded from user-deleted, so without the marker a deleted preset would come back on the next panel open. Verified end to end: a temp install with four roles came back from its firstGETwithDefaultholding exactly that map, a secondGETdid not duplicate it, aDELETEfollowed by anotherGETstayed empty, and the marker readtrue. A failed insert is swallowed (the panel's ownSave as…is the manual path) and still spends the run, so a config omp rejects cannot make every open retry. -
The panel's role wiring lives in
useModelRoles(src/client/hooks/settings/model-roles.ts) — the load is still the panel's singlePromise.allso one spinner covers the screen, henceapplyPayloadbeside the three writes.
- Search is a WHOLE-SCHEMA view, and the tab strip is HIDDEN while it is active. The results have always been global (they span every tab), so leaving the pills on screen made a tab click look broken: the highlighted tab changed and nothing in the results did. The strip is replaced by a summary line ("Searching every tab — N matching keys"), and each tab pill carries its own visible row count under the current config snapshot, so an empty tab is recognisable before it is opened.
-
Resetis offered only for a key config.yml actually holds.omp config list --jsonomitsvaluefor an unset key, andomp config reseton one is a silent no-op — the row's reset button was clickable and did nothing. It now readsThis key is not set — omp already uses the schema default. -
A row's text editor commits on blur, Enter or its own check button; Escape abandons the draft. It used to commit on blur only, so Enter did nothing at all, and a draft that could not be parsed (a trailing comma in a JSON array, a half-typed number) reverted with NO message — which reads as "saving is broken".
src/shared/lib/omp/config/row-value.tsnow returns the parsed value or a sentence naming the shape the key wants, and the row prints it under the field. - Credential rows get a reveal toggle. A password-type field with no way to check what was pasted is a field users get wrong once and never trust.
-
A boolean row's
savedbadge comes from the SERVER's answer. Measured:colorBlindModetoggled in the browser wrotetrueto config.yml and the row state matched, but omp does not validate a theme name, sotheme.dark = "definitely-not-a-theme"is a SUCCESS — a panel cannot use "the value looks wrong" as its failure signal. A real refusal (Unknown setting: <key>) renders omp's own sentence under the row. -
Extension toggles are switches with a per-row pending state and a refusal banner. The row used to be a
<select>whoseonChangeignored the chosen value, and a failed write wasconsole.erroronly — so the row could show a state config.yml did not hold. The empty case now says where extension modules are looked for instead of returningnull(a panel that vanishes is indistinguishable from a broken one). -
setExtensionDisabledread the list throughdoc.get(), which returns a YAML SEQ NODE.Array.isArrayon a node isfalse, so the list always looked empty: disabling replaced every other disabled id, and re-enabling found its own id "absent", answered "nothing to do", and left the extension disabled forever. Measured on a real config (disabledExtensions: [extension-module:smoke]→ POSTdisabled: falseansweredchanged: false, file untouched).valueAt(doc, ['disabledExtensions'])unwraps the node andseqAtedits the existing sequence in place. Pinned by two cases that fail on the old code. -
A preset's name form stays open until the preset is STORED.
commitNewclosed it on the click, so a refused name ("A preset needs at least one role assigned", "A preset named “cheap” already exists") threw away what the user typed. The bar also states how many roles carry an override (1 / 16 set) — the one number that says whether the map does anything. -
A failed config read is REPORTED, never rendered as defaults.
GET /api/settings/omp-configanswers{error}with a 500, and the panel used to drop it; it now shows the sentence with a Retry, and keeps the rows writable.
-
The Agents panel reads and writes omp's OWN definition files (
~/.omp/agent/agents/*.md,<workspace>/.omp/agents/*.md). It used to POST into a Kabmo-local mirror, so "Create Agent" reported success and omp had no agent to load. The route is now{type: 'write'|'delete'}overwriteAgentDefinition/deleteAgentDefinition, and every answer carries the re-read list. -
The field set is omp's
parseAgentFieldsat 18.16.0, not Kabmo's invention:name,description,tools,spawns,model,thinkingLevel,blocking,structured,prewalk,advisor,autoloadSkills,readSummarize, plus the body as the system prompt.mode,temperatureandtop_pare NONE of them — the pane offered all three, and editing them changed a file omp never reads. They are gone fromAgentItem, the pane and the mock data; the pane now editstoolsandspawns, which omp does read. -
A write edits the frontmatter IN PLACE. Re-serializing an owned key set deleted the keys the panel does not own: a shipped agent's block-list
tools:and its nestedoutput:schema vanished the moment its prompt was saved.writeAgentDefinitionreplaces an owned key where it stands, appends one the file lacks, and keeps every other line verbatim;tools: undefined(an untouched field) leaves the existingtools:alone. Measured on a real~/.omp/agent/agents/scout.md: after an edit, its five-linetools:list and 20-lineoutput:block were byte-identical and onlymodelmoved. -
modelis written as a YAML block list by omp's own shipped agents, so the scalar-onlyparseFrontmatterinyaml.tsread every one of them as having no model.parseAgentDefinition(agents.ts) handles both the scalar and the sequence form, andthinking/thinking-levelas aliases ofthinkingLevel. -
A definition needs a
description, and omp refuses to load one without it. The pane says so, and refuses an empty system prompt before sending: both would otherwise write a file omp silently ignores or an agent that does nothing. -
The model picker is the LIVE
/api/modelscatalog, grouped by provider, not the hardcoded display-name list the pane carried (gpt-4o,deepseek-reasoner-r1, …) — a value nothing reads and a name no provider serves. -
A rename writes the new file and deletes the old one in the same request (
previousFileName), so one definition cannot survive under two names.
-
useCrudListresolvessave/removewith{ ok, error }, and a pane sets its badge from that. Every panel used to paint "Saved successfully" the instant the button was pressed: a duplicate agent name, a read-only native file or a rejecting validator all showed a success over a row that had not changed. The shareduseWriteFeedback(src/client/hooks/settings/write-feedback.ts) ownssaving/saved/error, keeps the server's sentence, and is the only thing that flips the badge. Its own test pins a landed write, a refusal, a sentence-less refusal, a thrown request and the recovery path. -
A failed list read is
loadError, not an empty list. "No agents" and "the read failed" are different facts, and the sidebar now says which with a Retry.useCrudList'sreload()exists for that. - A delete asks first, in place. The Agents, Commands, MCP and Skill panes deleted on the first click; each now names what disappears.
-
ImportModalcloses on the save's ANSWER, so a refused MCP import stays readable against the JSON that produced it.
-
Three branches of POST/PUT
/api/settings/mcpreturnedjson({ servers: mergeServers(...) })withoutawait.JSON.stringifyturns a Promise into{}rather than failing, so the response was a 200 carryingservers: {}— the save landed inmcp.json, and the panel that adopts its own answer showed an empty list. Measured: create →{"success":true,"servers":{}}while~/.omp/agent/mcp.jsonheld the entry. Every list-reporting branch now awaits, pinned bysrc/server/routes/settings/mcp.test.ts(four of its five cases fail on the old code). -
A rename also left the OLD name behind as an app-local row. The native file was rewritten under the new name, but the SQLite mirror still held the old row and the panel listed both. The route drops the row named by
previousNativeNameafter the upsert.
-
The pane used to write
{command,args,env}or{url}and nothing else. omp's schema (mcp-schema.json) also definestype: stdio|http|sse,headers,cwd,timeout,requestIdFormat,instructions,authandoauth; a server needing anAuthorizationheader, a working directory or an SSE endpoint could only be configured by hand-editing the file.McpServerItemnow carries every field,toNativeServerwrites them, andnativeToServerItemreads them back.typeis written for both remote transports because omp infersurl → http— an SSE endpoint withouttype: "sse"silently loads as streamable HTTP. -
Enablement is omp's own three-part model, and the pane used to write none of it.
disabledServers(user file) is the highest-precedence denylist,enabledServersoverrides a source'senabled: false, and the entry's ownenabled: falsedisables it. The old save wrote only the entry, so the "Enable Server" checkbox flipped back on the next read.writeServerAtnow writes the entry's flag AND the user-level lists (a project-scope save updates both files), andisServerEnabledis the one precedence rule the pane and the session registry share.definitionFromNativealso honoursenabled: falsenow — before, a server disabled in the file still reached every session. -
Both user files and every project candidate are read. omp discovers
~/.omp/agent/mcp.jsonand~/.omp/agent/.mcp.json, and every existing project candidate (.omp/mcp.json,.omp/.mcp.json,mcp.json,.mcp.json), first name wins.readUserMcpConfig/readProjectMcpConfigmerge them;resolveProjectMcpConfigstays the single WRITE target.mcp.enableProjectConfig(default true, read fromconfig.yml) gates project discovery in both the pane and the registry. -
The connection test speaks all three transports. HTTP POSTs
initializewith the configured headers; SSE opens the stream, waits for theendpointevent, POSTsinitializethere and reads the answer off the same stream. A plain POST to an SSE URL — the old behaviour — cannot succeed. Header values whose key looks like a credential (authorization,cookie,*key*,*token*,*secret*) are redacted before the browser sees them, and the writer preserves the stored value when the form sends the sentinel back. -
Import reads every envelope and every server.
{mcpServers}(omp/Claude/Gemini,httpUrlincluded),{servers}(VS Code, typed transports),{mcp}(OpenCode,local|remote, command array,environment) and a bare definition; all entries are imported, not just the first. The parser issrc/shared/lib/mcp/import.ts, pure and unit-tested. -
Plugin contributions accept
ssetoo.PluginMcpTransportisstdio | http | sse; the registry already carried the transport through to ACP, so the SDK type was the only thing refusing it.
-
The navbar's context popover lists the session's MCP servers and switches them for THAT session only.
GET/POST /api/sessions/:sessionId/mcp(src/server/routes/sessions/mcp.ts) reads the same merge the spawn path uses (mcpServerEntriesFor,src/server/lib/mcp/registry.server.ts) and stores only the names that DIFFER from the configured state insession_mcp_state(overridesJSON:name → true|false). A toggle back to the configured value deletes the entry, so a later settings edit still reaches a session that never touched that server. The row is server-side, notsession_ui_state: the spawn path reads it before any client exists. -
omp-rpcreadsmcp.jsononce at spawn and has no RPC verb to add or remove a server. The only lever isPI_CODING_AGENT_DIR— the same oneutility-agent-dir.tsuses to spawn an MCP-free child. A session with overrides therefore gets$TMPDIR/kabmo-omp-session-mcp/<sessionId>: every entry of the real agent dir is SYMLINKED (auth, models, sessions, skills, extensions, the databases stay one copy),mcp.jsonis written from the merged list with the session's enablement, and.mcp.jsonis not linked at all (omp unions both user files, so a linked secondary would resurrect a disabled server). A--configoverlay setsmcp.enableProjectConfig: false, because the project's own file is read from the cwd and would otherwise add back a server the session disabled. Measured on 18.20.0: with the overlay a project server's command never ran; without it, it did. A session with no overrides gets no overlay and reads the real config exactly as before. -
A live toggle is
/mcp reload, not a respawn. Measured on 18.20.0 over RPC:/mcp reloadanswersagentInvoked: falsein a few ms, emits onecommand_outputframe, opens no turn, and re-runsdiscoverAndConnect— so rewriting the overlay'smcp.jsonand sending the prompt applies the change live (reload-mcp.ts, deliberately not routed throughdispatchSessionCommand). A child spawned WITHOUT an overlay read the real file, so an idle one is destroyed and the next command respawns it with the overlay; a busy one keeps its list until the next spawn and the response saysappliesOnNextSpawn: true. -
ACP receives the list as a handshake argument, so the filter is applied in
spawn.server.ts. An idle ACP session is destroyed and the next command respawns it throughresumeRecordedHarnessSessionwith the filtered list.omp-acpis excluded:session/loadon omp FORKS the conversation (measured), so that chat keeps its list until the next spawn rather than losing its id. -
The list is truthful per delivery.
omp-rpcshows only the sources omp can read (user + project files); app-local rows and plugin contributions stay ACP-only, as they were. The overlay materializes only those two sources, so the list does not change shape when the first override is applied. -
Status is a PROBE, not a guess. omp publishes no MCP state over RPC:
mcp:connection-statusis an internal TUI event bus,/mcp listover RPC prints the configured state, andget_state.dumpToolscarries only the built-in tools (measured on 18.20.0 — a live codegraph server mounted nomcp__entry there). The info control therefore runs a real handshake (testMcpServer, the same one the settings pane uses) and caches the answer per session+server for 60 s (probe.server.ts). Green = the handshake answered and listed tools; red = it failed or the server is disabled; yellow = checking, or not probed yet. The probe starts a SECOND instance of the server, which is why it runs on the info control and never on mount. -
The popover is one control for both layouts (
ContextUsageButton,layoutprop), widened fromw-56/14remtow-72/18remto hold the list. The checkbox uses the sharedCHECKBOX_CLASS— the repo's checkbox contract test counts every<input type="checkbox">call site.
-
A reload means DISPOSE, not re-read.
recycleStandbyProcesses(src/server/lib/omp/session/standby.server.ts) disposes the two pools that hold an omp process with no session and no turn — the shared utility children (--no-session --no-lsp, answeringget_available_models,get_login_providers,get_available_commands) and the per-cwd prewarm entries (an idle session host waiting for the next send) — so the next command boots the binary currently installed./reload-pluginsis a different question and lives inreload.server.ts: it re-reads skill/plugin FILES inside a live process and would leave the OLD BINARY running, which is exactly the staleness this exists to fix. -
The utility child carries NO MCP servers, and that is a deliberate subtraction.
omp --mode rpc-uiconnects every configured MCP server at startup, and no CLI flag skips it (--no-toolsstill spawned the proxy: measured). The shared utility child answers registry/auth/slash-command queries and never runs a turn, so thecodegraph serve --mcpproxy it spawned — plus that proxy's main-thread watchdog — was 88 MB per cwd serving nothing; thexd://notice proved it, mountingmcp__codegraph_exploreinto a child that can never call it.ensureUtilityAgentDir(rpc/utility-agent-dir.ts) builds$TMPDIR/kabmo-omp-utility-<pid>as a symlink farm over~/.omp/agentwithmcp.jsonandsessions/omitted, andstartProcesspasses it asPI_CODING_AGENT_DIR. Measured on the real path:children=[](no codegraph, no watchdog) withget_available_models220,get_login_providers86,get_available_commands58/7 skills,get_stateok — identical to the unlinked child, which is the acceptance bar. Symlinks, never copies:logoutwrites credentials and the.dbfiles are live WAL SQLite, so a copy would fork state. Directories must be linked too — materialisingskills/empty dropped the count to 52 commands / 1 skill, because omp discovers its roots by reading that directory. A build that fails returnsundefinedand the child uses the real dir: a slow models list is not worth a failed boot. -
Why it is needed at all: a running child is the build it was spawned from, for its whole life.
omp updatereplaces the launcher and the package on disk, but a utility child lives up to 5 minutes (IDLE_KILL_MS) and a prewarm waits for a send that may be an hour away — so the provider list, the model list and the composer's/popup keep answering from the previous version with nothing on screen to say so. Verified end to end against a real server: after a successful update the utility child's pid was gone and the next/api/modelsbooted a new one, while an already up-to-date run left the same pid alive (applyOmpUpdatereturnsupdated: falsefor the phrasecheckOmpUpdatealready matches — a success that must not bounce a warm pool). -
Live sessions are deliberately untouched. They may be mid-turn, and a
--resumeon their next command already boots the current binary. The button is therefore safe to press at any time, and the smoke run proves it: with a real session host and a utility child alive,POST /api/omp/reload-enginerecycled the utility pool and left the session's pid running and itsget_stateanswering. -
The prewarm pool's recycle is claim-safe by construction. An unclaimed entry owns no session and no turn, and
startNewRpcSessionclaims an entry with a synchronous check-and-set — so an entry is either taken before the pass reads it or taken after the pass removed it, never both.restartPrewarmedSessions(rpc/session-registry.ts) marks each doomed entry claimed before deleting it, then awaitsdestroyAndWait; a wrapper still booting is torn down the same way the prewarm's own error path does. -
A resumed session can come back under a DIFFERENT id, and the registry must answer for the one the CLIENT holds. omp 18.10.0 forks a session marked moved away (
omp session moved, or adepartedsession-transfermarker) instead of continuing it: the child answers a freshsessionIdand writes the fork to a fresh file under a fresh id — verified against a real child, which resumed a departed file into another directory. The registry is keyed by the id the caller holds (the URL's session id), so keying it on that alone MISSED on the very next message: the send re-resolved the ORIGINAL file and spawned again, and two sends on one session file produced two children with two different ids, each forking its own file — a chain of forks with a sidebar row each and nothing on screen to explain it (measured through bothstartRpcSessionand the route-level lookup).registerSpawnedSession(rpc/session-registration.ts) therefore registers the wrapper under the reported id AND, when they differ, under the requested one, removing both on destroy so a dead child cannot answer for the requested id; the spawn path also emitssession-attachedfor the requested id so a subscribed tab re-snapshots instead of holding the pre-spawnrunning:false.realSessionIdreports the child's OWN id even on a registry hit (it reported the requested id, which is the alias, not the session). Pinned byforked-resume.test.ts, which drives the real spawn path againsttest-support/fake-omp-fork.ts— the only way the two ids can differ — and fails with 2 children if the alias is removed. -
Caches built FROM a process or the binary are dropped in the same pass (
invalidateModelsCaches,invalidateSkillCache,invalidateUsageCache,invalidateOmpCliCache), because a recycled server behind a cached provider/model list makes the recycle look like it did nothing. The client half isuseReloadOmpEngine(src/client/hooks/settings/reload-engine.ts), which also callsinvalidateComposerCache+notifyModelsUpdated— the/popup holds its list for 5 minutes and would otherwise keep offering the old commands. -
Two triggers, one pass.
POST /api/omp/reload-engine(routesrc/server/routes/omp/reload-engine.ts) is the settings sidebar's "Reload OMP" button — previously a 1200 ms spinner with no request behind it — andapplyUpdate's omp branch fires the same recycle after a successful update, gated onupdatedso an already-current run does not bounce anything. Both coalesce onto one in-flight pass, and a failure in one pool never skips the other (each is caught and reported separately;standby.server.test.tspins all four properties). -
The toast carries a tone. The settings modal's single toast slot now reports the reload's real outcome —
Reloaded omp engine — N utility, M prewarmed process(es) recycled., or the empty-pool wording when nothing was live (a normal state, not a failure: the next command spawns the current build either way) — and a failed request renders under an alert icon intext-errorinstead of a check mark. Verified in the browser on a live server: the click issuedPOST /api/omp/reload-engine → 200, the toast named1 utility, 0 prewarmed, and a forced 500 renderedalert-circle text-error.
-
A Kabmo update from the console restarts the server that answered it, and the page then reloads ITSELF into the new build.
POST /api/updates/applyarms the detached restart and answers first (RESTART_GRACE_MS, 1.2 s — the margin that lets theresultframe reach the browser), so the page is still served by the process whose files were just replaced. Reloading on theresultframe would fetch the OLD bundle back; never reloading leaves the user on a stale page with a "restarting" toast and nothing else.useUpdatestherefore reads/api/healthBEFORE the run, waits for a process that answers with a differentpid/startedAt, and only then reloads (src/client/hooks/ui/updates/restart.ts,waitForServerRestart). -
Identity, never a timer, is what "the replacement is up" means. A timer is wrong in both directions: too short reloads into the dying process, too long leaves the user on a stale page after the new one is already serving.
/api/healthreports the serving process'spidandstartedAt, so a different pair IS the replacement. A failed probe is EXPECTED (the old server is exiting and the port is briefly unbound) and is never read as an answer; with no baseline — the pre-run health read failed — the fallback is a younguptime(REPLACEMENT_MAX_UPTIME_S), which the update's own multi-minute duration makes safe. The ceiling is 30 s (RESTART_WAIT_TIMEOUT_MS), and on a timeout the result comes back withrestarting: falseand a sentence telling the user to reload by hand rather than a promise the console cannot keep. Verified against a live server: the real/api/healthpayload carries both fields, a re-read of the same process is not a replacement, and a changed pid is. -
restartingis a FIELD on the result, not something the client sniffs out of the message.UpdateApplyResult.restartingis set from the planscheduleSelfRestartreturned, and the sentence is folded in by the same helper (withRestartPlan,src/server/lib/lifecycle/restart.ts) so the flag and the wording cannot drift apart. Absent on every other outcome — an "already up to date" success, amanualinstall, a failure — andfalsewhen a restart was refused (an instance the CLI does not own), where the appended sentence is the only place the user learns why. -
The message was wrong, and this is the fix. It read
… — the console reconnects on its own, which described the realtime socket and not the page: the console stayed on the old bundle until the user reloaded by hand. It now saysRestarting on port <port> to apply it — this page reloads on its own., pinned byselfRestartMessage's own test. -
The update check is not a mount-time fact.
useUpdateschecked once per mount, so a console that booted before a release reached npm kept the old answer forever: the "update available" popup never appeared until the page was reloaded (reported against v0.16.0 → v0.17.0; restarting the app remounted the page and the popup appeared). It now re-reads/api/updates/checkonvisibilitychange(visible), on windowfocus(a native shell's WebView can stayvisiblewhile backgrounded), and on aUPDATE_RECHECK_INTERVAL_MS30-minute interval for a console that never leaves the screen, with a 60 s floor between automatic reads so the two return-to-app triggers do not double-read. The popup gate itself is unchanged: a re-check that reports a newerlatestopens the same once-per-version dialog. Verified in the browser by stubbing only/api/updates/checkafter mount (mount: no update) and dispatchingvisibilitychangepast the floor: theUpdate availabledialog appeared with no reload. -
The dialog stays in its "working" state across the wait, and the install log is APPENDED to rather than replaced. A run that flashed back to idle before the navigation would read as finished;
applytherefore leavesapplyingset when it ends by navigating, and appendsUpdate installed — waiting for the server to restart on this port…to the log it already has, because a failed restart has to be read against the output that ran. An abort (the panel going away with the run) still returnsnull— the same answer the other abort path gives — so no caller toasts into a torn-down view. -
The omp target never enters this path.
applyUpdate's omp branch recycles the standby pools and restarts nothing, so the client only reads the baseline and only waits fortarget === 'kabmo'.restartingis never set for it. -
About's "What's new" control sits ON the version line and answers about the version you RUN; the update popup answers about the version you could INSTALL. Each line in the version block (
Kabmo v0.17.0,Oh-My-Pi 18.14.0) carries a circle-i button whose accessible name names the product (What's new in Kabmo/What's new in Oh-My-Pi), and clicking it opensNotesDialogabove About. A separate pair of buttons above the list was retired because it read as an action on the UPDATE — the updates row already answers that. The section is chosen SERVER-side bybuildActiveReleaseNotes(src/server/lib/updates/active-notes.ts):GET /api/updates/notes?target=accepts a PRODUCT only, never a version, so the dialog cannot describe a release the install never had. omp's prose comes frompackages/coding-agent/CHANGELOG.mdincan1357/oh-my-pi— the file the release bodies mirror; the repository root has no changelog (404, measured) — and the changelog cache is keyed by SOURCE URL, because one shared slot rendered omp's sections under the Kabmo heading. The Kabmo updates row and itsWhat's new in <latest>button stay: that release is what an update would install. Verified on a live server: About showedKabmo v0.17.0andOh-My-Pi 18.14.0with their controls, and each dialog rendered exactly that release's section with a link to the full changelog. Both changelog dialogs (NotesDialogand the update popup) aremax-w-3xland render prose at 13px: measured at 1440x900 the panel is 768px with a 726px article, omp's longest list item (430 chars) wraps to 4 lines instead of 7, and on a 390px phone the panel is 358px inside a 16px gutter with no horizontal overflow. The popup'ssticky bottom-0footer still pins its actions — the body scrolls, the action row does not. -
The settings sidebar carries the same restart as a button, beside "Reload OMP", and it reuses that contract rather than a second one.
POST /api/console/restart(src/server/routes/console/restart.ts, registered byroutes/console/index.ts; the pre-rename/api/chamber/restartstays mounted byroutes/chamber/index.ts) callsscheduleSelfRestart('restart')— the same detachedkabmo restart --port <port>the update path arms, on the sameRESTART_GRACE_MS— and answers{ success, restarting, message }.useRestartKabmo(src/client/hooks/settings/restart-kabmo.ts) reads/api/healthbefore the request, then waits throughwaitForServerRestartand reloads into the replacement, so the page cannot be left on the dying process's bundle. The purpose argument is the whole wording difference: an update saysRestarting on port <port> to apply it — …and its refusal saysstart it again to apply the update, while a plain restart drops that clause (Restarting on port <port> — …) because there is no update to apply — one function per sentence (selfRestartMessage,skipRestartNote) withSelfRestartPurposechoosing the branch, so the two surfaces cannot drift. An instance the CLI does not own is REFUSED with that sentence andrestarting: false(verified against a realbun run src/server/index.ts:this instance runs from source … — start it again), MOCK mode refuses outright because a demo must not take a server down, and the armed branch was verified end to end against a--launch-mode=daemoninstance:pid 76144answered the request, and 6 s laterpid 76188was serving the same port. Both buttons are disabled while either operation runs — a reload while the server is restarting answers a socket nobody serves. -
A restart launches the copy the update INSTALLED, never the one the running process happens to be in — and a rename is why.
bun add -g @kabmo-labs/kabmoinstalls a SECOND package beside the one that answered the update, so resolving the helper from that process's ownPKG_ROOTrelaunches the build the update just replaced. Measured on the 4.23.1 → 0.0.1 move: the log read[ompchamber] restarting on port 3001: … /node_modules/ompchamber/src/cli/ompchamber.js restart --port 3001, the console came back as 4.23.1, and the update had reported success.updateKabmotherefore reads the copy back off disk AFTER its steps (installed-cli.ts:copyAtfor a checkout,resolveInstalledCopyfor a global install) and returns it onKabmoUpdateResult.installed→AppliedUpdate.installed→scheduleSelfRestart('update', applied.installed);kabmo updatedoes the same throughrestartCtx. A null falls back to this process's own root, which is correct forRestart(it installs nothing) and for a copy whose install could not be read. -
The CLI file comes from the package's own
binmap, and the credential marker follows the TARGET package. Two consequences of a rename that fail silently on their own. A hard-codedsrc/cli/kabmo.jsdoes not exist in a copy that names its bin differently, sorestartInvocationresolves the bin frompackage.json, preferring the entry named after the package (@kabmo-labs/kabmo→kabmo) because a bridge release registers both and picking the first key would restart a renamed install through the legacy spelling. And the handover variable was renamed too (OMPCHAMBER_PASSWORD_HANDOVER→KABMO_PASSWORD_HANDOVER), so a restart that set only its own spelling handed a payload to a CLI that never reads it and the replacement came back with authentication disabled —HANDOVER_ENV_BY_PACKAGEkeys the marker by the target's package name. Both are pinned byinstalled-cli.test.ts(including that a pre-rename copy keeps the old marker) andupdate.test.js(restartCtxmoves the spawn to the installed root, and leaves it alone when the update reported none). -
What is not covered by a test: the real self-restart followed by a browser reload. Exercising it means killing a live CLI-managed instance mid-session, so the wiring is pinned by the pieces (
withRestartPlansets the flag and the sentence together; the hook's mounts drive the wait, the reload and the timeout through an injected clock and a stubbedwindow.location; the health payload is smoke-tested against a live server) and the assembled path is not.
-
A workspace folder is a row in
workspace_foldersand nothing else. The name, the bound directory (project_path), the default model, the accent, the icon and the pin all live there, and every surface — the sidebar's header and menu, Settings → Projects, the skills/commands/agents scopes — reads that one table through thesidebar-structuresignal. The retiredomp_projects_configJSON is read once bymigrateLegacyProjectSettingsand never again;src/client/data/settings/project.tsnow only holds the seed list that migration falls back to when that legacy row is not an array. -
Every project field is a REAL write, validated server-side, and a refusal is NAMED.
prepareProjectPatch(src/server/lib/workspace/project-patch.server.ts) enforces the four rules the form can violate: a name is required (the store skips an empty one, which used to show a cleared field over an unchanged row), names are unique case-insensitively (the sidebar identifies a workspace by name), aproject_pathmust be an existing directory with~expanded exactly likePOST /api/folders, and one directory belongs to one workspace (two rows list the same sessions and fight over the discovery tombstones). The refusals carryname_required/duplicate_name/directory_not_found/duplicate_path/invalid_icon, and the client reverts the row and shows the sentence — the pane used to log toconsole.errorand let the next refresh silently undo the edit. -
The name and the directory COMMIT on blur/Enter, never per keystroke. The old field wrote one PATCH per character, so a rename raced itself and the last response won regardless of order. The response's
projectis adopted (it carries the trimmed name and the expanded path), which is why the field a user typed into can come back different from what they typed. -
A changed
project_pathre-syncs the discovery watchers.syncDiscoveryRootsWatch()is keyed by the bound roots, so a re-bind otherwise kept watching the OLD root and never picked up the new one until a restart — a skill written in the new workspace stayed invisible to a live session. -
"Defaults for new chats" is
provider:modelId, and the SPAWN reads it. The picker offers the live/api/modelscatalog (this route no longer serves its own hardcoded display-name list, andModelEntryids are not unique across providers, hence the composite).projectModelForCwd(src/server/lib/workspace/project-model.server.ts) resolves the folder for the spawn's cwd — exact match first, then the longest bound root that contains it, so a worktree of a project resolves to that project — andPOST /api/agent/newconsults it BEFORE Kabmo's global pick.Not selectedand the legacy display names parse to null, i.e. "inherit", rather than to a model no provider serves. The pending composer shows the same value (usePendingProjectModel), so the pill and the spawn cannot disagree. -
An icon must be something an
<img>can render.customIconUrlaccepts an uploaded data URL (png/jpeg/svg/webp/gif, ≤512 KiB) or an absolute http(s) URL; anything else — including ajavascript:URI — is a 400. The client's generated mark is only saved after it LOADS (the old "discover favicon" button actually built a DiceBear identicon and saved the URL unverified, so an offline request overwrote the icon with a broken image). -
Deleting a project is a dialog that names what disappears, and the session counts are read from the sidebar payload. The trash button used to delete immediately. The tombstone (
deleted_workspaces) is what stops omp discovery from re-adding the folder on the next boot, and the dialog says so; the directory itself is never touched. -
One icon map and one accent palette.
src/shared/lib/workspace/project-icon.tsholds the glyph table the sidebar, the mobile row and the settings grid all iterate (PROJECT_ICON_OPTIONS), andsrc/shared/lib/workspace/project-accent.tsholds the swatches the route serves. The two halves had each drifted:defaultwas a folder in the sidebar and an ✕ in the settings grid, and a colour added on one side was missing on the other. -
A custom accent is a hex colour the palette does not contain, and the server checks that. The swatch row is a fixed table, but a user picks any colour through the native picker (
<input type="color">) beside it;normalizeHexAccentreduces#ABCto#aabbccso the stored string has ONE spelling — the sidebar compares it against the preset table to decide whether to highlight a swatch. The server refuses anything that is not#rgb/#rrggbbwithinvalid_accent, because the accent is painted straight into a CSScolor: before this,accentColor: "red;background:url(//evil)"was stored verbatim and reached the sidebar'sstyle. A custom accent is not a table entry —DEFAULT_CUSTOM_ACCENT(#7c3aed) is deliberately absent fromPROJECT_ACCENT_OPTIONS, so "custom" never lights up a preset. -
The custom control writes on COMMIT, and those listeners are attached natively. Dragging inside the system colour panel fires hundreds of
inputevents and each commit is a PATCH carrying the whole project, so only the colour input'schangeand the text field's blur/Enter write. They are bound withaddEventListenerin an effect rather than throughonChange/onInputprops:preact/compatmapsonChangeonto theinputevent, so under the app's runtime a prop would commit on every drag tick — and a test file where compat is not yet loaded reports the opposite. -
The Agents panel's project picker is a SCOPE.
GET /api/settings/agents?root=<workspace>discovers<workspace>/.omp/agentsthroughresolveRoot(the same gate skills and commands use), so a project's agents are reachable from the panel whose job is listing them; the selector used to offer three hardcoded names and read nothing. -
The icon is TWO fields and ONE write.
iconsays which glyph,customIconUrlcarries the image; sent as two PATCHes they race and the slower response decides the row, which showed up as an uploaded icon that saved and then reverted.useProjectSettings().updateFieldssends a multi-field patch, and the grid calls it for every icon change (selecting a built-in glyph clears the custom URL in the same request). -
A normal photo is not an error. The upload used to refuse anything over 512 KiB, which is smaller than a phone picture. The file is downscaled in the browser to a 128px PNG mark (
fileToIconMark), and SVG passes through untouched; only an image the browser cannot decode is refused. The server still enforces the real ceiling (invalid_icon), so the client's limit is a convenience rather than the contract.
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