ompchamber 1.2.0 → 2.0.0

package/src/server/routes/settings/model-override.ts

@@ -0,0 +1,69 @@
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { isMockMode } from '@/server/mock.server';
+import { writeModelOverride, type ReasoningEffort } from '@/server/lib/omp/config/model-overrides';
+import { invalidateModelsCaches } from '@/shared/lib/models/server-cache';
+
+/**
+ * PUT /api/settings/model-override — the per-model knobs omp actually honours.
+ *
+ * omp resolves `maxTokens` and the reasoning `thinking` block per model from
+ * models.yml `modelOverrides`, and has no per-model temperature/topP at all
+ * (those exist only as global `config.yml` settings, editable in Settings →
+ * OMP Engine). Writing the chamber's model dialog anywhere else made its
+ * controls inert, so this route is the one that reaches the agent.
+ *
+ * Body: { provider, modelId, maxTokens?: number|null, reasoningEffort?: string|null }
+ */
+
+const EFFORTS: readonly ReasoningEffort[] = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+export async function action({ request, params }: ActionFunctionArgs) {
+  if (request.method !== 'PUT' && request.method !== 'POST') {
+    return methodNotAllowed({ request, params });
+  }
+  try {
+    const body = await request.json() as {
+      provider?: unknown;
+      modelId?: unknown;
+      maxTokens?: unknown;
+      reasoningEffort?: unknown;
+    };
+    const provider = typeof body.provider === 'string' ? body.provider.trim() : '';
+    const modelId = typeof body.modelId === 'string' ? body.modelId.trim() : '';
+    if (!provider || !modelId) {
+      return json({ error: 'provider and modelId are required' }, { status: 400 });
+    }
+
+    // `null` means "clear the override"; `undefined` means "leave it alone".
+    let maxTokens: number | null | undefined;
+    if (body.maxTokens === null) maxTokens = null;
+    else if (typeof body.maxTokens === 'number' && Number.isFinite(body.maxTokens) && body.maxTokens > 0) {
+      maxTokens = Math.round(body.maxTokens);
+    } else if (body.maxTokens !== undefined) {
+      return json({ error: 'maxTokens must be a positive number or null' }, { status: 400 });
+    }
+
+    let reasoningEffort: ReasoningEffort | null | undefined;
+    if (body.reasoningEffort === null) reasoningEffort = null;
+    else if (typeof body.reasoningEffort === 'string' && (EFFORTS as readonly string[]).includes(body.reasoningEffort)) {
+      reasoningEffort = body.reasoningEffort as ReasoningEffort;
+    } else if (body.reasoningEffort !== undefined) {
+      return json({ error: `reasoningEffort must be one of ${EFFORTS.join(', ')} or null` }, { status: 400 });
+    }
+
+    if (maxTokens === undefined && reasoningEffort === undefined) {
+      return json({ error: 'nothing to write' }, { status: 400 });
+    }
+
+    // Mock mode has no models.yml to edit; the overlay already carries the value.
+    if (isMockMode()) return json({ success: true, written: false, isMock: true });
+
+    const result = await writeModelOverride({ provider, modelId, maxTokens, reasoningEffort });
+    if (result.written) invalidateModelsCaches();
+    return json({ success: result.written, ...result });
+  } catch (error) {
+    return json({ error: error instanceof Error ? error.message : String(error) }, { status: 400 });
+  }
+}

package/src/server/routes/settings/provider-models.ts

@@ -124,10 +124,26 @@ async function fetchRemoteModels(baseUrl: string, apiKey?: string): Promise<Fetc
   };
 }
 
+/**
+ * omp's `api` for a custom provider, inferred from its endpoint. omp accepts
+ * eleven `api` values and there is no way to ask a gateway which one it speaks,
+ * so the chamber only claims the two dialects it can recognise by URL; every
+ * other endpoint gets the OpenAI-compatible default, which is what the
+ * model-listing probe already assumes. A gateway that speaks something else
+ * (Azure, Bedrock, Vertex, …) needs its `api` set by hand in models.yml.
+ */
+function inferProviderApi(baseUrl: string): 'openai-completions' | 'anthropic-messages' | 'google-generative-ai' {
+  if (/anthropic\./i.test(baseUrl)) return 'anthropic-messages';
+  if (/generativelanguage\.googleapis\.com/i.test(baseUrl)) return 'google-generative-ai';
+  return 'openai-completions';
+}
+
 /**
  * omp's models.yml schema requires all four cost fields when cost is present,
  * so a price is only seeded when both sides are known; missing ones default
  * to 0. Context/output labels ("128K ctx · 16K out") parse back to tokens.
+ * Cache prices come from the catalog and are kept when known — dropping them
+ * makes every cached turn look free in omp's usage accounting.
  */
 function toOmpSeed(model: ProviderModel): {
   id: string;
@@ -148,7 +164,14 @@ function toOmpSeed(model: ProviderModel): {
   };
   const contextWindow = parseTokens(model.contextWindow, 'ctx');
   const outTokens = parseTokens(model.contextWindow, 'out');
-  const hasCost = typeof model.priceInput === 'number' && typeof model.priceOutput === 'number';
+  // omp rejects the whole file on a non-finite number, so a price has to be a
+  // real finite value before it may be written at all.
+  const price = (value: unknown): number | undefined => (
+    typeof value === 'number' && Number.isFinite(value) ? value : undefined
+  );
+  const priceInput = price(model.priceInput);
+  const priceOutput = price(model.priceOutput);
+  const hasCost = priceInput !== undefined && priceOutput !== undefined;
   return {
     id: model.id,
     ...(model.name && model.name !== model.id ? { name: model.name } : {}),
@@ -158,10 +181,10 @@ function toOmpSeed(model: ProviderModel): {
     ...(outTokens && outTokens > 0 ? { maxTokens: Math.round(outTokens) } : {}),
     ...(hasCost ? {
       cost: {
-        input: model.priceInput as number,
-        output: model.priceOutput as number,
-        cacheRead: 0,
-        cacheWrite: 0,
+        input: priceInput,
+        output: priceOutput,
+        cacheRead: price(model.priceCacheRead) ?? 0,
+        cacheWrite: price(model.priceCacheWrite) ?? 0,
       },
     } : {}),
   };
@@ -170,8 +193,8 @@ function toOmpSeed(model: ProviderModel): {
 /**
  * Fill in metadata the listing endpoint did not provide from the models.dev
  * catalog: vision/reasoning/tool flags, context + output window, and
- * per-1M-token pricing. Only empty fields are filled — anything the provider
- * reported itself is kept.
+ * per-1M-token pricing (cache rates included). Only empty fields are filled —
+ * anything the provider reported itself is kept.
  */
 async function enrichFromCatalog(
   models: ProviderModel[],
@@ -201,6 +224,10 @@ async function enrichFromCatalog(
       hasTools: model.hasTools || info.tool_call === true,
       priceInput: model.priceInput ?? (typeof info.cost?.input === 'number' ? info.cost.input : undefined),
       priceOutput: model.priceOutput ?? (typeof info.cost?.output === 'number' ? info.cost.output : undefined),
+      priceCacheRead: model.priceCacheRead
+        ?? (typeof info.cost?.cache_read === 'number' ? info.cost.cache_read : undefined),
+      priceCacheWrite: model.priceCacheWrite
+        ?? (typeof info.cost?.cache_write === 'number' ? info.cost.cache_write : undefined),
     };
   });
 }
@@ -244,11 +271,7 @@ export async function action({ request }: ActionFunctionArgs) {
         const upsert = await upsertOmpProviderModels(providerSlug, {
           baseUrl,
           apiKey,
-          api: /anthropic\.com/i.test(baseUrl)
-            ? 'anthropic-messages'
-            : /generativelanguage\.googleapis\.com/i.test(baseUrl)
-              ? 'google-generative-ai'
-              : 'openai-completions',
+          api: inferProviderApi(baseUrl),
           models: enriched.map(toOmpSeed),
         });
         if (upsert.written) invalidateModelsCaches();

package/src/server/routes/settings/providers.ts

@@ -7,6 +7,7 @@ import { isMockMode } from '@/server/mock.server';
 import type { ProviderItem } from '@/shared/types';
 import { createSettingsListStore } from '@/server/lib/db/settings-store';
 import { disableNativeProvider, enableNativeProvider } from '@/server/lib/omp/config/disabled-providers';
+import { removeOmpProvider } from '@/server/lib/omp/config/providers';
 import { PROVIDERS_SETTINGS_KEY as SETTINGS_KEY, deduplicateProviderItems, mergeProviders } from '@/server/lib/models/provider-registry.server';
 import { invalidateModelsCaches } from '@/shared/lib/models/server-cache';
 
@@ -111,8 +112,37 @@ export async function action({ request, params }: ActionFunctionArgs) {
       const id = url.searchParams.get('id');
       if (!id) return json({ error: 'id is required' }, { status: 400 });
 
+      const stored = await readStoredProviders();
+      const target = stored.find((provider) => provider.id === id);
       const list = await providersStore.remove(db, id, { absent: DEFAULT_PROVIDERS_LIST, empty: DEFAULT_PROVIDERS_LIST });
-      return respondWithProviders(list);
+
+      // Removing the overlay row alone left the provider registered in
+      // models.yml, so omp kept serving it and the next load merged it straight
+      // back into this list — a delete that visibly did nothing. Unregister it
+      // from the agent's own registry too.
+      let removedFromOmp = false;
+      if (target?.slug && !isMockMode()) {
+        try {
+          removedFromOmp = (await removeOmpProvider(target.slug)).removed;
+          // A provider omp still holds in disabledProviders would linger as a
+          // "disconnected" ghost entry after its models are gone.
+          await enableNativeProvider(target.slug);
+        } catch (error) {
+          // The overlay row is already gone; report the native failure instead
+          // of failing the whole request, so the UI can tell the user the entry
+          // is still in models.yml.
+          const merged = await mergeProviders(list).catch(() => null);
+          return json({
+            success: true,
+            providers: merged?.providers ?? list,
+            removedFromOmp: false,
+            warning: error instanceof Error ? error.message : 'models.yml cleanup failed',
+          });
+        }
+      }
+      invalidateModelsCaches();
+      const merged = await mergeProviders(list);
+      return json({ success: true, providers: merged.providers, removedFromOmp });
     }
 
     if (request.method === 'POST' || request.method === 'PUT') {

package/src/server/routes/settings/root.ts

@@ -3,7 +3,7 @@ import type { ActionFunctionArgs, LoaderFunctionArgs } from '@/server/lib/remix-
 import { methodNotAllowed } from '@/server/lib/route-adapter';
 import { getDb } from '@/server/db.server';
 import { isMockMode } from '@/server/mock.server';
-import { readAllSettingsJson, writeSettingsJson, writeSettingsRaw } from '@/server/lib/db/settings-store';
+import { isPlainObject, mergeSettingsJson, readAllSettingsJson, writeSettingsJson, writeSettingsRaw } from '@/server/lib/db/settings-store';
 
 export async function loader({ request: _request }: LoaderFunctionArgs) {
   try {
@@ -24,9 +24,14 @@ export async function action({ request, params }: ActionFunctionArgs) {
     const data = await request.json();
     const db = await getDb();
 
-    // Data should be an object of key-value pairs
+    // Data should be an object of key-value pairs. Object values merge into
+    // whatever the key already holds, so a writer that sends one key's patch —
+    // the settings modal now sends only what changed — cannot discard the keys
+    // another writer stored in between. Arrays and scalars still replace.
     for (const [key, value] of Object.entries(data)) {
-      if (typeof value === 'object') {
+      if (isPlainObject(value)) {
+        await mergeSettingsJson(db, key, value);
+      } else if (typeof value === 'object') {
         await writeSettingsJson(db, key, value);
       } else {
         await writeSettingsRaw(db, key, String(value));

package/src/shared/lib/chat/btw/client.ts

@@ -14,6 +14,8 @@
  */
 
 import type { AgentImage, BtwFrame, BtwState, StreamTransport } from '@/shared/types';
+import type { AttachedTextFileData } from '@/shared/lib/chat/attachments';
+import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { connectEvents } from '@/shared/lib/chat/omp/sse';
 import { connectSocket } from '@/shared/lib/chat/omp/socket';
 import { btwEventsUrl, btwSocketUrl } from '@/shared/lib/chat/omp/transport';
@@ -70,6 +72,13 @@ export interface AskBtwInput {
   topicId?: string;
   question: string;
   images?: AgentImage[];
+  /** Text files inlined for this question (read at attach time by the composer). */
+  textFiles?: AttachedTextFileData[];
+  /** Composer picks for a FIRST question — a topic that does not exist yet has
+   *  no row to hold them, so they ride the ask and reach the spawn. */
+  model?: { provider: string; id: string };
+  thinkingLevel?: string;
+  approvalMode?: ApprovalMode;
 }
 
 export function askBtwQuestion(sessionId: string, input: AskBtwInput): Promise<BtwState> {
@@ -78,6 +87,10 @@ export function askBtwQuestion(sessionId: string, input: AskBtwInput): Promise<B
     question: input.question,
     ...(input.topicId ? { topicId: input.topicId } : {}),
     ...(input.images?.length ? { images: input.images } : {}),
+    ...(input.textFiles?.length ? { textFiles: input.textFiles } : {}),
+    ...(input.model ? { provider: input.model.provider, modelId: input.model.id } : {}),
+    ...(input.thinkingLevel ? { thinkingLevel: input.thinkingLevel } : {}),
+    ...(input.approvalMode ? { accessMode: input.approvalMode } : {}),
   });
 }
 
@@ -85,6 +98,27 @@ export function abortBtwQuestion(sessionId: string, topicId: string): Promise<Bt
   return requestBtw<BtwState>(sessionId, 'POST', { action: 'abort', topicId });
 }
 
+export function setBtwModel(sessionId: string, topicId: string, provider: string, modelId: string): Promise<BtwState> {
+  return requestBtw<BtwState>(sessionId, 'POST', { action: 'set_model', topicId, provider, modelId });
+}
+
+export function setBtwThinkingLevel(sessionId: string, topicId: string, level: string): Promise<BtwState> {
+  return requestBtw<BtwState>(sessionId, 'POST', { action: 'set_thinking_level', topicId, level });
+}
+
+export function setBtwAccessMode(sessionId: string, topicId: string, accessMode: ApprovalMode): Promise<BtwState> {
+  return requestBtw<BtwState>(sessionId, 'POST', { action: 'set_access_mode', topicId, accessMode });
+}
+
+export function respondBtwDialog(
+  sessionId: string,
+  topicId: string,
+  id: string,
+  response: { value: string } | { confirmed: boolean } | { cancelled: true },
+): Promise<BtwState> {
+  return requestBtw<BtwState>(sessionId, 'POST', { action: 'dialog_response', topicId, id, response });
+}
+
 export function promoteBtwTopic(sessionId: string, topicId: string): Promise<{ sessionId: string }> {
   return requestBtw<{ sessionId: string }>(sessionId, 'POST', { action: 'promote', topicId });
 }

package/src/shared/lib/chat/timeline/tool-phrases.ts

@@ -90,10 +90,17 @@ export const DEVICE_VERBS: Record<string, string> = {
  * Phrase shown while the model streams reasoning or prose rather than running a
  * tool. A tool call always names itself from its own name (see
  * `describeAssistantPhase`), so there is no in-between "preparing" state.
+ *
+ * `sideQuestion` is the BTW panel's FALLBACK phase, used only before the side
+ * child has reported anything: once it does, the panel shows the child's own
+ * per-phase verb (`Thinking`, `Writing response`, or the running tool's name).
+ * It is named for the feature rather than reusing `thinking`, which would claim
+ * a reasoning phase that has not been observed yet.
  */
 export const PHASE_VERBS = {
   thinking: 'Thinking',
   writing: 'Writing response',
+  sideQuestion: 'Answering side question',
 } as const;
 
 export function asString(value: unknown): string | undefined {

package/src/shared/lib/code/shiki-themes.ts

@@ -3,12 +3,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * The two Shiki palettes every token carries.
+ *
+ * Shiki emits both palettes on every token span as `--shiki-light` /
+ * `--shiki-dark` custom properties with no inline color, so switching themes
+ * recolors code with zero JS and no re-highlight. `tailwind.css` selects which
+ * one paints, keyed off `<html data-theme-variant>` rather than a list of theme
+ * ids — that list is what a new theme used to fall through.
+ */
 export const SHIKI_LIGHT = 'one-light';
 export const SHIKI_DARK = 'one-dark-pro';
 
 export const SHIKI_THEMES = { light: SHIKI_LIGHT, dark: SHIKI_DARK } as const;
-
-/** Collapse any app theme id to the syntax theme key it uses. */
-export function resolveSyntaxThemeKey(theme?: string): 'light' | 'dark' {
-  return theme === 'noir' || theme === 'one-dark-pro-soft' ? 'dark' : 'light';
-}

package/src/shared/lib/fs/file-tree.ts

@@ -1,6 +1,9 @@
-export function setChildrenAt(nodes: any[], path: string, children: any[]): any[] {
+import type { FsNode } from '@/shared/types';
+
+/** Replace the children of the node at `path`, rebuilding only that branch. */
+export function setChildrenAt(nodes: FsNode[], path: string, children: FsNode[]): FsNode[] {
   return nodes.map(node => {
-    if (node.path === path) return { ...node, children, is_expanded: 1 };
+    if (node.path === path) return { ...node, children };
     if (Array.isArray(node.children)) {
       const nested = setChildrenAt(node.children, path, children);
       if (nested !== node.children) return { ...node, children: nested };
@@ -9,18 +12,20 @@ export function setChildrenAt(nodes: any[], path: string, children: any[]): any[
   });
 }
 
-export function rehydrateTree(nodes: any[], cache: Record<string, any[]>, expanded: Set<string>): any[] {
+/**
+ * Re-attach the children already loaded for a folder, so a re-listing of the
+ * same tree does not collapse what the user had open.
+ *
+ * Which folders are open is the caller's `expandedPaths` set, keyed by paths
+ * RELATIVE to the listed root — which is why the caller must drop both that set
+ * and the cache when the listed root changes: `src/` under one workspace would
+ * otherwise rehydrate into `src/` under the next.
+ */
+export function rehydrateTree(nodes: FsNode[], cache: Record<string, FsNode[]>): FsNode[] {
   return nodes.map(node => {
     if (node.type !== 'folder') return node;
     const cached = cache[node.path];
-    const wasExpanded = expanded.has(node.path);
-    if (cached) {
-      return {
-        ...node,
-        children: rehydrateTree(cached, cache, expanded),
-        is_expanded: wasExpanded ? 1 : 0,
-      };
-    }
-    return node;
+    if (!cached) return node;
+    return { ...node, children: rehydrateTree(cached, cache) };
   });
 }

package/src/shared/lib/markdown/autolink.test.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { renderMarkdown } from '@/shared/lib/markdown/marked';
+
+describe('autolink vs code span', () => {
+  test('a backticked email stays a code span, not a mailto link', () => {
+    const html = renderMarkdown('addresses (`NNN+login@users.noreply.github.com`) and more');
+    expect(html).toContain('<code class="inline-code">NNN+login@users.noreply.github.com</code>');
+    expect(html).not.toContain('mailto:');
+    expect(html).not.toContain('`');
+  });
+
+  test('a backticked URL stays a code span', () => {
+    const html = renderMarkdown('see `https://bun.sh/docs` for more');
+    expect(html).toContain('<code class="inline-code">https://bun.sh/docs</code>');
+  });
+
+  test('ordinary autolinks are untouched', () => {
+    expect(renderMarkdown('see https://bun.sh/docs for more')).toContain('<a href="https://bun.sh/docs">');
+    expect(renderMarkdown('write to a@b.com now')).toContain('<a href="mailto:a@b.com">');
+  });
+
+  test('a URL next to a code span keeps both', () => {
+    const html = renderMarkdown('https://bun.sh then `npm i`');
+    expect(html).toContain('<a href="https://bun.sh">');
+    expect(html).toContain('<code class="inline-code">npm i</code>');
+  });
+});

package/src/shared/lib/markdown/autolink.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * linkify-it autolinking that yields to code spans.
+ *
+ * linkify-it accepts a backtick as an email local-part character (RFC 5321's
+ * `!#$%&'*+/=?^_`{|}~-` set), so `` `NNN+login@users.noreply.github.com` ``
+ * matches as ONE autolink whose raw text spans both backticks. The extension
+ * runs before marked's own inline rules, so that match is consumed and the code
+ * span never forms: the backticks end up as link text and the href carries
+ * `%60` escapes (`mailto:%60NNN+…%60`) — a broken link AND a code span that
+ * shows its delimiters.
+ *
+ * A code span wins over an autolink in CommonMark, and the inline lexer reaches
+ * the OPENING backtick first — so refusing every match whose raw contains a
+ * backtick is enough to hand that position back to the `codespan` rule, which
+ * then swallows the whole span. Autolinks without a backtick in them are
+ * untouched, which is every ordinary URL and email.
+ */
+
+import type {
+  MarkedExtension,
+  RendererExtension,
+  Token,
+  TokenizerAndRendererExtension,
+  TokenizerThis,
+} from 'marked';
+import markedLinkifyIt from 'marked-linkify-it';
+
+/** Refuse an autolink whose raw text carries a backtick (see the file header). */
+function guardAutolink(
+  extension: TokenizerAndRendererExtension | RendererExtension,
+): TokenizerAndRendererExtension | RendererExtension {
+  if (!('tokenizer' in extension) || !extension.tokenizer) return extension;
+  const tokenize = extension.tokenizer;
+  return {
+    ...extension,
+    tokenizer(this: TokenizerThis, source: string, tokens: Token[]) {
+      const token = tokenize.call(this, source, tokens);
+      return token && !token.raw.includes('`') ? token : undefined;
+    },
+  };
+}
+
+export function codeSafeAutolink(): MarkedExtension {
+  return { extensions: (markedLinkifyIt().extensions ?? []).map(guardAutolink) };
+}

package/src/shared/lib/markdown/document-urls.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { resolveDocumentReference, rewriteDocumentReferences } from '@/shared/lib/markdown/document-urls';
+
+const doc = (path: string, root?: string, repo?: string) => ({ path, root, repo });
+
+describe('resolveDocumentReference', () => {
+  test('resolves beside the document, not beside the app', () => {
+    expect(resolveDocumentReference('docs/hero.png', doc('README.md'))?.path).toBe('docs/hero.png');
+    expect(resolveDocumentReference('img/a.png', doc('docs/guide.md'))?.path).toBe('docs/img/a.png');
+  });
+
+  test('walks out of the document folder', () => {
+    expect(resolveDocumentReference('../README.md', doc('docs/guide.md'))?.path).toBe('README.md');
+    expect(resolveDocumentReference('./a.png', doc('docs/guide.md'))?.path).toBe('docs/a.png');
+  });
+
+  test('a leading slash is the scope root, not the document folder', () => {
+    expect(resolveDocumentReference('/docs/a.png', doc('manual/v2/guide.md'))?.path).toBe('docs/a.png');
+  });
+
+  test('cannot climb above the scope root', () => {
+    expect(resolveDocumentReference('../../../../etc/passwd', doc('README.md'))?.path).toBe('etc/passwd');
+  });
+
+  test('keeps the scope in the raw URL', () => {
+    const resolved = resolveDocumentReference('a.png', doc('docs/guide.md', '/ws', 'projects/x'));
+    expect(resolved?.url).toBe('/api/fs/raw?path=docs%2Fa.png&root=%2Fws&repo=projects%2Fx');
+    // `repo: '.'` means the root itself, so the param is omitted.
+    expect(resolveDocumentReference('a.png', doc('docs/guide.md', '/ws', '.'))?.url)
+      .toBe('/api/fs/raw?path=docs%2Fa.png&root=%2Fws');
+  });
+
+  test('a query or fragment belongs to the reference, not the path', () => {
+    expect(resolveDocumentReference('img/a.png?v=2#frag', doc('docs/guide.md'))?.path).toBe('docs/img/a.png');
+  });
+
+  test('decodes percent escapes', () => {
+    expect(resolveDocumentReference('my%20image.png', doc('README.md'))?.path).toBe('my image.png');
+  });
+
+  test('leaves anything that is not a relative file reference alone', () => {
+    for (const reference of ['https://x.test/a.png', 'mailto:a@b.c', 'data:image/png;base64,AA', '//cdn.test/a.png', '#section', '   ', '']) {
+      expect(resolveDocumentReference(reference, doc('README.md'))).toBeNull();
+    }
+  });
+});
+
+describe('rewriteDocumentReferences', () => {
+  test('points images at the raw route and links at the file they name', () => {
+    expect(rewriteDocumentReferences('<img src="docs/a.png"><a href="AGENTS.md">x</a>', doc('README.md')))
+      .toBe('<img src="/api/fs/raw?path=docs%2Fa.png"><a href="/api/fs/raw?path=AGENTS.md" data-file-path="AGENTS.md">x</a>');
+  });
+
+  test('escapes the query separator so the attribute survives HTML parsing', () => {
+    expect(rewriteDocumentReferences('<img src="a.png">', doc('docs/g.md', '/ws')))
+      .toBe('<img src="/api/fs/raw?path=docs%2Fa.png&amp;root=%2Fws">');
+  });
+
+  test('leaves external references and escaped code untouched', () => {
+    const html = '<a href="https://x.test">x</a><code class="language-html">&lt;img src=&quot;a.png&quot;&gt;</code>';
+    expect(rewriteDocumentReferences(html, doc('README.md'))).toBe(html);
+  });
+});

package/src/shared/lib/markdown/document-urls.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Resolve the relative references of a markdown *document* (an opened file's
+ * preview) to the workspace files they actually name.
+ *
+ * A previewed file is not a chat message: `![](docs/hero.png)` means the image
+ * on disk beside the document, and `[Architecture](AGENTS.md)` means that file.
+ * Neither resolves on its own — the preview is an app route, so a relative URL
+ * is requested from the server's own origin (`/docs/hero.png` → 404, and a
+ * click would navigate the console away from itself). Each one is rewritten to
+ * the workspace file it points at: images through `/api/fs/raw` (real bytes,
+ * real content-type) and links through the same URL plus the resolved path in
+ * `data-file-path`, which the panel turns back into an editor tab.
+ *
+ * Only plain relative references are touched. Anything with a scheme
+ * (`https:`, `mailto:`, `data:`), a protocol-relative `//host`, or a bare
+ * `#anchor` is the document's own business and is left exactly as written.
+ */
+
+import { buildFsRawUrl } from '@/shared/lib/fs/paths';
+
+/**
+ * Where the document lives. `path` is relative to the picked scope exactly the
+ * way `/api/fs/raw` and the file panel read it: relative to `repo` when one is
+ * picked, otherwise to `root`.
+ */
+export interface DocumentScope {
+  path: string;
+  root?: string;
+  repo?: string;
+}
+
+export interface ResolvedDocumentReference {
+  /** Scope-relative path of the referenced file — what an editor tab opens. */
+  path: string;
+  /** Raw-bytes URL of the same file, for an `<img src>` or a middle-click. */
+  url: string;
+}
+
+/** A scheme (`https:`), protocol-relative host, fragment, or empty ref. */
+const ABSOLUTE_REFERENCE_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|$)/i;
+
+/** Collapse `.`/`..` segments; ascending above the scope root is dropped. */
+function normalizeSegments(segments: string[]): string {
+  const out: string[] = [];
+  for (const segment of segments) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join('/');
+}
+
+/** `%20`-style escapes are how a markdown link writes a space. */
+function decodeReference(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Resolve one reference written inside `scope`'s document, or null when it is
+ * not a relative file reference (leave those untouched).
+ */
+export function resolveDocumentReference(
+  reference: string,
+  scope: DocumentScope,
+): ResolvedDocumentReference | null {
+  const raw = reference.trim();
+  if (ABSOLUTE_REFERENCE_RE.test(raw)) return null;
+
+  // `?v=1` and `#section` address the preview, not the file on disk.
+  const withoutQuery = raw.split(/[?#]/)[0];
+  const decoded = decodeReference(withoutQuery);
+  if (!decoded) return null;
+
+  // A leading slash is root-relative (GitHub's repo-root rule), and the scope
+  // frame already IS that root, so it resolves without the document's folder.
+  const rootRelative = /^[/\\]/.test(decoded);
+  const documentDir = scope.path.replace(/\\/g, '/').split('/').slice(0, -1);
+  const segments = decoded.split(/[\\/]+/);
+  const path = normalizeSegments(rootRelative ? segments : [...documentDir, ...segments]);
+  if (!path) return null;
+
+  return { path, url: buildFsRawUrl({ path, root: scope.root, repo: scope.repo }) };
+}
+
+/** Attribute values are injected as HTML, so `&` and `"` must be entities. */
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+
+/**
+ * Rewrite the relative `src`/`href` attributes of rendered document HTML.
+ * Fenced code is already escaped by the renderer, so a literal `src="` inside
+ * a code block cannot be mistaken for an attribute.
+ */
+export function rewriteDocumentReferences(html: string, scope: DocumentScope): string {
+  return html.replace(/(\s(?:src|href))="([^"]*)"/g, (match, attribute: string, value: string) => {
+    const resolved = resolveDocumentReference(value, scope);
+    if (!resolved) return match;
+    const url = ` ${attribute.trim()}="${escapeAttribute(resolved.url)}"`;
+    // The resolved path rides along on links only: it is what a click opens as
+    // a tab, and a mid-click still has the raw URL to fall back to.
+    return attribute.trim() === 'href'
+      ? `${url} data-file-path="${escapeAttribute(resolved.path)}"`
+      : url;
+  });
+}