@visual-z/xeno 0.1.0

package/src/store/command.ts

@@ -0,0 +1,75 @@
+/** O.1: own the process group, preserve partial observations, and drain before returning. */
+import { captureCommandObservation } from "./observations.ts";
+
+/** Operational grace, not a measured optimum: do not let ignored SIGTERM defeat cancellation. */
+const TERMINATION_GRACE_MS = 200;
+
+/**
+ * Variables that make a command behave as if no one is at the keyboard.
+ *
+ * There never is: a pager waits on a tty that does not exist, colour codes
+ * spend budget on escape bytes, and a git credential prompt or an apt
+ * question hangs the command until the timeout. Codex sets the same core set
+ * for its exec sessions (`unified_exec/process_manager.rs`). LANG is filled in
+ * only when absent -- a user's own locale is not ours to override.
+ */
+export function commandEnvironment(base: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) if (value !== undefined) env[key] = value;
+  Object.assign(env, {
+    TERM: "dumb", PAGER: "cat", GIT_PAGER: "cat", NO_COLOR: "1",
+    GIT_TERMINAL_PROMPT: "0", DEBIAN_FRONTEND: "noninteractive",
+  });
+  if (env["LANG"] === undefined || env["LANG"] === "") env["LANG"] = "C.UTF-8";
+  return env;
+}
+
+export async function observeCommand(input: {
+  command: string;
+  cwd: string;
+  outputStore: string;
+  maxOutputBytes: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}) {
+  const started = performance.now();
+  const proc = Bun.spawn(["bash", "-o", "pipefail", "-lc", input.command], {
+    cwd: input.cwd, stdout: "pipe", stderr: "pipe", detached: true, env: commandEnvironment(process.env),
+  });
+  let stopped: "cancelled" | "timeout" | undefined;
+  let escalation: ReturnType<typeof setTimeout> | undefined;
+  const kill = (signal: "SIGTERM" | "SIGKILL") => {
+    try {
+      // POSIX detached children lead their own group; never signal the caller's group.
+      if (process.platform === "win32") proc.kill(signal);
+      else process.kill(-proc.pid, signal);
+    } catch (error) {
+      if ((error as { code?: string }).code !== "ESRCH") throw error;
+    }
+  };
+  const stop = (reason: "cancelled" | "timeout") => {
+    if (stopped !== undefined) return;
+    stopped = reason;
+    kill("SIGTERM");
+    escalation = setTimeout(() => kill("SIGKILL"), TERMINATION_GRACE_MS);
+  };
+  const abort = () => stop("cancelled");
+  input.signal?.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(() => stop("timeout"), input.timeoutMs);
+  if (input.signal?.aborted) abort();
+  try {
+    const captured = await captureCommandObservation(input.outputStore, proc.stdout, proc.stderr,
+      proc.exited, input.maxOutputBytes);
+    return { ...captured, wallMs: performance.now() - started, ...(stopped ? { stopped } : {}) };
+  } catch (error) {
+    kill("SIGKILL");
+    await proc.exited;
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    clearTimeout(escalation);
+    input.signal?.removeEventListener("abort", abort);
+    // A descendant can close stdio yet ignore SIGTERM; completing capture is not proof it stopped.
+    if (stopped !== undefined) kill("SIGKILL");
+  }
+}

package/src/store/config.ts

@@ -0,0 +1,69 @@
+/**
+ * The user's configuration, which lives with the user and not with the project.
+ *
+ * `~/.xeno/` rather than the workspace's `.xeno/`. The split is not cosmetic:
+ * the log and the blob store belong to one piece of work and should travel
+ * with it, while a credential belongs to a person. A key written into the
+ * workspace would be committed, would be seen by the snapshot scan that backs
+ * `/back`, and would ship with the project.
+ *
+ * This layer only reads and writes files. It knows nothing about providers,
+ * priority, or what a key means -- that is `runtime/auth.ts`, and keeping the
+ * two apart is what lets the priority rules be tested without a filesystem.
+ */
+
+import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function configDir(): string {
+  // XENO_CONFIG_DIR exists for tests and for anyone running two configurations
+  // side by side. Read here rather than threaded through every caller, because
+  // this is the one place that turns "the user" into a path.
+  return process.env["XENO_CONFIG_DIR"] ?? join(homedir(), ".xeno");
+}
+
+export function authPath(): string {
+  return join(configDir(), "auth.json");
+}
+
+export function settingsPath(): string {
+  return join(configDir(), "settings.json");
+}
+
+/**
+ * Reads a JSON config, treating "absent" and "unreadable" as empty.
+ *
+ * A missing config file is the normal first-run state, not an error. A
+ * corrupt one is reported to the caller as absent plus a reason, because
+ * silently starting with default settings after someone hand-edited a file
+ * is how a typo becomes an hour of confusion.
+ */
+export async function readJsonFile<T>(
+  path: string,
+): Promise<{ value: T | null; error: string | null }> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return { value: null, error: null };
+  }
+  try {
+    return { value: JSON.parse(text) as T, error: null };
+  } catch (err) {
+    return { value: null, error: `${path} is not valid JSON: ${(err as Error).message}` };
+  }
+}
+
+/**
+ * Writes a config file, 0600 for the one that holds secrets.
+ *
+ * `chmod` after the write rather than a `mode` on the open, because an
+ * existing file keeps its old permissions when reopened -- so a file created
+ * before this rule existed would stay world-readable and nothing would say so.
+ */
+export async function writeJsonFile(path: string, value: unknown, secret: boolean): Promise<void> {
+  await mkdir(configDir(), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  if (secret) await chmod(path, 0o600);
+}

package/src/store/context-files.ts

@@ -0,0 +1,356 @@
+/**
+ * Project context files (AGENTS.md and friends) and the system prompt they
+ * join.
+ *
+ * Two halves, kept apart because they have different reasons to change:
+ *
+ *   DISCOVERY is I/O. It walks directories, reads bytes, skips what it
+ *   cannot, and truncates what does not fit. It runs once at process
+ *   start.
+ *
+ *   ASSEMBLY is a pure function of those bytes. Same files in, same
+ *   string out. That is what makes the ordering rules testable without
+ *   a filesystem, and what makes `frozen.system` a value rather than a
+ *   live view of disk.
+ *
+ * Re-reading these files at a node boundary would change `system` and
+ * invalidate the prefix cache for the whole conversation (D6). They are
+ * frozen at startup; a reload is a cut, and is a later card.
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { assertNever } from "../core/exhaustive.ts";
+
+/**
+ * Per-file cap. Assumed, not measured: a rule file larger than this is a
+ * document someone should split, not a prompt prefix. Hitting it truncates
+ * that file and names it in the prompt; the omitted rules are simply not
+ * followed, which is the failure mode the notice exists to make visible.
+ */
+export const MAX_FILE_BYTES = 64 * 1024;
+
+/**
+ * Cap on the sum of loaded context files. Assumed, not measured: 256KB of
+ * instructions already crowds out the task. Hitting it truncates the file
+ * that overflowed (and names it); later files may be omitted, so a huge
+ * farther file can starve a nearer one.
+ */
+export const MAX_TOTAL_BYTES = 256 * 1024;
+
+/**
+ * Directories walked from cwd toward the workspace root, including cwd.
+ * Assumed, not measured: a 32-level nest is not a project layout, it is a
+ * pathologically generated tree. Hitting it drops the farther (workspace)
+ * files -- the walk starts at cwd so nearer rules are kept.
+ */
+export const MAX_WALK_DEPTH = 32;
+
+const AGENTS_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "CLAUDE.md"] as const;
+
+export type ContextRole = "system" | "agents" | "append";
+
+export interface LoadedFile {
+  path: string;
+  content: string;
+  /** Original size in UTF-8 bytes, before any truncation. */
+  bytes: number;
+  truncated: boolean;
+  role: ContextRole;
+}
+
+export type ContextNotice =
+  | { kind: "loaded"; path: string; truncated: boolean }
+  | { kind: "skipped"; path: string; reason: string };
+
+export interface LoadedContext {
+  /** Replacement for the builtin system prompt, if any. */
+  system: LoadedFile | null;
+  /** AGENTS.md chain, far (global) to near (cwd). */
+  agents: LoadedFile[];
+  /** APPEND_SYSTEM.md then `--append-system-prompt`, in append order. */
+  appends: LoadedFile[];
+  notices: ContextNotice[];
+}
+
+export interface LoadOptions {
+  workspace: string;
+  cwd: string;
+  /** `~/.xeno` or `XENO_CONFIG_DIR`. Injected so tests never touch the real home. */
+  configDir: string;
+  noContextFiles: boolean;
+  appendSystemPrompt: readonly string[];
+  /** Raw `--system-prompt` value. Omitted when the flag was not passed. */
+  systemPrompt?: string;
+}
+
+class Budget {
+  remaining = MAX_TOTAL_BYTES;
+
+  fit(text: string, bytes: number): { content: string; truncated: boolean } {
+    const cap = Math.min(MAX_FILE_BYTES, this.remaining);
+    if (bytes <= cap) {
+      this.remaining -= bytes;
+      return { content: text, truncated: false };
+    }
+    const content = truncateUtf8(text, cap);
+    this.remaining = Math.max(0, this.remaining - Buffer.byteLength(content, "utf8"));
+    return { content, truncated: true };
+  }
+}
+
+/**
+ * Walk from cwd up to the workspace root, nearest first, then reverse so
+ * assembly sees farther files first. cwd outside the workspace contributes
+ * only the workspace itself -- the session is rooted there, and climbing
+ * into unrelated trees would load someone else's rules.
+ */
+function projectDirectories(workspace: string, cwd: string): string[] {
+  const root = resolve(workspace);
+  const start = resolve(cwd);
+  if (!isInside(start, root)) return [root];
+
+  const fromCwd: string[] = [];
+  let dir = start;
+  for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+    fromCwd.push(dir);
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return fromCwd.reverse();
+}
+
+function isInside(child: string, parent: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+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 in
+  // the middle of a rule.
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end--;
+  return buf.subarray(0, end).toString("utf8");
+}
+
+type ReadResult =
+  | { status: "missing" }
+  | { status: "ok"; text: string; bytes: number }
+  | { status: "skip"; reason: string };
+
+async function tryRead(path: string): Promise<ReadResult> {
+  let buf: Buffer;
+  try {
+    buf = await readFile(path);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return { status: "missing" };
+    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 absorbText(
+  path: string,
+  text: string,
+  role: ContextRole,
+  bytes: number,
+  budget: Budget,
+  notices: ContextNotice[],
+): LoadedFile {
+  const fitted = budget.fit(text, bytes);
+  const file: LoadedFile = {
+    path,
+    content: fitted.content,
+    bytes,
+    truncated: fitted.truncated,
+    role,
+  };
+  notices.push({ kind: "loaded", path, truncated: file.truncated });
+  return file;
+}
+
+async function absorbFile(
+  path: string,
+  role: ContextRole,
+  budget: Budget,
+  notices: ContextNotice[],
+): Promise<LoadedFile | null> {
+  const got = await tryRead(path);
+  if (got.status === "missing") return null;
+  if (got.status === "skip") {
+    notices.push({ kind: "skipped", path, reason: got.reason });
+    return null;
+  }
+  return absorbText(path, got.text, role, got.bytes, budget, notices);
+}
+
+/**
+ * `--system-prompt` is text, or a file if the argument names one that
+ * exists. An existing path that cannot be read is skipped (and reported)
+ * rather than silently becoming the path string as the prompt.
+ */
+async function absorbSystemArg(
+  value: string,
+  cwd: string,
+  budget: Budget,
+  notices: ContextNotice[],
+): Promise<LoadedFile | null> {
+  const candidate = resolve(cwd, value);
+  let file = false;
+  try {
+    file = (await stat(candidate)).isFile();
+  } catch {
+    file = false;
+  }
+  if (file) return absorbFile(candidate, "system", budget, notices);
+  return absorbText("--system-prompt", value, "system", Buffer.byteLength(value, "utf8"), budget, notices);
+}
+
+/**
+ * One file per directory: override, else AGENTS.md, else CLAUDE.md.
+ *
+ * An unreadable chosen file does not fall through to the next name -- the
+ * directory had a preference, it just could not be honoured. A name that
+ * is missing or is a directory is not a preference, so the next candidate
+ * is tried.
+ */
+async function absorbAgentsAt(
+  dir: string,
+  budget: Budget,
+  notices: ContextNotice[],
+): Promise<LoadedFile | null> {
+  for (const name of AGENTS_CANDIDATES) {
+    const path = join(dir, name);
+    const got = await tryRead(path);
+    if (got.status === "missing") continue;
+    if (got.status === "skip") {
+      if (got.reason === "is a directory") continue;
+      notices.push({ kind: "skipped", path, reason: got.reason });
+      return null;
+    }
+    return absorbText(path, got.text, "agents", got.bytes, budget, notices);
+  }
+  return null;
+}
+
+export async function loadContext(opts: LoadOptions): Promise<LoadedContext> {
+  const budget = new Budget();
+  const notices: ContextNotice[] = [];
+  const agents: LoadedFile[] = [];
+  const appends: LoadedFile[] = [];
+
+  let system: LoadedFile | null = null;
+  if (opts.systemPrompt !== undefined) {
+    // The flag is an explicit choice. A missing/unreadable file does not
+    // fall through to SYSTEM.md -- that would make a typo in the path
+    // silently restore the project prompt.
+    system = await absorbSystemArg(opts.systemPrompt, opts.cwd, budget, notices);
+  } else {
+    system =
+      (await absorbFile(join(opts.workspace, ".xeno", "SYSTEM.md"), "system", budget, notices)) ??
+      (await absorbFile(join(opts.configDir, "SYSTEM.md"), "system", budget, notices));
+  }
+
+  if (!opts.noContextFiles) {
+    const globalAgents = await absorbFile(join(opts.configDir, "AGENTS.md"), "agents", budget, notices);
+    if (globalAgents) agents.push(globalAgents);
+    for (const dir of projectDirectories(opts.workspace, opts.cwd)) {
+      const file = await absorbAgentsAt(dir, budget, notices);
+      if (file) agents.push(file);
+    }
+  }
+
+  const globalAppend = await absorbFile(join(opts.configDir, "APPEND_SYSTEM.md"), "append", budget, notices);
+  if (globalAppend) appends.push(globalAppend);
+  const projectAppend = await absorbFile(
+    join(opts.workspace, ".xeno", "APPEND_SYSTEM.md"),
+    "append",
+    budget,
+    notices,
+  );
+  if (projectAppend) appends.push(projectAppend);
+  for (const text of opts.appendSystemPrompt) {
+    appends.push(
+      absorbText(
+        "--append-system-prompt",
+        text,
+        "append",
+        Buffer.byteLength(text, "utf8"),
+        budget,
+        notices,
+      ),
+    );
+  }
+
+  return { system, agents, appends, notices };
+}
+
+const CONTEXT_INTRO =
+  "# Project context\n\n" +
+  "These files were loaded at startup. Later files are closer to the working " +
+  "directory and take precedence.";
+
+function truncationLine(file: LoadedFile): string {
+  const included = Buffer.byteLength(file.content, "utf8");
+  const omitted = Math.max(0, file.bytes - included);
+  return `[truncated: ${file.path} exceeded a size limit; ${omitted} bytes omitted]`;
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
+function renderFile(file: LoadedFile): string {
+  const inner = file.truncated ? `${file.content}\n${truncationLine(file)}` : file.content;
+  return `<context_file path="${escapeAttr(file.path)}">\n${inner}\n</context_file>`;
+}
+
+/**
+ * File contents in, prompt string out. The path of every loaded file is in
+ * the result so the model can cite which rule it is following, and a
+ * truncated file is named so a silent cut cannot hide.
+ */
+export function assembleSystemPrompt(builtin: string, loaded: LoadedContext): string {
+  const parts: string[] = [];
+  if (loaded.system !== null) {
+    parts.push(loaded.system.content);
+    if (loaded.system.truncated) parts.push(truncationLine(loaded.system));
+  } else {
+    parts.push(builtin);
+  }
+
+  const files = [...loaded.agents, ...loaded.appends];
+  if (files.length > 0) {
+    parts.push(CONTEXT_INTRO);
+    for (const file of files) parts.push(renderFile(file));
+  }
+  return parts.join("\n\n");
+}
+
+export function formatNotice(notice: ContextNotice): string {
+  switch (notice.kind) {
+    case "loaded":
+      return notice.truncated
+        ? `context  ${notice.path}  (truncated)`
+        : `context  ${notice.path}`;
+    case "skipped":
+      return `context  skipped ${notice.path}  (${notice.reason})`;
+    default:
+      return assertNever(notice, "formatNotice");
+  }
+}

package/src/store/file-index.ts

@@ -0,0 +1,81 @@
+/**
+ * Candidate paths for @-file expansion.
+ *
+ * A glob on every keystroke is a stall in a large repo (the card's rejected
+ * alternative). Scan once, cache for the session. The snapshot scanner is a
+ * different job -- it hashes contents and refuses to truncate -- so this walk
+ * is its own function rather than a mode flag on scanWorkspace.
+ */
+
+import { readdir } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { DEFAULT_IGNORE } from "./workspace.ts";
+
+/**
+ * Cap on indexed paths. Assumed, not measured: enough to fuzzy-search a
+ * large repo; past this the picker is hiding a missing filter, not serving
+ * one. Hitting it truncates and says so -- a silent cut would make @ miss
+ * files that exist.
+ */
+export const MAX_INDEX_ENTRIES = 20_000;
+
+export interface FileIndex {
+  readonly paths: readonly string[];
+  readonly truncated: boolean;
+}
+
+export interface IndexOptions {
+  readonly ignore?: readonly string[];
+  readonly maxEntries?: number;
+}
+
+function isIgnored(rel: string, ignore: readonly string[]): boolean {
+  const parts = rel.split(sep);
+  return ignore.some((i) => parts.includes(i));
+}
+
+export async function buildFileIndex(root: string, opts: IndexOptions = {}): Promise<FileIndex> {
+  const ignore = opts.ignore ?? DEFAULT_IGNORE;
+  const max = opts.maxEntries ?? MAX_INDEX_ENTRIES;
+  const paths: string[] = [];
+  let truncated = false;
+
+  async function walk(dir: string): Promise<void> {
+    if (truncated) return;
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (truncated) return;
+      // Do not follow symlinks: a link to / walks the disk, and
+      // node_modules/.bin is nothing but links. Same judgment as
+      // feat-workspace-snapshots, which also skips them via isFile().
+      if (entry.isSymbolicLink()) continue;
+      const abs = join(dir, entry.name);
+      const rel = relative(root, abs);
+      if (isIgnored(rel, ignore)) continue;
+      if (entry.isDirectory()) {
+        await walk(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (paths.length >= max) {
+        truncated = true;
+        return;
+      }
+      paths.push(rel.split(sep).join("/"));
+    }
+  }
+
+  await walk(root);
+  return { paths, truncated };
+}
+
+export function indexTruncationNote(index: FileIndex): string | null {
+  if (!index.truncated) return null;
+  return `file index truncated at ${index.paths.length} entries; later paths are not searchable`;
+}

package/src/store/git-branch.ts

@@ -0,0 +1,35 @@
+/**
+ * Current git branch for the status line.
+ *
+ * I/O lives here because tui cannot do I/O. Failure is silent: a missing
+ * binary, a directory that is not a repo, a detached HEAD, or a hang must
+ * not throw and must not stall TUI attach -- the status line just omits
+ * the branch.
+ */
+
+/**
+ * Assumed, not measured. `git symbolic-ref` is a local read; 200ms is long
+ * enough for a cold disk and short enough that a hung credential helper
+ * cannot freeze the first paint.
+ */
+export const GIT_BRANCH_TIMEOUT_MS = 200;
+
+export function currentBranch(
+  cwd: string,
+  command = "git",
+  timeoutMs = GIT_BRANCH_TIMEOUT_MS,
+): string | null {
+  try {
+    const p = Bun.spawnSync([command, "symbolic-ref", "--short", "HEAD"], {
+      cwd,
+      timeout: timeoutMs,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode !== 0) return null;
+    const name = new TextDecoder().decode(p.stdout).trim();
+    return name.length > 0 ? name : null;
+  } catch {
+    return null;
+  }
+}

package/src/store/history-search.ts

@@ -0,0 +1,19 @@
+/** Search immutable observation bodies without loading large command output into RAM. */
+import { createReadStream } from "node:fs";
+import { blobFilePath, verifyBlob } from "./blobs.ts";
+
+export async function observationContains(dir: string, sha256: string, terms: readonly string[]): Promise<boolean> {
+  if (!await verifyBlob(dir, sha256)) throw new Error(`missing or corrupt observation ${sha256}`);
+  const remaining = new Set(terms);
+  const overlap = Math.max(0, ...terms.map((term) => term.length - 1));
+  const decoder = new TextDecoder();
+  let tail = "";
+  for await (const chunk of createReadStream(blobFilePath(dir, sha256))) {
+    const text = tail + decoder.decode(chunk as Uint8Array, { stream: true }).toLowerCase();
+    for (const term of remaining) if (text.includes(term)) remaining.delete(term);
+    if (remaining.size === 0) return true;
+    tail = overlap > 0 ? text.slice(-overlap) : "";
+  }
+  const last = tail + decoder.decode().toLowerCase();
+  return [...remaining].every((term) => last.includes(term));
+}