@visual-z/xeno 0.1.0

package/src/core/overflow.ts

@@ -0,0 +1,59 @@
+/**
+ * Whether a provider error means "the prompt does not fit the window".
+ *
+ * That failure needs a different remedy from every other one: retrying the
+ * same request fails the same way (so it must not be retried even when a
+ * relay reports it as a 5xx), and the only thing that makes it succeed is a
+ * smaller projection. Providers word it differently and none shares a code,
+ * so recognition is by message text.
+ *
+ * Patterns ported from pi-mono `packages/ai/src/utils/overflow.ts` (MIT,
+ * commit 6f75515); the provider each one came from is kept beside it. A
+ * provider not listed here surfaces as an ordinary error, which is the safe
+ * direction: a missed overflow ends the turn visibly, a false one would cut
+ * a healthy context.
+ */
+const OVERFLOW_PATTERNS: readonly RegExp[] = [
+  /prompt (?:is )?too long/i, // Anthropic, z.ai
+  /request_too_large/i, // Anthropic byte-size overflow (413)
+  /input is too long for requested model/i, // Amazon Bedrock
+  /exceeds the context window/i, // OpenAI (Completions & Responses)
+  /exceeds (?:the )?(?:model'?s )?maximum context length(?: of [\d,]+ tokens?|\s*\([\d,]+\))/i, // OpenAI-compatible proxies
+  /input token count.*exceeds the maximum/i, // Google Gemini
+  /maximum prompt length is \d+/i, // xAI
+  /reduce the length of the messages/i, // Groq
+  /maximum context length is \d+ tokens/i, // OpenRouter
+  /exceeds (?:the )?maximum allowed input length of [\d,]+ tokens?/i, // OpenRouter / Poolside
+  /input \(\d+ tokens\) is longer than the model'?s context length \(\d+ tokens\)/i, // Together AI
+  /exceeds the limit of \d+/i, // GitHub Copilot
+  /exceeds the available context size/i, // llama.cpp
+  /greater than the context length/i, // LM Studio
+  /context window exceeds limit/i, // MiniMax
+  /exceeded model token limit/i, // Kimi
+  /too large for model with \d+ maximum context length/i, // Mistral
+  /prompt has [\d,]+ tokens?, but the configured context size is [\d,]+ tokens?/i, // DS4
+  /model_context_window_exceeded/i, // z.ai finish reason surfaced as error text
+  /prompt too long; exceeded (?:max )?context length/i, // Ollama
+  /range of input length should be/i, // DashScope / Qwen
+  /context[_ ]length[_ ]exceeded/i, // generic
+  /too many tokens/i, // generic
+  /token limit exceeded/i, // generic
+];
+
+/** Throttling that happens to mention tokens; excluded even when a pattern above matches. */
+const NOT_OVERFLOW: readonly RegExp[] = [
+  /^(Throttling error|Service unavailable):/i,
+  /throttl/i,
+  /rate limit/i,
+  /too many requests/i,
+  /please wait/i,
+];
+
+/** Cerebras answers an oversized request with a bodiless 400 / 413. */
+const BODYLESS = /^4(?:00|13)\s*(?:status code)?\s*\(no body\)/i;
+
+export function isContextOverflow(message: string, status?: number): boolean {
+  if (status === 429) return false;
+  if (NOT_OVERFLOW.some((pattern) => pattern.test(message))) return false;
+  return OVERFLOW_PATTERNS.some((pattern) => pattern.test(message)) || BODYLESS.test(message.trim());
+}

package/src/core/permissions.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure permission rules: which tools the model may see, and whether a
+ * call is allow / ask / deny.
+ *
+ * Approval is the last look at what is about to run, not a boundary.
+ * Path tools are already confined to the workspace root; bash is not,
+ * which is why bash defaults to ask and everything else to allow.
+ *
+ * This module must stay free of I/O, clocks, and randomness. The CLI
+ * compiles flags and session memory into a rule list; this file only
+ * matches them. There is no command-danger heuristic: a screen that
+ * misses `find . -delete` is worse than none, because it implies
+ * someone is checking.
+ */
+
+export type PermissionAction = "allow" | "ask" | "deny";
+
+export interface PermissionRequest {
+  readonly tool: string;
+  /** Exact command string for bash; omitted for tools that have none. */
+  readonly command?: string;
+}
+
+export interface PermissionRule {
+  readonly action: PermissionAction;
+  /** Absent matches every tool. */
+  readonly tool?: string;
+  /** Absent matches every command. When set, matches only this exact string. */
+  readonly command?: string;
+}
+
+/**
+ * Who contributed the tool. `builtin` is the only producer today.
+ * `extension` is in the union so `--no-builtin-tools` can keep a
+ * non-builtin tool without a later schema change across layers.
+ */
+export type ToolSource = "builtin" | "extension";
+
+export interface ToolSelection {
+  /** `--tools`: a strict allowlist. */
+  readonly only?: readonly string[];
+  /** `--exclude-tools`: removed after the allowlist (or the full set) is built. */
+  readonly exclude?: readonly string[];
+  /** `--no-tools`: start from nothing. Ignored when `only` is set. */
+  readonly none?: boolean;
+  /**
+   * `--no-builtin-tools`. Drops `source === "builtin"` (and untagged tools,
+   * which are builtin). Ignored when `only` is set: an explicit `--tools`
+   * names a specific tool and is a stronger statement than "not that category".
+   */
+  readonly noBuiltin?: boolean;
+}
+
+/**
+ * The flag a no-tty refusal names so a pipeline can choose explicitly.
+ *
+ * Session memory is not this flag: session memory dies with the process.
+ * A persisted "always allow" would fire months later when nobody is watching.
+ */
+export const ALLOW_TOOLS_FLAG = "--allow-tools";
+
+/**
+ * Product default. bash asks because it is not confined to the workspace
+ * root; every other built-in is allow because the path tools are.
+ */
+export function defaultRules(): readonly PermissionRule[] {
+  return [
+    { action: "ask", tool: "bash" },
+    // Same reach as bash. write_stdin needs no rule of its own: it can only
+    // address a session exec_command already started, under this approval.
+    { action: "ask", tool: "exec_command" },
+    { action: "allow" },
+  ];
+}
+
+/**
+ * `--allow-tools` compiled to rules, in front of the defaults so they win.
+ */
+export function rulesWithAllowTools(allowTools: readonly string[]): PermissionRule[] {
+  return [
+    ...allowTools.map((tool) => ({ action: "allow" as const, tool })),
+    ...defaultRules(),
+  ];
+}
+
+export function ruleMatches(rule: PermissionRule, request: PermissionRequest): boolean {
+  if (rule.tool !== undefined && rule.tool !== request.tool) return false;
+  if (rule.command !== undefined && rule.command !== request.command) return false;
+  return true;
+}
+
+/**
+ * First matching rule wins. An empty list allows: the tool tests pass no
+ * rules because they are testing the tool, not the gate. The CLI always
+ * supplies defaultRules().
+ */
+export function decide(
+  rules: readonly PermissionRule[],
+  request: PermissionRequest,
+): PermissionAction {
+  for (const rule of rules) {
+    if (ruleMatches(rule, request)) return rule.action;
+  }
+  return "allow";
+}
+
+/**
+ * Comma-separated flag values. Empty tokens are dropped so `--tools a,,b`
+ * does not invent a blank name.
+ */
+export function parseToolList(raw: string): string[] {
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/**
+ * Names the model will see. An excluded tool has to vanish here -- leaving
+ * it in the schema and failing at call time teaches the model to retry
+ * the same call and burn tokens.
+ *
+ * `--tools` is a strict allowlist. `--no-tools` starts from nothing, then
+ * `--tools` can add names back (pi's combination). `--exclude-tools` is
+ * applied last.
+ */
+export function selectToolNames(
+  available: readonly string[],
+  selection: ToolSelection,
+): string[] {
+  let names: string[];
+  if (selection.only !== undefined) {
+    const allow = new Set(selection.only);
+    names = available.filter((n) => allow.has(n));
+  } else if (selection.none === true) {
+    names = [];
+  } else {
+    names = [...available];
+  }
+  if (selection.exclude !== undefined) {
+    const ex = new Set(selection.exclude);
+    names = names.filter((n) => !ex.has(n));
+  }
+  return names;
+}
+
+export function selectTools<T extends { name: string; source?: ToolSource }>(
+  tools: readonly T[],
+  selection: ToolSelection,
+): T[] {
+  const names = new Set(selectToolNames(tools.map((t) => t.name), selection));
+  let selected = tools.filter((t) => names.has(t.name));
+  // `--tools` already named specific tools, so the category filter does
+  // not get a second veto. Untagged tools are builtin: that is today's
+  // only producer, and treating absence as "keep" would make the flag a
+  // no-op until every schema is recut.
+  if (selection.noBuiltin === true && selection.only === undefined) {
+    selected = selected.filter((t) => (t.source ?? "builtin") !== "builtin");
+  }
+  return selected;
+}
+
+export function permissionRequest(name: string, input: unknown): PermissionRequest {
+  if ((name !== "bash" && name !== "exec_command") || typeof input !== "object" || input === null) {
+    return { tool: name };
+  }
+  const command = (input as { readonly [k: string]: unknown })[name === "bash" ? "command" : "cmd"];
+  if (typeof command !== "string") return { tool: name };
+  return { tool: name, command };
+}
+
+/**
+ * Why this ask became a deny: nobody could be asked. Names the flag that
+ * would have allowed the call without asking, so a CI author can choose.
+ */
+export function askWithoutTtyMessage(request: PermissionRequest): string {
+  return (
+    `refused: ${request.tool} requires approval and there is no tty to ask. ` +
+    `Pass ${ALLOW_TOOLS_FLAG} ${request.tool} to allow it without asking.`
+  );
+}
+
+export function deniedMessage(request: PermissionRequest): string {
+  return `refused: ${request.tool} was denied`;
+}

package/src/core/policy-evaluation.ts

@@ -0,0 +1,55 @@
+/** N.7: repetitions stay attached to their task; they are not independent questions. */
+import { type ContextPolicy } from "./context-policy.ts";
+import { shuffled } from "./experiment.ts";
+
+// N.7 is a frozen three-arm protocol; new production policies cannot change it.
+const EVALUATED_POLICIES: readonly ContextPolicy[] = ["segmented", "continuous", "adaptive"];
+
+export interface PolicyJob { id: string; policy: ContextPolicy; repeat: number }
+export function policyJobKey(job: PolicyJob): string { return JSON.stringify([job.id, job.policy, job.repeat]); }
+export function policySchedule(ids: readonly string[], repetitions: number, seed: number): PolicyJob[] {
+  if (ids.length === 0 || new Set(ids).size !== ids.length || !Number.isSafeInteger(repetitions) || repetitions < 1) throw new Error("invalid policy trial design");
+  const policies = shuffled(EVALUATED_POLICIES, seed);
+  const jobs: PolicyJob[] = [];
+  let block = 0;
+  for (let repeat = 0; repeat < repetitions; repeat++) for (const id of shuffled([...ids].sort(), seed + repeat + 1)) {
+    for (let position = 0; position < policies.length; position++) jobs.push({ id, repeat, policy: policies[(block + position) % policies.length]! });
+    block++;
+  }
+  return jobs;
+}
+export interface PolicyObservation extends PolicyJob {
+  status: string; correct: boolean; peakRateUsd: number; reservedUnknownUsd: number;
+  requests: number; cuts: number; incompleteHandoffs: number; wallMs: number;
+  usage: { prompt_tokens: number; cache_read_input_tokens: number; output_tokens: number };
+}
+export function summarizePolicies(plan: readonly PolicyJob[], results: readonly PolicyObservation[]) {
+  const planned = new Set(plan.map(policyJobKey)), observed = new Set<string>();
+  if (planned.size !== plan.length) throw new Error("duplicate planned policy job");
+  for (const result of results) {
+    const key = policyJobKey(result);
+    if (!planned.has(key) || observed.has(key) || (result.correct && result.status !== "answered")) throw new Error("invalid policy result");
+    observed.add(key);
+  }
+  return [...new Set(plan.map((job) => job.policy))].sort().map((policy) => {
+    const schedule = plan.filter((job) => job.policy === policy), group = results.filter((row) => row.policy === policy);
+    const sum = (read: (row: PolicyObservation) => number) => group.reduce((n, row) => n + read(row), 0);
+    const correct = group.filter((row) => row.correct).length;
+    const peakRateUsd = sum((row) => row.peakRateUsd), reservedUnknownUsd = sum((row) => row.reservedUnknownUsd);
+    const promptTokens = sum((row) => row.usage.prompt_tokens), cachedTokens = sum((row) => row.usage.cache_read_input_tokens);
+    return { policy, planned: schedule.length, attempted: group.length, missing: schedule.length - group.length,
+      independentTasks: new Set(schedule.map((job) => job.id)).size, correct,
+      accuracy: group.length ? correct / group.length : null, complete: group.length === schedule.length,
+      plannedSolvedFraction: schedule.length ? correct / schedule.length : null,
+      peakRateUsd, reservedUnknownUsd, allAttemptCostPerSuccessUsd: correct ? (peakRateUsd + reservedUnknownUsd) / correct : null,
+      promptTokens, cachedTokens, outputTokens: sum((row) => row.usage.output_tokens),
+      cacheHitRate: promptTokens ? cachedTokens / promptTokens : null,
+      requests: sum((row) => row.requests), cuts: sum((row) => row.cuts), incompleteHandoffs: sum((row) => row.incompleteHandoffs),
+      wallMs: sum((row) => row.wallMs),
+      tasks: [...new Set(schedule.map((job) => job.id))].map((id) => ({ id,
+        planned: schedule.filter((job) => job.id === id).length,
+        attempted: group.filter((row) => row.id === id).length,
+        correct: group.filter((row) => row.id === id && row.correct).length })),
+    };
+  });
+}

package/src/core/progress.ts

@@ -0,0 +1,101 @@
+/**
+ * D9 / research M.4: an anti-stall signal, not a judgment of task completion.
+ * Novelty belongs to observed content and executed checks, never note wording,
+ * event IDs, or timestamps. The full ledger is rebuilt from the active log path;
+ * its carried handoff view may be paged like the other structural state (D20).
+ */
+import type { LineRange, LogEvent } from "./events.ts";
+
+export type ProgressEvidence = (
+  | { kind: "read"; sha256: string; ranges?: readonly LineRange[]; observation_sha256?: string }
+  | { kind: "observation"; sha256: string }
+  | { kind: "check"; command: string; gate?: string; workspace_sha256?: string }
+) & { source: { node: number; event_id: string } };
+
+/** Test coverage without expanding arbitrarily long ranges into line numbers. */
+function hasUnseenLines(requested: readonly LineRange[], observed: readonly LineRange[]): boolean {
+  const sorted = [...observed].sort((a, b) => a[0] - b[0]);
+  return requested.some(([start, end]) => {
+    let next = start;
+    for (const [low, high] of sorted) {
+      if (high < next) continue;
+      if (low > next) return true;
+      if (high >= end) return false;
+      next = high + 1;
+    }
+    return next <= end;
+  });
+}
+
+export function deriveProgress(
+  previous: readonly ProgressEvidence[], events: readonly LogEvent[], node: number,
+  eligibleChecks: ReadonlySet<string>,
+): { evidence: ProgressEvidence[]; progressed: boolean } {
+  const evidence = [...previous];
+  const reads = new Map<string, Extract<ProgressEvidence, { kind: "read" }>[]>();
+  const observations = new Set<string>();
+  const checks = new Set<string>();
+  // A named gate has one status per workspace. Changing its arguments does not
+  // make another gate, and cannot keep the loop alive by spelling a pass anew.
+  const checkKey = (command: string, gate?: string, workspace?: string): string =>
+    JSON.stringify([gate === undefined ? "command" : "gate", gate ?? command, workspace ?? null]);
+  for (const item of previous) {
+    if (item.kind === "read") {
+      const seen = reads.get(item.sha256) ?? [];
+      seen.push(item);
+      reads.set(item.sha256, seen);
+      if (item.observation_sha256 !== undefined) observations.add(item.observation_sha256);
+    } else if (item.kind === "observation") observations.add(item.sha256);
+    else checks.add(checkKey(item.command, item.gate, item.workspace_sha256));
+  }
+  let progressed = false;
+  const calls = new Map<string, string>();
+  for (const event of events) {
+    if (event.t === "assistant") {
+      for (const block of event.blocks) if (block.type === "tool_use") calls.set(block.call_id, block.name);
+    }
+    if (event.t !== "tool_result") continue;
+    const name = calls.get(event.call_id);
+    calls.delete(event.call_id);
+    if (!event.ok) continue;
+    const source = { node, event_id: event.id };
+    const effect = event.effect;
+    const observation = event.observation_sha256 ?? event.content_ref?.sha256 ?? event.content_sha256;
+    if (effect?.kind === "read" && effect.sha256 !== "") {
+      const seen = reads.get(effect.sha256) ?? [];
+      const novel = !seen.some((r) => r.ranges === undefined) &&
+        (effect.ranges === undefined || hasUnseenLines(effect.ranges, seen.flatMap((r) => r.ranges ?? [])));
+      if (novel) {
+        const item: Extract<ProgressEvidence, { kind: "read" }> = {
+          kind: "read", sha256: effect.sha256, source,
+          ...(effect.ranges === undefined ? {} : { ranges: effect.ranges }),
+          ...(observation === undefined ? {} : { observation_sha256: observation }),
+        };
+        evidence.push(item);
+        reads.set(effect.sha256, [...seen, item]);
+        // Whole-file hashes can change outside the returned range. Such a read
+        // extends coverage for that version but unchanged bytes are not novelty.
+        if (observation === undefined || !observations.has(observation)) progressed = true;
+        if (observation !== undefined) observations.add(observation);
+      }
+    } else if (effect?.kind === "command" && effect.exit === 0) {
+      const key = checkKey(effect.cmd, effect.gate, effect.workspace_sha256);
+      if (!checks.has(key)) {
+        checks.add(key);
+        evidence.push({ kind: "check", command: effect.cmd, source,
+          ...(effect.gate === undefined ? {} : { gate: effect.gate }),
+          ...(effect.workspace_sha256 === undefined ? {} : { workspace_sha256: effect.workspace_sha256 }) });
+        // Remember even unclaimed successes. A later model note cannot turn a
+        // rerun of old evidence into a fresh completion by giving it a new name.
+        if (eligibleChecks.has(event.id)) progressed = true;
+      }
+    } else if ((name === "grep" || name === "find" || name === "ls" || name === "query") &&
+        observation !== undefined && (event.content_ref?.bytes ?? event.content.length) > 0 &&
+        !observations.has(observation)) {
+      observations.add(observation);
+      evidence.push({ kind: "observation", sha256: observation, source });
+      progressed = true;
+    }
+  }
+  return { evidence, progressed };
+}