@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/extensions.ts

@@ -1,370 +0,0 @@
-/** Pi's factory/registration protocol, attached to xeno's session rather than another AgentSession. */
-import { loadExtensionFactory } from "./extension-loader.ts";
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { ResourceIndex } from "../store/resource-index.ts";
-import type { ExtensionEvent, LogEvent } from "../core/events.ts";
-import { isJsonValue, type JsonValue } from "../core/tool-contract.ts";
-import type { ToolContext, ToolDefinition } from "./tools.ts";
-import { nativeCommandResult } from "./tools.ts";
-import { attachImageBytes } from "./images.ts";
-import type { ExtensionComponent, ExtensionUI, ExtensionTheme } from "./extension-ui.ts";
-import { DISCOVERY_TOOL, DISCOVERY_TOOL_NAME } from "./tool-discovery.ts";
-import { LazyIntegration, type ExtensionIntegration } from "./integrations.ts";
-
-export interface ExtensionContext {
-  ui: ExtensionUI; cwd: string; mode: "tui" | "json" | "print"; hasUI: boolean;
-  model: unknown; thinkingLevel: string; signal: AbortSignal | undefined;
-  isIdle(): boolean; isProjectTrusted(): boolean; hasPendingMessages(): boolean;
-  abort(): void; shutdown(): void; getSystemPrompt(): string;
-  sessionManager: {
-    getEntries(): readonly LogEvent[]; getBranch(): readonly LogEvent[];
-    getSessionId(): string; getSessionFile(): string; getCwd(): string;
-  };
-  [key: string]: unknown;
-}
-export type ExtensionHandler = (event: Record<string, unknown>, ctx: ExtensionContext) => unknown | Promise<unknown>;
-export interface ExtensionCommand {
-  description?: string;
-  handler(args: string, ctx: ExtensionContext): void | Promise<void>;
-  getArgumentCompletions?(prefix: string): { value: string; label: string; description?: string }[] | null | Promise<{ value: string; label: string; description?: string }[] | null>;
-}
-export interface ExtensionToolResult {
-  content: ({ type: "text"; text: string } | { type: "image"; data: string; mimeType: string })[];
-  details?: JsonValue; isError?: boolean;
-}
-export interface ExtensionToolRenderContext {
-  args: unknown; toolCallId: string; invalidate(): void;
-  lastComponent: ExtensionComponent | undefined; state: Record<string, unknown>; cwd: string;
-  executionStarted: boolean; argsComplete: boolean; isPartial: boolean; expanded: boolean; showImages: boolean; isError: boolean;
-}
-export interface ExtensionTool {
-  name: string; label?: string; description: string; parameters: unknown;
-  /** R11: omitted remains direct; deferred schemas are activated at a Session checkpoint. */
-  exposure?: "direct" | "deferred";
-  promptSnippet?: string; promptGuidelines?: string[]; executionMode?: "parallel" | "sequential";
-  prepareArguments?(input: unknown): unknown;
-  validateInput?(input: unknown): void;
-  execute(id: string, args: Record<string, unknown>, signal: AbortSignal | undefined,
-    onUpdate: (result: ExtensionToolResult) => void, ctx: ExtensionContext): Promise<ExtensionToolResult>;
-  renderCall?(args: unknown, theme: ExtensionTheme, context: ExtensionToolRenderContext): ExtensionComponent;
-  renderResult?(result: ExtensionToolResult, options: { expanded: boolean; isPartial: boolean }, theme: ExtensionTheme, context: ExtensionToolRenderContext): ExtensionComponent;
-}
-export type ExtensionRenderer = (message: Record<string, unknown>, options: { expanded: boolean; outputPad: number }, theme: ExtensionTheme) => ExtensionComponent | undefined;
-type Flag = { type: "string" | "boolean"; description?: string; default?: string | boolean };
-export interface ExtensionActions {
-  context(): ExtensionContext;
-  append(entry: Omit<ExtensionEvent, "t" | "id" | "at">, options?: { triggerTurn?: boolean; deliverAs?: string }): Promise<void>;
-  user(text: string, options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean }): Promise<void>;
-  setName(name: string): Promise<void>;
-  setLabel(id: string, label: string | undefined): Promise<void>;
-  setTools(names: string[]): Promise<void>;
-  getTools(): { name: string; description: string; parameters: unknown }[];
-  getAllTools?(): { name: string; description: string; parameters: unknown }[];
-  setModel(model: unknown): Promise<boolean>;
-  setThinking(level: string): Promise<void>;
-  exec(command: string, args: string[], options?: { cwd?: string; timeout?: number; signal?: AbortSignal }): Promise<{ stdout: string; stderr: string; code: number; killed: boolean }>;
-}
-export interface ExtensionAPI {
-  on(event: string, handler: ExtensionHandler): () => void;
-  registerCommand(name: string, command: ExtensionCommand): void;
-  registerTool(tool: ExtensionTool): void;
-  registerIntegration(integration: ExtensionIntegration): void;
-  registerShortcut(key: string, shortcut: { description?: string; handler(ctx: ExtensionContext): void | Promise<void> }): void;
-  registerFlag(name: string, options: Flag): void;
-  getFlag(name: string): string | boolean | undefined;
-  registerMessageRenderer(name: string, renderer: ExtensionRenderer): void;
-  registerEntryRenderer(name: string, renderer: ExtensionRenderer): void;
-  registerMarkdownTransformer(transform: (text: string, context: Record<string, unknown>) => string | undefined): void;
-  sendMessage(message: { customType: string; content: string | { type: "text"; text: string }[]; display?: boolean; details?: JsonValue }, options?: { triggerTurn?: boolean; deliverAs?: string }): void;
-  sendUserMessage(text: string, options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean }): void;
-  appendEntry(name: string, data?: JsonValue): void;
-  setSessionName(name: string): void;
-  setLabel(id: string, label: string | undefined): void;
-  getActiveTools(): string[];
-  getAllTools(): { name: string; description: string; parameters: unknown }[];
-  setActiveTools(names: string[]): void;
-  setModel(model: unknown): Promise<boolean>;
-  getThinkingLevel(): string;
-  setThinkingLevel(level: string): void;
-  getCommands(): { name: string; description?: string }[];
-  exec: ExtensionActions["exec"];
-  events: { on(name: string, handler: (data: unknown) => void): () => void; emit(name: string, data?: unknown): void };
-}
-
-const prohibited = new Set(["context", "context_with_system", "session_before_compact", "session_compact", "session_compact_failed"]);
-let generation = 0;
-
-interface ExtensionRegistryOptions {
-  reserved?: readonly string[]; reservedFlags?: readonly string[];
-  flags?: Readonly<Record<string, string | boolean>>;
-  flagValue?: (name: string, definition: Flag) => string | boolean | undefined;
-  report?: (message: string) => void;
-}
-
-/** Registrations are staged before activation, and disposed as one generation on reload. */
-export class ExtensionRegistry {
-  /** Harness-owned tools keep capability metadata; arbitrary extensions cannot claim it. */
-  readonly builtinTools = new Map<string, ToolDefinition>();
-  private readonly ownedDisposers: (() => Promise<void>)[] = [];
-  installBuiltin(tool: ToolDefinition): void {
-    if (this.tools.has(tool.name) || this.builtinTools.has(tool.name)) throw Error(`duplicate harness tool ${tool.name}`);
-    this.builtinTools.set(tool.name, tool);
-  }
-  own(dispose: () => Promise<void>): void { this.ownedDisposers.push(dispose); }
-  readonly commands = new Map<string, ExtensionCommand>();
-  readonly tools = new Map<string, ExtensionTool>();
-  readonly shortcuts = new Map<string, { description?: string; handler(ctx: ExtensionContext): void | Promise<void> }>();
-  readonly flags = new Map<string, Flag>();
-  readonly renderers = new Map<string, ExtensionRenderer>();
-  readonly entryRenderers = new Map<string, ExtensionRenderer>();
-  readonly markdown: ((text: string, context: Record<string, unknown>) => string | undefined)[] = [];
-  readonly diagnostics: string[] = [];
-  readonly loaded: string[] = [];
-  private handlers = new Map<string, Set<ExtensionHandler>>();
-  private bus = new Map<string, Set<(data: unknown) => void>>();
-  private pending = new Set<Promise<void>>();
-  /** Pi A / D8: void session mutations still have a durable invocation order. */
-  private actionTail: Promise<void> = Promise.resolve();
-  private disposers: (() => void)[] = [];
-  private detachListeners = new Set<() => void>();
-  private toolUpdateListeners = new Set<(name: string, id: string, input: unknown, result: ExtensionToolResult) => void>();
-  private actions: ExtensionActions | undefined;
-  private readonly execution = new AsyncLocalStorage<ToolContext>();
-  private disposed = false;
-  private readonly integrations = new Map<string, LazyIntegration>();
-  private readonly integrationTools = new Map<string, LazyIntegration>();
-  private readonly options: ExtensionRegistryOptions;
-  constructor(options: ExtensionRegistryOptions = {}) { this.options = options; }
-
-  bind(actions: ExtensionActions): void { this.actions = actions; }
-  onDispose(detach: () => void): () => void { this.detachListeners.add(detach); return () => this.detachListeners.delete(detach); }
-  onToolUpdate(listener: (name: string, id: string, input: unknown, result: ExtensionToolResult) => void): () => void {
-    this.toolUpdateListeners.add(listener); return () => this.toolUpdateListeners.delete(listener);
-  }
-  private active(): ExtensionActions {
-    if (this.disposed || !this.actions) throw new Error("Extension session is not active");
-    return this.actions;
-  }
-  private enqueue(operation: () => Promise<void>): void {
-    const pending = this.actionTail.then(operation).catch(error => this.report(String(error))).finally(() => this.pending.delete(pending));
-    this.pending.add(pending);
-    // A failing observer must not poison later accepted work or create an unhandled rejection.
-    this.actionTail = pending.catch(() => {});
-  }
-  async settle(): Promise<void> { while (this.pending.size) await Promise.all([...this.pending]); }
-  private report(message: string): void { this.diagnostics.push(message); this.options.report?.(`Extension: ${message}`); }
-  private insert<T>(map: Map<string, T>, name: string, value: T, source: string): void {
-    if (!name || map.has(name)) throw new Error(`${source}: duplicate or empty registration: ${name}`);
-    map.set(name, value);
-  }
-  api(source: string): ExtensionAPI {
-    return {
-      on: (event, handler) => {
-        if (prohibited.has(event)) throw new Error(`${event} rewrites model context or summarizes history; xeno requires append-only events and mechanical checkpoints`);
-        const handlers = this.handlers.get(event) ?? new Set<ExtensionHandler>(); this.handlers.set(event, handlers); handlers.add(handler);
-        return () => { handlers.delete(handler); };
-      },
-      registerCommand: (name, command) => {
-        if (this.options.reserved?.includes(name)) throw new Error(`Command /${name} is reserved`);
-        this.insert(this.commands, name, command, source);
-      },
-      registerTool: tool => {
-        if (this.builtinTools.has(tool.name)) throw Error(`${tool.name} is owned by the harness`);
-        if (!/^[a-zA-Z0-9_-]+$/.test(tool.name) || typeof tool.execute !== "function") throw new Error("Invalid tool definition");
-        if (["note", "history", "branch", "resolve", DISCOVERY_TOOL_NAME].includes(tool.name)) throw new Error(`${tool.name} owns the append-only harness and cannot be replaced`);
-        if (tool.exposure !== undefined && tool.exposure !== "direct" && tool.exposure !== "deferred") throw new Error("Unknown tool exposure");
-        if (tool.exposure === "deferred" && tool.name.length > 128) throw new Error("Deferred tool names must fit the discovery receipt");
-        extensionSchema(tool.parameters); this.insert(this.tools, tool.name, tool, source);
-      },
-      registerIntegration: integration => {
-        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(integration.name) || this.integrations.has(integration.name)
-          || typeof integration.connect !== "function" || !Array.isArray(integration.tools) || !integration.tools.length) throw Error("Invalid or duplicate integration");
-        const repair = integration.repair;
-        if (repair && (!/^[a-zA-Z0-9_-]{1,64}$/.test(repair.command) || this.commands.has(repair.command)
-          || this.options.reserved?.includes(repair.command) || typeof repair.run !== "function")) throw Error("Invalid or duplicate integration repair command");
-        const names = new Set<string>();
-        for (const tool of integration.tools) {
-          if (names.has(tool.name) || this.tools.has(tool.name)) throw Error("Duplicate integration tool");
-          names.add(tool.name);
-        }
-        // Copy the manifest before publishing. Registrations and live connection ownership share one generation.
-        const owner = new LazyIntegration({ ...integration, ...(repair ? { repair: { ...repair } } : {}),
-          tools: integration.tools.map(tool => ({ ...tool, parameters: structuredClone(tool.parameters) })) });
-        const added: string[] = [];
-        try {
-          for (const descriptor of owner.definition.tools) {
-            this.api(source).registerTool({ ...descriptor, exposure: descriptor.exposure ?? "deferred", execute: async () => { throw Error("Integration tools require their owner"); } });
-            added.push(descriptor.name); this.integrationTools.set(descriptor.name, owner);
-          }
-          if (repair) this.api(source).registerCommand(repair.command, { description: repair.description, handler: async (_args, ctx) => {
-            const result = await owner.repair(ctx);
-            await this.active().append({ customType: "integration_repair", content: result.content, display: true, inContext: false,
-              ...(result.data === undefined ? {} : { data: result.data }) });
-          } });
-          this.integrations.set(integration.name, owner);
-        } catch (error) {
-          for (const name of added) { this.tools.delete(name); this.integrationTools.delete(name); }
-          void owner.dispose(); throw error;
-        }
-      },
-      registerShortcut: (name, value) => this.insert(this.shortcuts, name, value, source),
-      registerFlag: (name, value) => {
-        if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(name) || this.options.reservedFlags?.includes(name)) throw new Error(`CLI flag --${name} is reserved or invalid`);
-        this.insert(this.flags, name, value, source);
-      },
-      getFlag: name => { const flag = this.flags.get(name); return this.options.flags && Object.hasOwn(this.options.flags, name) ? this.options.flags[name] : (flag ? this.options.flagValue?.(name, flag) ?? flag.default : undefined); },
-      registerMessageRenderer: (name, value) => this.insert(this.renderers, name, value, source),
-      registerEntryRenderer: (name, value) => this.insert(this.entryRenderers, name, value, source),
-      registerMarkdownTransformer: transform => { this.markdown.push(transform); },
-      sendMessage: (message, options) => this.enqueue(() => this.active().append({ customType: message.customType,
-        content: typeof message.content === "string" ? message.content : message.content.map(c => c.text).join("\n"),
-        display: message.display !== false, inContext: true, ...(message.details === undefined ? {} : { data: message.details }) }, options)),
-      appendEntry: (name, data) => this.enqueue(() => this.active().append({ customType: name, content: "", display: this.entryRenderers.has(name), inContext: false, ...(data === undefined ? {} : { data }) })),
-      sendUserMessage: (text, options) => this.enqueue(() => this.active().user(text, options)),
-      setSessionName: name => this.enqueue(() => this.active().setName(name)),
-      setLabel: (id, label) => this.enqueue(() => this.active().setLabel(id, label)),
-      getActiveTools: () => this.active().getTools().map(tool => tool.name),
-      getAllTools: () => this.active().getAllTools?.() ?? this.active().getTools(),
-      setActiveTools: names => this.enqueue(() => this.active().setTools(names)),
-      setModel: model => this.active().setModel(model),
-      getThinkingLevel: () => this.active().context().thinkingLevel,
-      setThinkingLevel: level => this.enqueue(() => this.active().setThinking(level)),
-      getCommands: () => [...this.commands].map(([name, command]) => ({ name, ...(command.description ? { description: command.description } : {}) })),
-      exec: (command, args, options) => {
-        const pending = (async () => {
-          this.active();
-          const scope = this.execution.getStore();
-          if (!scope) return this.active().exec(command, [...args], options);
-          if (!scope.invokeHost || !scope.outputStore) throw new Error("native commands require a live Session host scope");
-          const result = await scope.invokeHost({ argv: [command, ...args], ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),
-            ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}) }, options?.signal);
-          return nativeCommandResult(result, scope.outputStore);
-        })();
-        // The host owns accepted work even if the extension drops this SDK promise.
-        // Keep the rejection available to an awaiter while observing it ourselves.
-        void pending.catch(error => this.report(`exec: ${String(error)}`));
-        return pending;
-      },
-      events: {
-        on: (name, handler) => { const listeners = this.bus.get(name) ?? new Set(); this.bus.set(name, listeners); listeners.add(handler); return () => { listeners.delete(handler); }; },
-        emit: (name, data) => { for (const handler of this.bus.get(name) ?? []) try { handler(data); } catch (error) { this.report(String(error)); } },
-      },
-    };
-  }
-
-  async load(index: ResourceIndex): Promise<void> {
-    const version = ++generation;
-    for (const resource of index.entries.filter(r => r.kind === "extensions" && r.enabled)) {
-      const maps = [this.commands, this.tools, this.shortcuts, this.flags, this.renderers, this.entryRenderers, this.integrations, this.integrationTools];
-      const before = maps.map(map => new Set(map.keys()));
-      const oldHandlers = new Map([...this.handlers].map(([name, handlers]) => [name, new Set(handlers)]));
-      const oldBus = new Map([...this.bus].map(([name, handlers]) => [name, new Set(handlers)]));
-      const transforms = this.markdown.length;
-      try {
-        // External entry paths are runtime resources, never internal module aliases.
-        const factory = await loadExtensionFactory(resource.path, version);
-        if (typeof factory !== "function") throw new Error("Expected a default extension factory");
-        const dispose: unknown = await factory(this.api(resource.path));
-        if (typeof dispose === "function") this.disposers.push(dispose as () => void);
-        this.loaded.push(resource.path);
-      } catch (error) {
-        maps.forEach((map, i) => { for (const key of map.keys()) if (!before[i]!.has(key)) map.delete(key); });
-        this.handlers = oldHandlers; this.bus = oldBus; this.markdown.length = transforms;
-        this.report(`${resource.path}: ${String(error)}`);
-      }
-    }
-  }
-
-  async emit(type: string, event: Record<string, unknown> = {}): Promise<Record<string, unknown>[]> {
-    if (!this.actions || this.disposed) return [];
-    const results: Record<string, unknown>[] = [];
-    for (const handler of [...this.handlers.get(type) ?? []]) {
-      try { const value = await handler({ ...event, type }, this.active().context()); if (typeof value === "object" && value !== null) results.push(value as Record<string, unknown>); }
-      catch (error) { this.report(`${type}: ${String(error)}`); }
-    }
-    return results;
-  }
-  async command(name: string, args: string): Promise<boolean> {
-    const command = this.commands.get(name); if (!command) return false;
-    try { await command.handler(args, this.active().context()); await this.settle(); } catch (error) { this.report(`/${name}: ${String(error)}`); }
-    return true;
-  }
-  definitions(): ReadonlyMap<string, ToolDefinition> {
-    const definitions = new Map<string, ToolDefinition>([...this.tools].map(([name, tool]) => [name, {
-      name, description: tool.description, input_schema: extensionSchema(tool.parameters),
-      // Arbitrary local code is not provably read-only. Keep admission and effects
-      // serial; an extension's annotation cannot grant a parallel write capability.
-      access: "write", execution: "exclusive", branch: "none",
-      ...(this.integrationTools.has(name) ? { integrationHealth: () => this.integrationTools.get(name)!.observe() } : {}),
-      ...(tool.prepareArguments ? { prepareArguments: tool.prepareArguments } : {}),
-      ...(tool.validateInput ? { validateInput: tool.validateInput } : {}),
-      run: async (ctx: ToolContext, raw: Record<string, unknown>) => {
-        const context = { ...this.active().context(), signal: ctx.signal, tools: this.active().getTools(),
-          executeTool: async (target: string, input: unknown) => {
-            if (!ctx.invoke) return { isError: true, content: [{ type: "text", text: "Nested tools require a live Session execution scope" }] };
-            const out = await ctx.invoke(target, input);
-            return { isError: !out.ok, content: [{ type: "text", text: out.content }], details: out.data,
-              outcome: out.outcome, diagnostic: out.diagnostic, warnings: out.warnings, artifact: out.content_ref, observation: out.observation };
-          } };
-        const update = (update: ExtensionToolResult) => {
-          for (const listener of this.toolUpdateListeners) try { listener(name, ctx.callId ?? name, raw, update); } catch (error) { this.report(String(error)); }
-          ctx.onOutput?.(new TextEncoder().encode(update.content.filter(c => c.type === "text").map(c => c.text).join("\n")));
-        };
-        const integration = this.integrationTools.get(name);
-        const managed = integration ? await this.execution.run(ctx, () => integration.execute(name, ctx.callId ?? name, raw, ctx.signal, update, context)) : undefined;
-        if (managed && !managed.ok) return managed.result;
-        const result = managed?.ok ? managed.result : await this.execution.run(ctx, () => tool.execute(ctx.callId ?? name, raw, ctx.signal, update, context));
-        const text = result.content.filter(c => c.type === "text").map(c => c.text).join("\n");
-        const images = [];
-        for (const item of result.content) if (item.type === "image" && ctx.imageStore) images.push(await attachImageBytes(Buffer.from(item.data, "base64"), name + ".png", ctx.imageStore, ctx.imageAutoResize));
-        return { ok: result.isError !== true && !ctx.signal?.aborted, content: text,
-          ...(managed?.ok ? { data: { kind: "integration_observation", version: 1, phase: "call", health: managed.observation,
-            ...(isJsonValue(result.details) ? { result: result.details } : {}) } } : isJsonValue(result.details) ? { data: result.details } : {}),
-          ...(images.length ? { images } : {}) };
-      },
-    }]));
-    if ([...this.tools.values()].some(tool => tool.exposure === "deferred")) definitions.set(DISCOVERY_TOOL_NAME, DISCOVERY_TOOL);
-    for (const [name, tool] of this.builtinTools) definitions.set(name, tool);
-    return definitions;
-  }
-  toolHooks(): NonNullable<ToolContext["extensionHooks"]> {
-    return {
-      scope: (ctx, action) => this.execution.run(ctx, action),
-      serial: () => ["tool_call", "tool_execution_start", "tool_execution_update", "tool_result", "tool_execution_end"].some(type => (this.handlers.get(type)?.size ?? 0) > 0),
-      before: async (toolName, input, toolCallId, parentToolCallId) => {
-        const blocked = (await this.emit("tool_call", { toolName, input, toolCallId, ...(parentToolCallId ? { parentToolCallId } : {}) })).find(result => result["block"] === true);
-        return blocked ? String(blocked["reason"] ?? "Blocked by extension") : undefined;
-      },
-      event: async (type, fields) => { await this.emit(type, fields); },
-    };
-  }
-  async dispose(): Promise<void> {
-    if (this.disposed) return;
-    for (const dispose of this.ownedDisposers.splice(0)) await dispose();
-    await Promise.all([...this.integrations.values()].map(owner => owner.dispose()));
-    for (const detach of this.detachListeners) try { detach(); } catch (error) { this.report(String(error)); }
-    this.detachListeners.clear(); this.toolUpdateListeners.clear();
-    await this.emit("session_shutdown"); await this.settle(); this.disposed = true;
-    for (const dispose of this.disposers.reverse()) try { dispose(); } catch (error) { this.report(String(error)); }
-    this.handlers.clear(); this.bus.clear(); this.actions = undefined;
-  }
-  /** Q.13: a new generation must not overlap an unresolved callback from its predecessor. */
-  async releaseIntegrations(): Promise<boolean> {
-    if ([...this.integrations.values()].some(owner => !owner.canReleaseForReload())) return false;
-    const released = await Promise.all([...this.integrations.values()].map(owner => owner.releaseForReload()));
-    return released.every(Boolean);
-  }
-  restoreIntegrations(): boolean {
-    const restored = [...this.integrations.values()].map(owner => owner.resumeAfterReload());
-    return restored.every(Boolean);
-  }
-}
-
-function extensionSchema(parameters: unknown): ToolDefinition["input_schema"] {
-  if (typeof parameters !== "object" || parameters === null) throw new Error("Tool parameters must be an object schema");
-  const schema = parameters as Record<string, unknown>;
-  if (schema["type"] !== "object" || schema["properties"] !== undefined && (typeof schema["properties"] !== "object" || schema["properties"] === null || Array.isArray(schema["properties"]))) throw new Error("Tool parameters need an object schema");
-  const required = schema["required"] ?? [];
-  if (!Array.isArray(required) || required.some(value => typeof value !== "string")) throw new Error("Tool required fields must be names");
-  return { ...schema, type: "object", properties: (schema["properties"] ?? {}) as Record<string, unknown>, required: required as string[] };
-}

package/src/runtime/formatter-tool.ts

@@ -1,38 +0,0 @@
-/** Trusted formatter configuration controls commands; model arguments supply only paths. */
-import { planFormatters, runConfiguredFormatters, validateFormatters, type FormatterConfig } from "./formatter.ts";
-import { presentObservation, type ToolDefinition } from "./tools.ts";
-import { failureDiagnostic, failureFromError, NOT_STARTED, UNKNOWN_EFFECT } from "../core/tool-failure.ts";
-import { readEditableFile } from "../store/file-checkpoints.ts";
-
-export function createFormatterTool(configs: readonly FormatterConfig[]): ToolDefinition {
-  const frozen = validateFormatters(configs);
-  return {
-    name: "format", access: "shell", execution: "exclusive", branch: "write",
-    description: "Run explicitly configured trusted formatters for these existing workspace files. Every formatter command goes through the session's normal command admission, logs and checkpoints; no executable is auto-discovered or installed. Returns real command outcomes and resulting file digests. Formatting can change content; read the current file before deriving further edits.",
-    input_schema: { type: "object", required: ["paths"], properties: { paths: { type: "array", minItems: 1, maxItems: 100, items: { type: "string" } } } },
-    run: async (ctx, input) => {
-      if (!ctx.invokeHost) return { ok: false, content: "Formatter requires the session command lifecycle.", diagnostic: failureDiagnostic("environment_missing", "Formatter requires the session command lifecycle.", NOT_STARTED) };
-      let executing = false;
-      try {
-        const paths = input["paths"] as string[], plans = await planFormatters(ctx.root, paths, frozen);
-        if (!plans.length) return { ok: false, content: "No configured formatter matches these file extensions.", diagnostic: failureDiagnostic("environment_missing", "No configured formatter matches these file extensions.", NOT_STARTED) };
-        executing = true;
-        const results = await runConfiguredFormatters(plans, ctx.invokeHost, ctx.signal);
-        if (!results.length) return { ok: false, content: "Formatter cancelled before execution.", diagnostic: failureDiagnostic("cancelled", "Formatter cancelled before execution.", NOT_STARTED) };
-        const files = [];
-        for (const path of [...new Set(results.map(result => result.plan.path))]) {
-          const observed = await readEditableFile(ctx.root, path);
-          files.push({ path, sha256: observed.version?.sha256 ?? null });
-        }
-        const receipts = results.map(({ plan, result }) => `${plan.formatter} ${plan.path}: ${result.ok ? "completed" : "failed"}\n${result.content}`).join("\n\n");
-        const last = results.at(-1)!.result;
-        return { ...await presentObservation(ctx, receipts + "\n\nCurrent file versions:\n" + files.map(file => `${file.path}: ${file.sha256 ?? "absent"}`).join("\n")),
-          ok: results.length === plans.length && results.every(result => result.result.ok), data: { files, commands: results.length },
-          ...(last.outcome === undefined ? {} : { outcome: last.outcome }), ...(last.diagnostic === undefined ? {} : { diagnostic: last.diagnostic }) };
-      } catch (error) {
-        const diagnostic = failureFromError(error, executing ? UNKNOWN_EFFECT : NOT_STARTED);
-        return { ok: false, content: diagnostic.message, diagnostic };
-      }
-    },
-  };
-}

package/src/runtime/formatter.ts

@@ -1,50 +0,0 @@
-/** Explicit trusted formatters use the original command broker, never hidden subprocesses. */
-import { extname, resolve } from "node:path";
-import { readEditableFile } from "../store/file-checkpoints.ts";
-import type { NativeCommandInput, ToolResult } from "./tools.ts";
-export interface FormatterConfig { name: string; extensions: readonly string[]; command: readonly string[]; disabled?: boolean }
-export interface FormatterPlan { formatter: string; path: string; input: NativeCommandInput }
-
-export function validateFormatters(value: unknown): FormatterConfig[] {
-  if (!Array.isArray(value)) throw new Error("formatters must be an array of trusted command definitions");
-  const names = new Set<string>();
-  return value.map((entry: unknown) => {
-    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new Error("formatter must be an object");
-    const config = entry as Record<string, unknown>, name = config["name"], extensions = config["extensions"], command = config["command"], disabled = config["disabled"];
-    if (Object.keys(config).some(key => !["name", "extensions", "command", "disabled"].includes(key))) throw new Error("unknown formatter configuration field");
-    if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name) || names.has(name)) throw new Error("formatter names must be unique stable identifiers");
-    if (!Array.isArray(extensions) || !extensions.length || !extensions.every(extension => typeof extension === "string" && (extension === "*" || /^\.[A-Za-z0-9]+$/.test(extension)))) throw new Error("formatter extensions must contain dotted extensions or *");
-    if (!Array.isArray(command) || !command.length || !command.every(argument => typeof argument === "string" && !argument.includes("\0")) || !command[0]?.trim() || !command.some(argument => argument.includes("$FILE"))) throw new Error("formatter command must be literal argv containing $FILE");
-    if (disabled !== undefined && typeof disabled !== "boolean") throw new Error("formatter disabled must be boolean");
-    names.add(name);
-    return { name, extensions: extensions as string[], command: command as string[], ...(disabled === undefined ? {} : { disabled }) };
-  });
-}
-
-/** Absolute filename substitution prevents option and shell parsing of model paths. */
-export async function planFormatters(root: string, paths: readonly string[], configs: readonly FormatterConfig[]): Promise<FormatterPlan[]> {
-  const definitions = validateFormatters(configs), plans: FormatterPlan[] = [];
-  const known = new Set<string>();
-  for (const path of paths) {
-    const absolute = resolve(root, path);
-    if (known.has(absolute)) continue;
-    known.add(absolute);
-    const source = await readEditableFile(root, path);
-    if (source.version === null) throw new Error(`formatter target is missing: ${path}`);
-    for (const config of definitions) if (!config.disabled && (config.extensions.includes("*") || config.extensions.includes(extname(absolute))))
-      plans.push({ formatter: config.name, path, input: { argv: config.command.map(argument => argument.replaceAll("$FILE", absolute)), cwd: root } });
-  }
-  return plans;
-}
-
-/** Every command returns its real receipt; stop after failure or cancellation. */
-export async function runConfiguredFormatters(plans: readonly FormatterPlan[], invokeHost: (input: NativeCommandInput, signal?: AbortSignal) => Promise<ToolResult>, signal?: AbortSignal): Promise<{ plan: FormatterPlan; result: ToolResult }[]> {
-  const results: { plan: FormatterPlan; result: ToolResult }[] = [];
-  for (const plan of plans) {
-    if (signal?.aborted) break;
-    const result = await invokeHost(plan.input, signal);
-    results.push({ plan, result });
-    if (!result.ok || result.outcome?.status === "stopped") break;
-  }
-  return results;
-}

package/src/runtime/foundation.ts

@@ -1,116 +0,0 @@
-/** Foundations use the existing catalog, broker, permission and checkpoint owners. */
-import { parsePermissionRule, type PermissionRule } from "../core/permissions.ts";
-import { parsePatch, patchPaths } from "../core/patch.ts";
-import { parseWebSearchConfig } from "../core/web-content.ts";
-import { lastTurnChanges } from "../core/review.ts";
-import { discoverTargetInstructions, renderTargetInstructions } from "../store/context-files.ts";
-import { createPatchTool } from "./patch-tool.ts";
-import { createDiffTool } from "./review-tool.ts";
-import { createQuestionTool, type QuestionSlot } from "./question-tool.ts";
-import { createWebFetchTool, createWebSearchTool } from "./web-tools.ts";
-import { LspManager, parseLspConfig } from "./lsp-client.ts";
-import { validateFormatters } from "./formatter.ts";
-import { createFormatterTool } from "./formatter-tool.ts";
-import { permissionResourceAction } from "./permission-resources.ts";
-import type { InstructionCheck, ToolContext, ToolDefinition } from "./tools.ts";
-import { McpManager } from "./mcp-client.ts";
-import { parseMcpServers } from "../core/mcp-config.ts";
-import type { ExtensionRegistry } from "./extensions.ts";
-import { join } from "node:path";
-import { getBlob } from "../store/blobs.ts";
-
-/**
- * Calls that only observe run and carry newly discovered rules (S.6 item 3:
- * OpenCode, Gemini CLI and Claude Code do the same). A change is still held
- * back until the rules have been read: the reason for blocking first was never
- * to notify after a modification (foundation-editing research).
- */
-const OBSERVING_TOOLS = new Set(["read", "query", "lsp"]);
-/** Assumed: more batches than any interleaving of live sessions sharing this runtime. */
-const RECENT_BATCHES = 16;
-
-export class FoundationRuntime {
-  readonly questionSlot: QuestionSlot;
-  /** Per batch (assistant event id): instruction key -> the call that carried it. */
-  private readonly batches = new Map<string, Map<string, string>>();
-  readonly mcp: McpManager;
-  readonly tools: ToolDefinition[];
-  readonly permissions: PermissionRule[];
-  private readonly lsp: LspManager;
-  constructor(workspace: string, config: Record<string, unknown>, offline: boolean, configDirectory: string, questionSlot: QuestionSlot = {}) {
-    this.questionSlot = questionSlot;
-    const servers = Object.fromEntries(Object.entries(parseMcpServers(config["mcp"])).map(([name, server]) => [name, offline && server.transport === "http" ? { ...server, enabled: false } : server]));
-    this.mcp = new McpManager(servers, { cwd: workspace, credentialsDirectory: join(configDirectory, "mcp-credentials") });
-    if (config["permissions"] !== undefined && !Array.isArray(config["permissions"])) throw Error("permissions must be an array");
-    this.permissions = Array.isArray(config["permissions"]) ? config["permissions"].map(parsePermissionRule) : [];
-    const lsp = parseLspConfig(config["lsp"]); this.lsp = new LspManager(workspace, lsp);
-    const formatters = config["formatters"] === undefined ? [] : validateFormatters(config["formatters"]);
-    const search = parseWebSearchConfig(config["webSearch"]);
-    const network = [createWebFetchTool(), createWebSearchTool(search)];
-    if (offline) for (const tool of network) tool.run = async () => ({ ok: false, content: "Network tools are unavailable in offline mode." });
-    this.tools = [createQuestionTool(this.questionSlot), createPatchTool(), createDiffTool({ lastTurn: async ctx => {
-      if (!ctx.historyEvents || !ctx.checkpointBlobs) throw Error("original checkpoint history is unavailable");
-      return { blobs: ctx.checkpointBlobs, ...lastTurnChanges(await ctx.historyEvents()) };
-    }, canRead: async (ctx, path) => await permissionResourceAction(ctx.root, path, ctx.rules ?? [], ctx.sessionRules ?? [], "diff") === "allow" }), ...network, ...(lsp.length ? [this.lsp.tool()] : [])];
-    this.tools.push({ ...createFormatterTool(formatters), branch: "none" });
-  }
-  async register(registry: ExtensionRegistry): Promise<void> {
-    for (const tool of this.tools) registry.installBuiltin(tool);
-    const discovered = await this.mcp.discover();
-    for (const integration of discovered.integrations) registry.api("xeno-mcp").registerIntegration(integration);
-  }
-  /** Calls are prepared one at a time in their batch, so "first to discover carries the rules" is deterministic. */
-  private claims(batch: string): Map<string, string> {
-    let claimed = this.batches.get(batch);
-    if (claimed === undefined) {
-      claimed = new Map();
-      this.batches.set(batch, claimed);
-      for (const old of this.batches.keys()) if (this.batches.size > RECENT_BATCHES) this.batches.delete(old);
-    }
-    return claimed;
-  }
-  async instructions(ctx: ToolContext, name: string, input: unknown, noContextFiles: boolean): Promise<InstructionCheck | null> {
-    if (noContextFiles || !["read", "write", "edit", "apply_patch", "query", "format", "lsp"].includes(name) || !input || typeof input !== "object") return null;
-    const args = input as Record<string, unknown>;
-    const paths = name === "apply_patch" ? patchPaths(parsePatch(String(args["patchText"]))) : typeof args["path"] === "string" ? [args["path"]] : Array.isArray(args["paths"]) ? args["paths"].filter((path): path is string => typeof path === "string") : [];
-    if (!paths.length) return null;
-    const blocked = (content: string): InstructionCheck => ({ kind: "block", result: { ok: false, content } });
-    const known = new Set<string>();
-    const history = await ctx.historyEvents?.() ?? [];
-    // Rules count as read only once the model has seen them: results of this
-    // same batch may already be committed, but they reach the model together
-    // with this call's result. Within the batch, claims decide instead.
-    const batch = history.findLast(event => event.t === "assistant");
-    const sameBatch = new Set(batch?.t === "assistant" ? batch.blocks.flatMap(block => block.type === "tool_use" ? [block.call_id] : []) : []);
-    for (const event of history) {
-      if (event.t !== "tool_result" || sameBatch.has(event.call_id)) continue;
-      for (const key of event.instructions?.keys ?? []) known.add(key);
-      let data: unknown = event.data;
-      if (event.data_ref && ctx.outputStore) {
-        const saved = await getBlob(ctx.outputStore, event.data_ref.sha256);
-        if (saved) data = JSON.parse(saved) as unknown;
-      }
-      if (!data || typeof data !== "object" || Array.isArray(data)) continue;
-      const receipt = data as Record<string, unknown>;
-      if (receipt["kind"] !== "scoped_instructions") continue;
-      const keys = receipt["keys"]; if (Array.isArray(keys)) for (const key of keys) if (typeof key === "string") known.add(key);
-    }
-    const found = await discoverTargetInstructions({ workspace: ctx.root, paths, known,
-      canRead: async path => await permissionResourceAction(ctx.root, path, ctx.rules ?? [], ctx.sessionRules ?? []) === "allow" });
-    if (found.notices.some(notice => notice.kind === "skipped" && notice.reason === "instruction read permission is unavailable")) return blocked("Scoped instructions require read permission before this operation.");
-    const files = found.files.filter(file => !ctx.frozenSystem?.().includes(file.content));
-    if (!files.length) return null;
-    for (const file of files) if (await permissionResourceAction(ctx.root, file.path, ctx.rules ?? [], ctx.sessionRules ?? []) !== "allow") return blocked("Scoped instructions require read permission before this operation.");
-    // Once per batch: a later call in the same assistant message does not receive the same rules again.
-    const claimed = this.claims(batch?.id ?? "");
-    const fresh = files.filter(file => !claimed.has(file.key));
-    const carriers = [...new Set(files.flatMap(file => claimed.get(file.key) ?? []))];
-    for (const file of fresh) claimed.set(file.key, ctx.callId ?? name);
-    if (OBSERVING_TOOLS.has(name)) return fresh.length ? { kind: "attach", instructions: { keys: fresh.map(file => file.key), text: renderTargetInstructions(fresh) } } : null;
-    const earlier = carriers.length ? `Scoped instructions for this target were attached to the result of ${carriers.join(", ")} in this batch. ` : "";
-    if (!fresh.length) return blocked(`${earlier}No original operation was executed. Follow them, then retry.`);
-    return { kind: "block", result: { ok: false, content: `Scoped instructions were discovered. ${earlier}Read and follow them before deciding whether to retry the original operation. No original operation was executed.\n\n` + renderTargetInstructions(fresh),
-      data: { kind: "scoped_instructions", keys: fresh.map(file => file.key), files: fresh.map(file => ({ path: file.path, scope: file.scope, key: file.key, content: file.content, truncated: file.truncated })) } } };
-  }
-  async dispose(): Promise<void> { await Promise.all([this.lsp.dispose(), this.mcp.dispose()]); }
-}

package/src/runtime/history-cache.ts

@@ -1,57 +0,0 @@
-/** O.15: a disposable cache over already verified source contributions. */
-import { createHash } from "node:crypto";
-import type { LogEvent } from "../core/events.ts";
-import { HISTORY_INDEX_VERSION, historyKeyInput, historyEntries, historyIndex } from "../core/history-query.ts";
-
-type View = { entries: ReturnType<typeof historyEntries>; indexed: ReturnType<typeof historyIndex> };
-function freeze(value: unknown): void {
-  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
-  for (const child of Object.values(value)) freeze(child);
-  Object.freeze(value);
-}
-function sealedMap<K, V>(source: ReadonlyMap<K, V>): ReadonlyMap<K, V> {
-  for (const value of source.values()) freeze(value);
-  // Object.freeze(Map) still permits set/delete. Expose only read methods,
-  // including a forEach that cannot leak the mutable backing map.
-  const view: ReadonlyMap<K, V> = {
-    size: source.size, has: key => source.has(key), get: key => source.get(key),
-    keys: () => source.keys(), values: () => source.values(), entries: () => source.entries(),
-    [Symbol.iterator]: () => source[Symbol.iterator](),
-    forEach(callback, thisArg) { for (const [key, value] of source) callback.call(thisArg, value, key, view); },
-  };
-  return Object.freeze(view);
-}
-export class HistoryCache {
-  private readonly capacity: number;
-  private readonly payloadBudget: number;
-  // Operational assumptions, not segment thresholds or a hard heap bound.
-  constructor(capacity = 8, payloadBudget = 4 * 1024 * 1024) {
-    if (!Number.isSafeInteger(capacity) || capacity < 0 || !Number.isSafeInteger(payloadBudget) || payloadBudget < 0) throw new RangeError("invalid history cache budget");
-    this.capacity = capacity; this.payloadBudget = payloadBudget;
-  }
-  private readonly views = new Map<string, { view: View; bytes: number }>();
-  private builds = 0;
-  private hits = 0;
-  private bytes = 0;
-  get statistics() { return { builds: this.builds, hits: this.hits, entries: this.views.size, payloadBytes: this.bytes }; }
-  clear(): void { this.views.clear(); this.bytes = 0; }
-  read(scope: string, nodes: readonly { node: number; events: readonly LogEvent[] }[], sealed: readonly { node: number; sha256: string }[], version = HISTORY_INDEX_VERSION): View {
-    const key = createHash("sha256").update(JSON.stringify([scope, sealed])).update(historyKeyInput(nodes, version)).digest("hex");
-    const cached = version === HISTORY_INDEX_VERSION ? this.views.get(key) : undefined;
-    if (cached) { this.hits++; this.views.delete(key); this.views.set(key, cached); return cached.view; }
-    this.builds++;
-    // Freeze a detached projection; never freeze the source log or session state.
-    const entries = structuredClone(historyEntries(nodes)); freeze(entries);
-    const indexed = historyIndex(entries);
-    const view = { entries, indexed: { byEvent: sealedMap(indexed.byEvent), byResource: sealedMap(indexed.byResource), byWork: sealedMap(indexed.byWork) } };
-    freeze(view);
-    const bytes = new TextEncoder().encode(JSON.stringify(entries)).length;
-    if (version !== HISTORY_INDEX_VERSION || this.capacity === 0 || bytes > this.payloadBudget) return view;
-    this.views.set(key, { view, bytes }); this.bytes += bytes;
-    while (this.views.size > this.capacity || this.bytes > this.payloadBudget) {
-      const oldest = this.views.keys().next().value!;
-      this.bytes -= this.views.get(oldest)!.bytes; this.views.delete(oldest);
-    }
-    return view;
-  }
-}