@visual-z/xeno 0.1.0

package/src/apps/approve.ts

@@ -0,0 +1,49 @@
+/**
+ * Copy for the bash approval prompt.
+ *
+ * The full command is the point: approval is the last look at what will
+ * run. Truncating it would hide the thing the person is being asked to
+ * see. The word this must not use is any that would make the prompt
+ * sound like a boundary.
+ */
+
+import type { PermissionRequest } from "../core/permissions.ts";
+import type { ApprovalChoice } from "../runtime/tools.ts";
+import type { SelectItem } from "../tui/select.ts";
+
+export function approvalHeading(request: PermissionRequest): string {
+  if (request.command !== undefined) {
+    return [
+      `${request.tool} wants to run:`,
+      "",
+      request.command,
+      "",
+      "Approval is the last look at this command, not a boundary.",
+    ].join("\n");
+  }
+  return `${request.tool} wants to run. Approval is the last look, not a boundary.`;
+}
+
+export function approvalItems(request: PermissionRequest): SelectItem[] {
+  const items: SelectItem[] = [{ value: "once", label: "this once" }];
+  if (request.command !== undefined) {
+    items.push({ value: "command", label: "this command this session" });
+  }
+  items.push(
+    { value: "tool", label: `${request.tool} this session` },
+    { value: "deny", label: "deny" },
+  );
+  return items;
+}
+
+export function choiceFromValue(value: string): ApprovalChoice {
+  switch (value) {
+    case "once":
+    case "command":
+    case "tool":
+    case "deny":
+      return value;
+    default:
+      return "deny";
+  }
+}

package/src/apps/cli.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+/**
+ * A terminal session.
+ *
+ * Interactive output uses Pi's main-screen renderer and terminal lifecycle
+ * (D19). Durable messages are a pure log projection; deltas remain transient.
+ * Print and piped modes do not construct a terminal UI.
+ *
+ * Usage accounting is on by default rather than behind a flag, because the
+ * point of running this at all is to find out whether the prefix stays stable
+ * in practice. A cache that quietly stopped working raises no error -- it just
+ * costs more -- so the numbers have to be in front of you.
+ */
+
+import {
+  parseArgs, startup, readPipedStdin, mergePrintPrompt, silenceTtyEarly,
+} from "./startup.ts";
+import { runPrompt, runRepl } from "./shell.ts";
+
+const args = parseArgs(process.argv.slice(2));
+// Before startup reads auth, scans context files and prints the header:
+// in cooked mode the tty would echo anything typed during that window
+// straight into the banner.
+const restoreTty = silenceTtyEarly({ interactive: !args.print && !args.prompt });
+if (args.print) {
+  // With a prompt already given, stdin is optional context: wait briefly for it.
+  args.prompt = mergePrintPrompt(args.prompt,
+    await readPipedStdin(process.stdin, args.prompt.length > 0 ? { firstByteMs: 3_000 } : {}));
+}
+const app = await startup(args);
+if (args.prompt) {
+  restoreTty();
+  await runPrompt(app, args.prompt);
+} else {
+  try { await runRepl(app); }
+  finally { restoreTty(); }
+}

package/src/apps/commands.ts

@@ -0,0 +1,226 @@
+/**
+ * Slash-command dispatch as a pure function.
+ *
+ * Matching the first token, not a string prefix, is the whole point: a
+ * prompt that starts with `/backdrop` used to be swallowed as `/back`.
+ * Unknown lone `/word`s are `unknown`; a slash-like word followed by
+ * more text is a prompt, so ordinary sentences stay ordinary.
+ *
+ * Prompt templates and skills register names into the same space. Built-in
+ * commands win, then templates, then skills; a loser is named, never silent.
+ */
+
+import type { RewindMode } from "../runtime/loop.ts";
+import { expandTemplate, type PromptTemplate } from "../core/prompts.ts";
+import { skillInvocationMessage, type Skill } from "../core/skills.ts";
+
+export type Command =
+  | { kind: "prompt"; text: string }
+  | { kind: "quit" }
+  | { kind: "usage" }
+  | { kind: "state" }
+  | { kind: "model"; pattern?: string }
+  | { kind: "login"; provider?: string }
+  | { kind: "logout"; provider?: string }
+  | { kind: "back"; arg?: string; mode: RewindMode; confirm: boolean }
+  | { kind: "tree" }
+  | { kind: "new" }
+  | { kind: "resume"; id?: string }
+  | { kind: "name"; name: string }
+  | { kind: "session" }
+  | { kind: "help" }
+  | { kind: "trust"; target: "here" | "parent" | "never" }
+  | { kind: "models-refresh" }
+  | { kind: "settings"; field?: string; value?: string }
+  | { kind: "hotkeys" }
+  | { kind: "thinking"; level?: string }
+  | { kind: "export"; file?: string }
+  | { kind: "copy" }
+  | { kind: "fork"; arg?: string }
+  | { kind: "clone" }
+  | { kind: "unknown"; input: string };
+
+/** One catalog owns discoverability, parsing and busy-turn policy. */
+export const COMMANDS = [
+  { name: "model", description: "Choose a model", argumentHint: "[id]", busy: "idle" },
+  { name: "thinking", description: "Set reasoning effort", argumentHint: "[level]", busy: "idle" },
+  { name: "settings", description: "Change theme, thinking and status bar", argumentHint: "[key value]", busy: "idle" },
+  { name: "login", description: "Sign in or store an API key", argumentHint: "[provider]", busy: "idle" },
+  { name: "logout", description: "Remove a stored credential", argumentHint: "[provider]", busy: "idle" },
+  { name: "new", description: "Start a new session", busy: "idle" },
+  { name: "resume", description: "Search saved sessions", argumentHint: "[id]", busy: "idle" },
+  { name: "tree", description: "Navigate session context", busy: "run" },
+  { name: "fork", description: "Fork at a user message", argumentHint: "[n]", busy: "idle" },
+  { name: "clone", description: "Copy this branch into a new session", busy: "idle" },
+  { name: "back", description: "Restore context or files explicitly", argumentHint: "[n [files|context|both] [confirm]]", busy: "idle" },
+  { name: "name", description: "Name this session", argumentHint: "<name>", busy: "idle" },
+  { name: "session", description: "Show session details", busy: "run" },
+  { name: "usage", description: "Show token usage and costs", busy: "run" },
+  { name: "state", description: "Show log and handoff state", busy: "run" },
+  { name: "export", description: "Export HTML or JSONL", argumentHint: "[file]", busy: "idle" },
+  { name: "copy", description: "Copy the last assistant reply", busy: "run" },
+  { name: "models", description: "Refresh the model catalog", argumentHint: "refresh", busy: "idle" },
+  { name: "trust", description: "Set workspace configuration trust", argumentHint: "[here|parent|never]", busy: "idle" },
+  { name: "hotkeys", description: "Show active keybindings", busy: "run" },
+  { name: "help", description: "Show commands and input help", busy: "run" },
+  { name: "quit", description: "Exit xeno", busy: "run" },
+  { name: "exit", description: "Exit xeno", busy: "run" },
+] as const;
+
+export const BUILTIN_COMMAND_NAMES = COMMANDS.map((command) => command.name);
+
+export function commandDefinition(input: string): (typeof COMMANDS)[number] | undefined {
+  const name = input.trim().split(/\s/, 1)[0]?.slice(1).toLowerCase();
+  return COMMANDS.find((command) => command.name === name);
+}
+
+const BUILTIN_SET = new Set<string>(BUILTIN_COMMAND_NAMES);
+
+export interface SlashCatalog {
+  readonly prompts: ReadonlyMap<string, PromptTemplate>;
+  readonly skills: ReadonlyMap<string, Skill>;
+}
+
+export function resolveSlashCatalog(
+  prompts: readonly PromptTemplate[],
+  skills: readonly Skill[],
+): { catalog: SlashCatalog; diagnostics: readonly string[] } {
+  const diagnostics: string[] = [];
+  const promptMap = new Map<string, PromptTemplate>();
+  const skillMap = new Map<string, Skill>();
+
+  for (const prompt of prompts) {
+    if (BUILTIN_SET.has(prompt.name)) {
+      diagnostics.push(
+        `prompt template "${prompt.name}" from ${prompt.filePath} is shadowed by a built-in command`,
+      );
+      continue;
+    }
+    promptMap.set(prompt.name, prompt);
+  }
+
+  for (const skill of skills) {
+    if (BUILTIN_SET.has(skill.name)) {
+      diagnostics.push(
+        `skill "${skill.name}" from ${skill.filePath} is shadowed by a built-in command`,
+      );
+      continue;
+    }
+    const prompt = promptMap.get(skill.name);
+    if (prompt !== undefined) {
+      diagnostics.push(
+        `skill "${skill.name}" from ${skill.filePath} is shadowed by prompt template ${prompt.filePath}`,
+      );
+      continue;
+    }
+    skillMap.set(skill.name, skill);
+  }
+
+  return { catalog: { prompts: promptMap, skills: skillMap }, diagnostics };
+}
+
+export function parseCommand(input: string, catalog?: SlashCatalog): Command {
+  const text = input.trim();
+  if (!text.startsWith("/")) return { kind: "prompt", text };
+
+  const [head, ...rest] = text.split(/\s+/);
+  const token = (head ?? "").toLowerCase();
+  const arg = rest.join(" ");
+
+  if (!commandDefinition(text)) return resolveRegistered(token, arg, text, rest.length, catalog);
+
+  switch (token) {
+    case "/quit":
+    case "/exit":
+      return { kind: "quit" };
+    case "/usage":
+      return { kind: "usage" };
+    case "/state":
+      return { kind: "state" };
+    case "/model":
+      return arg.length > 0 ? { kind: "model", pattern: arg } : { kind: "model" };
+    case "/login":
+      return rest[0] === undefined ? { kind: "login" } : { kind: "login", provider: rest[0] };
+    case "/logout":
+      return rest[0] === undefined ? { kind: "logout" } : { kind: "logout", provider: rest[0] };
+    case "/back": {
+      const [n, ...flags] = rest;
+      const words = new Set(flags);
+      const mode: RewindMode =
+        words.has("files") ? "files" : words.has("context") ? "context" : "both";
+      const confirm = words.has("confirm");
+      return n === undefined
+        ? { kind: "back", mode, confirm }
+        : { kind: "back", arg: n, mode, confirm };
+    }
+    case "/tree":
+      return { kind: "tree" };
+    case "/new":
+      return { kind: "new" };
+    case "/resume":
+      return arg.length > 0 ? { kind: "resume", id: arg } : { kind: "resume" };
+    case "/name":
+      return { kind: "name", name: arg };
+    case "/session":
+      return { kind: "session" };
+    case "/help":
+      return { kind: "help" };
+    case "/models":
+      return arg === "refresh" ? { kind: "models-refresh" } : { kind: "unknown", input: text };
+    case "/settings": {
+      if (rest.length === 0) return { kind: "settings" };
+      const field = rest[0];
+      if (field === undefined) return { kind: "settings" };
+      if (rest.length === 1) return { kind: "settings", field };
+      return { kind: "settings", field, value: rest.slice(1).join(" ") };
+    }
+    case "/hotkeys":
+      return { kind: "hotkeys" };
+    case "/thinking":
+      return arg.length > 0 ? { kind: "thinking", level: arg } : { kind: "thinking" };
+    case "/export":
+      return arg.length > 0 ? { kind: "export", file: arg } : { kind: "export" };
+    case "/copy":
+      return { kind: "copy" };
+    case "/fork":
+      return arg.length > 0 ? { kind: "fork", arg } : { kind: "fork" };
+    case "/clone":
+      return { kind: "clone" };
+    case "/trust": {
+      const word = (rest[0] ?? "here").toLowerCase();
+      if (rest.length === 0 || word === "here" || word === "yes") {
+        return { kind: "trust", target: "here" };
+      }
+      if (word === "parent") return { kind: "trust", target: "parent" };
+      if (word === "never" || word === "no") return { kind: "trust", target: "never" };
+      return { kind: "unknown", input: text };
+    }
+    default:
+      return resolveRegistered(token, arg, text, rest.length, catalog);
+  }
+}
+
+function resolveRegistered(
+  token: string,
+  arg: string,
+  text: string,
+  restCount: number,
+  catalog: SlashCatalog | undefined,
+): Command {
+  if (catalog !== undefined) {
+    if (token.startsWith("/skill:")) {
+      const name = token.slice("/skill:".length);
+      const skill = catalog.skills.get(name);
+      if (skill !== undefined) {
+        return { kind: "prompt", text: skillInvocationMessage(skill, arg) };
+      }
+    }
+    const prompt = catalog.prompts.get(token.slice(1));
+    if (prompt !== undefined) {
+      return { kind: "prompt", text: expandTemplate(prompt.content, arg).text };
+    }
+  }
+  // A lone unknown /word is a failed command. More text means the user
+  // typed a sentence that happens to start with a slash-like token.
+  return restCount === 0 ? { kind: "unknown", input: text } : { kind: "prompt", text };
+}

package/src/apps/completions.ts

@@ -0,0 +1,28 @@
+import { COMMANDS } from "./commands.ts";
+import type { App } from "./startup.ts";
+import { WorkspaceAutocomplete } from "../tui/autocomplete.ts";
+import { SUBSCRIPTION_OPTIONS } from "../runtime/oauth.ts";
+
+export function interactiveAutocomplete(app: App, paths: (refresh?: boolean) => Promise<readonly string[]>): WorkspaceAutocomplete {
+  const providers = [...new Set([...app.catalog.map((m) => m.provider), ...SUBSCRIPTION_OPTIONS.map((p) => p.id)])];
+  const values: Record<string, () => string[]> = {
+    model: () => app.catalog.map((m) => m.id),
+    thinking: () => ["low", "medium", "high", "xhigh", "max"].filter((level) =>
+      app.providerConfig.spec.thinkingLevelMap?.[level as "low"] !== null),
+    login: () => providers, logout: () => providers,
+    settings: () => ["theme", "thinking", "statusBar"],
+    models: () => ["refresh"], trust: () => ["here", "parent", "never"],
+  };
+  const commands = COMMANDS.map((definition) => ({
+    ...definition,
+    getArgumentCompletions(prefix: string) {
+      return (values[definition.name]?.() ?? []).filter((v) => v.toLowerCase().includes(prefix.toLowerCase()))
+        .map((v) => ({ value: v, label: v }));
+    },
+  }));
+  const registered = [
+    ...[...(app.slash?.prompts.values() ?? [])].map((p) => ({ name: p.name, description: p.description })),
+    ...[...(app.slash?.skills.values() ?? [])].map((s) => ({ name: `skill:${s.name}`, description: s.description })),
+  ];
+  return new WorkspaceAutocomplete([...commands, ...registered], app.workspace, paths);
+}

package/src/apps/input.ts

@@ -0,0 +1,297 @@
+/**
+ * Expand @file and !cmd in a user prompt before the line is sent.
+ *
+ * These are the user's own keystrokes, not the model's: a shared path with
+ * the bash tool would either grant the model the user's authority or make
+ * the user ask permission to run their own shell.
+ *
+ * Shell commands trigger only at line start. Explicit @ references may
+ * occur inline; emails and code literals remain ordinary prompt text.
+ */
+
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fuzzyFilter } from "../tui/fuzzy.ts";
+import type { FileIndex } from "../store/file-index.ts";
+import { fileReferences } from "../core/file-references.ts";
+
+/**
+ * Per-file cap for @ expansion. Assumed, not measured: 256KB of one file
+ * already crowds a turn; a silent half-file would let the model invent
+ * the rest. Hitting it truncates and names the file.
+ */
+export const MAX_EXPAND_FILE_BYTES = 256 * 1024;
+
+/**
+ * Bound on captured command output. Assumed, not measured: a command that
+ * dumps a build log would otherwise be an unbounded allocation. Truncated
+ * output still carries the exit code -- the exit line is appended after
+ * the body is capped, so a cut cannot hide whether the command passed.
+ */
+export const MAX_COMMAND_OUTPUT_BYTES = 64 * 1024;
+
+/**
+ * Timeout for !cmd. Assumed, not measured: long enough for a test suite,
+ * short enough that a hung command cannot stall the editor. On expiry the
+ * process is killed and the timeout is reported as a nonzero exit.
+ */
+export const COMMAND_TIMEOUT_MS = 120_000;
+
+export interface ExpandContext {
+  readonly workspace: string;
+  readonly index: FileIndex;
+  /** Terminal writer for !!cmd (and user-visible notices). */
+  readonly say: (text: string) => void;
+  readonly timeoutMs?: number;
+  readonly maxFileBytes?: number;
+  readonly maxCommandBytes?: number;
+}
+
+export interface ExpandResult {
+  /** Text to send to the model. Empty when nothing should be sent. */
+  readonly message: string;
+  /** False when the input produced no model-facing text (a lone !!cmd). */
+  readonly send: boolean;
+}
+
+export function matchFiles(index: FileIndex, query: string): string[] {
+  return fuzzyFilter(index.paths, query);
+}
+
+export async function expandInput(text: string, ctx: ExpandContext): Promise<ExpandResult> {
+  const out: string[] = [];
+  const refs = fileReferences(text);
+  let offset = 0;
+  for (const line of text.split(/\r?\n/)) {
+    const start = offset;
+    offset += line.length + (text.slice(offset + line.length).startsWith("\r\n") ? 2 : 1);
+    if (line.startsWith("!!")) {
+      ctx.say(await runUserCommand(line.slice(2), ctx));
+      continue;
+    }
+    if (line.startsWith("!")) {
+      const rendered = await runUserCommand(line.slice(1), ctx);
+      ctx.say(rendered);
+      out.push(rendered);
+      continue;
+    }
+    if (line.trim() === "@") {
+      out.push(skip(ctx, "@", "empty file reference"));
+      continue;
+    }
+    const here = refs.filter((ref) => ref.start >= start && ref.end <= start + line.length);
+    if (here.length === 0) { out.push(line); continue; }
+    let end = 0;
+    for (const ref of here) {
+      const prefix = line.slice(end, ref.start - start);
+      if (prefix.trim()) out.push(prefix.trimEnd());
+      out.push(await expandReference(ref.path, ctx));
+      end = ref.end - start;
+    }
+    if (line.slice(end).trim()) out.push(line.slice(end).trimStart());
+  }
+  const message = out.join("\n");
+  return { message, send: message.trim().length > 0 };
+}
+
+async function expandReference(ref: string, ctx: ExpandContext): Promise<string> {
+  const abs = confine(ctx.workspace, ref);
+  if (abs === null) return skip(ctx, ref, "outside the workspace");
+
+  const got = await tryRead(abs);
+  if (got.status === "ok") return renderFile(posix(ref), got, ctx);
+  if (got.reason !== "not found") return skip(ctx, posix(ref), got.reason);
+
+  // Typed path missed; a unique fuzzy hit from the index is the query case.
+  const hits = matchFiles(ctx.index, ref);
+  if (hits.length === 1 && hits[0] !== posix(ref)) {
+    const path = hits[0]!;
+    const hitAbs = confine(ctx.workspace, path);
+    if (hitAbs === null) return skip(ctx, path, "outside the workspace");
+    const hit = await tryRead(hitAbs);
+    if (hit.status === "ok") return renderFile(path, hit, ctx);
+    return skip(ctx, path, hit.reason);
+  }
+  if (hits.length > 1) return skip(ctx, ref, `ambiguous (${hits.length} matches)`);
+  return skip(ctx, posix(ref), got.reason);
+}
+
+function posix(rel: string): string {
+  return rel.split(sep).join("/");
+}
+
+function confine(workspace: string, rel: string): string | null {
+  if (rel.length === 0) return null;
+  const abs = resolve(workspace, rel);
+  const inside = relative(workspace, abs);
+  if (inside === "" || inside.startsWith(`..${sep}`) || inside === ".." || isAbsolute(inside)) {
+    return null;
+  }
+  return abs;
+}
+
+type ReadResult =
+  | { status: "ok"; text: string; bytes: number }
+  | { status: "skip"; reason: string };
+
+async function tryRead(abs: string): Promise<ReadResult> {
+  let buf: Buffer;
+  try {
+    buf = await readFile(abs);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return { status: "skip", reason: "not found" };
+    if (code === "EACCES") return { status: "skip", reason: "permission denied" };
+    if (code === "EISDIR") return { status: "skip", reason: "is a directory" };
+    const message = err instanceof Error ? err.message : String(err);
+    return { status: "skip", reason: message };
+  }
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+    return { status: "ok", text, bytes: buf.byteLength };
+  } catch {
+    return { status: "skip", reason: "not valid UTF-8" };
+  }
+}
+
+function renderFile(
+  path: string,
+  got: Extract<ReadResult, { status: "ok" }>,
+  ctx: ExpandContext,
+): string {
+  const cap = ctx.maxFileBytes ?? MAX_EXPAND_FILE_BYTES;
+  let content = got.text;
+  let truncated = false;
+  let omitted = 0;
+  if (got.bytes > cap) {
+    content = truncateUtf8(got.text, cap);
+    truncated = true;
+    omitted = Math.max(0, got.bytes - Buffer.byteLength(content, "utf8"));
+    ctx.say(`[truncated ${path}: ${omitted} bytes omitted]`);
+  }
+  const inner = truncated
+    ? `${content}\n[truncated: ${path} exceeded a size limit; ${omitted} bytes omitted]`
+    : content;
+  return `<file path="${escapeAttr(path)}">\n${inner}\n</file>`;
+}
+
+function skip(ctx: ExpandContext, path: string, reason: string): string {
+  const notice = `[skipped ${path}: ${reason}]`;
+  ctx.say(notice);
+  return notice;
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  const buf = Buffer.from(text, "utf8");
+  if (buf.byteLength <= maxBytes) return text;
+  let end = maxBytes;
+  // Do not split a multibyte sequence: a dangling continuation byte is
+  // not valid UTF-8, and the model would see a replacement character.
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end--;
+  return buf.subarray(0, end).toString("utf8");
+}
+
+async function runUserCommand(raw: string, ctx: ExpandContext): Promise<string> {
+  const cmd = raw.trim();
+  if (cmd.length === 0) return skip(ctx, "!", "empty command");
+
+  const timeoutMs = ctx.timeoutMs ?? COMMAND_TIMEOUT_MS;
+  const maxBytes = ctx.maxCommandBytes ?? MAX_COMMAND_OUTPUT_BYTES;
+
+  const proc = Bun.spawn(["bash", "-lc", cmd], {
+    cwd: ctx.workspace,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+
+  let timedOut = false;
+  let escalate: ReturnType<typeof setTimeout> | null = null;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill();
+    escalate = setTimeout(() => proc.kill("SIGKILL"), 1000);
+  }, timeoutMs);
+
+  let stdout = "";
+  let stderr = "";
+  let exit = 1;
+  try {
+    const [out, err] = await Promise.all([
+      readCapped(proc.stdout, maxBytes),
+      readCapped(proc.stderr, maxBytes),
+    ]);
+    stdout = out.text;
+    stderr = err.text;
+    if (out.truncated) stdout = `${stdout}\n[stdout truncated]`;
+    if (err.truncated) stderr = `${stderr}\n[stderr truncated]`;
+    const rawExit = await proc.exited;
+    exit = rawExit ?? 1;
+    // A kill that somehow reports success would put the model back to
+    // guessing. GNU timeout uses 124; never report 0 after a timeout.
+    if (timedOut && exit === 0) exit = 124;
+  } finally {
+    clearTimeout(timer);
+    if (escalate !== null) clearTimeout(escalate);
+  }
+
+  const parts: string[] = [`$ ${cmd}`];
+  if (stdout.length > 0) parts.push(stripTrailingNewline(stdout));
+  if (stderr.length > 0) parts.push(stripTrailingNewline(stderr));
+  if (timedOut) parts.push(`[timed out after ${timeoutMs}ms]`);
+  // Exit last so a capped body cannot cut the one number D11 needs.
+  parts.push(`exit ${exit}`);
+  return parts.join("\n");
+}
+
+function stripTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s.slice(0, -1) : s;
+}
+
+async function readCapped(
+  stream: ReadableStream<Uint8Array> | number | undefined | null,
+  max: number,
+): Promise<{ text: string; truncated: boolean }> {
+  if (stream === null || stream === undefined || typeof stream === "number") {
+    return { text: "", truncated: false };
+  }
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let n = 0;
+  let truncated = false;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value === undefined) continue;
+    if (n >= max) {
+      truncated = true;
+      continue;
+    }
+    const take = Math.min(value.length, max - n);
+    chunks.push(take === value.length ? value : value.subarray(0, take));
+    n += take;
+    if (take < value.length) truncated = true;
+  }
+  const buf = new Uint8Array(n);
+  let off = 0;
+  for (const c of chunks) {
+    buf.set(c, off);
+    off += c.length;
+  }
+  return { text: new TextDecoder().decode(buf), truncated };
+}
+
+/** True when the whole submission is `@` or `@query`, so the TUI can pick. */
+export function bareAtQuery(text: string): string | null {
+  const m = /^@(\S*)$/.exec(text);
+  return m === null ? null : (m[1] ?? "");
+}
+
+export function isExactIndexedPath(index: FileIndex, query: string): boolean {
+  return query.length > 0 && index.paths.includes(query);
+}