@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/extensions.ts

@@ -1,11 +1,15 @@
 /** 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 { runTool, type ToolContext, type ToolDefinition } from "./tools.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;
@@ -35,6 +39,8 @@ export interface ExtensionToolRenderContext {
 }
 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;
   execute(id: string, args: Record<string, unknown>, signal: AbortSignal | undefined,
@@ -52,6 +58,7 @@ export interface ExtensionActions {
   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 }>;
@@ -60,6 +67,7 @@ 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;
@@ -106,11 +114,16 @@ export class ExtensionRegistry {
   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; }
 
@@ -124,8 +137,10 @@ export class ExtensionRegistry {
     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));
+    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}`); }
@@ -146,9 +161,42 @@ export class ExtensionRegistry {
       },
       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`);
+        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`);
@@ -166,13 +214,27 @@ export class ExtensionRegistry {
       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(),
+      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) => this.active().exec(command, args, options),
+      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)); } },
@@ -183,7 +245,7 @@ export class ExtensionRegistry {
   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 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)]));
@@ -218,36 +280,47 @@ export class ExtensionRegistry {
     return true;
   }
   definitions(): ReadonlyMap<string, ToolDefinition> {
-    return new Map<string, ToolDefinition>([...this.tools].map(([name, tool]) => [name, {
+    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 } : {}),
       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 };
+            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 result = await tool.execute(ctx.callId ?? name, raw, ctx.signal, update => {
+        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")));
-        }, context);
+        };
+        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,
-          ...(isJsonValue(result.details) ? { data: result.details } : {}), ...(images.length ? { images } : {}) };
+          ...(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);
+    return definitions;
   }
   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);
+      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); },
@@ -255,12 +328,18 @@ export class ExtensionRegistry {
   }
   async dispose(): Promise<void> {
     if (this.disposed) return;
+    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> {
+    const released = await Promise.all([...this.integrations.values()].map(owner => owner.releaseForReload()));
+    return released.every(Boolean);
+  }
 }
 
 function extensionSchema(parameters: unknown): ToolDefinition["input_schema"] {

package/src/runtime/harness-comparison.ts

@@ -8,6 +8,8 @@ import { Session } from "./loop.ts";
 import { buildRequest, OpenAICompletionsProvider } from "./openai.ts";
 import type { Provider, ProviderConfig, ToolSchema, Turn } from "./provider.ts";
 import { DEFAULT_TOOL_CONTEXT, TOOL_SCHEMAS, runTool, type ToolResult } from "./tools.ts";
+import { openTrialControl } from "./trial-control.ts";
+import type { TrialLifecycle } from "../core/trial-lifecycle.ts";
 
 export const COMPARISON_TOOLS = ["read", "grep", "find", "ls", "write", "edit", "query"] as const;
 export const COMPARISON_SYSTEM = "Use the supplied file tools to solve the user's task. " +
@@ -202,6 +204,7 @@ export function comparisonGateway(options: {
 }
 
 export interface ComparisonResult {
+  lifecycle?: TrialLifecycle;
   arm: ComparisonArm;
   status: "answered" | "error" | "budget" | "balance" | "stopped";
   response: string;
@@ -221,20 +224,25 @@ export async function runComparison(options: {
   arm: ComparisonArm; directory: string; workspace: string; prompt: string; config: ProviderConfig;
   price: BenchmarkPrice; ledger: ComparisonLedger; backend: ComparisonBackend;
   maxRequests: number; timeoutMs: number; pi: PiIdentity | null; extension: string;
+  signal?: AbortSignal;
   onRequest?: (record: GatewayRecord) => Promise<void>;
   /** Synthetic pressure only; live comparisons preserve Pi's default compaction. */
   piCompaction?: { reserveTokens: number; keepRecentTokens: number };
 }): Promise<ComparisonResult> {
   const started = performance.now(), outputStore = join(options.directory, "observations");
   await mkdir(outputStore, { recursive: true });
-  const gateway = comparisonGateway({ ...options, record: async (record) => {
+  const gateway = comparisonGateway({ ...options, backend: async (payload, signal) => {
+    control.beginBackend();
+    return options.backend(payload, AbortSignal.any([signal, control.signal]));
+  }, record: async (record) => {
     await appendFile(join(options.directory, "requests.jsonl"), JSON.stringify(record) + "\n");
     await options.onRequest?.(record);
   }, executeTool: (name, input) => runTool({ ...DEFAULT_TOOL_CONTEXT, root: options.workspace, allow: COMPARISON_TOOLS, outputStore }, name, input) });
   let response = "", cuts = 0, toolCalls = 0, toolFailures = 0, reason = "no completion";
   let status: ComparisonResult["status"] = "stopped";
   const config = { ...options.config, spec: { ...options.config.spec, baseUrl: gateway.url } };
-  const signal = AbortSignal.timeout(options.timeoutMs);
+  const control = await openTrialControl(options.timeoutMs, options.signal, () => gateway.close()), signal = control.signal;
+  let session: Session | undefined, cleanupFailed = false;
   try {
     if (options.arm !== "pi") {
       await mkdir(join(options.directory, "log"));
@@ -244,10 +252,11 @@ export async function runComparison(options: {
         response = turn.blocks.filter((block) => block.type === "text").map((block) => block.text).join("\n");
         return turn;
       } };
-      const session = new Session({ logDir: join(options.directory, "log"), frozen: { system: COMPARISON_SYSTEM, tools: comparisonTools() },
+      session = new Session({ logDir: join(options.directory, "log"), frozen: { system: COMPARISON_SYSTEM, tools: comparisonTools() },
         tools: { ...DEFAULT_TOOL_CONTEXT, root: options.workspace, allow: COMPARISON_TOOLS, outputStore },
         contextPolicy: options.arm === "xeno-windowed" ? "windowed" : "continuous", maxTurns: options.maxRequests, harnessReviews: false }, provider);
       await session.start();
+      control.enterExecution();
       for await (const event of session.send(options.prompt, signal)) {
         if (event.kind === "cut") cuts++;
         if (event.kind === "tool_call") toolCalls++;
@@ -257,21 +266,32 @@ export async function runComparison(options: {
       if (["stop", "end_turn"].includes(reason)) status = "answered";
     } else {
       if (!options.pi) throw new Error("Pi identity required");
+      control.enterExecution();
       const run = await runPiPrompt({ directory: options.directory, workspace: options.workspace, prompt: options.prompt, config,
         gateway, price: options.price, pi: options.pi, extension: options.extension, signal, resume: false,
         ...(options.piCompaction ? { piCompaction: options.piCompaction } : {}) });
       ({ response, reason, cuts, toolCalls, toolFailures } = run);
       status = run.answered ? "answered" : "error";
     }
-  } catch { status = "error"; reason = signal.aborted ? "timeout" : "harness failed; inspect local request and session evidence"; }
-  finally { await gateway.close(); }
+  } catch { status = "error"; reason = "harness failed; inspect local request and session evidence"; }
+  finally {
+    control.finishWork();
+    try { await session?.dispose(); } catch { cleanupFailed = true; options.ledger.halted = true; }
+    try { await gateway.close(); } catch { cleanupFailed = true; options.ledger.halted = true; }
+  }
   if (gateway.stopped) {
     status = gateway.stopped === "budget" || gateway.stopped === "balance" ? gateway.stopped : gateway.stopped === "limit" ? "stopped" : "error";
-    reason = signal.aborted ? "timeout" : `model gateway: ${gateway.stopped}`;
+    reason = `model gateway: ${gateway.stopped}`;
+  }
+  const lifecycle = control.observe(cleanupFailed ? "failed" : "complete");
+  if (lifecycle.interruption) {
+    status = lifecycle.interruption.source === "deadline" ? "error" : "stopped";
+    reason = lifecycle.interruption.source === "deadline" ? "timeout" : "cancelled";
   }
+  if (cleanupFailed) { status = "error"; reason = "execution_error"; }
   const usage: BenchmarkUsage = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 };
   for (const row of gateway.records) if (row.usage) for (const key of Object.keys(usage) as (keyof BenchmarkUsage)[]) usage[key] += row.usage[key];
-  return { arm: options.arm, status, response, requests: gateway.requests, cuts, toolCalls, toolFailures,
+  return { arm: options.arm, status, response, requests: gateway.requests, cuts, toolCalls, toolFailures, lifecycle,
     charged: gateway.records.reduce((n, row) => n + row.charge, 0),
     reservedUnknown: gateway.records.reduce((n, row) => n + (row.measured === null ? row.charge : 0), 0),
     usage, wallMs: performance.now() - started, reason,