@visual-z/xeno 0.1.3 → 0.2.0

package/src/runtime/provider-request.ts

@@ -0,0 +1,73 @@
+import { providerEnvironment, resolveKeyValue, type ResolveEffects } from "./auth.ts";
+import { providerAccess } from "./provider-access.ts";
+import type { ModelSpec } from "./model.ts";
+import { XENO_VERSION } from "./oauth.ts";
+
+const SDK_IDENTITY_HEADERS = ["x-app", "editor-version", "editor-plugin-version", "copilot-integration-id", "http-referer", "x-title"];
+
+/** D18/D16: a protocol SDK may not silently identify xeno as a different product. */
+function clientIdentity(headers: Headers): void {
+  headers.set("User-Agent", `xeno/${XENO_VERSION}`);
+  for (const name of SDK_IDENTITY_HEADERS) headers.delete(name);
+  if (headers.has("originator")) headers.set("originator", "xeno");
+  const beta = headers.get("anthropic-beta");
+  if (beta) headers.set("anthropic-beta", beta.split(",").filter(value => !value.trim().startsWith("claude-code-")).join(","));
+}
+
+export function requestEffects(): ResolveEffects {
+  return { env: name => process.env[name], run: command => {
+    const result = Bun.spawnSync(["bash", "-lc", command]);
+    if (result.exitCode !== 0) throw new Error("credential command failed");
+    return new TextDecoder().decode(result.stdout);
+  } };
+}
+
+export function providerRequest(spec: ModelSpec, key: string, effects: ResolveEffects = requestEffects(), fetchImpl: typeof fetch = globalThis.fetch, oauth = false): {
+  baseUrl: string; env: Record<string, string>; headers: Record<string, string | null>; fetch: typeof fetch;
+  options: Record<string, unknown>; body: Record<string, unknown>; key?: string;
+} {
+  const access = providerAccess(spec);
+  if (access.invalid) throw new Error(access.invalid);
+  const scoped = providerEnvironment(spec, effects);
+  const env = scoped.env;
+  const resolve = (value: string, field: string) => {
+    const resolved = resolveKeyValue(value, scoped.effects);
+    if (!resolved.ok) throw new Error(`${spec.provider} ${field}: could not resolve configured value`);
+    return resolved.key;
+  };
+  let baseUrl = spec.baseUrl ?? (spec.api === "anthropic-messages" ? "https://api.anthropic.com" : "");
+  if (baseUrl) baseUrl = resolve(baseUrl, "baseUrl");
+  if (baseUrl && !/^https?:\/\//.test(baseUrl)) throw new Error(`${spec.provider} baseUrl must use http or https`);
+  const headers: Record<string, string | null> = { ...spec.defaultHeaders };
+  for (const [name, value] of Object.entries(access.headers ?? {})) headers[name] = value === null ? null : resolve(value, `headers.${name}`);
+  const anthropicOAuth = spec.api === "anthropic-messages" && spec.provider !== "github-copilot" && (oauth || key.includes("sk-ant-oat"));
+  const noAutomaticAuth = access.auth === false || access.authHeader === false || typeof access.authHeader === "string" || anthropicOAuth;
+  if (noAutomaticAuth && (spec.api === "google-generative-ai" || spec.api === "google-vertex")) {
+    throw new Error(`${spec.api} owns API-key authentication; use apiKey or an OpenAI-compatible local endpoint`);
+  }
+  if (noAutomaticAuth && spec.api === "bedrock-converse-stream") env["AWS_BEDROCK_SKIP_AUTH"] = "1";
+  if (typeof access.authHeader === "string") headers[access.authHeader] = key;
+  if (anthropicOAuth && access.auth !== false && access.authHeader !== false) {
+    headers["authorization"] = `Bearer ${key}`;
+    headers["anthropic-beta"] = "oauth-2025-04-20";
+  }
+  // Apply the same identity to native SDKs which own their HTTP stack.
+  const identity = new Headers();
+  for (const [name, value] of Object.entries(headers)) if (value !== null) identity.set(name, value);
+  clientIdentity(identity);
+  for (const name of Object.keys(headers)) if (!identity.has(name)) headers[name] = null;
+  identity.forEach((value, name) => { headers[name] = value; });
+  delete headers["user-agent"];
+  headers["User-Agent"] = `xeno/${XENO_VERSION}`;
+  // SDKs still require a key to construct local clients. The placeholder never leaves this boundary.
+  const privateKey = noAutomaticAuth ? "xeno-keyless-local" : key || undefined;
+  const transport = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = new Request(input, init);
+    const nextHeaders = new Headers(request.headers);
+    if (noAutomaticAuth) for (const name of ["authorization", "x-api-key", "api-key", "x-goog-api-key"]) nextHeaders.delete(name);
+    for (const [name, value] of Object.entries(headers)) { if (value === null) nextHeaders.delete(name); else nextHeaders.set(name, value); }
+    clientIdentity(nextHeaders);
+    return fetchImpl(new Request(request, { headers: nextHeaders }));
+  }) as typeof fetch;
+  return { baseUrl, env, headers, fetch: transport, options: access.options ?? {}, body: access.body ?? {}, ...(privateKey ? { key: privateKey } : {}) };
+}

package/src/runtime/provider.ts

@@ -32,6 +32,7 @@
 
 import Anthropic from "@anthropic-ai/sdk";
 import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
+import { imageData } from "./images.ts";
 import type { AssistantBlock } from "../core/events.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import type { UsageSample } from "./usage.ts";
@@ -89,6 +90,8 @@ export const DEFAULT_PROVIDER: ProviderConfig = {
 export type StreamDelta =
   | { kind: "text"; text: string }
   | { kind: "thinking"; text: string }
+  | { kind: "tool"; id: string; name: string; arguments: string }
+  | { kind: "retry"; attempt: number; delayMs: number }
   | { kind: "discard" };
 
 export type OnDelta = (delta: StreamDelta) => void;
@@ -156,13 +159,14 @@ export class RefusalError extends Error {
 
 function buildAnthropicClient(
   apiKey: string | undefined,
-  options: { fetch?: typeof fetch; oauth?: boolean },
+  options: { fetch?: typeof fetch; oauth?: boolean; baseUrl?: string },
 ): AnthropicTransport {
   if (options.oauth === true && apiKey) {
     // authToken is Bearer. Passing apiKey here would send x-api-key, which
     // an OAuth token is not accepted as.
     return new Anthropic({
       maxRetries: 0,
+      ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
       authToken: apiKey,
       defaultHeaders: anthropicOAuthHeaders(),
       ...(options.fetch ? { fetch: options.fetch } : {}),
@@ -170,6 +174,7 @@ function buildAnthropicClient(
   }
   return new Anthropic({
     maxRetries: 0,
+    ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
     ...(apiKey ? { apiKey } : {}),
     ...(options.fetch ? { fetch: options.fetch } : {}),
   });
@@ -206,7 +211,7 @@ export class AnthropicProvider implements Provider {
     // it, so the usage report would quietly stop adding up. The SDK timer
     // also ignores AbortSignal, so an outer wait is the only one Escape
     // can actually cancel.
-    this.client = options.client ?? buildAnthropicClient(apiKey, options);
+    this.client = options.client ?? buildAnthropicClient(apiKey, { ...options, ...(config.spec.baseUrl ? { baseUrl: config.spec.baseUrl } : {}) });
     this.retry = options.retry ?? DEFAULT_RETRY;
     this.onRetry = options.onRetry;
   }
@@ -226,6 +231,7 @@ export class AnthropicProvider implements Provider {
         // The next attempt starts from empty. Without this the UI concatenates
         // two openings of the same sentence and has no sign a retry happened.
         onDelta?.({ kind: "discard" });
+        onDelta?.({ kind: "retry", attempt, delayMs });
         this.onRetry?.(attempt, delayMs, error);
       },
       signal,
@@ -262,8 +268,9 @@ export class AnthropicProvider implements Provider {
         // Anthropic-compatible endpoint serving some other model, answers
         // them with a 400 or silently ignores them.
         ...(this.config.spec.reasoning
-          ? { thinking: { type: "adaptive" as const, display: this.config.thinkingDisplay },
-              output_config: { effort: this.config.effort } }
+          ? this.config.effort === "off" ? { thinking: { type: "disabled" as const } }
+            : { thinking: { type: "adaptive" as const, display: this.config.thinkingDisplay },
+              output_config: { effort: anthropicEffort(this.config) } }
           : {}),
         messages: messages.map(toWireMessage),
       },
@@ -304,6 +311,13 @@ export class AnthropicProvider implements Provider {
   }
 }
 
+/** Pi maps minimal to low for adaptive thinking; off is a thinking switch, never an effort string. */
+function anthropicEffort(config: ProviderConfig): "low" | "medium" | "high" | "xhigh" | "max" {
+  const level = config.spec.thinkingLevelMap?.[config.effort] ?? config.effort;
+  return level === "minimal" || level === "off" ? "low" :
+    level === "low" || level === "medium" || level === "high" || level === "xhigh" || level === "max" ? level : "high";
+}
+
 function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
 }
@@ -402,7 +416,10 @@ async function consumeAnthropicStream(
         const index = event.index ?? content.length;
         if (event.content_block !== undefined) {
           content[index] = { ...event.content_block } as Anthropic.ContentBlock;
-          if (event.content_block.type === "tool_use") jsonBuf.set(index, "");
+          if (event.content_block.type === "tool_use") {
+            jsonBuf.set(index, "");
+            onDelta?.({ kind: "tool", id: event.content_block.id, name: event.content_block.name, arguments: "" });
+          }
         }
         break;
       }
@@ -421,6 +438,7 @@ async function consumeAnthropicStream(
           block.signature = (block.signature ?? "") + delta.signature;
         } else if (delta.type === "input_json_delta" && delta.partial_json) {
           jsonBuf.set(index, (jsonBuf.get(index) ?? "") + delta.partial_json);
+          if (block.type === "tool_use") onDelta?.({ kind: "tool", id: block.id, name: block.name, arguments: jsonBuf.get(index)! });
         }
         break;
       }
@@ -452,12 +470,14 @@ async function consumeAnthropicStream(
 function toWireMessage(m: Message): Anthropic.MessageParam {
   return {
     role: m.role,
-    content: m.content.map(toWireBlock) as Anthropic.ContentBlockParam[],
+    // Anthropic requires all parallel tool results before any text or image in the user message.
+    content: [...m.content.filter(b => b.type === "tool_result"), ...m.content.filter(b => b.type !== "tool_result")].map(toWireBlock) as Anthropic.ContentBlockParam[],
   };
 }
 
 function toWireBlock(b: ContentBlock): unknown {
   switch (b.type) {
+    case "image": return { type: "image", source: { type: "base64", media_type: b.image.mimeType, data: imageData(b) } };
     case "text":
       return { type: "text", text: b.text };
     case "thinking":

package/src/runtime/rich-text.ts

@@ -0,0 +1,36 @@
+/** Ported from Pi (MIT), theme.ts and components/mermaid.ts at 02eed88; only presentation, never log rewriting. */
+import { Marked } from "marked";
+import { render } from "grok-mermaid";
+import { highlight, supportsLanguage, loadAllHighlightLanguages } from "../vendor/pi-rich/syntax-highlight.ts";
+
+type Paint = (token: string, text: string) => string;
+export const warmSyntaxLanguages = loadAllHighlightLanguages;
+export function highlightCode(code: string, language: string | undefined, paint: Paint): string[] {
+  if (!language || !supportsLanguage(language)) return code.split("\n").map(line => paint("mdCodeBlock", line));
+  const tokens: Record<string, string> = { keyword: "Keyword", built_in: "Function", title: "Function", function: "Function",
+    string: "String", regexp: "String", number: "Number", literal: "Number", type: "Type", class: "Type",
+    variable: "Variable", params: "Variable", attr: "Variable", attribute: "Variable", symbol: "Variable",
+    comment: "Comment", meta: "Comment", operator: "Operator", punctuation: "Punctuation" };
+  try { return highlight(code, { language, ignoreIllegals: true,
+    theme: Object.fromEntries(Object.entries(tokens).map(([scope, token]) => [scope, (text: string) => paint("syntax" + token, text)])),
+  }).split("\n"); } catch { return code.split("\n"); }
+}
+const parser = new Marked();
+function codeSpan(line: string): string {
+  const content = line || "\u00a0";
+  const longest = Math.max(0, ...Array.from(content.matchAll(/`+/g), match => match[0].length));
+  const fence = "`".repeat(longest + 1), padding = content.startsWith("`") || content.endsWith("`") ? " " : "";
+  return `${fence}${padding}${content}${padding}${fence}`;
+}
+export function transformMermaid(markdown: string, width: number, mode: "off" | "final" | "streaming", streaming: boolean, paint: Paint): string {
+  if (mode === "off" || streaming && mode !== "streaming") return markdown;
+  try { return parser.lexer(markdown).map(token => {
+    if (token.type !== "code" || token.lang?.trim().split(/\s+/, 1)[0]?.toLowerCase() !== "mermaid") return token.raw;
+    // Incomplete stream fences remain source; rendering half a graph would flicker and lose error context.
+    if (streaming && !/\n\s*(`{3,}|~{3,})\s*$/.test(token.raw.trimEnd())) return token.raw;
+    const art = render(token.text);
+    if (!art || art.width > width || art.warnings.length) return token.raw;
+    const tokens: Record<string, string> = { border: "borderMuted", text: "text", edge: "accent", edgeLabel: "muted", title: "accent" };
+    return art.styled.map(row => codeSpan(row.map(span => paint(tokens[span.cls] ?? "text", span.text)).join(""))).join("  \n") + "\n";
+  }).join(""); } catch { return markdown; }
+}

package/src/runtime/tools.ts

@@ -25,6 +25,7 @@ import { createHash } from "node:crypto";
 import { dirname, resolve, relative, isAbsolute, join, sep } from "node:path";
 import type { Effect, LineRange, ArtifactRef } from "../core/events.ts";
 import { archiveObservation, type ArchivedObservation } from "../store/observations.ts";
+import { blobAddress } from "../store/blobs.ts";
 import { commandHeader, headTailView } from "../core/observation-view.ts";
 import {
   DEFAULT_YIELD_MS, MAX_YIELD_MS, MIN_YIELD_MS, findSession, runningSessions, startSession, takeOutput, waitSession,
@@ -51,10 +52,15 @@ import {
   type PermissionRule,
 } from "../core/permissions.ts";
 import type { ToolSchema } from "./provider.ts";
+import type { ImageRef } from "../core/images.ts";
+import { imageDescription } from "../core/images.ts";
+import { attachImageBytes } from "./images.ts";
+import { detectSupportedImageMimeType } from "../vendor/pi-rich/mime.ts";
 import { find as findFiles, grep, ls } from "../store/search.ts";
 import { scanWorkspace, workspaceVersion, DEFAULT_IGNORE } from "../store/workspace.ts";
 
 export interface ToolResult {
+  images?: readonly ImageRef[];
   /** What the model sees. */
   content: string;
   ok: boolean;
@@ -70,6 +76,16 @@ export interface ToolResult {
 }
 
 export interface ToolContext {
+  /** Session-owned registrations never mutate the built-in table (D13). */
+  extensions?: ReadonlyMap<string, ToolDefinition>;
+  callId?: string;
+  extensionDepth?: number;
+  extensionHooks?: {
+    before(name: string, input: unknown, id: string | undefined): Promise<string | undefined>;
+    event(type: string, fields: Record<string, unknown>): Promise<void>;
+  };
+  imageStore?: string;
+  imageAutoResize?: boolean;
   /** O.1: per-execution copy; never mutate the session's shared tool context with a live signal. */
   signal?: AbortSignal;
   /** Absolute path. Every tool path is confined to this subtree. */
@@ -99,6 +115,7 @@ export interface ToolContext {
   /** Tool output above this is truncated; the marker says how much was cut. */
   maxOutputBytes: number;
   outputStore?: string;
+  onOutput?: (chunk: Uint8Array) => void;
   /**
    * First-match permission rules. Absent means every call is allowed, which
    * is what the existing tests rely on: they exercise the tool, not the gate.
@@ -193,6 +210,7 @@ export interface ToolDefinition extends ToolSchema {
   branch: "read" | "write" | "none";
   /** Accepted by admission but not advertised to the model: harness and test switches. */
   hiddenInputs?: readonly string[];
+  prepareArguments?: (input: unknown) => unknown;
   run?: (ctx: ToolContext, input: Record<string, unknown>) => Promise<ToolResult>;
 }
 
@@ -525,8 +543,8 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
 /** Runtime policy metadata never leaks into provider-specific wire schemas. */
 export const TOOL_SCHEMAS: ToolSchema[] = TOOL_DEFINITIONS.map(({ name, description, input_schema }) => ({ name, description, input_schema }));
 
-export function toolDefinition(name: string): ToolDefinition | undefined {
-  return TOOL_DEFINITIONS.find(tool => tool.name === name);
+export function toolDefinition(name: string, ctx?: ToolContext): ToolDefinition | undefined {
+  return ctx?.extensions?.get(name) ?? TOOL_DEFINITIONS.find(tool => tool.name === name);
 }
 
 // ---------------------------------------------------------------------------
@@ -560,6 +578,10 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
     return { content: `cannot read ${path}: ${(err as Error).message}`, ok: false };
   }
 
+  if (ctx.imageStore && detectSupportedImageMimeType(bytes)) {
+    const image = await attachImageBytes(bytes, path, ctx.imageStore, ctx.imageAutoResize ?? true);
+    return { ok: true, content: imageDescription(image), images: [image], effect: { kind: "read", path, sha256: blobAddress(bytes) } };
+  }
   if (bytes.subarray(0, 8_192).includes(0)) {
     return { ok: false, content: `${path} looks binary (${bytes.length} bytes, contains NUL); inspect it with bash, e.g. \`file ${path}\` or \`xxd ${path} | head\`` };
   }
@@ -695,6 +717,7 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
     outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"),
     maxOutputBytes: ctx.maxOutputBytes, timeoutMs,
     ...(ctx.signal ? { signal: ctx.signal } : {}),
+    ...(ctx.onOutput ? { onOutput: ctx.onOutput } : {}),
   });
 
   const gate = matchGate(ctx, command);
@@ -933,7 +956,7 @@ export async function gateTool(
       ok: false,
     };
   }
-  const definition = toolDefinition(name);
+  const definition = toolDefinition(name, ctx);
   input = repairToolInput(name, input);
   const invalid = definition ? inputError(definition.input_schema, input, "input", definition.hiddenInputs) : null;
   if (invalid) return { ok: false, content: invalid, diagnostic: { code: "invalid_input", message: invalid } };
@@ -995,14 +1018,27 @@ export async function runTool(
 
 /** O.5: ordered admission returns a capability for this exact call, never a policy bypass flag. */
 export async function prepareTool(ctx: ToolContext, name: string, input: unknown): Promise<ToolResult | (() => Promise<ToolResult>)> {
+  try { input = toolDefinition(name, ctx)?.prepareArguments?.(input) ?? input; }
+  catch (error) { return finishToolResult({ ok: false, content: `Invalid ${name} arguments: ${String(error)}` }); }
   const gated = await gateTool(ctx, name, input);
   if (gated) return finishToolResult(gated);
-  return () => dispatchTool(ctx, name, input);
+  const veto = await ctx.extensionHooks?.before(name, input, ctx.callId);
+  if (veto) return finishToolResult({ ok: false, content: veto });
+  return async () => {
+    await ctx.extensionHooks?.event("tool_execution_start", { toolName: name, toolCallId: ctx.callId, args: input });
+    const result = await dispatchTool({ ...ctx, onOutput: chunk => {
+      ctx.onOutput?.(chunk);
+      void ctx.extensionHooks?.event("tool_execution_update", { toolName: name, toolCallId: ctx.callId, partialResult: { content: [{ type: "text", text: new TextDecoder().decode(chunk) }] } });
+    } }, name, input);
+    await ctx.extensionHooks?.event("tool_result", { toolName: name, toolCallId: ctx.callId, input, content: [{ type: "text", text: result.content }], isError: !result.ok, details: result.data });
+    await ctx.extensionHooks?.event("tool_execution_end", { toolName: name, toolCallId: ctx.callId, result, isError: !result.ok });
+    return result;
+  };
 }
 
 async function dispatchTool(ctx: ToolContext, name: string, input: unknown): Promise<ToolResult> {
   if (ctx.signal?.aborted) return finishToolResult(cancelledTool());
-  const impl = toolDefinition(name)?.run;
+  const impl = toolDefinition(name, ctx)?.run;
   if (!impl) {
     const near = closestName(name, TOOL_DEFINITIONS.filter((tool) => tool.run !== undefined).map((tool) => tool.name));
     return finishToolResult({ content: `unknown tool: ${name}` + (near === undefined ? "" : `; did you mean ${near}?`), ok: false });

package/src/store/command.ts

@@ -31,7 +31,13 @@ export async function observeCommand(input: {
   maxOutputBytes: number;
   timeoutMs: number;
   signal?: AbortSignal;
+  onOutput?: (chunk: Uint8Array) => void;
 }) {
+  if (input.signal?.aborted) {
+    const empty = () => new ReadableStream<Uint8Array>({ start: controller => controller.close() });
+    const captured = await captureCommandObservation(input.outputStore, empty(), empty(), Promise.resolve(130), input.maxOutputBytes);
+    return { ...captured, wallMs: 0, stopped: "cancelled" as const };
+  }
   const started = performance.now();
   const proc = Bun.spawn(["bash", "-o", "pipefail", "-lc", input.command], {
     cwd: input.cwd, stdout: "pipe", stderr: "pipe", detached: true, env: commandEnvironment(process.env),
@@ -59,7 +65,7 @@ export async function observeCommand(input: {
   if (input.signal?.aborted) abort();
   try {
     const captured = await captureCommandObservation(input.outputStore, proc.stdout, proc.stderr,
-      proc.exited, input.maxOutputBytes);
+      proc.exited, input.maxOutputBytes, input.onOutput);
     return { ...captured, wallMs: performance.now() - started, ...(stopped ? { stopped } : {}) };
   } catch (error) {
     kill("SIGKILL");

package/src/store/context-files.ts

@@ -15,7 +15,7 @@
  *
  * Re-reading these files at a node boundary would change `system` and
  * invalidate the prefix cache for the whole conversation (D6). They are
- * frozen at startup; a reload is a cut, and is a later card.
+ * frozen at startup; an explicit reload checkpoints a changed prefix.
  */
 
 import { readFile, stat } from "node:fs/promises";

package/src/store/log.ts

@@ -36,6 +36,7 @@ import { isLogEvent, isRecord, validNodeRef } from "../core/event-validation.ts"
 import { emitHandoff } from "../core/handoff.ts";
 import { atomicWrite, durableAppend } from "./atomic.ts";
 import { serialized } from "./serial.ts";
+import { stateAtPosition } from "../core/session-position.ts";
 
 /** Allocation number. Not an ordering over the tree. */
 export type NodeId = number;
@@ -110,6 +111,14 @@ export interface Cursor {
    * this rather than discovering it on the wire.
    */
   model: string;
+  /** New cursors disambiguate identical model IDs served by different providers. */
+  provider?: string;
+  /** Configuration takes effect after this committed event; absent means node start. */
+  at_event?: string;
+  thinking?: string;
+  blob_dir?: string;
+  /** Legacy historical positions with unknown model provenance must cut before dispatch. */
+  needs_model_checkpoint?: boolean;
   updated_at: IsoTime;
   /** Active checkout, which changes when a writing branch becomes mainline. */
   workspace?: string;
@@ -126,8 +135,12 @@ export interface Cursor {
 export interface Manifest {
   version: 1;
   nodes: NodeRecord[];
+  /** An import keeps historical bytes and relocates their storage through journal metadata. */
+  relocated?: true;
   /** Absent in a log written before resume existed, and in an empty one. */
   cursor?: Cursor;
+  parent_session?: string;
+  labels?: Record<string, { text: string; at: string }>;
 }
 
 /**
@@ -500,7 +513,10 @@ async function readLegacyManifest(dir: string): Promise<Manifest> {
 
 type MetadataRecord =
   | { kind: "seed"; manifest: Manifest }
+  | { kind: "relocate"; workspace: string }
   | { kind: "cursor"; cursor: Cursor }
+  | { kind: "parent_session"; path: string }
+  | { kind: "label"; target: string; text: string; at: string }
   | { kind: "node"; record: NodeRecord };
 
 function metadataPath(dir: string): string { return join(dir, "metadata.jsonl"); }
@@ -521,6 +537,22 @@ async function readMetadata(dir: string): Promise<MetadataRecord[] | null> {
   });
 }
 
+/** The metadata journal already owns configuration history; no second state log is needed. */
+export async function readCursorAt(dir: string, node: number, atEvent?: string): Promise<Cursor | null> {
+  const records = await readMetadata(dir);
+  const legacy = records === null ? await readLegacyManifest(dir) : undefined;
+  const states: Cursor[] = legacy?.cursor ? [legacy.cursor] : [];
+  let relocated = legacy?.relocated === true;
+  for (const record of records ?? []) {
+    if (record.kind === "cursor") states.push({ ...record.cursor });
+    else if (record.kind === "seed") { if (record.manifest.cursor) states.push({ ...record.manifest.cursor }); relocated ||= record.manifest.relocated === true; }
+    else if (record.kind === "relocate") { relocated = true; for (const state of states) state.workspace = record.workspace; }
+  }
+  if (relocated) for (const state of states) state.blob_dir = join(dir, "blobs");
+  const { events } = await readNode(dir, node);
+  return stateAtPosition(states, node, events.map(event => event.id), atEvent);
+}
+
 /** D3: the replaceable manifest is a projection of committed metadata events. */
 export async function readManifest(dir: string): Promise<Manifest> {
   return serialized(dir, () => readManifestUnlocked(dir));
@@ -534,6 +566,16 @@ async function readManifestUnlocked(dir: string): Promise<Manifest> {
     switch (event.kind) {
       case "seed": manifest = structuredClone(event.manifest); break;
       case "cursor": manifest.cursor = event.cursor; break;
+      case "relocate":
+        manifest.relocated = true;
+        if (manifest.cursor) manifest.cursor = { ...manifest.cursor, workspace: event.workspace };
+        break;
+      case "parent_session": manifest.parent_session = event.path; break;
+      case "label":
+        manifest.labels ??= {};
+        if (event.text) Object.defineProperty(manifest.labels, event.target, { value: { text: event.text, at: event.at }, enumerable: true, configurable: true, writable: true });
+        else delete manifest.labels[event.target];
+        break;
       case "node": {
         const i = manifest.nodes.findIndex((n) => n.node === event.record.node);
         if (i < 0) manifest.nodes.push(event.record);
@@ -544,9 +586,18 @@ async function readManifestUnlocked(dir: string): Promise<Manifest> {
     }
   }
   manifest.nodes.sort((a, b) => a.node - b.node);
+  if (manifest.relocated && manifest.cursor) manifest.cursor = { ...manifest.cursor, blob_dir: join(dir, "blobs") };
   return manifest;
 }
 
+/** Relocation changes recovery locations, not historical events or evidence (D3/D8). */
+export async function relocateSession(dir: string, workspace: string): Promise<void> {
+  return serialized(dir, async () => {
+    await appendMetadata(dir, { kind: "relocate", workspace });
+    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
+  });
+}
+
 async function appendMetadata(dir: string, event: MetadataRecord): Promise<void> {
   await mkdir(dir, { recursive: true });
   const encode = (record: MetadataRecord) => JSON.stringify({
@@ -589,6 +640,20 @@ export async function readCursor(dir: string): Promise<Cursor | null> {
   return (await readManifest(dir)).cursor ?? null;
 }
 
+/** Labels are display metadata, never model evidence or rewritten conversation events. */
+export async function setSessionLabel(dir: string, target: string, text: string, at: string): Promise<void> {
+  return serialized(dir, async () => {
+    await appendMetadata(dir, { kind: "label", target, text: text.trim(), at });
+    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
+  });
+}
+export async function setParentSession(dir: string, path: string): Promise<void> {
+  return serialized(dir, async () => {
+    await appendMetadata(dir, { kind: "parent_session", path });
+    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
+  });
+}
+
 /** Direct children of `node`, in allocation order. */
 export function childrenOf(manifest: Manifest, node: NodeId): NodeRecord[] {
   return manifest.nodes.filter((r) => r.parent?.node === node);

package/src/store/models.ts

@@ -8,23 +8,35 @@
  * forbids.
  */
 
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { configDir } from "./config.ts";
 
 export function modelsPath(): string {
   return join(configDir(), "models.json");
 }
+export function catalogCachePath(): string { return join(configDir(), "models-cache.json"); }
 
 export async function readModelsText(): Promise<{ text: string | null; error: string | null }> {
+  return readModelFile(modelsPath());
+}
+export async function readCatalogCacheText(): Promise<{ text: string | null; error: string | null }> {
+  return readModelFile(catalogCachePath());
+}
+async function readModelFile(path: string): Promise<{ text: string | null; error: string | null }> {
   try {
-    const text = await readFile(modelsPath(), "utf8");
+    const text = await readFile(path, "utf8");
     return { text, error: null };
-  } catch {
-    // Absent is the normal first-run state, not an error.
-    return { text: null, error: null };
+  } catch (err) {
+    const absent = typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+    return { text: null, error: absent ? null : `cannot read ${path}` };
   }
 }
+export async function readModelSources(): Promise<{ userText: string | null; cacheText: string | null; readWarnings: string[] }> {
+  const [user, cache] = await Promise.all([readModelsText(), readCatalogCacheText()]);
+  return { userText: user.text, cacheText: cache.text, readWarnings: [user.error, cache.error].filter((value): value is string => value !== null) };
+}
 
 /**
  * Replace, don't truncate. writeFile on the live path empties it first, so a
@@ -33,9 +45,16 @@ export async function readModelsText(): Promise<{ text: string | null; error: st
  * existing bytes untouched (feat-json-mode-and-header).
  */
 export async function writeModelsFile(value: unknown): Promise<void> {
+  return writeModelFile(modelsPath(), value);
+}
+export async function writeCatalogCache(value: unknown): Promise<void> {
+  return writeModelFile(catalogCachePath(), value);
+}
+async function writeModelFile(dest: string, value: unknown): Promise<void> {
   await mkdir(configDir(), { recursive: true });
-  const dest = modelsPath();
-  const tmp = `${dest}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-  await rename(tmp, dest);
+  const tmp = `${dest}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, dest);
+  } finally { await rm(tmp, { force: true }); }
 }

package/src/store/observations.ts

@@ -52,6 +52,7 @@ const EXIT_DRAIN_MS = 1_000;
  */
 async function spoolMerged(
   dir: string, streams: readonly ReadableStream<Uint8Array>[], exited: Promise<number>,
+  onOutput?: (chunk: Uint8Array) => void,
 ): Promise<string> {
   await mkdir(dir, { recursive: true });
   const path = join(dir, `.${randomUUID()}.stream`);
@@ -74,7 +75,7 @@ async function spoolMerged(
         const result = await reader.read();
         if (result.done) return;
         armIdle();
-        queue = queue.then(() => file.writeFile(result.value));
+        queue = queue.then(async () => { await file.writeFile(result.value); onOutput?.(result.value); });
         await queue;
       }
     }));
@@ -165,8 +166,9 @@ export async function archiveObservation(
 export async function captureCommandObservation(
   dir: string, stdout: ReadableStream<Uint8Array>, stderr: ReadableStream<Uint8Array>,
   exited: Promise<number>, previewBytes: number,
+  onOutput?: (chunk: Uint8Array) => void,
 ): Promise<ArchivedObservation & { exit: number; prefixBytes: number }> {
-  const merged = await spoolMerged(dir, [stdout, stderr], exited);
+  const merged = await spoolMerged(dir, [stdout, stderr], exited, onOutput);
   try {
     const exit = await exited;
     const prefix = new TextEncoder().encode(`exit ${exit}\n`);