@visual-z/xeno 0.3.0 → 0.4.0

package/src/runtime/session-control.ts

@@ -0,0 +1,198 @@
+/** Q24: one controller per live Session, shared by the TUI and structured adapters. */
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { goalView, contextLens, type GoalView, type ContextLens } from "../core/control-view.ts";
+import { DEFAULT_CONTEXT_POLICY } from "../core/context-policy.ts";
+import { userInputData, type UserInput } from "../core/images.ts";
+import type { Phase } from "../core/queue.ts";
+import type { PermissionRequest } from "../core/permissions.ts";
+import type { ExecutionOutcome } from "../core/outcome.ts";
+import type { LogEvent } from "../core/events.ts";
+import { readNodeHistory } from "../store/restore.ts";
+import type { Session, LoopEvent } from "./loop.ts";
+import type { ApprovalChoice } from "./tools.ts";
+
+export type ControlNotice = { method: string; params: { threadId: string; streamId: string; sequence: number; turnId?: string; [key: string]: unknown } };
+export type PendingApproval = { id: string; turnId: string; request: PermissionRequest };
+export type ControlSnapshot = {
+  version: "xeno-control/0.1"; threadId: string; streamId: string; sequence: number; node: number;
+  activeTurnId: string | null; goal: GoalView | null; context: ContextLens;
+  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[];
+};
+
+export class SessionControl {
+  readonly session: Session;
+  readonly threadId: string;
+  readonly streamId = randomUUID();
+  private sequence = 0;
+  private listeners = new Set<(event: ControlNotice) => void>();
+  private active: { id: string; abort: AbortController; queue: UserInput[] } | null = null;
+  private task: Promise<void> | null = null;
+  private approvals = new Map<string, { data: PendingApproval; resolve: (choice: ApprovalChoice) => void }>();
+  private waiting: ControlSnapshot["waiting"] = null;
+  private changing = false;
+  private inputSource: ((phase: Phase) => Promise<UserInput | null>) | undefined;
+
+  constructor(session: Session) {
+    this.session = session;
+    // Same identity rule as provider affinity; no new durable identity store (D8).
+    this.threadId = createHash("sha256").update(resolve(session.config.logDir)).digest("hex");
+    session.subscribeRecords(item => this.emit("item/completed", { item }));
+  }
+  get activeTurnId(): string | null { return this.active?.id ?? null; }
+  get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
+
+  subscribe(listener: (event: ControlNotice) => void): () => void {
+    this.listeners.add(listener); return () => { this.listeners.delete(listener); };
+  }
+  /** The attached editor owns retractable drafts even when an adapter starts the turn. */
+  attachInput(pull: (phase: Phase) => Promise<UserInput | null>): () => void {
+    if (this.inputSource) throw Error("the session already has an attached input owner");
+    this.inputSource = pull;
+    return () => { if (this.inputSource === pull) this.inputSource = undefined; };
+  }
+  private emit(method: string, data: Record<string, unknown> = {}): void {
+    const event: ControlNotice = { method, params: { ...data, threadId: this.threadId, streamId: this.streamId,
+      sequence: ++this.sequence, ...(this.active ? { turnId: this.active.id } : {}) } };
+    for (const listener of this.listeners) {
+      // Observers are outside the evidence owner: mutations and failures cannot alter execution.
+      try { listener(structuredClone(event)); } catch { /* the transport owns delivery errors */ }
+    }
+  }
+  async snapshot(observe = true): Promise<ControlSnapshot> {
+    if (observe && !this.busy) await this.session.acceptanceState();
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    const s = this.session;
+    // Ancestors are sealed. The live segment must share the cursor's publication
+    // boundary: a disk read can finish between append and in-memory publication.
+    const parts = history.nodes.map(part => part.node === node ? { node, events: structuredClone(s.state.events) } : part);
+    const projectedGoal = goalView(parts);
+    const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
+    return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
+      activeTurnId: this.activeTurnId, goal, waiting: this.waiting,
+      approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
+      context: contextLens({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
+        contextWindow: s.provider.config.spec.contextWindow, outputReserve: s.provider.config.maxTokens,
+        ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) }) };
+  }
+  async items(): Promise<{ node: number; event: LogEvent }[]> {
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    return history.nodes.flatMap(part => (part.node === node ? structuredClone(this.session.state.events) : part.events)
+      .map(event => ({ node: part.node, event })));
+  }
+
+  /** Both local and remote turns pass through this iterator; Session remains the execution owner. */
+  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>): AsyncGenerator<LoopEvent> {
+    if (this.busy) throw Error("a turn is already running");
+    const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
+    this.active = active;
+    const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
+    let outcome: ExecutionOutcome | undefined;
+    try {
+      this.emit("turn/started");
+      const steering = async (phase: Phase): Promise<UserInput | null> => {
+        const external = active.queue.splice(0), local = await (pull ?? this.inputSource)?.(phase);
+        if (local) external.push(local);
+        const data = external.map(value => userInputData(value));
+        const text = data.map(value => value.text).join("\n\n"), images = data.flatMap(value => value.images ?? []);
+        return images.length ? { text, images } : text || null;
+      };
+      for await (const event of this.session.send(input, signals, steering, active.id)) {
+        this.emit("turn/event", { event });
+        if (event.kind === "done") outcome = event.outcome;
+        yield event;
+      }
+    } catch (error) {
+      // Raw provider errors may contain credentials. The owner can report a sanitized error separately.
+      this.emit("turn/error", { message: "turn failed; inspect the session outcome" });
+      throw error;
+    } finally {
+      for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+      this.waiting = null;
+      // A thrown provider error also appends an outcome. Clients must be able to discover it.
+      try {
+        if (!outcome) {
+          const state = (await this.snapshot(false)).goal?.state;
+          if (state?.request.event === active.id) outcome = state.execution;
+        }
+      } catch { /* unreadable storage stays unknown, never an invented completion */ }
+      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length });
+      this.active = null;
+    }
+  }
+  start(input: UserInput): string {
+    if (this.busy) throw Error("a turn is already running");
+    this.task = (async () => { for await (const _event of this.send(input)) { /* notices are the client stream */ } })();
+    void this.task.catch(() => {});
+    return this.active!.id;
+  }
+  async whenIdle(): Promise<void> { await this.task; await this.session.whenIdle(); }
+  private current(turnId: string): NonNullable<SessionControl["active"]> {
+    if (!this.active || this.active.id !== turnId) throw Error("stale or unknown turnId");
+    return this.active;
+  }
+  steer(turnId: string, input: UserInput): void {
+    const turn = this.current(turnId);
+    // Assumed ingress bound, not an execution policy. Keep a client from queuing unbounded work.
+    if (turn.queue.length >= 32) throw Error("steering queue is full");
+    turn.queue.push(structuredClone(input));
+    this.emit("turn/steeringQueued", { count: turn.queue.length });
+  }
+  interrupt(turnId: string): void {
+    this.current(turnId).abort.abort();
+    for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+    this.session.cancel();
+  }
+  setWaiting(kind: ControlSnapshot["waiting"]): void {
+    this.waiting = this.approvals.size ? "permission" : kind;
+    this.emit("thread/statusChanged", { waiting: this.waiting });
+  }
+  ask(request: PermissionRequest, present?: (id: string, resolve: (choice: ApprovalChoice) => void) => (() => void)): Promise<ApprovalChoice> {
+    if (!this.active) return Promise.resolve("deny");
+    const data = { id: randomUUID(), turnId: this.active.id, request: structuredClone(request) };
+    return new Promise(resolveChoice => {
+      let close: (() => void) | undefined;
+      const resolveOnce = (choice: ApprovalChoice) => {
+        if (!this.approvals.delete(data.id)) return;
+        close?.(); this.waiting = this.approvals.size ? "permission" : null;
+        this.emit("approval/resolved", { approvalId: data.id }); resolveChoice(choice);
+      };
+      this.approvals.set(data.id, { data, resolve: resolveOnce }); this.waiting = "permission";
+      this.emit("approval/request", { approval: data });
+      if (this.approvals.has(data.id)) {
+        try { close = present?.(data.id, resolveOnce); }
+        catch { resolveOnce("deny"); }
+      }
+    });
+  }
+  respond(turnId: string, id: string, choice: ApprovalChoice): void {
+    this.current(turnId);
+    const approval = this.approvals.get(id);
+    if (!approval || approval.data.turnId !== turnId) throw Error("stale or unknown approvalId");
+    approval.resolve(choice);
+  }
+  denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
+  async accept(requestId: string, criterion: string): Promise<void> {
+    if (this.busy) throw Error("acceptance requires an idle session");
+    this.changing = true;
+    try {
+      const state = await this.session.requestState();
+      if (state?.request.event !== requestId) throw Error("stale or unknown requestId");
+      await this.session.acceptCriterion(criterion);
+      this.emit("thread/statusChanged");
+    } finally { this.changing = false; }
+  }
+}
+
+const controls = new WeakMap<Session, SessionControl>();
+export function sessionControl(session: Session): SessionControl {
+  let control = controls.get(session);
+  if (!control) { control = new SessionControl(session); controls.set(session, control); }
+  return control;
+}

package/src/tui/ui/composer.ts

@@ -16,6 +16,7 @@ import { draftRows, type DraftRows } from "./draft.ts";
 import type { ListItem } from "./list-model.ts";
 
 export interface Completion {
+  readonly kind: "command" | "argument" | "path";
   /** Replace text[start, end) with an item's value. */
   readonly start: number;
   readonly end: number;
@@ -89,8 +90,8 @@ export class Composer {
   setAtoms(spans: (text: string) => readonly DraftAtom[]): void { this.area.atoms = spans; }
   get completing(): boolean { return this.completion !== undefined && this.completion.items.length > 0; }
   /** What the completion list shows (screen draws it). */
-  get completionView(): { readonly items: readonly ListItem[]; readonly selected: number } | undefined {
-    return this.completion ? { items: this.completion.items, selected: this.completionIndex } : undefined;
+  get completionView(): { readonly kind: Completion["kind"]; readonly items: readonly ListItem[]; readonly selected: number } | undefined {
+    return this.completion ? { kind: this.completion.kind, items: this.completion.items, selected: this.completionIndex } : undefined;
   }
   get historyEntries(): readonly string[] { return this.history; }
   get rows(): number { return Math.max(1, this.area.height); }

package/src/tui/ui/control-panel.ts

@@ -0,0 +1,23 @@
+/** View-only data: apps owns the projection and actions, as required by D20. */
+import { clipText } from "./edge.ts";
+
+export type ControlPanelModel = {
+  thread: string; turn: string | null; goal: string; status: string; execution: string; gaps: readonly string[];
+  progress: readonly { label: string; count: number; sources: readonly string[] }[]; checks: readonly string[];
+  context: readonly string[]; omitted: readonly string[]; history: readonly string[];
+};
+export type ControlTab = "goal" | "progress" | "context";
+export type ControlFocus = "messages" | "omitted" | "history";
+
+export function controlPanelLines(model: ControlPanelModel, tab: ControlTab, width: number, focus: ControlFocus = "messages"): string[] {
+  const lines = [`${tab === "goal" ? "●" : "○"} Goal    ${tab === "progress" ? "●" : "○"} Progress    ${tab === "context" ? "●" : "○"} Context Lens`, "",
+    ...(tab === "goal" ? [model.goal, `Goal: ${model.status}`, `Execution: ${model.execution}`, "", ...model.gaps,
+      ...model.checks, "", `Thread ${model.thread}`, `Turn ${model.turn ?? "none"}`]
+      : tab === "progress" ? ["Evidence for this request", ...model.progress.map(item => `${item.label}: ${item.count}`), "",
+        "Counts describe observations, not a completion percentage.", ...model.checks,
+        ...model.progress.flatMap(item => item.sources.map(source => `${item.label}: ${source}`))]
+      : focus === "messages" ? ["Actual model context · ←/→ change lens", ...model.context]
+        : focus === "omitted" ? ["Not replayed as messages · ←/→ change lens", ...(model.omitted.length ? model.omitted : ["No omitted events in this segment."])]
+          : ["Handoff retention and recovery · ←/→ change lens", ...(model.history.length ? model.history : ["No carried history in this segment."])])];
+  return lines.map(line => clipText(line.replace(/[\x00-\x1f\x7f-\x9f]/g, " "), Math.max(1, width)));
+}

package/src/tui/ui/mascot.ts

@@ -61,7 +61,7 @@ export function greetingLines(greeting: Greeting, frame: readonly string[] = MAS
     [art(0), gap, { text: "xeno", role: "text", bold: true }, { text: ` ${greeting.version}`, role: "muted" }],
     [art(1), gap, ...(greeting.model
       ? [{ text: greeting.model, role: "text" as const }, { text: ` · ${greeting.thinking}`, role: "muted" as const }]
-      : [{ text: "No provider connected yet · /login", role: "warning" as const }])],
+      : [{ text: "No provider connected yet · /provider", role: "warning" as const }])],
     [art(2), gap, { text: greeting.workspace, role: "muted" }, ...(greeting.branch ? [{ text: ` ⎇ ${greeting.branch}`, role: "muted" as const }] : [])],
   ];
 }

package/src/tui/ui/status.ts

@@ -30,6 +30,7 @@ export interface StatusModel {
   readonly version: string;
   /** `/name`, else the first prompt; null for a session with neither. */
   readonly title: string | null;
+  readonly goal?: { readonly text: string; readonly status: string; readonly execution: string; readonly observations: number; readonly retries: number };
   readonly workspace: string;
   readonly workspaceShort: string;
   readonly branch: string | null;
@@ -176,6 +177,13 @@ function sidebarBlocks(model: StatusModel, w: number): Block[] {
     ...(model.branch ? [[{ text: "⎇ ", role: "muted" }, { text: model.branch, role: "muted" }] as Line] : []),
   ] });
   const context = model.context;
+  if (model.goal) blocks.push({ list: false, items: [], head: [
+    [{ text: "Goal", role: "text", bold: true }, { text: ` · ${model.goal.status}`, role: model.goal.status === "verified" ? "success" : "warning" }],
+    ...wrap(firstLine(model.goal.text), w, 2).map(text => [{ text, role: "text" }] as Line),
+    [{ text: model.goal.execution, role: "muted" }],
+    [{ text: `${model.goal.observations} observations · ${model.goal.retries} retries`, role: "muted" }],
+    [{ text: "/control · goal, evidence, context", role: "muted" }],
+  ] });
   if (context) {
     const share = contextShare(context), est = context.estimated ? "~" : "";
     const filled = share === undefined ? 0 : Math.max(share > 0 ? 1 : 0, Math.round(share * w));