@visual-z/xeno 0.2.0 → 0.3.0

package/src/apps/ui/status-model.ts

@@ -0,0 +1,68 @@
+/**
+ * Log → status facts for the sidebar and top bar (docs/tasks/refactor-tui-dock-layout.md). Pure.
+ *
+ * Everything here is a projection of what the log already records: file
+ * counts come from the logged input of edit calls that succeeded, handoff
+ * entries from the derived preview (D8), background work from the processes
+ * and branches the log observed. Nothing reads model narration (D11).
+ */
+import type { Handoff } from "../../core/handoff.ts";
+import type { TranscriptItem } from "../../core/transcript.ts";
+import { diffCounts } from "../../tui/ui/tool-card.ts";
+import type { FileStatus, StatusModel } from "../../tui/ui/status.ts";
+
+/** Files the session touched, most recent first. Counts only for files changed solely by edits (a write's prior content is unknown). */
+export function fileChanges(items: readonly TranscriptItem[]): FileStatus[] {
+  const files = new Map<string, { edited: boolean; added: number; removed: number; rewritten: boolean; at: number }>();
+  items.forEach((item, at) => {
+    if (item.kind !== "tool" || !item.result?.ok) return;
+    const input = item.input !== null && typeof item.input === "object" ? item.input as Record<string, unknown> : {};
+    const path = typeof input["path"] === "string" ? input["path"] : undefined;
+    if (!path || !["read", "edit", "write"].includes(item.name)) return;
+    const entry = files.get(path) ?? { edited: false, added: 0, removed: 0, rewritten: false, at };
+    entry.at = at;
+    if (item.name === "edit") { const counts = diffCounts(item.input); entry.edited = true; entry.added += counts.added; entry.removed += counts.removed; }
+    if (item.name === "write") { entry.edited = true; entry.rewritten = true; }
+    files.set(path, entry);
+  });
+  return [...files.entries()].sort((a, b) => b[1].at - a[1].at)
+    .map(([path, entry]) => ({ path, edited: entry.edited, added: entry.rewritten ? 0 : entry.added, removed: entry.rewritten ? 0 : entry.removed }));
+}
+
+export function firstPrompt(items: readonly TranscriptItem[]): string | null {
+  const user = items.find(item => item.kind === "user" && item.text.trim());
+  return user?.kind === "user" ? user.text.trim() : null;
+}
+
+type Derived = Pick<StatusModel, "handoff" | "tasks" | "background">;
+
+/** The parts of a handoff preview the status surfaces show. Each list keeps its most recent entries last. */
+export function handoffStatus(handoff: Handoff): Derived {
+  const background = [
+    ...handoff.branches.filter(branch => branch.background && branch.resolution === null && !branch.handoff_ref).map(branch => `branch ${branch.node} · ${branch.purpose}`),
+    ...(handoff.processes ?? []).filter(process => process.observed === "running").map(process => process.command ?? `process ${process.session}`),
+  ];
+  const tasks = (handoff.state.work_items ?? []).filter(item => item.status === "active" || item.status === "blocked")
+    .map(item => ({ what: item.what, status: item.status === "blocked" ? "blocked" as const : "active" as const }));
+  return {
+    handoff: {
+      verified: handoff.state.completed.map(item => item.what),
+      inFlight: handoff.state.in_flight.map(item => item.what),
+      unverified: handoff.state.unverified_claims.map(item => item.what),
+    },
+    tasks, background,
+  };
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** "20:13" today, "Oct 5 20:13" on another day, in the given local offset. */
+export function sessionClock(iso: string, now: Date, offsetMinutes = -now.getTimezoneOffset()): string | undefined {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return undefined;
+  const local = (ms: number) => new Date(ms + offsetMinutes * 60_000);
+  const t = local(at), n = local(now.getTime());
+  const hhmm = `${String(t.getUTCHours()).padStart(2, "0")}:${String(t.getUTCMinutes()).padStart(2, "0")}`;
+  const sameDay = t.getUTCFullYear() === n.getUTCFullYear() && t.getUTCMonth() === n.getUTCMonth() && t.getUTCDate() === n.getUTCDate();
+  return sameDay ? hhmm : `${MONTHS[t.getUTCMonth()]} ${t.getUTCDate()} ${hhmm}`;
+}

package/src/apps/ui/surface.ts

@@ -0,0 +1,84 @@
+/**
+ * What command and turn code may ask of the interactive UI. shell.ts
+ * depends on this interface only; apps/ui/app.ts implements it. A null Ui
+ * means print/json/line mode, where every branch has a text fallback.
+ */
+import type { ImageRef, UserInput } from "../../core/images.ts";
+import type { Phase, QueueKind } from "../../core/queue.ts";
+import type { PermissionRequest } from "../../core/permissions.ts";
+import type { ApprovalChoice } from "../../runtime/tools.ts";
+import type { LoopEvent } from "../../runtime/loop.ts";
+import type { ExtensionUI } from "../../runtime/extension-ui.ts";
+import type { ClipboardContent } from "../../runtime/clipboard.ts";
+import type { CallbackServer, OAuthCredential, OAuthInteraction } from "../../runtime/oauth.ts";
+
+export interface TurnSurface {
+  pushDelta(kind: "text" | "thinking", text: string): void;
+  discardStream(): void;
+  commitStream(): void;
+  syncTranscript(): Promise<void>;
+  pushProgress?(progress: NonNullable<LoopEvent["progress"]>): void;
+  pullQueued?(phase: Phase): Promise<UserInput | null>;
+}
+
+export interface Ui extends TurnSurface {
+  readonly extensionUi: ExtensionUI;
+  readonly signal: AbortSignal | undefined;
+  readonly queueLength: number;
+  sessionName: string | null;
+  oauthEffects: OAuthEffects;
+  clipboardWriter: (text: string) => boolean | Promise<boolean>;
+  clipboardReader: () => Promise<ClipboardContent>;
+
+  /** Notices and documents in the message stream. */
+  notice(text: string, tone?: "info" | "success" | "warning" | "error"): void;
+  showDocument(title: string, text: string): void;
+  toast(text: string, tone?: "info" | "success" | "warning" | "error"): void;
+  redraw(): void;
+
+  /** A masked single-line form; resolves undefined when cancelled. The value never reaches a renderable. */
+  askSecret(title: string, label: string, hint: string): Promise<string | undefined>;
+  confirm(title: string, message: string): Promise<boolean>;
+  /** A cancellable "waiting" dialog (OAuth browser / device code). Returns a closer. */
+  waiting(title: string, lines: readonly string[], onCancel: () => void, pasteLabel?: string, onPaste?: (value: string) => void): () => void;
+
+  openLogin(method?: "oauth" | "api_key"): void;
+  openLogout(): void;
+  openModel(): void;
+  openScopedModels(): void;
+  openThinking(): void;
+  openSettings(field?: string): void;
+  openResume(): Promise<void>;
+  openFork(): Promise<void>;
+  openTree(): Promise<void>;
+  openResources(): Promise<void>;
+  openTrust(): Promise<void>;
+  openAttachments(): void;
+
+  restoreDraft(text: string, images?: readonly ImageRef[]): void;
+  refreshResources(): Promise<void>;
+  applyConfiguration(): void;
+  followTheme(): void;
+  beginBash(command: string): void;
+  pushBash(chunk: Uint8Array): void;
+  ask(request: PermissionRequest): Promise<ApprovalChoice>;
+
+  runExtensionAction(action: () => void | Promise<void>): void;
+  runExtensionCommand(name: string, args: string): void;
+  runSessionTransition(action: () => Promise<void>): void;
+  deliverExtension(text: string, kind: QueueKind): void;
+  bindExtensionRegistry(): void;
+  requestShutdown(): void;
+  /** Abort the running turn (Esc semantics) without quitting. */
+  interrupt(): void;
+  /** Plain-text snapshot of the current frame (/debug). */
+  snapshot(): { width: number; height: number; lines: string[] };
+}
+
+/** Injectable OAuth side effects (browser, callback server, device flow, fetch). */
+export interface OAuthEffects {
+  fetch: typeof globalThis.fetch;
+  openBrowser(url: string): void;
+  callback(options: { expectedState: string; host: string; port: number; path: string }): Promise<CallbackServer>;
+  device(interaction: OAuthInteraction): Promise<OAuthCredential>;
+}

package/src/apps/ui/theme.ts

@@ -0,0 +1,86 @@
+/**
+ * core Theme + the terminal's reported palette → the view's colours.
+ *
+ * Built-in appearances (dark, light, system/auto) take every colour from the
+ * terminal (tui/ui/ink.ts); their name only says which way to guess when the
+ * terminal does not answer the palette query. A custom theme file is an
+ * explicit choice and is drawn with its own colours; it paints a background
+ * only when it sets one (refactor-tui-terminal-colors).
+ */
+import type { TerminalColors } from "@opentui/core";
+import { isBuiltinTheme, type Theme } from "../../core/theme.ts";
+import { colorsFromInks, rgba, type UiColors } from "../../tui/ui/colors.ts";
+import { isHex, terminalInks, type InkSet, type InkSpec, type TerminalPalette } from "../../tui/ui/ink.ts";
+
+/** OpenTUI's detection result → the 16-slot palette ink.ts expects, or null when incomplete. */
+export function terminalPalette(colors: TerminalColors | null | undefined): TerminalPalette | null {
+  if (!colors) return null;
+  const slots = colors.palette.slice(0, 16).map(hex => normalizeHex(hex));
+  const foreground = normalizeHex(colors.defaultForeground), background = normalizeHex(colors.defaultBackground);
+  if (!foreground || !background || slots.length < 16 || slots.some(slot => !slot)) return null;
+  const hb = normalizeHex(colors.highlightBackground), hf = normalizeHex(colors.highlightForeground);
+  return { foreground, background, slots: slots as string[], ...(hb && hf ? { highlight: { background: hb, foreground: hf } } : {}) };
+}
+
+function normalizeHex(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  const hex = value.startsWith("#") ? value : `#${value}`;
+  return isHex(hex) ? hex.toLowerCase() : undefined;
+}
+
+function hint(theme: Theme): "dark" | "light" { return theme.name === "light" ? "light" : "dark"; }
+
+/** "38;2;r;g;b" / "48;2;r;g;b" → "#rrggbb"; anything else is undefined. */
+export function sgrHex(value: string | undefined): string | undefined {
+  const match = value ? /(?:^|;)[34]8;2;(\d+);(\d+);(\d+)/.exec(value) : null;
+  if (!match) return undefined;
+  return "#" + [match[1], match[2], match[3]].map(n => Math.max(0, Math.min(255, Number(n))).toString(16).padStart(2, "0")).join("");
+}
+
+export function uiColors(theme: Theme, palette: TerminalPalette | null = null): UiColors {
+  const terminal = colorsFromInks(terminalInks(palette, hint(theme)));
+  if (isBuiltinTheme(theme)) return terminal;
+  // A theme file's colours are the user's explicit choice; tokens it leaves
+  // out (or sets to the terminal default) still come from the terminal.
+  const pick = (...tokens: string[]) => { const hex = tokens.map(token => sgrHex(theme.colors[token])).find(Boolean); return hex ? rgba(hex) : undefined; };
+  return {
+    background: pick("background") ?? terminal.background,
+    text: pick("text") ?? terminal.text,
+    muted: pick("muted", "toolOutput") ?? terminal.muted,
+    edge: pick("border", "borderMuted") ?? terminal.edge,
+    line: pick("borderMuted", "border") ?? terminal.line,
+    accent: pick("accent", "mdLink") ?? terminal.accent,
+    success: pick("success", "toolDiffAdded") ?? terminal.success,
+    error: pick("error", "toolDiffRemoved") ?? terminal.error,
+    warning: pick("warning") ?? terminal.warning,
+    reasoning: pick("thinkingText") ?? terminal.reasoning,
+    code: pick("mdCode") ?? terminal.code,
+    selectionBg: pick("selectedBg") ?? terminal.selectionBg,
+    selectionFg: terminal.selectionFg,
+  };
+}
+
+/**
+ * SGR tokens for the ANSI renderers (tool details, diffs, code highlighting)
+ * from the same terminal-derived inks, so text drawn through ANSI strings
+ * matches the view. Custom themes keep their own tokens.
+ */
+export function styleTokens(theme: Theme, palette: TerminalPalette | null): Readonly<Record<string, string>> {
+  if (!isBuiltinTheme(theme)) return theme.colors;
+  const inks: InkSet = terminalInks(palette, hint(theme));
+  const sgr = (spec: InkSpec): string => spec.kind === "default" ? "" : spec.kind === "index"
+    ? String(spec.index < 8 ? 30 + spec.index : 90 + spec.index - 8)
+    : `38;2;${[1, 3, 5].map(i => Number.parseInt(spec.hex.slice(i, i + 2), 16)).join(";")}`;
+  const muted = sgr(inks.muted);
+  return {
+    ...theme.colors,
+    text: "", prompt: "", toolTitle: "",
+    muted, dim: muted, status: muted, toolOutput: muted, thinkingOff: muted, syntaxComment: muted,
+    error: sgr(inks.error), toolDiffRemoved: sgr(inks.error), toolDiffAdded: sgr(inks.success), success: sgr(inks.success),
+    warning: sgr(inks.warning), syntaxNumber: sgr(inks.warning),
+    accent: sgr(inks.accent), mdHeading: sgr(inks.accent), mdLink: sgr(inks.accent), syntaxFunction: sgr(inks.accent),
+    mdCode: sgr(inks.code), syntaxString: sgr(inks.success),
+    thinkingText: sgr(inks.reasoning), syntaxKeyword: sgr(inks.reasoning),
+    border: sgr(inks.line), borderMuted: sgr(inks.line),
+  };
+}

package/src/core/acceptance.ts

@@ -0,0 +1,107 @@
+/** O.11: declared criteria, command evidence and human acceptance are separate. */
+import type { LogEvent } from "./events.ts";
+import type { Evidence } from "./handoff.ts";
+import { evidenceStale } from "./evidence.ts";
+import { changedPaths } from "./checkpoints.ts";
+import { parseRuntimeTarget, type RuntimeTarget, type TargetAcceptance } from "./runtime-target.ts";
+
+export type AcceptanceCriterion = { id: string; description: string } &
+  ({ kind: "command"; command: string } | { kind: "human"; target?: string });
+export type AcceptanceContract = { version: 1; id: string; scope?: "request" | "changes"; criteria: AcceptanceCriterion[];
+  source?: { path: string; sha256: string }; targets?: RuntimeTarget[] };
+export type AcceptanceState = {
+  contract_id: string; contract_event: string; request: string; scope: "request" | "changes"; changed: boolean;
+  criteria: (AcceptanceCriterion & { status: "not_run" | "pass" | "fail" | "stale" | "awaiting_human" | "accepted"; evidence?: Evidence; accepted_event?: string; accepted_binding?: string })[];
+  targets?: TargetAcceptance[];
+  status: "needs_work" | "awaiting_human" | "verified" | "not_applicable";
+};
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const label = (value: unknown, max: number) => typeof value === "string" && value.trim().length > 0 && value.length <= max;
+
+export function parseAcceptanceContract(value: unknown): AcceptanceContract {
+  if (!record(value) || value["version"] !== 1 || !label(value["id"], 80) ||
+      (value["scope"] !== undefined && value["scope"] !== "request" && value["scope"] !== "changes") ||
+      !Array.isArray(value["criteria"]) || value["criteria"].length < 1 || value["criteria"].length > 20) throw new Error("invalid acceptance contract v1");
+  if (Object.keys(value).some(key => !["version", "id", "scope", "criteria", "source", "targets"].includes(key))) throw new Error("unsupported acceptance contract field");
+  const source = value["source"];
+  if (source !== undefined && (!record(source) || !label(source["path"], 4096) || typeof source["sha256"] !== "string" || !/^[a-f0-9]{64}$/.test(source["sha256"]))) throw new Error("invalid acceptance source");
+  const criteria: AcceptanceCriterion[] = value["criteria"].map((item: unknown) => {
+    if (!record(item) || !label(item["id"], 80) || !label(item["description"], 300)) throw new Error("invalid acceptance criterion");
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/.test(String(item["id"])) || Object.keys(item).some(key => !["id", "description", "kind", "command", "target"].includes(key))) throw new Error("unsupported acceptance criterion field or ID");
+    const fields = { id: String(item["id"]), description: String(item["description"]) };
+    if (item["kind"] === "human" && item["command"] === undefined && (item["target"] === undefined || label(item["target"], 80))) return { ...fields, kind: "human", ...(item["target"] ? { target: String(item["target"]) } : {}) };
+    if (item["kind"] === "command" && item["target"] === undefined && label(item["command"], 500)) return { ...fields, kind: "command", command: String(item["command"]) };
+    throw new Error("acceptance criterion must declare a command or human decision");
+  });
+  if (new Set(criteria.map(item => item.id)).size !== criteria.length) throw new Error("duplicate acceptance criterion IDs");
+  const declarations = value["targets"];
+  if (declarations !== undefined && (!Array.isArray(declarations) || declarations.length < 1 || declarations.length > 8)) throw Error("targets requires 1..8 declared runtimes");
+  const targets = Array.isArray(declarations) ? declarations.map(parseRuntimeTarget) : undefined;
+  if (targets && (new Set(targets.map(target => target.id)).size !== targets.length || targets.some(target =>
+    !criteria.some(item => item.id === target.build && item.kind === "command") || !criteria.some(item => item.kind === "human" && item.target === target.id)))) throw Error("targets require a build condition and a bound human condition");
+  if (criteria.some(item => item.kind === "human" && item.target && !targets?.some(target => target.id === item.target))) throw Error("unknown human acceptance target");
+  return { version: 1, id: String(value["id"]), criteria,
+    ...(targets ? { targets } : {}),
+    ...(record(source) ? { source: { path: String(source["path"]), sha256: String(source["sha256"]) } } : {}),
+    ...(value["scope"] ? { scope: value["scope"] as "request" | "changes" } : {}) };
+}
+
+export function deriveAcceptance(previous: AcceptanceState | undefined, events: readonly LogEvent[]): AcceptanceState | undefined {
+  let state = previous ? { ...previous, criteria: previous.criteria.map(item => ({ ...item })), ...(previous.targets ? { targets: previous.targets.map(target => ({ ...target })) } : {}) } : undefined;
+  for (const event of events) {
+    if (event.t === "acceptance_contract") {
+      state = { contract_id: event.contract.id, contract_event: event.id, request: event.request, scope: event.contract.scope ?? "request", changed: false,
+        criteria: event.contract.criteria.map(item => ({ ...item, status: item.kind === "human" ? "awaiting_human" : "not_run" })), status: "needs_work" };
+      if (event.contract.targets) state.targets = event.contract.targets.map(target => ({ id: target.id, build: target.build, status: "not_run" }));
+      continue;
+    }
+    if (!state) continue;
+    const mutation = event.t === "tool_result" && event.effect?.kind === "edit" && event.effect.sha256_before !== event.effect.sha256_after ||
+      event.t === "snapshot" && Object.keys(event.added).length + Object.keys(event.changed).length + event.removed.length > 0 ||
+      event.t === "checkpoint" && event.phase === "applied" && changedPaths(event.changes).length > 0 ||
+      event.t === "workspace_observation" && event.changed;
+    if (mutation) { state.changed = true; for (const target of state.targets ?? []) target.status = "stale"; }
+    if (event.t === "target_observation" && event.observation.request === state.request && event.observation.contract_event === state.contract_event) {
+      const target = state.targets?.find(item => item.id === event.observation.target), receipt = event.observation;
+      if (target) {
+        const build = state.criteria.find(item => item.id === target.build);
+        target.status = receipt.state === "ready" && (build?.status !== "pass" || build.evidence?.event_id !== receipt.build?.event) ? "stale" : receipt.state;
+        target.observation = event.id; target.reason = receipt.reason;
+        if (receipt.build) target.build_event = receipt.build.event;
+        if (receipt.instance) { target.binding = receipt.instance.id; target.session = receipt.instance.session; target.pid = receipt.instance.pid; target.entry = receipt.instance.entry.path; }
+        else { delete target.binding; delete target.session; delete target.pid; delete target.entry; }
+        if (receipt.port !== undefined) target.port = receipt.port;
+      }
+    }
+    for (const target of state.targets ?? []) if (event.t === "process_exit" && event.session === target.session ||
+      event.t === "tool_result" && record(event.data) && event.data["session_id"] === target.session && event.data["running"] === false) target.status = "stale";
+    for (const item of state.criteria) {
+      if (item.evidence && evidenceStale([event], item.evidence, item.status === "stale")) item.status = "stale";
+      if (mutation && item.kind === "human" && item.status === "accepted") { item.status = "awaiting_human"; delete item.accepted_event; delete item.accepted_binding; }
+      if (item.kind === "command" && event.t === "tool_result" && event.effect?.kind === "command" && event.effect.cmd === item.command) {
+        item.status = event.effect.exit === 0 && event.ok ? event.effect.workspace_observed === false ? "stale" : "pass" : "fail";
+        item.evidence = { command: event.effect.cmd, exit: event.effect.exit, event_id: event.id, at: event.at,
+          ...(event.effect.workspace_scope ? { workspace_scope: event.effect.workspace_scope } : {}),
+          ...(event.effect.workspace_sha256 ? { workspace_sha256: event.effect.workspace_sha256 } : {}) };
+        for (const target of state.targets ?? []) if (target.build === item.id && target.build_event !== event.id) target.status = "stale";
+      }
+      if (item.kind === "human" && event.t === "acceptance_decision" && event.request === state.request &&
+          event.contract_id === state.contract_id && event.criterion === item.id && event.actor === "user") {
+        const target = item.target ? state.targets?.find(target => target.id === item.target) : undefined;
+        if (!item.target || target?.status === "ready" && target.binding === event.target_binding && target.observation === event.target_observation) {
+          item.status = "accepted"; item.accepted_event = event.id;
+          if (event.target_binding) item.accepted_binding = event.target_binding;
+        }
+      }
+    }
+    for (const target of state.targets ?? []) if (target.status === "ready" && !state.criteria.some(item => item.id === target.build && item.status === "pass" && item.evidence?.event_id === target.build_event)) target.status = "stale";
+    for (const item of state.criteria) if (item.kind === "human" && item.target && item.status === "accepted") {
+      const target = state.targets?.find(target => target.id === item.target);
+      if (target?.status !== "ready" || target.binding !== item.accepted_binding) { item.status = "awaiting_human"; delete item.accepted_event; delete item.accepted_binding; }
+    }
+  }
+  if (state) state.status = state.scope === "changes" && !state.changed ? "not_applicable" :
+    state.criteria.some(item => item.kind === "command" && item.status !== "pass") || state.targets?.some(target => target.status !== "ready") ? "needs_work" :
+    state.criteria.some(item => item.kind === "human" && item.status !== "accepted") ? "awaiting_human" : "verified";
+  return state;
+}