@visual-z/xeno 0.1.0

package/src/core/recall-trial.ts

@@ -0,0 +1,153 @@
+/**
+ * F2 delayed recall: information observed exactly once, asked about later.
+ *
+ * The runner deletes each page when its stage ends, so the workspace holds no
+ * durable copy; only what the harness kept (a log, a summary, the model's own
+ * notes) can answer a later question. This isolates the claim the harness makes
+ * -- lossless history beats lossy summaries when a detail's relevance is only
+ * revealed later -- from the F1 ledger task, where state lives on disk and any
+ * file-capable harness can continue. Modelled on MemoryAgentBench's incremental
+ * chunk injection (accurate retrieval + conflict resolution); none of its data
+ * or scoring is reused. Pure: no I/O, clock or ambient randomness.
+ */
+import { seededRandom } from "./experiment.ts";
+
+export type RecallKind = "recent" | "recall" | "latest";
+export interface RecallEvent { ticket: string; code: string; action: "assign" | "reassign" }
+export interface RecallQuestion {
+  stage: number; kind: RecallKind; ticket: string; expected: string;
+  /** Page holding the expected code; distance is stage - source. */
+  source: number;
+  /** Codes the ticket held earlier; answering one of them is a stale answer. */
+  stale: string[];
+}
+export interface RecallPage { stage: number; path: string; answerPath: string; body: string; events: RecallEvent[]; question: RecallQuestion }
+export interface RecallFixture { seed: number; disclose: boolean; contract: string; pages: RecallPage[] }
+export interface RecallOptions {
+  stages: number; eventsPerPage: number; paddingChars: number;
+  /**
+   * Whether the contract says later stages may ask about earlier pages.
+   * Default false: disclosed, a diligent model copies every event into a notes
+   * file and the task collapses into F1 (state on disk). Undisclosed is the
+   * case the claim is about -- relevance revealed only after the fact.
+   */
+  disclose?: boolean;
+}
+
+// Log-like filler at roughly 4 chars/token: hex filler tokenizes ~2x denser,
+// which would double the cost of the same nominal length for no realism gain.
+const LEVELS = ["INFO", "INFO", "INFO", "DEBUG", "WARN"];
+const SERVICES = ["api", "worker", "scheduler", "cache", "gateway", "billing", "search", "auth"];
+const MESSAGES = ["heartbeat ok", "request served", "cache refreshed", "retrying upstream call", "job finished",
+  "connection pooled", "config reloaded", "slow query logged", "queue drained", "health check passed"];
+
+const pad = (n: number, width: number) => String(n).padStart(width, "0");
+
+export function recallFixture(seed: number, options: RecallOptions): RecallFixture {
+  const { stages, eventsPerPage, paddingChars } = options, disclose = options.disclose ?? false;
+  if (!Number.isSafeInteger(seed) || !Number.isSafeInteger(stages) || stages < 1 || stages > 256 ||
+      !Number.isSafeInteger(eventsPerPage) || eventsPerPage < 2 || eventsPerPage > 200 ||
+      !Number.isSafeInteger(paddingChars) || paddingChars < 0 || paddingChars > 4_000_000) throw new RangeError("invalid recall fixture dimensions");
+  const random = seededRandom(seed), int = (n: number) => Math.floor(random() * n);
+  const pick = <T>(xs: readonly T[]): T => xs[int(xs.length)]!;
+  const used = new Set<string>();
+  const fresh = (make: () => string) => { for (;;) { const v = make(); if (!used.has(v)) { used.add(v); return v; } } };
+  const hex = (n: number) => Array.from({ length: n }, () => "0123456789abcdef"[int(16)]).join("");
+  // Current state and each ticket's history, replayed exactly as a reader would.
+  const history = new Map<string, { stage: number; code: string }[]>();
+  const asked = new Set<string>();
+  const pages: RecallPage[] = [];
+  for (let stage = 0; stage < stages; stage++) {
+    const earlier = [...history.keys()];
+    // A quarter of events after page 0 reassign an earlier ticket (conflicts).
+    const reassign = stage === 0 ? 0 : Math.min(earlier.length, Math.floor(eventsPerPage / 4));
+    const events: RecallEvent[] = [];
+    const targets = new Set<string>();
+    while (targets.size < reassign) targets.add(pick(earlier));
+    for (const ticket of targets) events.push({ ticket, code: fresh(() => `K-${hex(12)}`), action: "reassign" });
+    while (events.length < eventsPerPage) events.push({ ticket: fresh(() => `T-${pad(10000 + int(90000), 5)}`), code: fresh(() => `K-${hex(12)}`), action: "assign" });
+    // Shuffle so reassignments are not always first on the page.
+    for (let i = events.length - 1; i > 0; i--) { const j = int(i + 1); [events[i], events[j]] = [events[j]!, events[i]!]; }
+    for (const event of events) {
+      const past = history.get(event.ticket) ?? [];
+      past.push({ stage, code: event.code }); history.set(event.ticket, past);
+    }
+
+    const question = chooseQuestion(stage, history, asked, int);
+    asked.add(question.ticket);
+    const lines: string[] = [];
+    for (let usedChars = 0, second = 0; usedChars < paddingChars; second++) {
+      const line = `2026-09-28T${pad(Math.floor(second / 3600) % 24, 2)}:${pad(Math.floor(second / 60) % 60, 2)}:${pad(second % 60, 2)}Z ` +
+        `${pick(LEVELS)} ${pick(SERVICES)}-${int(8)} ${pick(MESSAGES)} latency=${int(900)}ms queue=${int(64)}`;
+      lines.push(line); usedChars += line.length + 1;
+    }
+    // Spread events through the whole page, including its tail, so a head-only
+    // preview cannot pass as a full observation (same rule as F1).
+    for (let i = events.length - 1; i >= 0; i--) {
+      const at = Math.floor((i + 0.5) * lines.length / events.length);
+      lines.splice(at, 0, `EVENT ${JSON.stringify(events[i])}`);
+    }
+    pages.push({ stage, path: `incoming/page-${pad(stage, 2)}.txt`, answerPath: `answers/stage-${pad(stage, 2)}.txt`,
+      body: lines.join("\n"), events, question });
+  }
+  const contract = "This task runs in stages. Each stage delivers one page at incoming/page-NN.txt; the page is deleted when the stage ends. " +
+    "Pages contain EVENT lines (JSON) that assign or reassign a code to a ticket, mixed with unrelated log lines. " +
+    "A ticket's current code is the code from its most recent EVENT across all pages so far. " +
+    (disclose ? "Each stage asks about one ticket, which may have appeared on this page or on any earlier page. "
+      : "Each stage asks about one ticket. ") +
+    "Read the page in full with read, then write only the ticket's current code to the stage's answer file. Use only the provided tools. Reply briefly when the stage is done.";
+  return { seed, disclose, contract, pages };
+}
+
+/** Rotate kinds so every family appears; fall back when a kind has no candidate yet. */
+function chooseQuestion(stage: number, history: Map<string, { stage: number; code: string }[]>, asked: Set<string>, int: (n: number) => number): RecallQuestion {
+  const rows = [...history.entries()].filter(([ticket]) => !asked.has(ticket)).map(([ticket, past]) => ({ ticket, past, last: past.at(-1)! }));
+  const candidates: Record<RecallKind, typeof rows> = {
+    // Asked on the page that last set it, so no retention is needed.
+    recent: rows.filter((row) => row.last.stage === stage),
+    // Set once, on an earlier page: pure retrieval of a detail seen once.
+    recall: rows.filter((row) => row.past.length === 1 && row.last.stage < stage),
+    // Changed on an earlier page: the stale code must be rejected.
+    latest: rows.filter((row) => row.past.length > 1 && row.last.stage < stage),
+  };
+  const rotation: RecallKind[] = ["recent", "recall", "latest"];
+  const preferred = rotation[stage % 3]!;
+  for (const kind of [preferred, "recall", "latest", "recent"] as RecallKind[]) {
+    const pool = candidates[kind];
+    if (pool.length === 0) continue;
+    // Pick the source page first, uniformly, so distances are spread rather
+    // than dominated by whichever page had the most unasked tickets.
+    const sources = [...new Set(pool.map((row) => row.last.stage))].sort((a, b) => a - b);
+    const source = sources[int(sources.length)]!;
+    const onSource = pool.filter((row) => row.last.stage === source);
+    const row = onSource[int(onSource.length)]!;
+    return { stage, kind, ticket: row.ticket, expected: row.last.code, source, stale: row.past.slice(0, -1).map((p) => p.code) };
+  }
+  throw new Error("recall fixture has no question candidate");
+}
+
+export function recallPrompt(fixture: RecallFixture, stage: number): string {
+  const page = fixture.pages[stage]; if (!page) throw new RangeError("unknown recall stage");
+  return (stage === 0 ? fixture.contract + "\n\n" : "Continue under the original rules. ") +
+    `Stage ${stage}: read ${page.path} in full. Question: what is the current code of ticket ${page.question.ticket}? ` +
+    `Write only the code to ${page.answerPath}, then finish this stage.`;
+}
+
+export type RecallVerdict = { ok: true; reason: "exact" } | { ok: false; reason: "missing" | "stale" | "other_ticket" | "wrong" };
+
+/** Only whitespace and one wrapping quote/backtick pair are forgiven. */
+export function verifyRecallAnswer(body: string | null, question: RecallQuestion, codes: ReadonlySet<string>): RecallVerdict {
+  if (body === null) return { ok: false, reason: "missing" };
+  let answer = body.trim();
+  const wrapped = /^(["'`])(.*)\1$/s.exec(answer);
+  if (wrapped) answer = wrapped[2]!.trim();
+  if (answer === "") return { ok: false, reason: "missing" };
+  if (answer === question.expected) return { ok: true, reason: "exact" };
+  if (question.stale.includes(answer)) return { ok: false, reason: "stale" };
+  return { ok: false, reason: codes.has(answer) ? "other_ticket" : "wrong" };
+}
+
+/** Every code any page issued, to tell a confused lookup from a fabrication. */
+export function recallCodes(fixture: RecallFixture): Set<string> {
+  return new Set(fixture.pages.flatMap((page) => page.events.map((event) => event.code)));
+}

package/src/core/response-recovery.ts

@@ -0,0 +1,46 @@
+/** N.12: a returned response is durable evidence, not necessarily a completed action. */
+import type { GuidanceEvent, LogEvent } from "./events.ts";
+
+// One appended attempt is an operational assumption, not a measured optimum.
+// It shares the existing request ceiling and never replays a tool automatically.
+export const DEFAULT_OUTPUT_RECOVERY_LIMIT = 1;
+
+export function validateOutputRecoveryLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new RangeError("output recovery limit must be a nonnegative safe integer");
+}
+
+/** Both wire dialects have explicit terminal reasons; an unknown reason is not success. */
+export function isCompleteResponse(reason: string | null | undefined): boolean {
+  return reason !== undefined && reason !== null && ["stop", "end_turn", "stop_sequence", "tool_calls", "tool_use"].includes(reason);
+}
+
+export function isOutputLimit(reason: string | null | undefined): boolean {
+  return reason === "length" || reason === "max_tokens";
+}
+
+export function incompleteToolText(reason: string | null | undefined): string {
+  return `not executed: the model response ${isOutputLimit(reason) ? "reached its output limit" : "did not finish successfully"}; ` +
+    "no tools from that response were run. Regenerate a complete call only if the action is still needed.";
+}
+
+/** Explicit metadata proves non-execution; legacy pending calls remain unknown (D11). */
+export function knownUnexecutedTool(events: readonly LogEvent[], callId: string): string | null {
+  const owner = events.findLast(event => event.t === "assistant" && event.blocks.some(block => block.type === "tool_use" && block.call_id === callId));
+  return owner?.t === "assistant" && owner.stop_reason !== undefined && !isCompleteResponse(owner.stop_reason)
+    ? incompleteToolText(owner.stop_reason) : null;
+}
+
+/** Supply effective ancestry, not only the current segment: cutting must not reset this limit. */
+export function outputRecoveryNotice(events: readonly LogEvent[], limit: number, remainingRequests: number):
+  Pick<GuidanceEvent, "reason" | "sources" | "text"> | null {
+  validateOutputRecoveryLimit(limit);
+  const current = events.slice(events.findLastIndex(event => event.t === "user") + 1);
+  const assistant = current.findLast(event => event.t === "assistant");
+  const notices = current.filter(event => event.t === "guidance" && event.reason === "output_recovery");
+  if (assistant?.t !== "assistant" || !isOutputLimit(assistant.stop_reason) || notices.length >= limit || remainingRequests < 1 ||
+      notices.some(event => event.t === "guidance" && event.sources.includes(assistant.id))) return null;
+  return { reason: "output_recovery", sources: [assistant.id], text:
+    "Harness: the previous response hit its output token limit and is incomplete. All tool calls in that response were left unexecuted. " +
+    "Continue from the existing evidence, avoid repeating the earlier analysis, and give a concise result or the next necessary complete tool call. " +
+    "Do not claim unexecuted actions succeeded. This recovery consumes the existing request allowance." };
+}

package/src/core/scheduling.ts

@@ -0,0 +1,8 @@
+/** O.5: shared work may overlap only before the next exclusive barrier. */
+export function schedulingWindow(modes: readonly ("parallel" | "exclusive")[], start: number, limit: number): number {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError("maxParallelTools must be a positive integer");
+  if (modes[start] !== "parallel") return Math.min(start + 1, modes.length);
+  let end = start;
+  while (end < modes.length && modes[end] === "parallel" && end - start < limit) end++;
+  return end;
+}

package/src/core/settings.ts

@@ -0,0 +1,174 @@
+/**
+ * Settings schema and merge. Pure: store reads the files, this module
+ * decides which keys exist and which layer wins.
+ *
+ * Write-back is a patch of keys the user actually changed. Dumping the
+ * whole default object into ~/.xeno/settings.json freezes today's defaults
+ * for that user forever (feat-theming design).
+ */
+
+export const SETTINGS_KEYS = [
+  "theme",
+  "thinking",
+  "statusBar",
+  "defaultProvider",
+  "defaultModel",
+  "defaultThinking",
+  "scopedModels",
+] as const;
+
+export type SettingsKey = (typeof SETTINGS_KEYS)[number];
+
+export interface Settings {
+  readonly theme?: string;
+  readonly thinking?: string;
+  readonly statusBar?: boolean;
+  readonly defaultProvider?: string;
+  readonly defaultModel?: string;
+  /** Ctrl+S in the thinking selector. Distinct from `thinking` so /settings does not overwrite a saved default. */
+  readonly defaultThinking?: string;
+  /** `--models` / Ctrl+P set. Absent means there is nothing to cycle. */
+  readonly scopedModels?: readonly string[];
+}
+
+export interface SettingsLayers {
+  readonly builtin: Settings;
+  readonly user?: Settings;
+  readonly project?: Settings;
+  readonly cli?: Settings;
+}
+
+export interface SettingsParse {
+  readonly settings: Settings;
+  readonly diagnostics: readonly string[];
+}
+
+const THINKING_LEVELS = new Set(["low", "medium", "high", "xhigh", "max"]);
+
+export function defaultSettings(): Settings {
+  return { theme: "dark", thinking: "high", statusBar: true };
+}
+
+export function mergeSettings(layers: SettingsLayers): Settings {
+  return {
+    ...layers.builtin,
+    ...layers.user,
+    ...layers.project,
+    ...layers.cli,
+  };
+}
+
+/**
+ * Only keys present on `explicit`. Passing the merged object here would
+ * persist defaults and pin old users to them.
+ */
+export function settingsToWrite(explicit: Partial<Settings>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (explicit.theme !== undefined) out["theme"] = explicit.theme;
+  if (explicit.thinking !== undefined) out["thinking"] = explicit.thinking;
+  if (explicit.statusBar !== undefined) out["statusBar"] = explicit.statusBar;
+  if (explicit.defaultProvider !== undefined) out["defaultProvider"] = explicit.defaultProvider;
+  if (explicit.defaultModel !== undefined) out["defaultModel"] = explicit.defaultModel;
+  if (explicit.defaultThinking !== undefined) out["defaultThinking"] = explicit.defaultThinking;
+  if (explicit.scopedModels !== undefined) out["scopedModels"] = explicit.scopedModels;
+  return out;
+}
+
+export function parseSettings(json: unknown): SettingsParse {
+  if (json === null || json === undefined) {
+    return { settings: {}, diagnostics: [] };
+  }
+  if (typeof json !== "object" || Array.isArray(json)) {
+    return { settings: {}, diagnostics: ["settings is not an object"] };
+  }
+  const rec = json as { readonly [k: string]: unknown };
+  const diagnostics: string[] = [];
+  const settings: { [K in SettingsKey]?: Settings[K] } = {};
+
+  for (const key of Object.keys(rec)) {
+    if (!(SETTINGS_KEYS as readonly string[]).includes(key)) {
+      diagnostics.push(`unknown setting: ${key}`);
+    }
+  }
+
+  const theme = rec["theme"];
+  if (theme !== undefined) {
+    if (typeof theme === "string" && theme.length > 0) settings.theme = theme;
+    else diagnostics.push("settings.theme must be a non-empty string");
+  }
+
+  const thinking = rec["thinking"];
+  if (thinking !== undefined) {
+    if (typeof thinking === "string" && THINKING_LEVELS.has(thinking)) settings.thinking = thinking;
+    else diagnostics.push("settings.thinking must be low|medium|high|xhigh|max");
+  }
+
+  const statusBar = rec["statusBar"];
+  if (statusBar !== undefined) {
+    if (typeof statusBar === "boolean") settings.statusBar = statusBar;
+    else diagnostics.push("settings.statusBar must be a boolean");
+  }
+
+  const defaultProvider = rec["defaultProvider"];
+  if (defaultProvider !== undefined) {
+    if (typeof defaultProvider === "string") settings.defaultProvider = defaultProvider;
+    else diagnostics.push("settings.defaultProvider must be a string");
+  }
+
+  const defaultModel = rec["defaultModel"];
+  if (defaultModel !== undefined) {
+    if (typeof defaultModel === "string") settings.defaultModel = defaultModel;
+    else diagnostics.push("settings.defaultModel must be a string");
+  }
+
+  const defaultThinking = rec["defaultThinking"];
+  if (defaultThinking !== undefined) {
+    if (typeof defaultThinking === "string" && THINKING_LEVELS.has(defaultThinking)) {
+      settings.defaultThinking = defaultThinking;
+    } else diagnostics.push("settings.defaultThinking must be low|medium|high|xhigh|max");
+  }
+
+  const scopedModels = rec["scopedModels"];
+  if (scopedModels !== undefined) {
+    const parsed = parseScopedModels(scopedModels);
+    if (parsed === undefined) diagnostics.push("settings.scopedModels must be an array of strings");
+    else settings.scopedModels = parsed;
+  }
+
+  return { settings, diagnostics };
+}
+
+function parseScopedModels(raw: unknown): readonly string[] | undefined {
+  if (Array.isArray(raw) && raw.every((x) => typeof x === "string")) return raw as string[];
+  if (typeof raw === "string") {
+    return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return undefined;
+}
+
+/** Keys that were actually present on the raw object, after validation. */
+export function explicitSettings(raw: unknown, parsed: Settings): Partial<Settings> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
+  const rec = raw as { readonly [k: string]: unknown };
+  const out: {
+    theme?: string;
+    thinking?: string;
+    statusBar?: boolean;
+    defaultProvider?: string;
+    defaultModel?: string;
+    defaultThinking?: string;
+    scopedModels?: readonly string[];
+  } = {};
+  if ("theme" in rec && parsed.theme !== undefined) out.theme = parsed.theme;
+  if ("thinking" in rec && parsed.thinking !== undefined) out.thinking = parsed.thinking;
+  if ("statusBar" in rec && parsed.statusBar !== undefined) out.statusBar = parsed.statusBar;
+  if ("defaultProvider" in rec && parsed.defaultProvider !== undefined) {
+    out.defaultProvider = parsed.defaultProvider;
+  }
+  if ("defaultModel" in rec && parsed.defaultModel !== undefined) out.defaultModel = parsed.defaultModel;
+  if ("defaultThinking" in rec && parsed.defaultThinking !== undefined) {
+    out.defaultThinking = parsed.defaultThinking;
+  }
+  if ("scopedModels" in rec && parsed.scopedModels !== undefined) out.scopedModels = parsed.scopedModels;
+  return out;
+}

package/src/core/skills.ts

@@ -0,0 +1,121 @@
+/**
+ * Skill validation and the frozen-prefix fragment.
+ *
+ * A skill is a text resource, not a tool. The system prompt gets the name
+ * and description so the model can decide whether to read the file; the
+ * body stays out of the prefix because the prefix is sent on every request
+ * (feat-skills-and-prompts design; Agent Skills progressive disclosure).
+ */
+
+import { parseFrontmatter } from "./frontmatter.ts";
+
+/** Agent Skills name rule. Assumed from the spec, not measured. */
+const MAX_NAME_LENGTH = 64;
+
+/**
+ * 1–64 chars, lowercase / digits / hyphens, no leading, trailing, or
+ * doubled hyphen. A name that fails this is skipped, not coerced — an
+ * auto-slug would make two different directories collide silently.
+ */
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export interface Skill {
+  readonly name: string;
+  readonly description: string;
+  readonly filePath: string;
+  readonly body: string;
+  readonly disableModelInvocation: boolean;
+}
+
+export function isValidSkillName(name: string): boolean {
+  return name.length >= 1 && name.length <= MAX_NAME_LENGTH && NAME_RE.test(name);
+}
+
+export function parseSkill(input: {
+  readonly filePath: string;
+  readonly parentDirName: string;
+  readonly text: string;
+}): { skill: Skill | null; diagnostics: readonly string[] } {
+  const parsed = parseFrontmatter(input.text);
+  const diagnostics = [...parsed.diagnostics];
+  const desc = parsed.fields["description"];
+  const description = typeof desc === "string" ? desc.trim() : "";
+  if (description.length === 0) {
+    diagnostics.push(`${input.filePath}: missing description`);
+    return { skill: null, diagnostics };
+  }
+
+  const named = parsed.fields["name"];
+  const name = typeof named === "string" && named.trim().length > 0
+    ? named.trim()
+    : input.parentDirName;
+  if (!isValidSkillName(name)) {
+    diagnostics.push(`${input.filePath}: name "${name}" is not a valid skill name`);
+    return { skill: null, diagnostics };
+  }
+
+  const disable = parsed.fields["disable-model-invocation"] === true;
+  return {
+    skill: {
+      name,
+      description,
+      filePath: input.filePath,
+      body: parsed.body,
+      disableModelInvocation: disable,
+    },
+    diagnostics,
+  };
+}
+
+/**
+ * XML fragment per the Agent Skills integrate-skills shape, so a skill
+ * written for pi is recognised here. Location is the path the model should
+ * `read`; the body is deliberately absent.
+ */
+export function formatSkillsForPrompt(skills: readonly Skill[]): string {
+  const visible = skills.filter((s) => !s.disableModelInvocation);
+  if (visible.length === 0) return "";
+  const lines = [
+    "The following skills provide specialized instructions for specific tasks.",
+    "Use the read tool to load a skill's file when the task matches its description.",
+    "When a skill file references a relative path, resolve it against the skill directory.",
+    "",
+    "<available_skills>",
+  ];
+  for (const skill of visible) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+
+/** Append the skills section without touching the context-file assembly. */
+export function appendSkillsToSystem(system: string, skills: readonly Skill[]): string {
+  const section = formatSkillsForPrompt(skills);
+  return section.length === 0 ? system : `${system}\n\n${section}`;
+}
+
+/**
+ * `/skill:name` is the user forcing a read. Wrapping the body with the
+ * path lets relative references inside the skill resolve the same way a
+ * model-issued `read` would.
+ */
+export function skillInvocationMessage(skill: Skill, args: string): string {
+  const wrapped =
+    `<skill name="${escapeXml(skill.name)}" location="${escapeXml(skill.filePath)}">\n` +
+    `${skill.body}\n` +
+    `</skill>`;
+  return args.length > 0 ? `${wrapped}\n\nUser: ${args}` : wrapped;
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/core/stall.ts

@@ -0,0 +1,48 @@
+/** N.9: restartable progress accounting independent of model-context boundaries. */
+import type { LogEvent } from "./events.ts";
+import { pendingToolCalls } from "./execution.ts";
+import { exchangeProgressChecks } from "./evidence.ts";
+import { deriveProgress, type ProgressEvidence } from "./progress.ts";
+
+// A conservative hypothesis: enough room to change method after a mid-budget
+// notice, while bounding repeated paid requests. Not a task-quality classifier.
+export const DEFAULT_STALL_LIMIT = 12;
+export interface StallState {
+  evidence: readonly ProgressEvidence[];
+  pending: readonly LogEvent[];
+  pendingNode: number;
+  consecutive: number;
+  warned: boolean;
+}
+export function emptyStallState(): StallState {
+  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, warned: false };
+}
+export function finishStallExchange(state: StallState): StallState {
+  const assistant = state.pending[0];
+  if (assistant?.t !== "assistant" || pendingToolCalls(state.pending).length > 0) return state;
+  if (!assistant.blocks.some((block) => block.type === "tool_use")) return { ...state, pending: [] };
+  const progress = deriveProgress(state.evidence, state.pending, state.pendingNode, exchangeProgressChecks(state.pending));
+  return { ...state, pending: [], evidence: progress.evidence,
+    consecutive: progress.progressed ? 0 : state.consecutive + 1, warned: progress.progressed ? false : state.warned };
+}
+
+/** Fold original events, never the retained projection where evidence can repeat. */
+export function advanceStall(state: StallState, entries: readonly { node: number; event: LogEvent }[]): StallState {
+  let result = state;
+  for (const { node, event } of entries) {
+    if (event.t === "assistant" || event.t === "user" || event.t === "cut" || (event.t === "guidance" && event.reason === "stall")) {
+      result = finishStallExchange(result);
+      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, warned: false };
+      if (event.t === "assistant") result = { ...result, pending: [event], pendingNode: node };
+      if (event.t === "guidance") result = { ...result, warned: true };
+    } else if (result.pending.length > 0) result = { ...result, pending: [...result.pending, event] };
+  }
+  return result;
+}
+export function stallDecision(state: StallState, limit: number) {
+  if (!Number.isSafeInteger(limit) || limit < 0 || limit === 1) throw new RangeError("stall limit must be zero or an integer of at least two");
+  const current = finishStallExchange(state);
+  return { consecutive: current.consecutive,
+    stop: limit > 0 && current.consecutive >= limit,
+    warn: limit > 0 && current.consecutive >= Math.max(1, Math.floor(limit / 2)) && !current.warned };
+}

package/src/core/text-normalize.ts

@@ -0,0 +1,81 @@
+/**
+ * Text views an edit is matched against.
+ *
+ * A model never sees the bytes of a file, only read's rendering of them:
+ * no byte order mark, no carriage returns. An edit copied from that
+ * rendering has to be matched against the same view and written back in the
+ * file's own encoding -- otherwise every edit to a CRLF file fails, however
+ * exactly the model copied what it was shown.
+ */
+
+export interface TextView {
+  /** Content with the BOM removed and every line ending as `\n`. */
+  text: string;
+  bom: boolean;
+  /** Decided by the first line ending, as pi does; mixed files take the first. */
+  ending: "\n" | "\r\n";
+}
+
+export function toView(raw: string): TextView {
+  const bom = raw.startsWith("");
+  const body = bom ? raw.slice(1) : raw;
+  const lf = body.indexOf("\n");
+  const ending = lf > 0 && body[lf - 1] === "\r" ? "\r\n" : "\n";
+  return { text: toLF(body), bom, ending };
+}
+
+export function fromView(view: TextView, text: string): string {
+  return (view.bom ? "" : "") + (view.ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text);
+}
+
+export function toLF(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/**
+ * The equivalence a copied snippet is allowed to differ by.
+ *
+ * Each rule is a known way a model's copy drifts from the file: trailing
+ * whitespace dropped, typographic quotes and dashes straightened, exotic
+ * spaces turned into plain ones, compatibility forms folded (NFKC). Ported
+ * from pi-mono `edit-diff.ts` `normalizeForFuzzyMatch` (MIT, 6f75515).
+ *
+ * The line count is preserved -- no rule adds or removes a `\n` -- which is
+ * what lets a match found here be mapped back onto whole lines of the
+ * original, leaving every untouched line byte for byte as it was.
+ */
+export function normalizeLoose(text: string): string {
+  return text
+    .normalize("NFKC")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, "\"")
+    .replace(/[‐‑‒–—―−]/g, "-")
+    .replace(/[  -   　]/g, " ");
+}
+
+/** Levenshtein distance with the row buffer reused; inputs are bounded by callers. */
+export function editDistance(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let current = new Array<number>(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    current[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      current[j] = Math.min(previous[j]! + 1, current[j - 1]! + 1, previous[j - 1]! + cost);
+    }
+    [previous, current] = [current, previous];
+  }
+  return previous[b.length]!;
+}
+
+/** 1 for identical, 0 for nothing in common. */
+export function similarity(a: string, b: string): number {
+  const longest = Math.max(a.length, b.length);
+  return longest === 0 ? 1 : 1 - editDistance(a, b) / longest;
+}