@visual-z/xeno 0.5.0 → 0.6.0

package/src/core/permissions.ts

@@ -19,6 +19,8 @@ export interface PermissionRequest {
   readonly tool: string;
   /** Exact command string for bash; omitted for tools that have none. */
   readonly command?: string;
+  /** Normalized workspace-relative or external absolute file resources. */
+  readonly paths?: readonly string[];
 }
 
 export interface PermissionRule {
@@ -27,6 +29,11 @@ export interface PermissionRule {
   readonly tool?: string;
   /** Absent matches every command. When set, matches only this exact string. */
   readonly command?: string;
+  /** Literal argv prefix, matched only for a single command without expansion. */
+  readonly commandPrefix?: readonly string[];
+  readonly path?: string;
+  /** Portable path glob: *, ?, and **; no brace or character-class expansion. */
+  readonly pathGlob?: string;
 }
 
 /**
@@ -39,6 +46,8 @@ export type ToolSource = "builtin" | "extension";
 /** Task capabilities are frozen once at session creation (O.7); not permissions. */
 export const TOOL_PROFILES = {
   coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note"],
+  // An explicit preset preserves the measured legacy ten-tool coding contract.
+  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
   readonly: ["read", "grep", "find", "history", "note"],
   research: ["read", "grep", "find", "history", "note", "branch", "resolve"],
   data: ["read", "grep", "find", "history", "note", "query"],
@@ -80,6 +89,11 @@ export const ALLOW_TOOLS_FLAG = "--allow-tools";
  */
 export function defaultRules(): readonly PermissionRule[] {
   return [
+    // Templates are ordinary source; actual environment values deserve the
+    // same last look as commands. Indirect readers also check read resources.
+    { action: "allow", tool: "read", pathGlob: "**/.env.example" },
+    { action: "ask", tool: "read", pathGlob: "**/.env" },
+    { action: "ask", tool: "read", pathGlob: "**/.env.*" },
     { 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.
@@ -109,6 +123,12 @@ export function rulesWithAllowTools(
 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;
+  if (rule.commandPrefix !== undefined) {
+    const words = request.command === undefined ? null : literalCommandWords(request.command);
+    if (!words || rule.commandPrefix.length === 0 || rule.commandPrefix.some((word, i) => words[i] !== word)) return false;
+  }
+  if (rule.path !== undefined && !request.paths?.some(path => normalizePermissionPath(path) === normalizePermissionPath(rule.path!))) return false;
+  if (rule.pathGlob !== undefined && !request.paths?.some(path => permissionPathMatches(rule.pathGlob!, path))) return false;
   return true;
 }
 
@@ -121,12 +141,128 @@ export function decide(
   rules: readonly PermissionRule[],
   request: PermissionRequest,
 ): PermissionAction {
+  // A multi-file call needs every resource admitted. A broad allow for its
+  // first path must not conceal a denial on a later file (D13 / R13).
+  if (request.paths && request.paths.length > 1) {
+    const actions = request.paths.map(path => decide(rules, { ...request, paths: [path] }));
+    return actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
+  }
   for (const rule of rules) {
     if (ruleMatches(rule, request)) return rule.action;
   }
   return "allow";
 }
 
+/** Configured denial is a ceiling; in-memory approval can only resolve asks. */
+export function decideWithSessionRules(
+  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
+): PermissionAction {
+  if (decide(configured, request) === "deny") return "deny";
+  return decide([...remembered, ...configured], request);
+}
+
+/** Lexical normalization is pure; the store adds canonical symlink resources. */
+export function normalizePermissionPath(path: string): string {
+  const absolute = path.startsWith("/");
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop();
+    else if (part === ".." && absolute) continue;
+    else parts.push(part);
+  }
+  return (absolute ? "/" : "") + parts.join("/") || ".";
+}
+
+/** Dynamic programming avoids exponential regexp backtracking on model input. */
+export function permissionPathMatches(pattern: string, path: string): boolean {
+  const glob = normalizePermissionPath(pattern), value = normalizePermissionPath(path);
+  let row = Array<boolean>(value.length + 1).fill(false); row[0] = true;
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i]!;
+    const next = Array<boolean>(value.length + 1).fill(false);
+    if (char === "*") {
+      const deep = glob[i + 1] === "*";
+      if (deep) i++;
+      // **/ also matches zero directories, as in **/.env at the root.
+      const directories = deep && glob[i + 1] === "/";
+      if (directories) i++;
+      next[0] = row[0]!;
+      for (let j = 1; j <= value.length; j++) {
+        next[j] = row[j]! || ((deep || value[j - 1] !== "/") && next[j - 1]!);
+        if (directories && value[j - 1] !== "/") next[j] = row[j]!;
+      }
+      // A globstar followed by slash may consume complete directories only.
+      if (directories) {
+        let reachable = row[0]!;
+        for (let j = 1; j <= value.length; j++) {
+          reachable = reachable || row[j]!;
+          next[j] = row[j]! || (value[j - 1] === "/" && reachable);
+        }
+      }
+    } else {
+      for (let j = 1; j <= value.length; j++) next[j] = row[j - 1]! &&
+        (char === "?" ? value[j - 1] !== "/" : char === value[j - 1]);
+    }
+    row = next;
+  }
+  return row[value.length]!;
+}
+
+/**
+ * This is a prefix matcher, never a command-danger classifier. Unknown shell
+ * syntax fails to match and therefore retains the full-command ask (D13).
+ */
+export function literalCommandWords(command: string): string[] | null {
+  const words: string[] = [];
+  let word = "", started = false, quote: "'" | '"' | null = null;
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i]!;
+    if (char === "\n" || char === "\r" || char === "\0") return null;
+    if (quote === "'") {
+      if (char === "'") quote = null; else word += char;
+      continue;
+    }
+    if (char === "\\") {
+      const escaped = command[++i];
+      if (escaped === undefined || escaped === "\n" || escaped === "\r") return null;
+      // Bash double quotes retain backslash before ordinary characters.
+      word += quote === '"' && !['$', '`', '"', "\\"].includes(escaped) ? `\\${escaped}` : escaped;
+      started = true; continue;
+    }
+    if (quote === '"') {
+      if (char === '"') quote = null;
+      else if (char === "$" || char === "`") return null;
+      else word += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; started = true; continue; }
+    if (char === " " || char === "\t") { if (started) words.push(word); word = ""; started = false; continue; }
+    if (";|&<>($`*?[]{}~#".includes(char)) return null;
+    word += char; started = true;
+  }
+  if (quote !== null) return null;
+  if (started) words.push(word);
+  return words.length ? words : null;
+}
+
+/** Unknown config keys are errors: a typo must not silently weaken a policy. */
+export function parsePermissionRule(value: unknown): PermissionRule {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("permission rule must be an object");
+  const rule = value as Record<string, unknown>;
+  if (Object.keys(rule).some(key => !["action", "tool", "command", "commandPrefix", "path", "pathGlob"].includes(key))) throw Error("unknown permission rule field");
+  if (!["allow", "ask", "deny"].includes(String(rule["action"]))) throw Error("permission rule action must be allow, ask or deny");
+  for (const key of ["tool", "command", "path", "pathGlob"]) {
+    if (rule[key] !== undefined && (typeof rule[key] !== "string" || !String(rule[key]).trim() || String(rule[key]).includes("\0"))) throw Error(`permission ${key} must be a nonempty string`);
+  }
+  if (rule["path"] !== undefined && rule["pathGlob"] !== undefined) throw Error("permission path and pathGlob are mutually exclusive");
+  if (typeof rule["pathGlob"] === "string" && /[\[\]{}]/.test(rule["pathGlob"])) throw Error("permission pathGlob supports only *, ? and **");
+  const prefix = rule["commandPrefix"];
+  if (prefix !== undefined && (!Array.isArray(prefix) || prefix.length === 0 || prefix.some(word => typeof word !== "string" || !word || /[\r\n\0]/.test(word)))) throw Error("permission commandPrefix must contain literal argv tokens");
+  if (prefix !== undefined && rule["command"] !== undefined) throw Error("permission command and commandPrefix are mutually exclusive");
+  return structuredClone(value) as PermissionRule;
+}
+
 /**
  * Comma-separated flag values. Empty tokens are dropped so `--tools a,,b`
  * does not invent a blank name.
@@ -186,12 +322,15 @@ export function selectTools<T extends { name: string; source?: ToolSource }>(
 }
 
 export function permissionRequest(name: string, input: unknown): PermissionRequest {
-  if (!["bash", "exec_command", "environment"].includes(name) || typeof input !== "object" || input === null) {
+  if (typeof input !== "object" || input === null) {
     return { tool: name };
   }
-  const command = (input as { readonly [k: string]: unknown })[name === "exec_command" ? "cmd" : "command"];
-  if (typeof command !== "string") return { tool: name };
-  return { tool: name, command };
+  const fields = input as { readonly [k: string]: unknown };
+  const command = ["bash", "exec_command", "environment"].includes(name) ? fields[name === "exec_command" ? "cmd" : "command"] : undefined;
+  const paths = typeof fields["path"] === "string" ? [fields["path"]]
+    : Array.isArray(fields["paths"]) && fields["paths"].every(path => typeof path === "string") ? fields["paths"] as string[] : undefined;
+  return { tool: name, ...(typeof command === "string" ? { command } : {}),
+    ...(paths ? { paths: paths.map(normalizePermissionPath) } : {}) };
 }
 
 /**

package/src/core/question.ts

@@ -0,0 +1,94 @@
+/** R13 / D11: an answer is bound to its original active invocation, never guessed. */
+
+// Product limits keep one interaction reviewable, not measured model limits.
+export const MAX_QUESTIONS = 3;
+export const MAX_QUESTION_CHOICES = 8;
+export interface QuestionChoice { readonly id: string; readonly label: string; readonly description?: string }
+export interface QuestionSpec {
+  readonly id: string;
+  readonly header: string;
+  readonly question: string;
+  readonly options: readonly QuestionChoice[];
+  readonly multiple: boolean;
+  readonly custom: boolean;
+}
+export interface QuestionRequest {
+  readonly request_id: string;
+  readonly turn_id: string;
+  readonly call_id: string;
+  readonly questions: readonly QuestionSpec[];
+}
+export interface QuestionAnswer { readonly id: string; readonly choices: readonly string[]; readonly text?: string }
+export interface QuestionReply {
+  readonly request_id: string;
+  readonly turn_id: string;
+  readonly answers: readonly QuestionAnswer[];
+}
+function object(value: unknown, label: string, fields: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  const result = value as Record<string, unknown>;
+  if (Object.keys(result).some(key => !fields.includes(key))) throw Error(`${label} contains an unknown field`);
+  return result;
+}
+function string(value: unknown, label: string, max = 2000): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max || /[\0\x1b]/.test(value)) throw Error(`${label} must be nonempty plain text (max ${max} characters)`);
+  return value;
+}
+function identifier(value: unknown, label: string): string {
+  const id = string(value, label, 64);
+  if (!/^[a-z][a-z0-9_-]*$/.test(id)) throw Error(`${label} must be a stable lowercase identifier`);
+  return id;
+}
+
+export function parseQuestions(value: unknown): QuestionSpec[] {
+  const input = object(value, "question input", ["questions"]);
+  const questions = input["questions"];
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > MAX_QUESTIONS) throw Error(`question requires 1..${MAX_QUESTIONS} questions`);
+  const parsed = questions.map(value => {
+    const item = object(value, "question", ["id", "header", "question", "options", "multiple", "custom"]);
+    const options = item["options"] ?? [];
+    if (!Array.isArray(options) || options.length > MAX_QUESTION_CHOICES) throw Error(`question options must contain at most ${MAX_QUESTION_CHOICES} choices`);
+    const choices = options.map(value => {
+      const choice = object(value, "question option", ["id", "label", "description"]);
+      return { id: identifier(choice["id"], "option id"), label: string(choice["label"], "option label", 120),
+        ...(choice["description"] !== undefined ? { description: string(choice["description"], "option description", 600) } : {}) };
+    });
+    if (new Set(choices.map(choice => choice.id)).size !== choices.length) throw Error("question option ids must be unique");
+    if (new Set(choices.map(choice => choice.label)).size !== choices.length) throw Error("question option labels must be unique");
+    for (const key of ["multiple", "custom"]) if (item[key] !== undefined && typeof item[key] !== "boolean") throw Error(`question ${key} must be boolean`);
+    const multiple = item["multiple"] === true, custom = item["custom"] !== false;
+    if (!choices.length && !custom) throw Error("question must offer choices or custom text");
+    return { id: identifier(item["id"], "question id"), header: string(item["header"], "question header", 40),
+      question: string(item["question"], "question text"), options: choices, multiple, custom };
+  });
+  if (new Set(parsed.map(question => question.id)).size !== parsed.length) throw Error("question ids must be unique");
+  return parsed;
+}
+
+export function questionRequest(turnId: string, callId: string, questions: readonly QuestionSpec[]): QuestionRequest {
+  if (!turnId || !callId || /[\r\n\0]/.test(turnId + callId)) throw Error("question requires a trusted active turn and call identity");
+  // Tuple encoding avoids slash/delimiter collisions in opaque runtime IDs.
+  return { request_id: JSON.stringify([turnId, callId]), turn_id: turnId, call_id: callId, questions: structuredClone(questions) };
+}
+
+export function validateQuestionReply(request: QuestionRequest, value: unknown): QuestionReply {
+  const reply = object(value, "question reply", ["request_id", "turn_id", "answers"]);
+  if (reply["request_id"] !== request.request_id || reply["turn_id"] !== request.turn_id) throw Error("question reply belongs to a different invocation or turn");
+  const answers = reply["answers"];
+  if (!Array.isArray(answers) || answers.length !== request.questions.length) throw Error("question reply must answer every question exactly once");
+  const parsed = answers.map(value => {
+    const answer = object(value, "question answer", ["id", "choices", "text"]);
+    const id = identifier(answer["id"], "answer id"), question = request.questions.find(question => question.id === id);
+    if (!question) throw Error("question reply contains an unknown question id");
+    const choices = answer["choices"];
+    if (!Array.isArray(choices) || choices.some(choice => typeof choice !== "string" || !question.options.some(option => option.id === choice)) || new Set(choices).size !== choices.length) throw Error("question reply contains unknown or duplicate choices");
+    const text = answer["text"] === undefined ? undefined : string(answer["text"], "answer text", 10000);
+    if (text !== undefined && !question.custom) throw Error("custom text is not permitted for this question");
+    const count = choices.length + (text === undefined ? 0 : 1);
+    if (count === 0 || (!question.multiple && count !== 1)) throw Error("question reply requires one answer, or multiple only when enabled");
+    return { id, choices: [...choices] as string[], ...(text !== undefined ? { text } : {}) };
+  });
+  if (new Set(parsed.map(answer => answer.id)).size !== parsed.length) throw Error("question reply contains duplicate question ids");
+  return { request_id: request.request_id, turn_id: request.turn_id,
+    answers: request.questions.map(question => parsed.find(answer => answer.id === question.id)!) };
+}

package/src/core/review.ts

@@ -0,0 +1,68 @@
+/** Review scopes and checkpoint projection are data, never authorization (D8 / D11). */
+import type { LogEvent } from "./events.ts";
+import { sameVersion, changedPaths, type FileChanges } from "./checkpoints.ts";
+export type ReviewScope = { kind: "working" } | { kind: "branch"; base: string } |
+  { kind: "commit"; commit: string } | { kind: "last-turn" };
+export interface ReviewSnapshot {
+  scope: ReviewScope;
+  label: string;
+  diff: string;
+  paths: string[];
+  limitations: string[];
+  /** Resolved commits are immutable review premises, never raw shell expressions. */
+  base?: string;
+}
+
+/** Fold observed operations after the latest request; uncaptured effects remain unknown. */
+export function lastTurnChanges(events: readonly LogEvent[]): { changes: FileChanges; limitations: string[] } {
+  let start = 0;
+  for (let i = events.length - 1; i >= 0; i--) if (events[i]!.t === "user" || events[i]!.t === "user_bash") { start = i + 1; break; }
+  const changes: FileChanges = Object.create(null) as FileChanges;
+  const limitations = new Set<string>(["Last-turn diff covers durable file checkpoints; uncaptured command or external changes are unknown."]);
+  const suffix = events.slice(start);
+  const finalPhases = new Map(suffix.filter(event => event.t === "checkpoint").map(event => [event.operation, event.phase]));
+  for (const event of suffix) {
+    if (event.t !== "checkpoint") continue;
+    if (event.phase === "unavailable" && finalPhases.get(event.operation) !== "applied") limitations.add(event.reason ?? "A file checkpoint is unavailable.");
+    if (event.phase !== "applied" || finalPhases.get(event.operation) !== "applied") continue;
+    for (const path of changedPaths(event.changes)) {
+      const next = event.changes[path]!, previous = changes[path];
+      if (previous && !sameVersion(previous.after, next.before)) throw new Error(`discontinuous last-turn checkpoint: ${path}; external changes cannot be attributed`);
+      changes[path] = { before: previous ? previous.before : next.before, after: next.after };
+    }
+  }
+  return { changes: Object.fromEntries(changedPaths(changes).map(path => [path, changes[path]!])), limitations: [...limitations] };
+}
+
+/** A linear contiguous hunk avoids quadratic whole-file diff memory. No bytes are omitted. */
+export function unifiedFileDiff(path: string, before: string | null, after: string | null, destination = path): string {
+  if (before === after && path === destination) return "";
+  const lines = (text: string | null): { text: string; newline: boolean }[] => {
+    if (!text) return [];
+    const result = text.split("\n");
+    if (text.endsWith("\n")) result.pop();
+    return result.map((line, index) => ({ text: line, newline: index < result.length - 1 || text.endsWith("\n") }));
+  };
+  const oldLines = lines(before), newLines = lines(after);
+  const equal = (left: typeof oldLines[number] | undefined, right: typeof oldLines[number] | undefined) =>
+    left !== undefined && right !== undefined && left.text === right.text && left.newline === right.newline;
+  let prefix = 0, suffix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && equal(oldLines[prefix], newLines[prefix])) prefix++;
+  while (suffix < oldLines.length - prefix && suffix < newLines.length - prefix && equal(oldLines.at(-suffix - 1), newLines.at(-suffix - 1))) suffix++;
+  // Assumed familiar Git default: retain three lines of unchanged context per side.
+  const start = Math.max(0, prefix - 3), oldEnd = Math.min(oldLines.length, oldLines.length - suffix + 3), newEnd = Math.min(newLines.length, newLines.length - suffix + 3);
+  const quoted = (value: string) => /[\s"\\]/.test(value) ? JSON.stringify(value) : value;
+  const emit = (entries: typeof oldLines, marker: string) => entries.flatMap(line =>
+    [marker + line.text, ...(line.newline ? [] : ["\"])]);
+  const body = [...emit(oldLines.slice(start, prefix), " "),
+    ...emit(oldLines.slice(prefix, oldLines.length - suffix), "-"),
+    ...emit(newLines.slice(prefix, newLines.length - suffix), "+"),
+    ...emit(oldLines.slice(oldLines.length - suffix, oldEnd), " ")];
+  const range = (count: number) => count ? start + 1 : 0;
+  const oldCount = oldEnd - start, newCount = newEnd - start;
+  const headers = [`diff --git ${quoted("a/" + path)} ${quoted("b/" + destination)}`,
+    ...(path === destination ? [] : [`rename from ${quoted(path)}`, `rename to ${quoted(destination)}`]),
+    `--- ${before === null ? "/dev/null" : quoted("a/" + path)}`, `+++ ${after === null ? "/dev/null" : quoted("b/" + destination)}`];
+  if (body.length) headers.push(`@@ -${range(oldCount)},${oldCount} +${range(newCount)},${newCount} @@`, ...body);
+  return headers.join("\n") + "\n";
+}

package/src/core/update-check.ts

@@ -2,13 +2,14 @@
  * Whether to look for a newer xeno and what to say about it (docs/tasks/feat-update-check.md). Pure.
  *
  * Notify only: xeno names the command for the way it was installed and never
- * runs it. At most one registry request a day, recorded even when it fails,
- * and none at all offline, in CI, when turned off, or from a source checkout
+ * runs it. Automatic checks run at most once a day, recorded even when they fail,
+ * and no automatic requests offline, in CI, when turned off, or from a source checkout
  * (where the right update is `git pull`, not a package manager). Clock,
  * environment and the cached answer are all arguments, so every rule is a
- * plain function of its inputs.
+ * plain function of its inputs. Explicit checks bypass automatic scheduling
+ * and opt-outs, while retaining the offline and source-checkout boundaries.
  */
-import { isUpgrade } from "./version.ts";
+import { compareVersions, isUpgrade, parseVersion } from "./version.ts";
 
 export const PACKAGE_NAME = "@visual-z/xeno";
 /** One request a day, like update-notifier; Codex uses 20 hours. Assumed. */
@@ -32,6 +33,8 @@ export interface UpdateInput {
   /** Settings `updateCheck`; undefined means on. */
   readonly enabled: boolean | undefined;
   readonly install: InstallKind;
+  /** Explicit checks bypass only automatic scheduling and opt-outs (D16 manual-check extension). */
+  readonly manual?: boolean;
 }
 
 export interface UpdatePlan {
@@ -46,9 +49,10 @@ function truthy(value: string | undefined): boolean {
 }
 
 /** Reasons not to send a request at all, in the order they are checked. */
-export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "enabled" | "install">): string | undefined {
+export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "enabled" | "install" | "manual">): string | undefined {
   if (input.install === "checkout") return "running from a source checkout";
   if (input.offline || truthy(input.env["XENO_OFFLINE"])) return "offline";
+  if (input.manual) return undefined;
   if (input.enabled === false) return "updateCheck is off";
   if (truthy(input.env["XENO_NO_UPDATE_CHECK"]) || truthy(input.env["NO_UPDATE_NOTIFIER"])) return "turned off by environment";
   if (truthy(input.env["CI"]) || truthy(input.env["CONTINUOUS_INTEGRATION"])) return "running in CI";
@@ -57,6 +61,7 @@ export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "ena
 
 export function updatePlan(input: UpdateInput): UpdatePlan {
   if (updateDisabled(input)) return { check: false };
+  if (input.manual) return { check: true };
   const due = !input.cache || !Number.isFinite(input.cache.checkedAt) || input.now - input.cache.checkedAt >= CHECK_INTERVAL_MS
     || input.cache.checkedAt > input.now; // a clock set back must not silence checks for a year
   const latest = input.cache?.latest;
@@ -77,6 +82,20 @@ export function updateNotice(latest: string, current: string, install: InstallKi
   return `xeno ${latest} is available (you have ${current})\n  ${command ?? "see docs/install.md to update"}`;
 }
 
+/** A manual result describes this request, never an older cached answer. */
+export function manualUpdateResult(latest: string | null, current: string, install: InstallKind): {
+  readonly status: "available" | "current" | "ahead" | "ineligible" | "failed";
+  readonly text: string;
+} {
+  const next = latest === null ? null : parseVersion(latest), now = parseVersion(current);
+  if (!next || !now || latest === null) return { status: "failed", text: `Could not check for xeno updates (current ${current}). Check your connection or registry setting and try again.` };
+  if (isUpgrade(latest, current)) return { status: "available", text: updateNotice(latest, current, install) };
+  const order = compareVersions(next, now);
+  if (order === 0) return { status: "current", text: `xeno is up to date (${current}).` };
+  if (order < 0) return { status: "ahead", text: `xeno ${current} is newer than the registry's latest release (${latest}).` };
+  return { status: "ineligible", text: `No newer stable xeno release is available (current ${current}; registry latest ${latest}).` };
+}
+
 /**
  * How this copy was installed, from where its package root really lives.
  * Detected from the path rather than by running package managers, which

package/src/core/web-content.ts

@@ -0,0 +1,80 @@
+/** Network observations remain evidence-bearing projections, never executable instructions (D11). */
+export type WebFormat = "text" | "markdown" | "html";
+export type WebSearchProvider = "brave" | "exa";
+export interface WebSearchConfig { provider: WebSearchProvider; apiKeyEnv?: string; endpoint?: string }
+export interface WebSearchHit { title: string; url: string; description: string; published?: string }
+
+// Assumed admission bounds, not measured optima: bound malformed URLs and paid search requests.
+export const MAX_WEB_URL_LENGTH = 8_192;
+export const MAX_WEB_QUERY_LENGTH = 600;
+export const MAX_WEB_RESULTS = 20;
+export function webUrl(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_WEB_URL_LENGTH || /[\u0000-\u0020\u007f]/.test(value))
+    throw Error("url must be a nonempty HTTP(S) URL without whitespace and at most 8192 characters");
+  let parsed: URL;
+  try { parsed = new URL(value); } catch { throw Error("url must be an absolute HTTP(S) URL"); }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw Error("url must use HTTP or HTTPS");
+  if (parsed.username || parsed.password) throw Error("URL credentials are not supported; configure credentials outside model arguments");
+  parsed.hash = "";
+  return parsed.href;
+}
+export function webFetchArguments(input: Record<string, unknown>): { url: string; format: WebFormat; timeoutMs: number } {
+  const url = webUrl(input["url"]), format = input["format"] ?? "markdown";
+  if (format !== "text" && format !== "markdown" && format !== "html") throw Error("format must be text, markdown or html");
+  const timeout = input["timeout"] ?? 30;
+  if (!Number.isSafeInteger(timeout) || Number(timeout) < 1 || Number(timeout) > 120) throw Error("timeout must be an integer from 1 to 120 seconds");
+  return { url, format, timeoutMs: Number(timeout) * 1_000 };
+}
+export function webSearchArguments(input: Record<string, unknown>): { query: string; count: number } {
+  const query = input["query"], count = input["count"] ?? 8;
+  if (typeof query !== "string" || !query.trim() || query.length > MAX_WEB_QUERY_LENGTH || query.trim().split(/\s+/).length > 75)
+    throw Error("query must contain 1 to 600 characters and at most 75 words");
+  if (!Number.isSafeInteger(count) || Number(count) < 1 || Number(count) > MAX_WEB_RESULTS) throw Error("count must be an integer from 1 to 20");
+  return { query: query.trim(), count: Number(count) };
+}
+export function parseWebSearchConfig(value: unknown): WebSearchConfig | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) throw Error("webSearch must be an object");
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some(key => !["provider", "apiKeyEnv", "endpoint"].includes(key))) throw Error("webSearch has an unsupported field");
+  if (record["provider"] !== "brave" && record["provider"] !== "exa") throw Error("webSearch.provider must be brave or exa");
+  const key = record["apiKeyEnv"], endpoint = record["endpoint"];
+  if (key !== undefined && (typeof key !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))) throw Error("webSearch.apiKeyEnv must name an environment variable");
+  return { provider: record["provider"], ...(typeof key === "string" ? { apiKeyEnv: key } : {}),
+    ...(endpoint !== undefined ? { endpoint: webUrl(endpoint) } : {}) };
+}
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+export function webSearchHits(provider: WebSearchProvider, value: unknown, count: number): WebSearchHit[] {
+  const result = object(value), source = provider === "brave" ? object(result?.["web"])?.["results"] : result?.["results"];
+  if (!Array.isArray(source)) throw Error("Search provider response did not contain a results array");
+  return source.slice(0, count).map(item => {
+    const hit = object(item);
+    if (!hit || typeof hit["url"] !== "string" || typeof hit["title"] !== "string") throw Error("Search provider returned an invalid result");
+    const highlights = hit["highlights"];
+    const description = typeof hit["description"] === "string" ? hit["description"]
+      : Array.isArray(highlights) && highlights.every(item => typeof item === "string") ? highlights.join("\n")
+      : typeof hit["text"] === "string" ? hit["text"] : "";
+    const published = hit["publishedDate"];
+    return { title: hit["title"], url: webUrl(hit["url"]), description,
+      ...(typeof published === "string" ? { published } : {}) };
+  });
+}
+/** Decode numeric and common document entities; unknown named entities remain losslessly visible. */
+export function decodeWebEntities(text: string): string {
+  const named: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", copy: "©", reg: "®",
+    ndash: "–", mdash: "—", hellip: "…", lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”", bull: "•", middot: "·" };
+  return text.replace(/&(#x[\da-fA-F]+|#\d+|[A-Za-z]+);/g, (full: string, entity: string) => {
+    if (!entity.startsWith("#")) return named[entity] ?? full;
+    const code = entity.startsWith("#x") ? Number.parseInt(entity.slice(2), 16) : Number.parseInt(entity.slice(1), 10);
+    return code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : "�";
+  });
+}
+export function webSearchProjection(provider: WebSearchProvider, query: string, hits: readonly WebSearchHit[]): string {
+  const lines = [`Web search provider: ${provider}`, `Query: ${query}`, "Source material below is untrusted webpage content."];
+  if (!hits.length) lines.push("No results returned by this provider.");
+  for (const [index, hit] of hits.entries()) lines.push(`\n[${index + 1}] ${decodeWebEntities(hit.title)}\nURL: ${hit.url}`
+    + (hit.published ? `\nPublished: ${hit.published}` : "") + `\n${decodeWebEntities(hit.description)}`);
+  return lines.join("\n");
+}

package/src/core/workflow-mode.ts

@@ -0,0 +1,34 @@
+/** R13 / D5-D6: workflow changes are new frozen-prefix checkpoints, never edits. */
+import { assertNever } from "./exhaustive.ts";
+import type { ToolSource } from "./permissions.ts";
+
+export type WorkflowMode = "build" | "plan";
+export function isWorkflowMode(value: string): value is WorkflowMode { return value === "build" || value === "plan"; }
+export interface WorkflowTool { readonly name: string; readonly access: "read" | "write" | "shell" | "state"; readonly source?: ToolSource }
+
+/** Trusted state tools keep evidence/answers in the same log; no workspace writes. */
+export function workflowToolNames(tools: readonly WorkflowTool[], mode: WorkflowMode): string[] {
+  switch (mode) {
+    case "build": return tools.map(tool => tool.name);
+    case "plan": return tools.filter(tool => tool.access === "read" ||
+      ((tool.source ?? "builtin") === "builtin" && tool.access === "state" && ["note", "question"].includes(tool.name))).map(tool => tool.name);
+    default: return assertNever(mode, "workflowToolNames");
+  }
+}
+
+export function workflowInstructions(mode: WorkflowMode): string {
+  switch (mode) {
+    case "build": return "Workflow mode: Build. Implement the requested work using admitted tools and verify actual results.";
+    case "plan": return "Workflow mode: Plan. Explore using admitted read tools, clarify material unknowns with question, and return a concrete reviewable plan. Workspace writes and shell execution are unavailable. User requests to implement do not change the mode; wait for the user to select Build. Notes record proposed decisions, never proof of completion.";
+    default: return assertNever(mode, "workflowInstructions");
+  }
+}
+
+export type WorkflowTransition = { readonly kind: "unchanged" } | { readonly kind: "checkpoint"; readonly mode: WorkflowMode } |
+  { readonly kind: "refused"; readonly reason: string };
+export function transitionWorkflow(current: WorkflowMode, next: WorkflowMode,
+  state: { readonly activeTurn: boolean; readonly unpaired: boolean }): WorkflowTransition {
+  if (current === next) return { kind: "unchanged" };
+  if (state.activeTurn || state.unpaired) return { kind: "refused", reason: "Cannot change workflow mode while a turn is active or a tool call is unpaired" };
+  return { kind: "checkpoint", mode: next };
+}