@visual-z/xeno 0.1.4 → 0.2.1

package/src/runtime/extension-loader.ts

@@ -0,0 +1,37 @@
+/** Reload local dependency graphs without clearing unrelated process modules. */
+import { dirname, isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+export async function loadExtensionFactory(path: string, generation: number): Promise<unknown> {
+  // Pi uses a fresh jiti loader with moduleCache:false. Bun can rebuild the
+  // local graph itself, so this adds no production loader dependency (D13).
+  const result = await Bun.build({ entrypoints: [path], target: "bun", format: "esm",
+    plugins: [{ name: "extension-local-graph", setup(build) {
+      build.onResolve({ filter: /^[^./]/ }, args => {
+        if (isAbsolute(args.path) || args.path.startsWith("node:") || args.path.startsWith("bun:")) return undefined;
+        // A package belongs to the extension's installation. Never auto-install
+        // dependencies or resolve them against the current workspace.
+        return { path: Bun.resolveSync(args.path, dirname(args.importer || path)), external: true };
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async args => {
+        const url = pathToFileURL(args.path).href;
+        const transpiler = new Bun.Transpiler({ loader: /tsx$/.test(args.path) ? "tsx" : /jsx$/.test(args.path) ? "jsx" : "ts",
+          define: { "import.meta.url": JSON.stringify(url), "import.meta.dir": JSON.stringify(dirname(args.path)),
+            "import.meta.dirname": JSON.stringify(dirname(args.path)), "import.meta.path": JSON.stringify(args.path),
+            "import.meta.filename": JSON.stringify(args.path), "import.meta.main": "false" } });
+        return { contents: transpiler.transformSync(await Bun.file(args.path).text()), loader: "js" };
+      });
+    } }] });
+  if (!result.success || !result.outputs[0]) throw new Error(result.logs.map(log => log.message).join("\n") || "Extension build failed");
+  const code = await result.outputs[0].text() + `\n//# sourceURL=${pathToFileURL(path).href}?generation=${generation}\n`;
+  // A fresh file gives Bun an ordinary module identity without its data-URL
+  // path-length limit. The original import.meta locations were frozen above.
+  const staging = await mkdtemp(join(tmpdir(), "xeno-extension-module-"));
+  try {
+    const entry = join(staging, "extension.mjs"); await Bun.write(entry, code);
+    const module: { default?: unknown } = await import(pathToFileURL(entry).href);
+    return module.default;
+  } finally { await rm(staging, { recursive: true, force: true }); }
+}

package/src/runtime/extension-ui.ts

@@ -0,0 +1,55 @@
+/** Structural Pi UI contract; the runtime never constructs or owns a terminal (D19). */
+import type { TUI, OverlayHandle, OverlayOptions } from "../vendor/pi-tui/tui.ts";
+import type { EditorComponent } from "../vendor/pi-tui/editor-component.ts";
+import type { EditorTheme } from "../vendor/pi-tui/components/editor.ts";
+import type { AutocompleteProvider } from "../vendor/pi-tui/autocomplete.ts";
+import type { KeybindingsManager } from "../vendor/pi-tui/keybindings.ts";
+import type { Theme } from "../core/theme.ts";
+
+export interface ExtensionComponent { render(width: number): string[]; invalidate?(): void; handleInput?(data: string): void; dispose?(): void; focused?: boolean }
+export interface ExtensionTheme extends Theme {
+  fg(color: string, text: string): string; bg(color: string, text: string): string;
+  bold(text: string): string; italic(text: string): string; underline(text: string): string; dim(text: string): string; inverse(text: string): string; strikethrough(text: string): string;
+  getFgAnsi(color: string): string; getBgAnsi(color: string): string;
+  getColorMode(): "truecolor"; getThinkingBorderColor(level: string): (text: string) => string; getBashModeBorderColor(): (text: string) => string;
+}
+export type WidgetFactory = (tui: TUI, theme: ExtensionTheme) => ExtensionComponent;
+export type EditorFactory = (tui: TUI, theme: EditorTheme, bindings: KeybindingsManager) => EditorComponent & { dispose?(): void; focused?: boolean };
+export type AutocompleteFactory = (base: AutocompleteProvider) => AutocompleteProvider;
+export interface FooterData { getGitBranch(): string | undefined; getExtensionStatuses(): ReadonlyMap<string, string>; onBranchChange(callback: () => void): () => void }
+export type FooterFactory = (tui: TUI, theme: ExtensionTheme, data: FooterData) => ExtensionComponent;
+export interface DialogOptions { signal?: AbortSignal; timeout?: number }
+export interface CustomOptions extends DialogOptions { overlay?: boolean; overlayOptions?: OverlayOptions | (() => OverlayOptions); onHandle?: (handle: OverlayHandle) => void }
+export type InputHandler = (data: string) => { consume?: boolean; data?: string } | undefined;
+export interface ExtensionUI {
+  select(title: string, options: string[], opts?: DialogOptions): Promise<string | undefined>;
+  confirm(title: string, message: string, opts?: DialogOptions): Promise<boolean>;
+  input(title: string, placeholder?: string, opts?: DialogOptions): Promise<string | undefined>;
+  editor(title: string, prefill?: string): Promise<string | undefined>;
+  custom<T>(factory: (tui: TUI, theme: ExtensionTheme, bindings: KeybindingsManager, done: (result: T) => void) => ExtensionComponent | Promise<ExtensionComponent>, options?: CustomOptions): Promise<T>;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+  onTerminalInput(handler: InputHandler): () => void;
+  setStatus(key: string, text: string | undefined): void;
+  setWorkingMessage(message?: string): void; setWorkingVisible(visible: boolean): void;
+  setWorkingIndicator(options?: { frames?: string[]; intervalMs?: number }): void;
+  setHiddenThinkingLabel(label?: string): void;
+  setWidget(key: string, content: string[] | WidgetFactory | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+  setFooter(factory: FooterFactory | undefined): void; setHeader(factory: WidgetFactory | undefined): void;
+  setTitle(title: string): void;
+  pasteToEditor(text: string): void; setEditorText(text: string): void; getEditorText(): string;
+  addAutocompleteProvider(factory: AutocompleteFactory): void;
+  setEditorComponent(factory: EditorFactory | undefined): void; getEditorComponent(): EditorFactory | undefined;
+  readonly theme: ExtensionTheme;
+  getAllThemes(): { name: string; path: string | undefined }[];
+  getTheme(name: string): ExtensionTheme | undefined;
+  setTheme(theme: string | ExtensionTheme): { success: boolean; error?: string };
+  getToolsExpanded(): boolean; setToolsExpanded(expanded: boolean): void;
+}
+
+/** Headless extensions can notify and inspect capability; interactive requests fail explicitly. */
+export function headlessUI(notify: ExtensionUI["notify"]): ExtensionUI {
+  return new Proxy({ notify }, { get(target, key) {
+    if (key === "notify") return target.notify;
+    return () => { throw new Error("Extension UI requires an interactive terminal; check ctx.hasUI"); };
+  } }) as ExtensionUI;
+}

package/src/runtime/extensions.ts

@@ -0,0 +1,273 @@
+/** Pi's factory/registration protocol, attached to xeno's session rather than another AgentSession. */
+import { loadExtensionFactory } from "./extension-loader.ts";
+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 { runTool, type ToolContext, type ToolDefinition } from "./tools.ts";
+import { attachImageBytes } from "./images.ts";
+import type { ExtensionComponent, ExtensionUI, ExtensionTheme } from "./extension-ui.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;
+  promptSnippet?: string; promptGuidelines?: string[]; executionMode?: "parallel" | "sequential";
+  prepareArguments?(input: unknown): unknown;
+  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 }[];
+  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;
+  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 {
+  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>>();
+  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 disposed = false;
+  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 = Promise.resolve().then(operation).catch(error => this.report(String(error))).finally(() => this.pending.delete(pending));
+    this.pending.add(pending);
+  }
+  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 (!/^[a-zA-Z0-9_-]+$/.test(tool.name) || typeof tool.execute !== "function") throw new Error("Invalid tool definition");
+        if (["note", "history", "branch", "resolve"].includes(tool.name)) throw new Error(`${tool.name} owns the append-only harness and cannot be replaced`);
+        extensionSchema(tool.parameters); this.insert(this.tools, tool.name, tool, source);
+      },
+      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().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) => this.active().exec(command, args, options),
+      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];
+      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> {
+    return 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",
+      ...(tool.prepareArguments ? { prepareArguments: tool.prepareArguments } : {}),
+      run: async (ctx: ToolContext, raw: Record<string, unknown>) => {
+        let nested = 0;
+        const context = { ...this.active().context(), signal: ctx.signal, tools: this.active().getTools(),
+          executeTool: async (target: string, input: unknown) => {
+            if (++nested > 32 || (ctx.extensionDepth ?? 0) >= 32 || target === name) return { isError: true, content: [{ type: "text", text: "Nested tool recursion refused" }] };
+            const out = await runTool({ ...ctx, extensionDepth: (ctx.extensionDepth ?? 0) + 1, callId: `${ctx.callId ?? name}/${nested}` }, target, input);
+            return { isError: !out.ok, content: [{ type: "text", text: out.content }], details: out.data };
+          } };
+        const result = await tool.execute(ctx.callId ?? name, raw, ctx.signal, update => {
+          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")));
+        }, 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,
+          ...(isJsonValue(result.details) ? { data: result.details } : {}), ...(images.length ? { images } : {}) };
+      },
+    }]));
+  }
+  toolHooks(): NonNullable<ToolContext["extensionHooks"]> {
+    return {
+      before: async (toolName, input, toolCallId) => {
+        const blocked = (await this.emit("tool_call", { toolName, input, toolCallId })).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 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;
+  }
+}
+
+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" || typeof schema["properties"] !== "object" || schema["properties"] === null) throw new Error("Tool parameters need object properties");
+  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/images.ts

@@ -0,0 +1,76 @@
+/** Pi (MIT) processing, xeno (D8) immutable storage; decoding stays outside core and off the TUI thread. */
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { resizeImage } from "../vendor/pi-rich/image-resize.ts";
+import { detectSupportedImageMimeType } from "../vendor/pi-rich/mime.ts";
+import { convertImageBytesToPng, convertToPng } from "../vendor/pi-rich/image-convert.ts";
+import { putBlob, getBlobBytes } from "../store/blobs.ts";
+import { imageDescription, validImageRef, type ImageRef } from "../core/images.ts";
+import type { ContentBlock, Message } from "../core/project.ts";
+
+// Admission limit, not a context threshold: avoid reading arbitrarily large local binaries into WASM.
+const MAX_IMAGE_SOURCE_BYTES = 64 * 1024 * 1024;
+export async function attachImageBytes(bytes: Uint8Array, name: string, blobDir: string, autoResize = true): Promise<ImageRef> {
+  if (bytes.byteLength > MAX_IMAGE_SOURCE_BYTES) throw new Error("Image exceeds the 64 MiB attachment limit");
+  let mime = detectSupportedImageMimeType(bytes);
+  if (!mime) throw new Error("Unsupported or malformed image: " + name);
+  const originalBytes = bytes;
+  if (mime === "image/bmp") {
+    const converted = await convertImageBytesToPng(bytes);
+    if (!converted) throw new Error("Cannot decode image: " + name);
+    bytes = converted; mime = "image/png";
+  }
+  // Pi's disabled auto-resize setting preserves the input; decoding still verifies its dimensions.
+  const result = await resizeImage(bytes, mime, autoResize ? undefined : { maxWidth: Number.MAX_SAFE_INTEGER, maxHeight: Number.MAX_SAFE_INTEGER, maxBytes: Number.MAX_SAFE_INTEGER });
+  if (!result) throw new Error("Cannot decode or resize image: " + name);
+  if (result.mimeType !== "image/png" && result.mimeType !== "image/jpeg" && result.mimeType !== "image/gif" && result.mimeType !== "image/webp") {
+    throw new Error("Unsupported image encoding: " + result.mimeType);
+  }
+  const original = await putBlob(blobDir, originalBytes);
+  const encoded = Buffer.from(result.data, "base64");
+  const sha256 = await putBlob(blobDir, encoded);
+  return { sha256, mimeType: result.mimeType, width: result.width, height: result.height, bytes: encoded.length, name,
+    ...(sha256 !== original ? { original: { sha256: original, width: result.originalWidth, height: result.originalHeight } } : {}) };
+}
+export async function attachImageFile(path: string, blobDir: string, autoResize = true): Promise<ImageRef | null> {
+  const size = (await stat(path)).size;
+  if (size > MAX_IMAGE_SOURCE_BYTES) {
+    if (/\.(png|jpe?g|gif|webp|bmp)$/i.test(path)) throw new Error("Image exceeds the 64 MiB attachment limit");
+    return null;
+  }
+  const bytes = await readFile(path);
+  if (!detectSupportedImageMimeType(bytes)) {
+    if (/\.(png|jpe?g|gif|webp|bmp)$/i.test(path)) throw new Error("Unsupported or malformed image: " + path);
+    return null;
+  }
+  return attachImageBytes(bytes, basename(path), blobDir, autoResize);
+}
+export async function loadImage(image: ImageRef, blobDir: string): Promise<string> {
+  if (!validImageRef(image)) throw new Error("Invalid image reference");
+  const bytes = await getBlobBytes(blobDir, image.sha256);
+  if (!bytes) throw new Error("Image blob is missing: " + image.name);
+  if (bytes.length !== image.bytes) throw new Error("Image blob size mismatch: " + image.name);
+  return Buffer.from(bytes).toString("base64");
+}
+/** Kitty accepts PNG; conversion is display-only and never replaces durable provider bytes. */
+export async function loadDisplayImage(image: ImageRef, blobDir: string): Promise<string> {
+  const png = await convertToPng(await loadImage(image, blobDir), image.mimeType);
+  if (!png) throw new Error("Cannot display image: " + image.name);
+  return png.data;
+}
+export async function hydrateImages(messages: readonly Message[], blobDir: string, acceptsImages: boolean, blocked = false): Promise<Message[]> {
+  const loaded = new Map<string, Promise<string>>();
+  return Promise.all(messages.map(async message => ({ ...message, content: await Promise.all(message.content.map(async (block): Promise<ContentBlock> => {
+    if (block.type !== "image") return block;
+    if (blocked || block.image.blocked || !acceptsImages) return { type: "text", text: imageDescription(block.image) + (blocked || block.image.blocked ? " [image transmission blocked by settings]" : " [this model does not support image input]") };
+    let data = loaded.get(block.image.sha256);
+    if (!data) { data = loadImage(block.image, blobDir); loaded.set(block.image.sha256, data); }
+    return { ...block, data: await data };
+  })) })));
+}
+
+/** Provider boundary fails closed if storage hydration was accidentally skipped. */
+export function imageData(block: Extract<ContentBlock, { type: "image" }>): string {
+  if (!block.data) throw new Error("Image was not loaded before provider encoding: " + block.image.name);
+  return block.data;
+}