ompchamber 1.1.0 → 1.2.1

package/src/shared/lib/chat/composer/trigger.ts

@@ -1,4 +1,4 @@
-import type { ComposerPickItem, ComposerTrigger } from '@/shared/types';
+import type { CommandItem, ComposerMatchItem, ComposerPickItem, ComposerTrigger } from '@/shared/types';
 
 /** Chars that may legally precede an `@` agent trigger (besides string start). */
 const AT_PRECEDING_RE = /[\s([{]/;
@@ -9,6 +9,35 @@ export const SKILL_NAMESPACE = 'skill:';
 /** The collapsed namespace row's token (no trailing space on accept). */
 export const SKILL_NAMESPACE_TOKEN = `/${SKILL_NAMESPACE}`;
 
+/**
+ * Slash commands the chamber answers itself, reserved exactly like oh-my-pi
+ * reserves its own tokens.
+ *
+ * omp's `/btw` is TUI-only — its registry entry has `handleTui` and no
+ * text-mode `handle`, and `get_available_commands` only advertises entries the
+ * RPC dispatcher can run — so the composer would offer every command except the
+ * one it intercepts on send. The entry is byte-for-byte omp's own metadata
+ * (description and inline hint), so the popup reads the same in both clients.
+ */
+export const CHAMBER_COMMANDS: CommandItem[] = [
+  {
+    id: 'chamber-btw',
+    name: 'btw',
+    description: "Ask a side question, or browse this session's BTW history",
+    scope: 'system',
+    template: '',
+    isBuiltIn: true,
+    inputHint: '[question]',
+  },
+];
+
+/** True when the chamber intercepts this command instead of forwarding it to
+ *  omp as chat text. */
+function isChamberOwnedCommand(name: string): boolean {
+  const lower = name.toLowerCase();
+  return CHAMBER_COMMANDS.some((command) => command.name.toLowerCase() === lower);
+}
+
 /**
  * Index of a `/` that starts the draft, ignoring leading whitespace —
  * oh-my-pi's `findLeadingSlashCommandStart`.
@@ -131,6 +160,21 @@ export function tokenForItem(item: ComposerPickItem): string {
   return item.insertWithoutSpace ? item.token : `${item.token} `;
 }
 
+/**
+ * Whether a popup accept should stand aside and let Enter mean "send".
+ *
+ * Only the chamber's own commands qualify: the composer intercepts those on
+ * send, so for `/btw` the Enter *is* the action and accept-on-Enter would
+ * swallow the very keystroke the user is aiming at. Every command omp owns
+ * keeps accepting, which is what opens its argument completions — including the
+ * ones that declare no subcommands and take free-form arguments.
+ */
+export function sendInsteadOfAccept(trigger: ComposerTrigger, item: ComposerMatchItem | undefined): boolean {
+  if (!item || trigger.kind !== 'command' || trigger.phase !== 'name') return false;
+  if (item.name.toLowerCase() !== trigger.query.toLowerCase()) return false;
+  return isChamberOwnedCommand(item.name);
+}
+
 /** Splice `token` over the trigger span in `value`, returning the new value and caret. */
 export function insertToken(
   value: string,

package/src/shared/lib/chat/omp/agent-events.ts

@@ -20,40 +20,20 @@ import { normalizeThinkingLevel } from '@/shared/lib/models/thinking-levels';
 import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
 import { describeAssistantPhase, describeToolActivity } from '@/shared/lib/chat/timeline/tool-verbs';
 import { FILE_MUTATION_EVENT, isFileMutatingTool } from '@/shared/lib/chat/omp/file-mutations';
+import {
+  pairToolOutputs,
+  putToolResult,
+  recordToolResult,
+  refreshToolMessage,
+  type ToolResultHost,
+  type ToolResultRecord,
+} from '@/shared/lib/chat/omp/tool-results';
 
-/** Tool output accumulated between a `toolCall` block and its result frame. */
-export interface ToolResultRecord {
-  output: string;
-  isError?: boolean;
-  details?: Record<string, any>;
-}
-
-/** Per-entry cap on stored tool output; the tail of a build log is what matters. */
-const MAX_TOOL_OUTPUT_CHARS = 200_000;
-/** Max tool results retained per session; oldest entries are dropped first. */
-const MAX_TRACKED_TOOL_RESULTS = 200;
-
-/** Truncate tool output to the cap, keeping the tail and marking the cut. */
-function capToolOutput(output: string): string {
-  if (output.length <= MAX_TOOL_OUTPUT_CHARS) return output;
-  return `…[truncated]\n${output.slice(-MAX_TOOL_OUTPUT_CHARS)}`;
-}
+// Re-exported so stream.ts and the timeline hook keep their existing import
+// site; the implementation lives in tool-results.ts.
+export type { ToolResultRecord } from '@/shared/lib/chat/omp/tool-results';
 
-/** Write a tool result into the map, enforcing both caps. */
-function storeToolResult(
-  map: Map<string, ToolResultRecord>,
-  callId: string,
-  record: ToolResultRecord,
-): void {
-  map.set(callId, { ...record, output: capToolOutput(record.output) });
-  while (map.size > MAX_TRACKED_TOOL_RESULTS) {
-    const oldest = map.keys().next().value;
-    if (oldest === undefined) break;
-    map.delete(oldest);
-  }
-}
-
-export interface OmpAgentFoldDeps {
+export interface OmpAgentFoldDeps extends ToolResultHost {
   sessionId: string;
   setState: Dispatch<SetStateAction<OmpAgentState>>;
   callbacksRef: RefObject<OmpAgentCallbacks>;
@@ -78,45 +58,9 @@ function setActivity(verb: string | undefined, deps: OmpAgentFoldDeps): void {
   deps.callbacksRef.current?.onActivity?.(verb);
 }
 
-/** Re-emit the last tool-carrying assistant message with its results paired. */
-function pairToolOutputs(
-  msg: ChatMessageData,
-  toolResultsRef: RefObject<Map<string, ToolResultRecord>>,
-): ChatMessageData {
-  if (!msg.toolCalls?.length) return msg;
-  const toolCalls = msg.toolCalls.map(tc => {
-    const res = toolResultsRef.current?.get(tc.id);
-    return res
-      ? {
-          ...tc,
-          output: res.output,
-          details: tc.details || res.details || undefined,
-          status: (res.isError ? 'error' : 'success') as ToolCallData['status'],
-        }
-      : tc;
-  });
-  return { ...msg, toolCalls };
-}
-
-/** Record a toolResult frame's output against its tool call id. */
-function recordToolResult(
-  raw: Record<string, unknown>,
-  deps: OmpAgentFoldDeps,
-): void {
-  const callId = typeof raw.toolCallId === 'string' ? raw.toolCallId : undefined;
-  if (!callId) return;
-  deps.toolResultsRef.current?.set(callId, {
-    output: extractTextFromContent(raw.content),
-    details: (raw.details && typeof raw.details === 'object' ? raw.details : undefined) as ToolResultRecord['details'],
-  });
-}
-
-/** Re-emit the last tool-carrying message when `callId` belongs to it. */
-function refreshToolMessage(callId: string | undefined, deps: OmpAgentFoldDeps): void {
-  if (!callId) return;
-  const last = deps.lastToolMessageRef.current;
-  if (!last?.toolCalls?.some(tc => tc.id === callId)) return;
-  deps.callbacksRef.current?.onMessageUpdate?.(pairToolOutputs(last, deps.toolResultsRef));
+/** Narrow a deps record to the tool-output host, adding the re-emit sink. */
+function toolHost(deps: OmpAgentFoldDeps): ToolResultHost {
+  return { ...deps, onMessageUpdate: deps.callbacksRef.current?.onMessageUpdate };
 }
 
 /** Flush assistant turns that stopped abnormally and were never streamed as
@@ -141,7 +85,7 @@ function materializeTerminalMessages(
     if (raw.stopReason !== 'aborted' && raw.stopReason !== 'error') continue;
     const converted = toChatMessage(raw, false);
     if (!converted) continue;
-    const paired = pairToolOutputs(converted, deps.toolResultsRef);
+    const paired = pairToolOutputs(converted, deps);
     if (paired.toolCalls?.length) deps.lastToolMessageRef.current = paired;
     callbacks?.onMessageEnd?.(paired);
     if (typeof raw.errorMessage === 'string') errorMessage = raw.errorMessage;
@@ -205,7 +149,7 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       const completed = data.message as Record<string, unknown> | undefined;
       if (!completed) break;
       if (completed.role === 'toolResult') {
-        recordToolResult(completed, deps);
+        recordToolResult(completed, toolHost(deps));
         break;
       }
       if (completed.role === 'custom') break;
@@ -219,7 +163,7 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       if (converted.role !== 'user' && deps.currentThinkingLevelRef.current) {
         converted.thinkingLevel = deps.currentThinkingLevelRef.current;
       }
-      const paired = pairToolOutputs(converted, deps.toolResultsRef);
+      const paired = pairToolOutputs(converted, deps);
       if (paired.toolCalls?.length) deps.lastToolMessageRef.current = paired;
       callbacks?.onMessageEnd?.(paired);
       break;
@@ -254,9 +198,8 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       const partial = toolResultText(data.partialResult);
       if (!callId || !partial) break;
       const prev = deps.toolResultsRef.current?.get(callId)?.output ?? '';
-      const map = deps.toolResultsRef.current;
-      if (map) storeToolResult(map, callId, { output: prev + partial });
-      refreshToolMessage(callId, deps);
+      putToolResult(deps, callId, { output: prev + partial });
+      refreshToolMessage(callId, toolHost(deps));
       break;
     }
 
@@ -264,13 +207,12 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       const callId = typeof data.toolCallId === 'string' ? data.toolCallId : undefined;
       if (!callId) break;
       setActivity(PHASE_VERBS.thinking, deps);
-      const map = deps.toolResultsRef.current;
-      if (map) storeToolResult(map, callId, {
+      putToolResult(deps, callId, {
         output: toolResultText(data.result),
         isError: data.isError === true,
         details: (data.details && typeof data.details === 'object' ? data.details : undefined) as ToolResultRecord['details'],
       });
-      refreshToolMessage(callId, deps);
+      refreshToolMessage(callId, toolHost(deps));
       // A file-mutating tool just finished — tell the data-bearing right panels
       // (files / git / context) to re-read now, not on their next poll tick.
       // Guarded: the fold also runs headless under `bun test` (no window).
@@ -328,6 +270,17 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       break;
     }
 
+    // omp renamed the session (auto-title generation, /rename, set_session_name).
+    // Nothing in the timeline changes, but the sidebar reads titles from the
+    // session file — and the rename is a 256-byte in-place slot write that the
+    // scan cache's mtime key cannot see — so this frame is the only push
+    // signal that the list is stale.
+    case 'session_info_update': {
+      const title = typeof data.title === 'string' ? data.title.trim() : '';
+      if (title) callbacks?.onSessionTitleChanged?.(title);
+      break;
+    }
+
     case 'notice': {
       callbacks?.onNotice?.(
         typeof data.level === 'string' ? data.level : 'info',

package/src/shared/lib/chat/omp/socket.ts

@@ -18,8 +18,7 @@
  * route's observer-only contract.
  */
 
-import type { OmpAgentEvent } from '@/shared/types';
-import type { AgentStreamConnection, AgentStreamHandlers } from '@/shared/lib/chat/omp/transport';
+import type { AgentStreamConnection, AgentStreamHandlers, StreamConnection, StreamHandlers } from '@/shared/lib/chat/omp/transport';
 import { agentSocketUrl } from '@/shared/lib/chat/omp/transport';
 
 const RECONNECT_BASE_MS = 500;
@@ -27,7 +26,8 @@ const RECONNECT_MAX_MS = 8_000;
 /** Consecutive re-dials that never opened before the stream is given up on. */
 const MAX_FAILED_DIALS = 4;
 
-export function connectAgentSocket(sessionId: string, handlers: AgentStreamHandlers): AgentStreamConnection {
+/** One duplex JSON socket: reconnect with capped backoff, terminal first dial. */
+export function connectSocket<TFrame>(url: string, handlers: StreamHandlers<TFrame>): StreamConnection {
   let socket: WebSocket | null = null;
   let retryTimer: ReturnType<typeof setTimeout> | null = null;
   let failures = 0;
@@ -35,7 +35,7 @@ export function connectAgentSocket(sessionId: string, handlers: AgentStreamHandl
   let released = false;
 
   const dial = () => {
-    const ws = new WebSocket(agentSocketUrl(sessionId));
+    const ws = new WebSocket(url);
     socket = ws;
 
     ws.onopen = () => {
@@ -47,9 +47,9 @@ export function connectAgentSocket(sessionId: string, handlers: AgentStreamHandl
 
     ws.onmessage = (event) => {
       if (released) return;
-      let data: OmpAgentEvent;
+      let data: TFrame;
       try {
-        data = JSON.parse(String(event.data)) as OmpAgentEvent;
+        data = JSON.parse(String(event.data)) as TFrame;
       } catch {
         return;
       }
@@ -93,3 +93,8 @@ export function connectAgentSocket(sessionId: string, handlers: AgentStreamHandl
     },
   };
 }
+
+/** WebSocket transport for a session's agent event stream. */
+export function connectAgentSocket(sessionId: string, handlers: AgentStreamHandlers): AgentStreamConnection {
+  return connectSocket(agentSocketUrl(sessionId), handlers);
+}

package/src/shared/lib/chat/omp/sse.ts

@@ -12,12 +12,12 @@
  * (the server closed the stream) is reported upward.
  */
 
-import type { OmpAgentEvent } from '@/shared/types';
-import type { AgentStreamConnection, AgentStreamHandlers } from '@/shared/lib/chat/omp/transport';
+import type { AgentStreamConnection, AgentStreamHandlers, StreamConnection, StreamHandlers } from '@/shared/lib/chat/omp/transport';
 import { agentEventsUrl } from '@/shared/lib/chat/omp/transport';
 
-export function connectAgentEvents(sessionId: string, handlers: AgentStreamHandlers): AgentStreamConnection {
-  const source = new EventSource(agentEventsUrl(sessionId));
+/** One EventSource stream: the browser owns reconnection on transient drops. */
+export function connectEvents<TFrame>(url: string, handlers: StreamHandlers<TFrame>): StreamConnection {
+  const source = new EventSource(url);
   let released = false;
 
   source.onopen = () => {
@@ -27,9 +27,9 @@ export function connectAgentEvents(sessionId: string, handlers: AgentStreamHandl
 
   source.onmessage = (event) => {
     if (released) return;
-    let data: OmpAgentEvent;
+    let data: TFrame;
     try {
-      data = JSON.parse(event.data) as OmpAgentEvent;
+      data = JSON.parse(event.data) as TFrame;
     } catch {
       return;
     }
@@ -51,3 +51,8 @@ export function connectAgentEvents(sessionId: string, handlers: AgentStreamHandl
     },
   };
 }
+
+/** SSE transport for a session's agent event stream. */
+export function connectAgentEvents(sessionId: string, handlers: AgentStreamHandlers): AgentStreamConnection {
+  return connectEvents(agentEventsUrl(sessionId), handlers);
+}

package/src/shared/lib/chat/omp/tool-results.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tool-output bookkeeping for the live agent stream.
+ *
+ * omp reports a tool call in an assistant message and its output in separate
+ * frames (`tool_execution_update` partials, then `tool_execution_end`). The
+ * timeline needs the two halves re-joined on the message that carries the call,
+ * so this module owns the call-id → output map and the re-emit that pairs them.
+ *
+ * Split out of agent-events.ts so that file stays under the repo's per-file
+ * size ceiling. The host is a narrow structural view of the fold's deps — not
+ * the deps type itself — so neither module imports the other.
+ */
+
+import type { RefObject } from 'preact/compat';
+import type { ChatMessageData, ToolCallData } from '@/shared/types';
+import { extractTextFromContent } from '@/shared/lib/omp/session/mapper';
+
+/** Tool output accumulated between a `toolCall` block and its result frame. */
+export interface ToolResultRecord {
+  output: string;
+  isError?: boolean;
+  details?: Record<string, any>;
+}
+
+/** Per-entry cap on stored tool output; the tail of a build log is what matters. */
+const MAX_TOOL_OUTPUT_CHARS = 200_000;
+/** Max tool results retained per session; oldest entries are dropped first. */
+const MAX_TRACKED_TOOL_RESULTS = 200;
+
+/** The slice of the fold's deps this module needs. */
+export interface ToolResultHost {
+  toolResultsRef: RefObject<Map<string, ToolResultRecord>>;
+  lastToolMessageRef: RefObject<ChatMessageData>;
+  /** Re-emit an updated assistant message into the timeline. */
+  onMessageUpdate?: (msg: ChatMessageData) => void;
+}
+
+/** Truncate tool output to the cap, keeping the tail and marking the cut. */
+function capToolOutput(output: string): string {
+  if (output.length <= MAX_TOOL_OUTPUT_CHARS) return output;
+  return `…[truncated]\n${output.slice(-MAX_TOOL_OUTPUT_CHARS)}`;
+}
+
+/** Write a tool result into the map, enforcing both caps. */
+function storeToolResult(
+  map: Map<string, ToolResultRecord>,
+  callId: string,
+  record: ToolResultRecord,
+): void {
+  map.set(callId, { ...record, output: capToolOutput(record.output) });
+  while (map.size > MAX_TRACKED_TOOL_RESULTS) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+/** Write a result into the map, enforcing both caps. */
+export function putToolResult(host: ToolResultHost, callId: string, record: ToolResultRecord): void {
+  const map = host.toolResultsRef.current;
+  if (map) storeToolResult(map, callId, record);
+}
+
+/** Record a toolResult frame's output against its tool call id. */
+export function recordToolResult(raw: Record<string, unknown>, host: ToolResultHost): void {
+  const callId = typeof raw.toolCallId === 'string' ? raw.toolCallId : undefined;
+  if (!callId) return;
+  host.toolResultsRef.current?.set(callId, {
+    output: extractTextFromContent(raw.content),
+    details: (raw.details && typeof raw.details === 'object' ? raw.details : undefined) as ToolResultRecord['details'],
+  });
+}
+
+/** Re-emit the last tool-carrying assistant message with its results paired. */
+export function pairToolOutputs(msg: ChatMessageData, host: ToolResultHost): ChatMessageData {
+  if (!msg.toolCalls?.length) return msg;
+  const toolCalls = msg.toolCalls.map(tc => {
+    const res = host.toolResultsRef.current?.get(tc.id);
+    return res
+      ? {
+          ...tc,
+          output: res.output,
+          details: tc.details || res.details || undefined,
+          status: (res.isError ? 'error' : 'success') as ToolCallData['status'],
+        }
+      : tc;
+  });
+  return { ...msg, toolCalls };
+}
+
+/** Re-emit the last tool-carrying message when `callId` belongs to it. */
+export function refreshToolMessage(callId: string | undefined, host: ToolResultHost): void {
+  if (!callId) return;
+  const last = host.lastToolMessageRef.current;
+  if (!last?.toolCalls?.some(tc => tc.id === callId)) return;
+  host.onMessageUpdate?.(pairToolOutputs(last, host));
+}

package/src/shared/lib/chat/omp/transport.ts

@@ -14,20 +14,25 @@
 import type { OmpAgentEvent, StreamTransport } from '@/shared/types';
 import { readChamberSetting } from '@/shared/lib/settings/client';
 
-export interface AgentStreamHandlers {
+export interface StreamHandlers<TFrame> {
   /** Transport is attached; frames may arrive. */
   onOpen: () => void;
   /** One decoded event frame. */
-  onFrame: (data: OmpAgentEvent) => void;
+  onFrame: (data: TFrame) => void;
   /** Transport is gone for good (no further frames without a re-dial). */
   onClose: () => void;
 }
 
-export interface AgentStreamConnection {
+export interface StreamConnection {
   /** Permanently release the transport; no callbacks fire afterwards. */
   close: () => void;
 }
 
+/** Agent-stream handlers — the socket's frames feed the timeline's fold. */
+export type AgentStreamHandlers = StreamHandlers<OmpAgentEvent>;
+
+export type AgentStreamConnection = StreamConnection;
+
 export const DEFAULT_STREAM_TRANSPORT: StreamTransport = 'websocket';
 
 /** WebSocket endpoint for a session's agent event stream. */
@@ -41,6 +46,17 @@ export function agentEventsUrl(sessionId: string): string {
   return `/api/agent/${encodeURIComponent(sessionId)}/events`;
 }
 
+/** WebSocket endpoint for a session's BTW frame stream. */
+export function btwSocketUrl(sessionId: string): string {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.host}/api/btw/${encodeURIComponent(sessionId)}/ws`;
+}
+
+/** SSE endpoint for a session's BTW frame stream. */
+export function btwEventsUrl(sessionId: string): string {
+  return `/api/btw/${encodeURIComponent(sessionId)}/events`;
+}
+
 /**
  * Resolve the configured stream transport from the chamber settings snapshot.
  */

package/src/shared/lib/chat/text-file.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Deciding whether a file's contents are text, and what language to fence them
+ * under, from the file itself rather than from its metadata.
+ *
+ * Split out of `attachments.ts` because it is the one part of classification
+ * that reads BYTES: everything else there works from `name`/`type`/`size`,
+ * which is what a replayed attachment has.
+ */
+
+/**
+ * Extensions treated as inline-able text when the browser reports no useful
+ * MIME type. `File.type` is empty for many code files, so the extension is the
+ * only signal — a dropped `script.py` used to attach without its contents ever
+ * reaching the prompt.
+ */
+export const TEXT_FILE_EXTENSIONS: Record<string, true> = {
+  txt: true,
+  text: true,
+  md: true,
+  markdown: true,
+  mdx: true,
+  json: true,
+  jsonc: true,
+  yaml: true,
+  yml: true,
+  toml: true,
+  ini: true,
+  env: true,
+  csv: true,
+  tsv: true,
+  log: true,
+  xml: true,
+  html: true,
+  htm: true,
+  css: true,
+  scss: true,
+  less: true,
+  js: true,
+  mjs: true,
+  cjs: true,
+  jsx: true,
+  ts: true,
+  mts: true,
+  cts: true,
+  tsx: true,
+  py: true,
+  rb: true,
+  go: true,
+  rs: true,
+  java: true,
+  kt: true,
+  kts: true,
+  swift: true,
+  c: true,
+  h: true,
+  cc: true,
+  cpp: true,
+  cxx: true,
+  hpp: true,
+  hh: true,
+  cs: true,
+  php: true,
+  pl: true,
+  lua: true,
+  r: true,
+  sql: true,
+  sh: true,
+  bash: true,
+  zsh: true,
+  fish: true,
+  ps1: true,
+  bat: true,
+  cmd: true,
+  dockerfile: true,
+  makefile: true,
+  gitignore: true,
+  editorconfig: true,
+  diff: true,
+  patch: true,
+};
+
+/** MIME types the browser reports for text-ish files it does know. */
+export function isTextMimeType(type: string): boolean {
+  if (!type) return false;
+  if (type === 'text/plain' || type === 'text/markdown') return true;
+  return type.startsWith('text/')
+    || type === 'application/json'
+    || type === 'application/xml'
+    || type === 'application/x-yaml'
+    || type === 'application/yaml'
+    || type === 'application/javascript'
+    || type === 'application/x-sh'
+    || type === 'application/sql'
+    || type.endsWith('+json')
+    || type.endsWith('+xml');
+}
+
+/** Bytes sampled to decide whether an unclassified file is text. */
+const SNIFF_BYTES = 4096;
+
+/**
+ * Whether an unclassified file's own bytes read as text.
+ *
+ * Some hosts hand over a file whose name and MIME say nothing useful: a
+ * promised-file drag from another app arrives as `document` with an empty type,
+ * and an opaque download as `application/octet-stream`. Deciding from the name
+ * alone left those attached but never inlined — the chip rendered, the model saw
+ * nothing.
+ *
+ * Three signals, because control-character density alone misses a short binary:
+ * a NUL byte (no text encoding this app handles contains one), an invalid UTF-8
+ * sequence (a lone continuation or lead byte), and the control-character ratio
+ * a browser applies to a Blob. `TextDecoder` in fatal mode is the cheapest
+ * correct UTF-8 validator available.
+ */
+export async function looksLikeTextFile(
+  file: Pick<File, 'slice'>,
+  /**
+   * Bytes already read while the drop's permission was live. A dropped file
+   * cannot be `slice()`d after that window closes, so the sniff is served from
+   * the primed read where one exists. See `file-reads.ts`.
+   */
+  primed?: Uint8Array,
+): Promise<boolean> {
+  try {
+    const bytes = primed ?? new Uint8Array(await file.slice(0, SNIFF_BYTES).arrayBuffer());
+    if (bytes.length === 0) return false;
+    if (bytes.includes(0)) return false;
+    try {
+      new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch {
+      return false;
+    }
+    let control = 0;
+    for (const byte of bytes) {
+      if (byte < 9 || (byte > 13 && byte < 32)) control += 1;
+    }
+    return control / bytes.length <= 0.3;
+  } catch {
+    return false;
+  }
+}
+