@visual-z/xeno 0.4.0 → 0.6.0

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/settings.ts

@@ -17,7 +17,7 @@ export interface Settings {
   readonly defaultThinking?: string;
   readonly modelThinkingLevels?: Readonly<Record<string, ThinkingLevel>>;
   readonly scopedModels?: readonly string[];
-  /** provider/model keys, most recent first; the /model picker's first section. */
+  /** provider/model keys, most recent first; picker ordering and startup fallback for older settings. */
   readonly recentModels?: readonly string[];
   readonly steeringMode?: "all" | "one-at-a-time";
   readonly followUpMode?: "all" | "one-at-a-time";

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 };
+}