@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/clipboard.ts

@@ -1,6 +1,17 @@
-/** Pi's files → image → text precedence, with native-helper and OS-command fallbacks (MIT, 02eed88). */
+/**
+ * Pi's files → image → text precedence (MIT, 02eed88) over the platform's own
+ * clipboard commands. The optional native helper went with the vendored TUI
+ * (D20); a caller may still inject one.
+ */
 import { fileURLToPath } from "node:url";
-import { getNativeClipboard, type NativeClipboard } from "../vendor/pi-tui/native-platform.ts";
+
+export interface NativeClipboard {
+  setText?(text: string): Promise<void>;
+  getText?(): Promise<string | null | undefined>;
+  getImage?(): Promise<Uint8Array | null | undefined>;
+  getFilePaths?(): Promise<string[] | null | undefined>;
+}
+function getNativeClipboard(): NativeClipboard | null { return null; }
 import { runClipboardCommand } from "../vendor/pi-rich/clipboard-command.ts";
 
 export type ClipboardContent = { files: string[] } | { image: Uint8Array } | { text: string } | null;
@@ -104,9 +115,9 @@ export async function readClipboard(options: ClipboardOptions = {}): Promise<Cli
       return bytes.length ? { text: bytes.toString("utf8") } : null;
     }
   }
-  const image = await native?.getImage();
+  const image = await native?.getImage?.();
   if (image?.length) return { image };
-  const text = await native?.getText();
+  const text = await native?.getText?.();
   if (text !== undefined) return text ? { text } : null;
   const fallback = env["TERMUX_VERSION"] ? await run("termux-clipboard-get", []) : platform === "darwin" ? await run("pbpaste", []) : undefined;
   if (fallback === undefined) throw new Error("Clipboard unavailable for this terminal session");

package/src/runtime/command-artifacts.ts

@@ -0,0 +1,64 @@
+/** R8: one owner observes an admitted command once, including after a managed call yields. */
+import { hostname } from "node:os";
+import { resolve, join } from "node:path";
+import { artifactChange, commandArtifactState, parseCommandArtifactPlan, COMMAND_ARTIFACT_SCOPE, type CommandArtifactReceipt } from "../core/command-artifacts.ts";
+import { observeArtifactInputs, observeArtifactFiles, artifactExclusions, archiveCommandArtifacts } from "../store/command-artifacts.ts";
+import type { ToolContext } from "./tools.ts";
+
+export type ArtifactCommandEnd = { exit: number; stopped?: "cancelled" | "timeout"; capture?: "complete" | "partial"; cleanup?: unknown };
+export type CommandArtifactObserver = {
+  pending: CommandArtifactReceipt;
+  finish(end: ArtifactCommandEnd): Promise<CommandArtifactReceipt>;
+};
+
+/** Syntactic validation precedes admission; no preflight disk probing is smuggled through a denied tool. */
+export function prepareArtifactArguments(input: unknown): unknown {
+  if (input === null || typeof input !== "object" || Array.isArray(input) || !("artifacts" in input)) return input;
+  return { ...input, artifacts: parseCommandArtifactPlan(input.artifacts) };
+}
+
+export async function beginCommandArtifacts(ctx: Pick<ToolContext, "root" | "hostId" | "ownedStatePaths" | "outputStore" | "signal">,
+  command: string, cwd: string, requested: unknown): Promise<CommandArtifactObserver | undefined> {
+  if (requested === undefined) return undefined;
+  const plan = parseCommandArtifactPlan(requested), exclusions = artifactExclusions(ctx.root, plan,
+    [...(ctx.ownedStatePaths ?? []), ctx.outputStore ?? join(ctx.root, ".xeno", "observations")]);
+  const beforeInputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
+  const before = await observeArtifactFiles(ctx.root, plan.paths, ctx.signal);
+  const pending: CommandArtifactReceipt = {
+    kind: "command_artifacts", version: 1, state: "pending", plan,
+    source: { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(cwd), runtime: `bun/${Bun.version}` },
+    command, exit: null, started_at: new Date().toISOString(), observed_at: null,
+    inputs: { scope: COMMAND_ARTIFACT_SCOPE, exclusions, before: beforeInputs.sha256, after: null },
+    outputs: [], reasons: beforeInputs.reason ? [beforeInputs.reason] : [],
+  };
+  let completed: Promise<CommandArtifactReceipt> | undefined;
+  return { pending, finish(end) {
+    completed ??= (async () => {
+      // Observation failures retain the actual exit. Never retry a post-exit read against later files.
+      const reasons = [...pending.reasons];
+      if (end.exit !== 0) reasons.push("command exited unsuccessfully");
+      if (end.stopped) reasons.push(`command ${end.stopped}`);
+      if (end.capture === "partial") reasons.push("command output capture is partial");
+      if (end.cleanup) reasons.push("command cleanup is unconfirmed");
+      const after = await observeArtifactFiles(ctx.root, plan.paths, ctx.signal);
+      const afterInputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
+      if (afterInputs.reason) reasons.push(afterInputs.reason);
+      const receipt: CommandArtifactReceipt = { ...pending, exit: end.exit, observed_at: new Date().toISOString(),
+        inputs: { ...pending.inputs, after: afterInputs.sha256 },
+        outputs: plan.paths.map((path, i) => ({ path, before: before[i]!, after: after[i]!, change: artifactChange(before[i]!, after[i]!) })), reasons };
+      receipt.state = commandArtifactState(receipt);
+      try { receipt.manifest = await archiveCommandArtifacts(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), receipt); }
+      catch { receipt.reasons.push("artifact observation archive unavailable"); receipt.state = commandArtifactState(receipt); }
+      return receipt;
+    })();
+    return completed;
+  } };
+}
+
+export function commandArtifactSummary(receipt: CommandArtifactReceipt | undefined): string {
+  if (!receipt) return "";
+  const changes = ["created", "modified", "unchanged", "unknown"].map(change => `${change}=${receipt.outputs.filter(output => output.change === change).length}`).join(", ");
+  return `\n[artifacts ${receipt.state}; ${changes}; reasons=${receipt.reasons.length}; ` +
+    (receipt.manifest ? `history artifact=${receipt.manifest.sha256}; ` : "") +
+    "command association only, not build causality or runtime acceptance]";
+}

package/src/runtime/control-connection.ts

@@ -0,0 +1,104 @@
+/** Connection lifecycle is transient; durable state belongs exclusively to Session's log (Q24). */
+import { CONTROL_SCHEMA, parseControlRequest, ControlProtocolError, type RpcId } from "../core/control-protocol.ts";
+import { selectLens, type LensFocus } from "../core/control-view.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import type { SessionControl } from "./session-control.ts";
+import type { ApprovalChoice } from "./tools.ts";
+
+export type RpcOutput = { id: RpcId | null; result?: unknown; error?: { code: number; message: string } } | { method: string; params: unknown };
+
+export class ControlConnection {
+  private readonly control: () => SessionControl;
+  private readonly write: (output: RpcOutput) => void;
+  private initialized = false;
+  private ready = false;
+  private subscribed = false;
+  private closed = false;
+  private attached: SessionControl | undefined;
+  private stop: (() => void) | undefined;
+  private readonly denyOnClose: boolean;
+
+  constructor(control: () => SessionControl, write: (output: RpcOutput) => void, options: { denyOnClose?: boolean } = {}) {
+    this.control = control; this.write = write; this.denyOnClose = options.denyOnClose ?? false;
+  }
+  private attach(): SessionControl {
+    const control = this.control();
+    if (this.attached !== control) {
+      this.stop?.(); this.attached = control;
+      this.stop = control.subscribe(notice => { if (!this.closed && this.ready && this.subscribed) this.write(notice); });
+    }
+    return control;
+  }
+  async receive(value: unknown): Promise<void> {
+    if (this.closed) return;
+    let id: RpcId | null = null;
+    try {
+      if (typeof value === "object" && value !== null && "id" in value &&
+        (typeof value.id === "string" && value.id.length <= 128 || typeof value.id === "number" && Number.isSafeInteger(value.id))) id = value.id;
+      const request = parseControlRequest(value), params = request.params;
+      const control = this.attach();
+      if (request.method === "initialize") {
+        if (this.initialized) throw new ControlProtocolError(-32000, "already initialized");
+        this.initialized = true;
+        this.write({ id, result: { protocol: CONTROL_SCHEMA.protocol, experimental: true, threadId: control.threadId, streamId: control.streamId,
+          capabilities: { turns: true, steering: true, approvals: true, contextLens: true, snapshotResync: true, durableEventReplay: "item/list", adaptiveExecution: false } } });
+        return;
+      }
+      if (!this.initialized) throw new ControlProtocolError(-32000, "not initialized");
+      if (request.method === "initialized") { if (this.ready) throw new ControlProtocolError(-32000, "already ready"); this.ready = true; return; }
+      if (!this.ready) throw new ControlProtocolError(-32000, "send initialized before using the session");
+      if (params["threadId"] !== control.threadId) throw new ControlProtocolError(-32000, "stale or unknown threadId; initialize a new connection after changing sessions");
+      let result: unknown;
+      switch (request.method) {
+        case "thread/read": result = await control.snapshot(); break;
+        case "thread/subscribe": {
+          this.subscribed = true;
+          const snapshot = await control.snapshot();
+          const after = params["after"] as { streamId: string; sequence: number } | undefined;
+          result = { snapshot, resyncRequired: after !== undefined && (after.streamId !== snapshot.streamId || after.sequence !== snapshot.sequence) };
+          break;
+        }
+        case "turn/start": result = { turnId: control.start(String(params["input"])) }; break;
+        case "turn/steer": control.steer(String(params["turnId"]), String(params["input"])); result = { queued: true }; break;
+        case "turn/interrupt": control.interrupt(String(params["turnId"])); result = { interruptRequested: true }; break;
+        case "approval/respond": control.respond(String(params["turnId"]), String(params["approvalId"]), params["choice"] as ApprovalChoice); result = { accepted: true }; break;
+        case "acceptance/accept": await control.accept(String(params["requestId"]), String(params["criterionId"])); result = { accepted: true }; break;
+        case "context/read": {
+          const snapshot = await control.snapshot(false), all = selectLens(snapshot.context, params["focus"] as LensFocus);
+          const offset = Number(params["offset"] ?? 0), limit = Number(params["limit"] ?? 50);
+          result = { node: snapshot.node, streamId: snapshot.streamId, sequence: snapshot.sequence, focus: params["focus"], total: all.length,
+            entries: all.slice(offset, offset + limit), nextOffset: offset + limit < all.length ? offset + limit : null,
+            components: snapshot.context.components, used: snapshot.context.used, countKind: snapshot.context.countKind };
+          break;
+        }
+        case "item/list": {
+          const all = await control.items(), after = params["after"] as { node: number; event: string } | undefined;
+          const index = after ? all.findIndex(item => item.node === after.node && item.event.id === after.event) : -1;
+          if (after && index < 0) throw Error("cursor is not on the current path; refresh the snapshot");
+          const entries = all.slice(index + 1, index + 1 + Number(params["limit"] ?? 50));
+          const last = entries.at(-1);
+          result = { items: entries.map(item => ({ node: item.node, id: item.event.id, type: item.event.t })),
+            nextCursor: last && index + 1 + entries.length < all.length ? { node: last.node, event: last.event.id } : null };
+          break;
+        }
+        case "item/read": {
+          const item = (await control.items()).find(item => item.node === params["node"] && item.event.id === params["event"]);
+          if (!item) throw Error("item is not on the current path");
+          result = item; break;
+        }
+        default: assertNever(request.method, "control request");
+      }
+      if (!this.closed) this.write({ id, result });
+    } catch (error) {
+      if (!this.closed) this.write({ id, error: { code: error instanceof ControlProtocolError ? error.code : -32000,
+        message: error instanceof Error ? error.message.slice(0, 512) : "control request failed" } });
+    }
+  }
+  close(): void {
+    this.closed = true; this.stop?.();
+    if (this.denyOnClose && this.attached) {
+      this.attached.denyApprovals();
+      if (this.attached.activeTurnId) this.attached.interrupt(this.attached.activeTurnId);
+    }
+  }
+}

package/src/runtime/environment-tools.ts

@@ -0,0 +1,60 @@
+/** R6: observe through the same shell and process owner; never infer versions from the host PATH. */
+import { createHash } from "node:crypto";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { ENVIRONMENT_OUTPUT_BYTES, ENVIRONMENT_PARSE_BYTES, ENVIRONMENT_TIMEOUT_MS, ENVIRONMENT_TTL_MS,
+  environmentCapability, parseEnvironmentFrame, type EnvironmentProbe, type EnvironmentReceipt, type EnvironmentSource } from "../core/environment.ts";
+import { executionOutcome } from "../core/outcome.ts";
+import { canonicalValue } from "../core/continuation.ts";
+import { failureDiagnostic } from "../core/tool-failure.ts";
+import { observeCommand } from "../store/command.ts";
+import type { ToolContext, ToolResult } from "./tools.ts";
+
+const hash = (text: string) => createHash("sha256").update(text).digest("hex");
+/** Hash only resolution-related inherited inputs; never expose the full environment or its credentials. */
+export function environmentSource(ctx: Pick<ToolContext, "root" | "hostId">, cwd: string): EnvironmentSource {
+  const keys = ["PATH", "HOME", "SHELL", "LANG", "BASH_ENV", "PYTHONHOME", "PYTHONPATH", "PYENV_VERSION", "VIRTUAL_ENV", "CONDA_PREFIX", "NVM_BIN"];
+  return { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(cwd),
+    runtime: `bun/${Bun.version};${process.platform}/${process.arch};${process.execPath}`,
+    inherited_sha256: hash(canonicalValue(Object.fromEntries(keys.map(key => [key, process.env[key] ?? null])))) };
+}
+
+export async function observeEnvironment(ctx: ToolContext, cwd: string, program: string, probe: EnvironmentProbe, command: string): Promise<ToolResult> {
+  const budget = new AbortController();
+  const signal = ctx.signal ? AbortSignal.any([ctx.signal, budget.signal]) : budget.signal;
+  let outputBytes = 0;
+  const source = environmentSource(ctx, cwd);
+  const captured = await observeCommand({ command, cwd, cleanupOnExit: true, outputLimitBytes: ENVIRONMENT_OUTPUT_BYTES,
+    outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"),
+    maxOutputBytes: ENVIRONMENT_PARSE_BYTES, timeoutMs: Math.min(ENVIRONMENT_TIMEOUT_MS, ctx.timeoutMs, ctx.maxTimeoutMs ?? Infinity), signal,
+    onOutput: chunk => {
+      outputBytes += chunk.byteLength;
+      if (outputBytes > ENVIRONMENT_OUTPUT_BYTES) budget.abort();
+      ctx.onOutput?.(chunk);
+    },
+  });
+  const outputLimited = budget.signal.aborted;
+  const parseLimited = captured.ref.bytes > ENVIRONMENT_PARSE_BYTES;
+  const frame = parseEnvironmentFrame(new TextDecoder().decode(captured.head), program, probe);
+  const capability = captured.cleanup ? { state: "unknown" as const, reported_version: null, reason: captured.cleanup.message } : environmentCapability(frame, captured.exit, { complete: captured.capture === "complete",
+    ...(captured.stopped ? { stopped: captured.stopped } : {}),
+    ...(outputLimited ? { limited: "output" } : parseLimited ? { limited: "parse" } : {}) });
+  const observedAt = Date.now();
+  const receipt: EnvironmentReceipt = { kind: "environment", version: 1, query: { program, probe }, source,
+    observed_at: observedAt, expires_at: observedAt + ENVIRONMENT_TTL_MS, ...capability,
+    shell: frame ? { executable: frame.shell, version: frame.shell_version, cwd: frame.cwd, path_sha256: hash(frame.path) } : null,
+    resolution: frame ? { kind: frame.kind, executable: frame.executable } : null,
+    evidence: { output: captured.ref, exit: captured.exit, complete: captured.capture === "complete" } };
+  const status = outputLimited ? "tool_failed" : captured.stopped ?? (capability.state === "observed" ? "tool_completed" : "tool_failed");
+  const code = outputLimited ? "execution_failed" : captured.stopped ?? (capability.state === "missing" ? "environment_missing" : "execution_failed");
+  const text = JSON.stringify(receipt);
+  const bytes = new TextEncoder().encode(text);
+  // Raw output is the primary artifact. Structured data is separately preserved by the Session broker.
+  const content = bytes.length <= ctx.maxOutputBytes ? text :
+    `environment ${receipt.state}; exit ${captured.exit}; full receipt in data; original output: ${captured.ref.sha256}`;
+  return { ok: capability.state === "observed", content, content_ref: captured.ref, data: receipt,
+    ...(captured.cleanup ? { warnings: [captured.cleanup] } : {}),
+    observation_sha256: hash(canonicalValue({ query: receipt.query, source, ...capability, shell: receipt.shell, resolution: receipt.resolution, evidence: receipt.evidence })),
+    effect: { kind: "command", cmd: command, exit: captured.exit }, outcome: executionOutcome(status),
+    ...(capability.state === "observed" ? {} : { diagnostic: failureDiagnostic(code, capability.reason ?? "capability unconfirmed", { execution: "started", effects: "possible" }) }) };
+}

package/src/runtime/evidence-notes.ts

@@ -5,14 +5,16 @@ import { historyEntries } from "../core/history-query.ts";
 import { observedVersion, resourceKey } from "../core/evidence-links.ts";
 import { scopedWorkId } from "../core/work-state.ts";
 import { readNodeHistory } from "../store/restore.ts";
+import { failureDiagnostic, NOT_STARTED, READ_ATTEMPTED } from "../core/tool-failure.ts";
 import type { ToolResult } from "./tools.ts";
 
 export async function resolveEvidenceNote(logDir: string, node: number, namespace: string, current: Handoff, event: EvidenceLinkEvent): Promise<{ event?: EvidenceLinkEvent; result: ToolResult }> {
   const work = scopedWorkId(namespace, event.work, current.state.work_items ?? []);
-  const fail = (message: string) => ({ result: { ok: false, content: message } });
+  const fail = (message: string, attempted = false) => ({ result: { ok: false, content: message, data: { recorded: false },
+    diagnostic: failureDiagnostic(attempted ? "execution_failed" : "invalid_input", message, attempted ? READ_ATTEMPTED : NOT_STARTED) } });
   if (!current.state.work_items?.some(item => item.id === work)) return fail("pin requires an existing work item");
   const history = await readNodeHistory(logDir, node);
-  if (!history.ok) return fail(history.error);
+  if (!history.ok) return fail(history.error, true);
   const entries = historyEntries(history.nodes);
   const source = entries.find(entry => entry.event === event.source && entry.kind === "tool_result");
   if (!source) return fail("pin source must be an original tool observation in the active ancestry");