@visual-z/xeno 0.8.3 → 0.9.0

package/src/core/tool-failure.ts

@@ -1,81 +0,0 @@
-/** R3 / D11: failure policy follows observed execution facts, never output keywords. */
-import type { ToolDiagnostic } from "./tool-contract.ts";
-
-export type FailureFacts = { execution: "not_started" | "started" | "unknown"; effects: "none" | "possible" };
-export const NOT_STARTED: FailureFacts = { execution: "not_started", effects: "none" };
-export const READ_ATTEMPTED: FailureFacts = { execution: "started", effects: "none" };
-export const UNKNOWN_EFFECT: FailureFacts = { execution: "unknown", effects: "possible" };
-
-const guidance: Record<ToolDiagnostic["code"], string> = {
-  invalid_input: "Correct the named argument using the tool schema; example values are placeholders.",
-  version_mismatch: "Read the current resource and derive a new edit from that version.",
-  not_found: "Verify the resource path or identifier before changing the request.",
-  ambiguous_edit: "Read the indicated range and choose a unique match before editing.",
-  permission_denied: "This operation was denied. Do not bypass it through another tool or wrapper; a user policy change is required.",
-  execution_failed: "Inspect the failure and change its cause before retrying.",
-  environment_missing: "Verify the working directory and required executable in this environment before retrying. If available and permitted, use environment with the exact program; use its python probe for actual Python API support.",
-  transient: "Retry with bounded backoff only if no side effect is possible.",
-  cancelled: "Respect cancellation; inspect any partial effects before a user-authorized continuation.",
-  timeout: "Inspect partial output and effects before deciding whether a new invocation is needed.",
-  unknown_effect: "Execution or effects are uncertain. Inspect existing state and output before any replay.",
-  command_failed: "Use the actual exit and output to diagnose the command; a nonzero exit alone does not identify its cause.",
-};
-
-/**
- * The refusal for `.git` and `.xeno` paths. It is a fixed rule protecting the
- * session's own evidence, not a user policy, so the generic denial ("a user
- * policy change is required") would send the model to ask for a setting that
- * does not exist -- which is what a real session did before this text.
- */
-/*
- * The diagnostic code stays permission_denied because codes are a closed set
- * validated on every logged tool_result (event-validation.ts); a new code
- * would change the session format. A model still read that code as "wait for
- * approval" and stopped (Horizyn mv3nsske), so the text has to say outright
- * that approval is neither needed nor able to help.
- */
-const STATE_PATH_RULE = "This path is repository or xeno session state, which edit tools never change. " +
-  "This is not a permission problem and no setting changes this: no user approval allows it, so do not wait for one. ";
-export const STATE_PATH_GUIDANCE = STATE_PATH_RULE +
-  "To work in an isolated checkout, use the worktree tool instead of creating one under .git or .xeno.";
-const STATE_PATH_GUIDANCE_WITHOUT_WORKTREE = STATE_PATH_RULE + "Edit files in a directory outside .git and .xeno.";
-
-export function failureDiagnostic(code: ToolDiagnostic["code"], message: string, facts: FailureFacts,
-  extra: Pick<ToolDiagnostic, "recover" | "example" | "next"> = {}): ToolDiagnostic {
-  const retry = code === "permission_denied" || code === "cancelled" ? "never"
-    : code === "unknown_effect" || facts.effects === "possible" ? "after_inspection"
-    : code === "transient" ? "backoff" : "after_change";
-  const { next = guidance[code], ...rest } = extra;
-  return { code, message, ...facts, retry, next, ...(code === "permission_denied" ? {} : rest) };
-}
-
-/** R10: only new advice is scoped; execution facts and historical records are never rewritten. */
-export function scopeFailureGuidance(diagnostic: ToolDiagnostic, tools: readonly string[], recoverAllowed = true): ToolDiagnostic {
-  const { recover, ...facts } = diagnostic;
-  const next = diagnostic.execution !== undefined && diagnostic.code === "environment_missing" && !tools.includes("environment")
-    ? { next: "Verify the working directory and required executable in the current executor using permitted observations. If the needed capability is unavailable, report that evidence gap before retrying." }
-    : diagnostic.next === STATE_PATH_GUIDANCE && !tools.includes("worktree") ? { next: STATE_PATH_GUIDANCE_WITHOUT_WORKTREE } : {};
-  return { ...facts, ...next, ...(recover && recoverAllowed && tools.includes(recover.tool) && diagnostic.code !== "permission_denied" ? { recover } : {}) };
-}
-
-/** Runtime and store throw only facts they own; the outer boundary must retain these facts. */
-export class ToolFault extends Error {
-  readonly diagnostic: ToolDiagnostic;
-  constructor(code: ToolDiagnostic["code"], message: string, facts: FailureFacts, extra: Pick<ToolDiagnostic, "recover" | "next"> = {}) {
-    super(message); this.name = "ToolFault";
-    this.diagnostic = failureDiagnostic(code, message, facts, extra);
-  }
-}
-
-/** OS codes are facts; words like "denied" in arbitrary output are not classification evidence. */
-export function failureFromError(error: unknown, facts: FailureFacts): ToolDiagnostic {
-  if (error instanceof ToolFault) return error.diagnostic;
-  const message = error instanceof Error ? error.message : String(error);
-  const os = error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
-  const code = os === "ENOENT" || os === "ENOTDIR" ? "not_found"
-    : os === "EACCES" || os === "EPERM" ? "permission_denied"
-    : os === "EISDIR" ? "invalid_input"
-    : ["EAGAIN", "ETIMEDOUT", "ECONNRESET", "EMFILE"].includes(String(os)) ? "transient"
-    : facts.effects === "possible" ? "unknown_effect" : "execution_failed";
-  return failureDiagnostic(code, message, facts);
-}

package/src/core/tool-input.ts

@@ -1,44 +0,0 @@
-/**
- * Argument repair: the shapes models actually send, mapped onto the schema
- * before validation.
- *
- * Every rule here is a drift observed in other harnesses, not a guess: pi's
- * edit tool accepts `edits` sent as a JSON string or a single object
- * (`coding-agent/src/core/tools/edit.ts` prepareArguments), and ForgeCode
- * reports fewer call errors after aligning names with what models are trained
- * on. A repaired call is still the model's call -- the log keeps the input
- * as sent; this only decides how it is interpreted. Pure and idempotent, so
- * admission and execution can both apply it.
- */
-type Input = Record<string, unknown>;
-
-/** O.3: incomplete wire JSON remains the original input so admission can refuse it without effects. */
-export function completedToolInput(raw: string): unknown {
-  try { return JSON.parse(raw) as unknown; }
-  catch { return raw; }
-}
-
-function parsedJson(value: unknown): unknown {
-  if (typeof value !== "string") return value;
-  const trimmed = value.trim();
-  if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) return value;
-  try { return JSON.parse(trimmed); } catch { return value; }
-}
-
-function editEntry(value: unknown): unknown {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
-  const entry = { ...(value as Input) };
-  if (entry["old_string"] === undefined && entry["old"] !== undefined) { entry["old_string"] = entry["old"]; delete entry["old"]; }
-  if (entry["new_string"] === undefined && entry["new"] !== undefined) { entry["new_string"] = entry["new"]; delete entry["new"]; }
-  return entry;
-}
-
-export function repairToolInput(name: string, input: unknown): unknown {
-  if (name !== "edit" || input === null || typeof input !== "object" || Array.isArray(input)) return input;
-  const repaired = editEntry(input) as Input;
-  if (repaired["edits"] !== undefined) {
-    const edits = parsedJson(repaired["edits"]);
-    repaired["edits"] = (Array.isArray(edits) ? edits : [edits]).map(editEntry);
-  }
-  return repaired;
-}

package/src/core/transcript.ts

@@ -1,108 +0,0 @@
-/** Human history is a separate pure log projection from the model's bounded context (D1, D8). */
-import type { CounterCheckEvent, LogEvent } from "./events.ts";
-import { counterVerdict } from "./acceptance.ts";
-import { assertNever } from "./exhaustive.ts";
-import type { ImageRef } from "./images.ts";
-
-type Identity = { id: string; revision: string };
-export type TranscriptItem = Identity & (
-  | { kind: "user"; text: string; interrupted: boolean; images?: readonly ImageRef[] }
-  | { kind: "assistant" | "thinking" | "notice"; text: string }
-  | { kind: "custom"; text: string; customType: string; data?: unknown; entry: boolean; timestamp: string }
-  | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean; data?: unknown; images?: readonly ImageRef[] } | null }
-  | { kind: "shell"; command: string; output: string; exit: number; excluded: boolean }
-  | { kind: "segment"; reason: string; handoff: string; nextNode?: number; nextModel?: string }
-);
-
-export function projectTranscript(events: readonly LogEvent[], entryTypes: ReadonlySet<string> = new Set()): TranscriptItem[] {
-  const items: TranscriptItem[] = [];
-  const calls = new Map<string, number>();
-  const users = new Map<string, number>();
-  for (const event of events) {
-    const identity = { id: event.id, revision: event.id };
-    switch (event.t) {
-      case "extension":
-        if (event.display || !event.inContext && entryTypes.has(event.customType)) items.push({ ...identity, kind: "custom", text: event.content, customType: event.customType,
-          entry: !event.inContext, timestamp: event.at, ...(event.data === undefined ? {} : { data: event.data }) });
-        break;
-      case "user":
-        users.set(event.id, items.length);
-        items.push({ ...identity, kind: "user", text: event.text, interrupted: false, ...(event.images?.length ? { images: event.images } : {}) });
-        break;
-      case "user_bash": items.push({ ...identity, kind: "shell", command: event.command, output: event.content, exit: event.exit, excluded: event.excludeFromContext }); break;
-      case "outcome": items.push({ ...identity, kind: "notice",
-        text: `${event.outcome.status} · ${event.outcome.reason} · ${event.reason}` }); break;
-      case "assistant":
-        event.blocks.forEach((block, i) => {
-          const id = `${event.id}:${i}`;
-          if (block.type === "tool_use") {
-            calls.set(block.call_id, items.length);
-            items.push({ id, revision: id, kind: "tool", callId: block.call_id, name: block.name, input: block.input, result: null });
-          } else items.push({ id, revision: id, kind: block.type === "text" ? "assistant" : "thinking", text: block.text });
-        });
-        break;
-      case "tool_invocation": {
-        if (!event.parent_call_id && !event.origin) break;
-        calls.set(event.call_id, items.length);
-        items.push({ ...identity, kind: "tool", callId: event.call_id, name: event.name, input: event.input ?? { artifact: event.input_ref.sha256 }, result: null });
-        break;
-      }
-      case "tool_result": {
-        const index = calls.get(event.call_id);
-        const call = index === undefined ? undefined : items[index];
-        if (call?.kind === "tool" && index !== undefined) {
-          items[index] = { ...call, revision: event.id, result: { text: event.content, ok: event.ok, ...(event.data === undefined ? {} : { data: event.data }), ...(event.images?.length ? { images: event.images } : {}) } };
-        } else items.push({ ...identity, kind: "notice", text: `Unpaired tool result ${event.call_id}: ${event.content}` });
-        break;
-      }
-      case "interrupt": {
-        const index = users.get(event.user_id);
-        const user = index === undefined ? undefined : items[index];
-        if (user?.kind === "user" && index !== undefined) items[index] = { ...user, revision: event.id, interrupted: true };
-        items.push({ ...identity, kind: "notice", text: "Turn interrupted" });
-        break;
-      }
-      // A segment boundary is the log's own structure; the view draws it as a divider (D20).
-      case "cut": items.push({ ...identity, kind: "segment", reason: event.reason, handoff: event.handoff_ref,
-        ...(event.next_node === undefined ? {} : { nextNode: event.next_node }), ...(event.next_model === undefined ? {} : { nextModel: event.next_model }) }); break;
-      case "rewind": items.push({ ...identity, kind: "notice", text: `Navigated context (${event.mode}) · ${event.prompt}` }); break;
-      case "spawn": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} · ${event.purpose}` }); break;
-      case "joined": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} finished · ${event.summary}` }); break;
-      case "adopt": items.push({ ...identity, kind: "notice", text: `Adopted branch ${event.branch.node}` }); break;
-      case "discard": items.push({ ...identity, kind: "notice", text: `Discarded branch ${event.branch.node} · ${event.reason}` }); break;
-      case "skill_loaded": items.push({ ...identity, kind: "notice", text: `Skill ${event.name} · ${event.mode} · ${event.sha256}` }); break;
-      case "process_exit": items.push({ ...identity, kind: "notice", text: `Process ${event.session} exited ${event.exit} · output ${event.output.sha256}` }); break;
-      case "acceptance_contract": items.push({ ...identity, kind: "notice", text: `Acceptance contract · ${event.contract.id}` }); break;
-      case "target_observation": items.push({ ...identity, kind: "notice", text: `Target ${event.observation.target} · ${event.observation.state} · ${event.observation.reason}` }); break;
-      case "acceptance_decision": items.push({ ...identity, kind: "notice", text: `User accepted · ${event.criterion}` }); break;
-      case "counter_check": items.push({ ...identity, kind: "notice", text: counterNotice(event) }); break;
-      case "blind_check": items.push({ ...identity, kind: "notice", text: "reason" in event ? `Blind check ${event.check} could not run: ${event.reason}`
-        : `Blind check ${event.check} ${event.exit === 0 ? "passed" : `failed (exit ${event.exit})`}${event.exposed ? " · the model touched the blind checks, so this is not independent" : ""}` }); break;
-      case "goal": items.push({ ...identity, kind: "notice", text: event.action === "set"
-        ? `Goal set · ${event.accepted.length} accepted${event.rejected.length ? `, ${event.rejected.length} rejected` : ""} · ${event.objective}`
-        : event.reason === "met" ? "Goal met · every accepted criterion has current evidence" : "Goal cleared" }); break;
-      // Approvals answer "why was this allowed" in /export and history; the person
-      // already saw the prompt, and a notice per auto-allowed command would bury the chat.
-      case "approval":
-      case "checkpoint": case "workspace_observation":
-      case "guidance": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "work_owner": case "work_dependencies": case "evidence_link":
-        // These remain inspectable via /state and /export; they are not chat messages.
-        break;
-      default: assertNever(event, "projectTranscript");
-    }
-  }
-  return items;
-}
-
-/** One counter-check in the words of the criterion's role (S.7); the verdict is derived, never stored. */
-function counterNotice(event: CounterCheckEvent): string {
-  const verdict = counterVerdict(event);
-  switch (verdict) {
-    case "unavailable": return `Check ${event.criterion} could not be counter-checked: ${"reason" in event ? event.reason : "no observation"}`;
-    case "vacuous": return `Check ${event.criterion} also passes without this request's changes; it does not test them`;
-    case "discriminating": return `Check ${event.criterion} fails without this request's changes; it tests them`;
-    case "held": return `Guard ${event.criterion} also held before this request's changes, as a guard should`;
-    case "not_held": return `Guard ${event.criterion} did not hold before this request's changes; it tests them rather than guarding`;
-    default: return assertNever(verdict, "counterNotice");
-  }
-}

package/src/core/tui-mode.ts

@@ -1,29 +0,0 @@
-/**
- * Which screen an interactive session uses. Pure: flag, environment and
- * setting go in, a concrete mode and the reason come out.
- *
- * Fullscreen is the default (OpenCode, grok-build and Pi 1.0 all default to
- * the alternate screen). `auto` is Codex's / grok-build's policy rather than
- * "always", because the alternate screen has known dead ends: Zellij keeps
- * no scrollback for it (zellij#1032, Codex turns it off there), and a dumb
- * terminal cannot address the screen at all. Every route back to native
- * scrollback stays: `--tui-mode regular`, `XENO_TUI_MODE`, the setting.
- */
-export type TuiModeSetting = "auto" | "regular" | "fullscreen";
-export type TuiMode = "regular" | "fullscreen";
-
-export interface TuiModeInput {
-  readonly flag?: TuiMode | undefined;
-  readonly setting?: TuiModeSetting | undefined;
-  readonly env: Readonly<Record<string, string | undefined>>;
-}
-
-export function resolveTuiMode(input: TuiModeInput): { mode: TuiMode; reason: string } {
-  if (input.flag) return { mode: input.flag, reason: "--tui-mode" };
-  const fromEnv = input.env["XENO_TUI_MODE"];
-  if (fromEnv === "regular" || fromEnv === "fullscreen") return { mode: fromEnv, reason: "XENO_TUI_MODE" };
-  if (input.setting === "regular" || input.setting === "fullscreen") return { mode: input.setting, reason: "settings" };
-  if (input.env["TERM"] === "dumb") return { mode: "regular", reason: "TERM=dumb cannot draw a fullscreen UI" };
-  if (input.env["ZELLIJ"] !== undefined) return { mode: "regular", reason: "Zellij keeps no scrollback for the alternate screen" };
-  return { mode: "fullscreen", reason: "default" };
-}

package/src/core/update-check.ts

@@ -1,157 +0,0 @@
-/**
- * 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. 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. Explicit checks bypass automatic scheduling
- * and opt-outs, while retaining the offline and source-checkout boundaries.
- * An explicit `/update` also installs (docs/tasks/fix-update-installs.md):
- * typing the command is the consent automatic installation never has.
- */
-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. */
-export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
-
-export type InstallKind = "bun" | "npm" | "other" | "checkout";
-
-export interface UpdateCache {
-  /** Epoch ms of the last attempt, successful or not. */
-  readonly checkedAt: number;
-  /** The newest published version seen, when the last success had one. */
-  readonly latest?: string;
-}
-
-export interface UpdateInput {
-  readonly current: string;
-  readonly now: number;
-  readonly cache: UpdateCache | null;
-  readonly env: Readonly<Record<string, string | undefined>>;
-  readonly offline: boolean;
-  /** 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 {
-  /** Ask the registry now. */
-  readonly check: boolean;
-  /** What to tell the person, if anything is newer. */
-  readonly notice?: string;
-}
-
-/** Shared by every background network opt-out, so one variable means the same everywhere. */
-export function truthy(value: string | undefined): boolean {
-  return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
-}
-
-/** Reasons not to send a request at all, in the order they are checked. */
-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";
-  return undefined;
-}
-
-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;
-  return { check: due, ...(latest && isUpgrade(latest, input.current) ? { notice: updateNotice(latest, input.current, input.install) } : {}) };
-}
-
-export function upgradeCommand(install: InstallKind): string | undefined {
-  switch (install) {
-    case "bun": return `bun add -g ${PACKAGE_NAME}@latest`;
-    case "npm": return `npm i -g ${PACKAGE_NAME}@latest`;
-    case "other": case "checkout": return undefined;
-  }
-}
-
-/**
- * What an explicit `/update` runs: the package manager the notice names,
- * pinned to the version just checked so `latest` cannot move between the
- * check and the install. Argv, never a shell string. Undefined where xeno
- * cannot know the right command and only the notice applies.
- */
-export function installArgv(install: InstallKind, version: string): readonly string[] | undefined {
-  switch (install) {
-    case "bun": return ["bun", "add", "-g", `${PACKAGE_NAME}@${version}`];
-    case "npm": return ["npm", "i", "-g", `${PACKAGE_NAME}@${version}`];
-    case "other": case "checkout": return undefined;
-  }
-}
-
-export type InstallOutcome =
-  | { readonly kind: "installed" }
-  | { readonly kind: "exit"; readonly code: number; readonly output: readonly string[] }
-  | { readonly kind: "timeout"; readonly ms: number; readonly output: readonly string[] }
-  | { readonly kind: "unavailable"; readonly reason: string }
-  | { readonly kind: "cancelled" };
-
-/**
- * How an install ended, in words a person can act on. A bare exit code hides
- * ENOTEMPTY and EACCES (codex #5015, #21897), so failures carry the package
- * manager's last lines and always the command to run by hand.
- */
-export function installResult(outcome: InstallOutcome, argv: readonly string[], current: string, latest: string): { readonly ok: boolean; readonly text: string } {
-  const manual = `Run it yourself: ${argv.join(" ")}`;
-  const tail = (output: readonly string[]) => output.length ? `\n${output.map(line => `  ${line}`).join("\n")}` : "";
-  switch (outcome.kind) {
-    case "installed": return { ok: true, text: `Updated xeno ${current} → ${latest}. Restart xeno to use it.` };
-    case "exit": return { ok: false, text: `Could not update xeno: ${argv[0]} exited ${outcome.code}.${tail(outcome.output)}\n${manual}` };
-    case "timeout": return { ok: false, text: `Could not update xeno: ${argv[0]} did not finish within ${Math.round(outcome.ms / 1000)}s and was stopped.${tail(outcome.output)}\n${manual}` };
-    case "unavailable": return { ok: false, text: `Could not update xeno: ${outcome.reason}.\n${manual}` };
-    case "cancelled": return { ok: false, text: "xeno update cancelled." };
-  }
-}
-
-/** Two lines: what is new, then the command on its own line so it can be copied whole. */
-export function updateNotice(latest: string, current: string, install: InstallKind): string {
-  const command = upgradeCommand(install);
-  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
- * costs seconds at startup (OpenCode runs up to seven list commands).
- */
-export function installKind(packageRoot: string, hasGit: boolean): InstallKind {
-  const path = packageRoot.replaceAll("\\", "/");
-  if (hasGit || !path.includes("/node_modules/")) return "checkout";
-  if (path.includes("/.bun/install/global/")) return "bun";
-  if (path.includes("/lib/node_modules/") || /\/npm\/node_modules\//i.test(path)) return "npm";
-  return "other";
-}
-
-/** The registry's dist-tags for the package, honouring npm's registry setting. */
-export function distTagsUrl(registry: string | undefined): string {
-  const base = (registry && /^https?:\/\//.test(registry) ? registry : "https://registry.npmjs.org/").replace(/\/+$/, "");
-  return `${base}/-/package/${PACKAGE_NAME.replace("/", "%2f")}/dist-tags`;
-}

package/src/core/version.ts

@@ -1,55 +0,0 @@
-/**
- * Semantic version comparison (semver.org §11), without a dependency. Pure.
- *
- * Used to decide whether a published version is newer than the running one
- * (docs/tasks/feat-update-check.md). Anything that does not parse is not a
- * version, and an unparseable version never produces an update notice.
- */
-
-export interface Version {
-  readonly major: number;
-  readonly minor: number;
-  readonly patch: number;
-  /** Dot-separated pre-release identifiers; empty for a release. */
-  readonly prerelease: readonly (number | string)[];
-}
-
-const PATTERN = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-
-export function parseVersion(text: string): Version | null {
-  const match = PATTERN.exec(text.trim());
-  if (!match) return null;
-  const numbers = [match[1], match[2], match[3]].map(Number);
-  if (numbers.some(n => !Number.isSafeInteger(n))) return null;
-  const prerelease = match[4] ? match[4].split(".").map(part => /^\d+$/.test(part) ? Number(part) : part) : [];
-  return { major: numbers[0]!, minor: numbers[1]!, patch: numbers[2]!, prerelease };
-}
-
-/** -1, 0 or 1, by §11: numbers, then a release outranks its pre-releases, then identifiers left to right. Build metadata is ignored. */
-export function compareVersions(a: Version, b: Version): -1 | 0 | 1 {
-  for (const key of ["major", "minor", "patch"] as const) if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
-  const x = a.prerelease, y = b.prerelease;
-  if (!x.length || !y.length) return x.length === y.length ? 0 : x.length ? -1 : 1;
-  for (let i = 0; i < Math.min(x.length, y.length); i++) {
-    const p = x[i]!, q = y[i]!;
-    if (p === q) continue;
-    if (typeof p === "number" && typeof q === "number") return p < q ? -1 : 1;
-    // Numeric identifiers have lower precedence than alphanumeric ones.
-    if (typeof p === "number") return -1;
-    if (typeof q === "number") return 1;
-    return p < q ? -1 : 1;
-  }
-  return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
-}
-
-/**
- * Whether `latest` should be offered to someone running `current`. Never a
- * downgrade, never something unparseable, and a release is not nudged
- * towards a pre-release (a pre-release user may move to the next release).
- */
-export function isUpgrade(latest: string, current: string): boolean {
-  const next = parseVersion(latest), now = parseVersion(current);
-  if (!next || !now) return false;
-  if (next.prerelease.length && !now.prerelease.length) return false;
-  return compareVersions(next, now) > 0;
-}

package/src/core/web-content.ts

@@ -1,80 +0,0 @@
-/** 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");
-}