@kabmo-labs/kabmo 0.5.3 → 0.6.0

package/src/server/routes/sessions/batch-delete.test.ts

@@ -28,14 +28,14 @@ import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 const AGENT_DIR = path.join(os.tmpdir(), `omc-batch-delete-${process.pid}`, 'agent');
 let priorAgentDir: string | undefined;
 
-beforeAll(() => {
+beforeAll(async () => {
   // This suite reaches the database: `removeSession` → `purgeSessionData`
   // resolves `getDb()`. Without isolating, it inherits whatever handle an
   // earlier file left on the process-wide slot — and when that handle points at
   // a temp directory its owner already deleted, SQLite answers `disk I/O error`
   // and the verdict loses its code (measured on CI: `not_found` came back
   // `undefined` while the same file passed alone).
-  isolateDb();
+  await isolateDb();
   fs.rmSync(AGENT_DIR, { recursive: true, force: true });
   fs.mkdirSync(path.join(AGENT_DIR, 'sessions'), { recursive: true });
   priorAgentDir = Bun.env.PI_CODING_AGENT_DIR;
@@ -43,12 +43,12 @@ beforeAll(() => {
   clearSessionFileCaches();
 });
 
-afterAll(() => {
+afterAll(async () => {
   clearSessionFileCaches();
   if (priorAgentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
   else Bun.env.PI_CODING_AGENT_DIR = priorAgentDir;
   fs.rmSync(path.dirname(AGENT_DIR), { recursive: true, force: true });
-  releaseDb();
+  await releaseDb();
 });
 
 function post(body: unknown, url: string): Promise<Response> {

package/src/server/routes/updates/android.ts

@@ -1,5 +1,5 @@
 import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
-import { fetchAndroidRelease, type AndroidRelease } from '@/server/lib/updates/android-release';
+import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell-release';
 
 /**
  * GET /api/updates/android — the newest APK a visitor can download.
@@ -14,7 +14,7 @@ import { fetchAndroidRelease, type AndroidRelease } from '@/server/lib/updates/a
  * is to omit a button it cannot back with a link.
  */
 export async function loader() {
-  const release: AndroidRelease | null = await fetchAndroidRelease();
+  const release: ShellRelease | null = await fetchShellRelease('android');
   return json(
     release ?? { url: null, latest: null, releaseUrl: null },
     { headers: NO_STORE_HEADERS },

package/src/server/routes/updates/index.ts

@@ -3,10 +3,12 @@ import * as updatesAndroid from '@/server/routes/updates/android';
 import * as updatesApply from '@/server/routes/updates/apply';
 import * as updatesChangelog from '@/server/routes/updates/changelog';
 import * as updatesCheck from '@/server/routes/updates/check';
+import * as updatesIos from '@/server/routes/updates/ios';
 
 export const updatesBindings: HandlerBinding[] = [
   ...bindingsFor(updatesAndroid, '/api/updates/android'),
   ...bindingsFor(updatesApply, '/api/updates/apply'),
   ...bindingsFor(updatesChangelog, '/api/updates/changelog'),
   ...bindingsFor(updatesCheck, '/api/updates/check'),
+  ...bindingsFor(updatesIos, '/api/updates/ios'),
 ];

package/src/server/routes/updates/ios.ts

@@ -0,0 +1,26 @@
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell-release';
+
+/**
+ * GET /api/updates/ios — the newest iOS shell a visitor can install.
+ *
+ * A separate route from `/api/updates/android` even though both read the same
+ * release list: the two shells are different artifacts on different tracks, and
+ * one endpoint answering "the newest shell" would force the client to say which
+ * one it meant in a query string — a parameter whose absence silently means
+ * Android.
+ *
+ * Only an INSTALLED shell asks for this. There is no browser-side install offer
+ * on iOS (an IPA cannot be sideloaded from a page the way an APK can), so the
+ * payload is only ever compared against `KabmoIOS/<version>`.
+ *
+ * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
+ * is to omit a button it cannot back with a link.
+ */
+export async function loader() {
+  const release: ShellRelease | null = await fetchShellRelease('ios');
+  return json(
+    release ?? { url: null, latest: null, releaseUrl: null },
+    { headers: NO_STORE_HEADERS },
+  );
+}

package/src/server/routes/waiting/routes.test.ts

@@ -44,11 +44,11 @@ async function call(body: unknown): Promise<{ status: number; body: Record<strin
 
 beforeAll(async () => {
   fs.mkdirSync(ROOT, { recursive: true });
-  isolateDb();
+  await isolateDb();
 });
 
 afterAll(async () => {
-  releaseDb();
+  await releaseDb();
   fs.rmSync(ROOT, { recursive: true, force: true });
 });
 

package/src/shared/lib/models/server-cache.ts

@@ -12,6 +12,7 @@
  */
 
 import type { ModelsData, ProviderItem } from '@/shared/types';
+import type { ModelRoleCandidate } from '@/shared/types/model-roles';
 import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
 
 declare global {
@@ -19,6 +20,15 @@ declare global {
   var __kabmoModelsCache: { data: ModelsData; expiresAt: number } | undefined;
   // eslint-disable-next-line no-var
   var __kabmoProvidersRpcCache: { data: ProviderItem[]; expiresAt: number } | undefined;
+  /**
+   * The role dropdowns' candidate list (`lib/model-roles/catalog.server.ts`).
+   * Declared HERE because it is dropped by the same signal: a model removed
+   * from models.yml, or a provider that lost its credential, must leave the
+   * role pickers too — otherwise they keep offering a selector omp can no
+   * longer resolve.
+   */
+  // eslint-disable-next-line no-var
+  var __kabmoRoleCandidatesCache: { data: ModelRoleCandidate[]; expiresAt: number } | undefined;
 }
 
 /**
@@ -33,5 +43,6 @@ declare global {
 export function invalidateModelsCaches(): void {
   globalThis.__kabmoModelsCache = undefined;
   globalThis.__kabmoProvidersRpcCache = undefined;
+  globalThis.__kabmoRoleCandidatesCache = undefined;
   emitRealtimeSignal('models-changed');
 }

package/src/shared/lib/omp/config/model-roles.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * omp's built-in model roles, and which catalog kinds each one accepts.
+ *
+ * One table, read by the role editor (labels + sections), by the role dropdowns
+ * (which models to offer) and by the server (which role ids a preset may hold).
+ * It mirrors `MODEL_ROLES` in `@oh-my-pi/pi-coding-agent/src/config/model-roles.ts`
+ * — the `accepts` predicates are flattened into `kinds` so the same rule can run
+ * on a catalog row that has no `Model` object.
+ *
+ * `kinds` is a CATALOG-kind list, and the predicates upstream are not all
+ * expressible that way: `web` also accepts chat models that declare a grounding
+ * transport (`webSearch`), which the catalog JSON does not carry. Those rows are
+ * marked `webCapable` by the server and admitted by
+ * {@link roleAcceptsCandidate} — the one predicate both the UI and the tests use.
+ *
+ * `widget` ("Job widgets") exists at omp 18.12.6 and was missing from this
+ * panel, which made it the only role a user could not set from the console.
+ */
+
+import type { ModelRoleCandidate } from '@/shared/types/model-roles';
+
+export interface ModelRoleInfo {
+  /** omp's display name for the role (`MODEL_ROLES[role].name`). */
+  label: string;
+  /** omp's section: a chat model, or a model of that kind only. */
+  section: 'chat' | 'kind';
+  /** Catalog kinds this role accepts. */
+  kinds: readonly string[];
+}
+
+/** omp's `MODEL_ROLES` table, in its own declaration order. */
+export const MODEL_ROLES: Record<string, ModelRoleInfo> = {
+  default: { label: 'Default', section: 'chat', kinds: ['chat'] },
+  smol: { label: 'Fast', section: 'chat', kinds: ['chat'] },
+  slow: { label: 'Thinking', section: 'chat', kinds: ['chat'] },
+  vision: { label: 'Vision', section: 'chat', kinds: ['chat'] },
+  plan: { label: 'Architect', section: 'chat', kinds: ['chat'] },
+  commit: { label: 'Commit', section: 'chat', kinds: ['chat'] },
+  tiny: { label: 'Tiny', section: 'chat', kinds: ['tiny', 'chat'] },
+  memory: { label: 'Memory', section: 'chat', kinds: ['tiny', 'chat'] },
+  task: { label: 'Subtask', section: 'chat', kinds: ['chat'] },
+  advisor: { label: 'Advisor', section: 'chat', kinds: ['chat'] },
+  widget: { label: 'Job widgets', section: 'chat', kinds: ['chat'] },
+  image: { label: 'Image generation', section: 'kind', kinds: ['image'] },
+  web: { label: 'Web search', section: 'kind', kinds: ['search'] },
+  speech: { label: 'Speech (TTS)', section: 'kind', kinds: ['tts'] },
+  dictation: { label: 'Dictation (STT)', section: 'kind', kinds: ['stt'] },
+  judge: { label: 'Judge', section: 'kind', kinds: ['judge', 'tiny', 'chat'] },
+};
+
+/** Role ids in omp's declaration order. */
+export const ROLE_IDS: string[] = Object.keys(MODEL_ROLES);
+
+/** Whether `role` is one of omp's built-in roles. */
+export function isModelRole(role: string): boolean {
+  return Object.prototype.hasOwnProperty.call(MODEL_ROLES, role);
+}
+
+/**
+ * Whether a catalog row can fill `role`.
+ *
+ * `web` is the only role whose upstream predicate needs a field the catalog
+ * JSON omits, so its chat rows are admitted through `webCapable` — a search
+ * provider is admitted by kind alone.
+ */
+export function roleAcceptsCandidate(role: string, candidate: ModelRoleCandidate): boolean {
+  const info = MODEL_ROLES[role];
+  if (!info) return false;
+  if (info.kinds.includes(candidate.kind)) return true;
+  return role === 'web' && candidate.kind === 'chat' && candidate.webCapable === true;
+}
+
+/** Role ids: a letter, then letters, digits, `-` or `_` (omp's own role-name rule). */
+const ROLE_ID_PATTERN = /^[a-zA-Z][\w-]*$/;
+
+/**
+ * Validate a `modelRoles` map from a request.
+ *
+ * The keys are NOT narrowed to omp's built-ins: `modelRoles` accepts custom role
+ * ids and omp adds them to its own role list, so a filtered copy would silently
+ * delete a custom role the moment a preset was applied (the map is written
+ * whole). A key that cannot be a role name, or an empty selector, is dropped —
+ * those are typos, not assignments.
+ */
+export function normalizeRoleMap(raw: unknown): Record<string, string> {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error('roles must be a role → model selector map');
+  }
+  const roles: Record<string, string> = {};
+  for (const [role, value] of Object.entries(raw)) {
+    if (!ROLE_ID_PATTERN.test(role)) continue;
+    if (typeof value !== 'string' || !value.trim()) continue;
+    roles[role] = value.trim();
+  }
+  return roles;
+}
+
+/** Candidates for one role, ordered by provider then display name. */
+export function candidatesForRole(role: string, candidates: readonly ModelRoleCandidate[]): ModelRoleCandidate[] {
+  return candidates
+    .filter((candidate) => roleAcceptsCandidate(role, candidate))
+    .sort((a, b) => a.provider.localeCompare(b.provider) || a.name.localeCompare(b.name));
+}
+
+/** Two `modelRoles` maps hold the same assignments (order-insensitive). */
+export function roleMapsEqual(a: Record<string, string>, b: Record<string, string>): boolean {
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => b[key] === a[key]);
+}
+
+/**
+ * The preset whose assignments ARE the live map, or null.
+ *
+ * This is how the picker says which preset is in force: not a stored "last
+ * applied" flag, which goes stale the moment a role is edited by hand — the map
+ * itself is the state, and a preset matches when it equals it exactly.
+ */
+export function matchPreset<T extends { roles: Record<string, string> }>(
+  presets: readonly T[],
+  roles: Record<string, string>,
+): T | null {
+  return presets.find((preset) => roleMapsEqual(preset.roles, roles)) ?? null;
+}

package/src/shared/lib/updates/shell-ua.test.ts

@@ -5,51 +5,83 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import { androidShellVersion, isAndroidDevice, SHELL_UA_PREFIX } from '@/shared/lib/updates/shell-ua';
+import { isAndroidDevice, shellVersion, SHELL_UA_PREFIXES } from '@/shared/lib/updates/shell-ua';
 
 /**
- * The token is the only signal that a page is running inside the Android app,
- * and it decides whether a download button appears. Two failure modes matter:
- * a browser mistaken for the app (a button in a place it does not belong) and a
+ * The token is the only signal that a page is running inside a native shell, and
+ * it decides whether a download button appears. Two failure modes matter: a
+ * browser mistaken for the shell (a button in a place it does not belong) and a
  * malformed token read as a version (a comparison against `''`).
+ *
+ * Both shells are exercised against the same parser, because the grammar is one
+ * grammar and only the prefix differs — the shape that silently reads the other
+ * shell's version.
  */
-describe('androidShellVersion', () => {
-  test('reads the version from a real WebView UA', () => {
+describe('shellVersion', () => {
+  test('reads the version from a real Android WebView UA', () => {
     const ua =
       'Mozilla/5.0 (Linux; Android 15; Pixel 6 Build/AP4A; wv) AppleWebKit/537.36 (KHTML, like Gecko) '
-      + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIX}0.1.0`;
-    expect(androidShellVersion(ua)).toBe('0.1.0');
+      + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIXES.android}0.1.0`;
+    expect(shellVersion(ua, 'android')).toBe('0.1.0');
+    expect(shellVersion(ua, 'ios')).toBeNull();
+  });
+
+  test('reads the version from a real iOS WKWebView UA', () => {
+    const ua =
+      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) '
+      + `Mobile/15E148 ${SHELL_UA_PREFIXES.ios}0.1.0`;
+    expect(shellVersion(ua, 'ios')).toBe('0.1.0');
+    // The platform token is `iPhone`, not `Android` — so the Android install
+    // offer must not fire for the iOS shell.
+    expect(isAndroidDevice(ua)).toBe(false);
   });
 
   test('is null for a plain browser', () => {
-    expect(androidShellVersion('Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/124.0 Safari/537.36')).toBeNull();
-    expect(androidShellVersion('')).toBeNull();
-    expect(androidShellVersion(null)).toBeNull();
-    expect(androidShellVersion(undefined)).toBeNull();
+    const browser = 'Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/124.0 Safari/537.36';
+    expect(shellVersion(browser, 'android')).toBeNull();
+    expect(shellVersion(browser, 'ios')).toBeNull();
+    expect(shellVersion('', 'android')).toBeNull();
+    expect(shellVersion(null, 'android')).toBeNull();
+    expect(shellVersion(undefined, 'ios')).toBeNull();
   });
 
   test('is null when the token carries no usable version', () => {
     // A forged or truncated token must not read as version '' — that would make
     // `isNewer(latest, '')` true for every release and show a button always.
-    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/')).toBeNull();
-    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/abc')).toBeNull();
-    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/1.x.3')).toBeNull();
+    expect(shellVersion('Mozilla/5.0 KabmoAndroid/', 'android')).toBeNull();
+    expect(shellVersion('Mozilla/5.0 KabmoAndroid/abc', 'android')).toBeNull();
+    expect(shellVersion('Mozilla/5.0 KabmoAndroid/1.x.3', 'android')).toBeNull();
+    expect(shellVersion('Mozilla/5.0 KabmoIOS/', 'ios')).toBeNull();
+    expect(shellVersion('Mozilla/5.0 KabmoIOS/1.x.3', 'ios')).toBeNull();
   });
 
   test('accepts one-, two- and three-part versions and a prerelease', () => {
-    expect(androidShellVersion('KabmoAndroid/1')).toBe('1');
-    expect(androidShellVersion('KabmoAndroid/1.2')).toBe('1.2');
-    expect(androidShellVersion('KabmoAndroid/1.2.3')).toBe('1.2.3');
-    expect(androidShellVersion('KabmoAndroid/1.2.3-beta.1')).toBe('1.2.3-beta.1');
+    for (const prefix of Object.values(SHELL_UA_PREFIXES)) {
+      const kind = prefix === SHELL_UA_PREFIXES.android ? 'android' : 'ios';
+      expect(shellVersion(`${prefix}1`, kind)).toBe('1');
+      expect(shellVersion(`${prefix}1.2`, kind)).toBe('1.2');
+      expect(shellVersion(`${prefix}1.2.3`, kind)).toBe('1.2.3');
+      expect(shellVersion(`${prefix}1.2.3-beta.1`, kind)).toBe('1.2.3-beta.1');
+    }
   });
 
   test('takes the first token when the UA was crafted twice', () => {
-    expect(androidShellVersion('KabmoAndroid/1.0.0 KabmoAndroid/9.9.9')).toBe('1.0.0');
+    expect(shellVersion('KabmoAndroid/1.0.0 KabmoAndroid/9.9.9', 'android')).toBe('1.0.0');
+    expect(shellVersion('KabmoIOS/1.0.0 KabmoIOS/9.9.9', 'ios')).toBe('1.0.0');
   });
 
   test('does not match a lookalike token', () => {
-    expect(androidShellVersion('KabmoAndroidX/1.0.0')).toBeNull();
-    expect(androidShellVersion('Mozilla KabmoAndroid')).toBeNull();
+    expect(shellVersion('KabmoAndroidX/1.0.0', 'android')).toBeNull();
+    expect(shellVersion('Mozilla KabmoAndroid', 'android')).toBeNull();
+    expect(shellVersion('KabmoIOSX/1.0.0', 'ios')).toBeNull();
+    expect(shellVersion('Mozilla KabmoIOS', 'ios')).toBeNull();
+  });
+
+  test('the two prefixes are distinct', () => {
+    // A shared prefix would make one shell's token readable as the other's, and
+    // the two artifacts are on separate release tracks.
+    expect(SHELL_UA_PREFIXES.android).not.toBe(SHELL_UA_PREFIXES.ios);
+    expect(SHELL_UA_PREFIXES.android.startsWith(SHELL_UA_PREFIXES.ios)).toBe(false);
   });
 });
 
@@ -82,7 +114,7 @@ describe('isAndroidDevice', () => {
     expect(
       isAndroidDevice(
         `Mozilla/5.0 (Linux; Android 15; Pixel 6 Build/AP4A; wv) AppleWebKit/537.36 (KHTML, like Gecko) `
-        + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIX}0.3.0`,
+        + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIXES.android}0.3.0`,
       ),
     ).toBe(true);
   });
@@ -114,7 +146,7 @@ describe('isAndroidDevice', () => {
   });
 
   test('does not match a lookalike word', () => {
-    // `` is what stops a crafted or unrelated token from counting.
+    // `` is what stops a crafted or unrelated token from counting.
     expect(isAndroidDevice('Mozilla/5.0 (compatible; NotAndroidBot/1.0)')).toBe(false);
     expect(isAndroidDevice('Mozilla/5.0 AndroidX/1.0')).toBe(false);
   });

package/src/shared/lib/updates/shell-ua.ts

@@ -1,35 +1,51 @@
 /**
- * The `KabmoAndroid/<version>` token in a request's User-Agent.
+ * The `KabmoAndroid/<version>` / `KabmoIOS/<version>` token in a request's
+ * User-Agent.
  *
- * The APK appends it (`KabmoWebView.configure`), and it is the console's only
- * signal for two questions at once: "am I running inside the Android app" and
- * "which build of it". The UA is the right channel because it crosses the very
- * request that renders the shell, so the answer needs no bridge, no extra
- * endpoint, and no round trip — the page is served already knowing.
+ * Each native shell appends its own token, and it is the console's only signal
+ * for two questions at once: "am I running inside a shell" and "which build of
+ * it". The UA is the right channel because it crosses the very request that
+ * renders the shell, so the answer needs no bridge, no extra endpoint, and no
+ * round trip — the page is served already knowing.
+ *
+ * ONE parser for both shells, because the token grammar is one grammar and two
+ * copies would be two answers to "is this a version". What differs per shell is
+ * only the prefix, which is the table below.
  *
  * Parsed leniently and defensively: a browser can be made to send any UA, so a
  * forged token buys nothing here (the value only decides whether to show a
- * download button), and a malformed one must read as "not the app" rather than
- * as version `''`.
+ * download button), and a malformed one must read as "not the shell" rather
+ * than as version `''`.
  */
 
-/** The token's name, before the slash. */
-export const SHELL_UA_PREFIX = 'KabmoAndroid/';
+/** The native shells that report themselves on the UA. */
+export type ShellKind = 'android' | 'ios';
+
+/** The token's name, before the slash, per shell. */
+export const SHELL_UA_PREFIXES: Record<ShellKind, string> = {
+  android: 'KabmoAndroid/',
+  ios: 'KabmoIOS/',
+};
 
 /**
  * Whether this request came from an Android device at all — the app or a
  * browser on it.
  *
- * The download button has two reasons to appear and they are different offers:
- * an installed APK that is behind (an UPDATE), and a reader using Chrome or
- * Brave on a phone who may not know a native shell exists (an INSTALL). The
- * second one needs this fact, which the shell token cannot supply: a browser
- * carries no `KabmoAndroid/` token, and "no token" alone means "not the app" on
- * every platform, including a desktop where an APK is useless.
+ * The Android download button has two reasons to appear and they are different
+ * offers: an installed APK that is behind (an UPDATE), and a reader using
+ * Chrome or Brave on a phone who may not know a native shell exists (an
+ * INSTALL). The second one needs this fact, which the shell token cannot
+ * supply: a browser carries no `KabmoAndroid/` token, and "no token" alone
+ * means "not the app" on every platform, including a desktop where an APK is
+ * useless.
  *
  * Matched on `Android`, the platform token every Android browser sends, and NOT
  * on `Mobile`: an iPad sends `Mobile` and cannot install an APK, while an
  * Android tablet sends `Android` without it.
+ *
+ * There is deliberately no iOS counterpart. An IPA cannot be installed from a
+ * browser at all — iOS has no sideload-by-URL path — so an iOS browser is
+ * offered nothing, and only the installed shell asks for an update.
  */
 export function isAndroidDevice(userAgent: string | null | undefined): boolean {
   if (!userAgent) return false;
@@ -37,17 +53,22 @@ export function isAndroidDevice(userAgent: string | null | undefined): boolean {
 }
 
 /**
- * The APK version that sent this request, or null when it is not the app.
+ * The shell version that sent this request, or null when it is not that shell.
  *
  * The FIRST matching token wins: the suffix is appended once, and a duplicate
  * would mean something else crafted the string.
  */
-export function androidShellVersion(userAgent: string | null | undefined): string | null {
+export function shellVersion(
+  userAgent: string | null | undefined,
+  kind: ShellKind,
+): string | null {
   if (!userAgent) return null;
 
+  const prefix = SHELL_UA_PREFIXES[kind];
+
   for (const token of userAgent.split(/\s+/)) {
-    if (!token.startsWith(SHELL_UA_PREFIX)) continue;
-    const version = token.slice(SHELL_UA_PREFIX.length);
+    if (!token.startsWith(prefix)) continue;
+    const version = token.slice(prefix.length);
     // A version, not an arbitrary string: `1`, `1.2`, `1.2.3`, optionally with a
     // prerelease suffix. Anything else is a token this parser does not own.
     if (/^\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?$/.test(version)) return version;

package/src/shared/lib/workspace/panel-open.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which phone drawer can reach a panel, and when none can.
+ *
+ * Three answers and each is a silent failure when wrong:
+ *
+ * - a panel placed on the left with the rail ON belongs to the LEFT drawer —
+ *   the right drawer's catalog deliberately drops it (`phoneRightPanels`), so
+ *   sending the user there would open a drawer that does not list it;
+ * - the same panel with the rail OFF belongs to the RIGHT drawer, which is the
+ *   rule that keeps a placement reachable when the left drawer has no strip;
+ * - an `editor`-slot takeover belongs to NEITHER, because a phone has no editor
+ *   column — the caller must do nothing rather than navigate to a blank screen.
+ *
+ * A built-in view is always `right`, so it never lands on the left drawer even
+ * though its id is not a plugin key.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { phoneDrawerForPanel } from '@/shared/lib/workspace/panel-open';
+import type { LeftDockState } from '@/shared/lib/workspace/left-dock';
+
+const RAIL_ON: LeftDockState = { enabled: true, panels: ['plugin:stats:rightPanel'] };
+const RAIL_OFF: LeftDockState = { enabled: false, panels: ['plugin:stats:rightPanel'] };
+
+describe('phoneDrawerForPanel', () => {
+  test('a panel placed on the left, with the rail on, is the left drawer', () => {
+    expect(phoneDrawerForPanel('plugin:stats:rightPanel', RAIL_ON)).toBe('left');
+  });
+
+  test('the same placement with the rail off is the right drawer', () => {
+    // The left drawer draws no chip strip while the rail is off, so the panel
+    // stays in the right drawer's `all` catalog — and that is where the click
+    // has to land.
+    expect(phoneDrawerForPanel('plugin:stats:rightPanel', RAIL_OFF)).toBe('right');
+  });
+
+  test('an unplaced panel is the right drawer', () => {
+    expect(phoneDrawerForPanel('plugin:stats:rightPanel', { enabled: true, panels: [] })).toBe('right');
+  });
+
+  test('a built-in view is the right drawer, never the left one', () => {
+    expect(phoneDrawerForPanel('git', RAIL_ON)).toBe('right');
+    expect(phoneDrawerForPanel('files', RAIL_OFF)).toBe('right');
+  });
+
+  test('an editor-slot takeover has no drawer at all', () => {
+    // A phone has no editor column. Reporting a drawer would navigate to a
+    // screen whose catalog cannot show the panel.
+    expect(phoneDrawerForPanel('plugin:session-info:panel', RAIL_ON)).toBeNull();
+  });
+});

package/src/shared/lib/workspace/panel-open.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Opening a panel from somewhere that is not its own rail.
+ *
+ * A plugin's navbar entry can be an ACTION — `app.headerPanel({ opensPanel })`
+ * — and so can anything else that names a panel it does not draw. The click
+ * cannot resolve the destination itself, because the destination is the USER's
+ * choice: the same panel may sit on the left dock, in the right column, in the
+ * editor column, or in one of a phone's two drawers. So the event carries the
+ * panel INSTANCE key and the layout decides where that key lives right now.
+ *
+ * The placement rules live in `left-dock.ts` (one source, read by the catalogs,
+ * the rails and this module), and this file adds the one thing they cannot
+ * answer: which of a PHONE's two drawers can reach a panel. A phone has no
+ * rail, so "left" and "right" are screens rather than columns — and a panel
+ * placed on the left is drawn by the RIGHT drawer while the rail is off, which
+ * is the case a naive `side === 'left' ? leftDrawer : rightDrawer` gets wrong.
+ */
+
+import { panelSideOf, type LeftDockState, type PanelSide } from '@/shared/lib/workspace/left-dock';
+
+/**
+ * The window event that asks a layout to show a panel.
+ *
+ * `detail.panelKey` is a panel INSTANCE key (`plugin:<pluginId>:<slot>`) or a
+ * built-in view id. A key no layout can resolve is reported by the panel
+ * position's own notice, never silently ignored — the same answer the activity
+ * bar gives for a panel whose plugin was uninstalled.
+ */
+export const OPEN_PANEL_EVENT = 'omp:open-panel';
+
+export interface OpenPanelDetail {
+  /** The panel instance key to show. */
+  panelKey: string;
+}
+
+/**
+ * Ask the layout to show a panel.
+ *
+ * The one place the event is dispatched: a navbar readout, a folded menu row and
+ * anything else that names a panel must send the SAME shape, or one of them
+ * silently stops opening anything.
+ */
+export function requestOpenPanel(panelKey: string): void {
+  if (typeof window === 'undefined' || !panelKey) return;
+  window.dispatchEvent(new CustomEvent(OPEN_PANEL_EVENT, { detail: { panelKey } }));
+}
+
+/** The two screens a phone can put a panel on. */
+export type PanelDrawer = 'left' | 'right';
+
+/**
+ * The phone drawer that can reach a panel, or null when none can.
+ *
+ * Three answers, each a different fact:
+ *
+ * - `left` — the panel is placed on the dock AND the rail is on, so the left
+ *   drawer is where its chip is drawn;
+ * - `right` — everything else that the right drawer lists. That includes a
+ *   panel placed on the left while the rail is OFF: `phoneRightPanels` keeps it
+ *   there on purpose, because the left drawer then has no strip and the
+ *   placement would otherwise be unreachable;
+ * - `null` — an `editor`-slot takeover. The phone has no editor column, so
+ *   there is no screen to navigate to and the caller must do nothing rather
+ *   than send the user to a drawer that will not show it.
+ */
+export function phoneDrawerForPanel(panelKey: string, dock: LeftDockState): PanelDrawer | null {
+  const side: PanelSide = panelSideOf(panelKey, dock);
+  if (side === 'editor') return null;
+  if (side === 'left' && dock.enabled) return 'left';
+  return 'right';
+}