@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/session-hub.ts

@@ -1,85 +0,0 @@
-/** A hub owns live sessions, not transcript mirrors. Durable listing stays a store projection. */
-import type { SessionControl } from "./session-control.ts";
-import { basename } from "node:path";
-
-// Assumed live-owner bound includes admitted opens, so concurrent requests cannot exceed it.
-export const MAX_LIVE_SESSIONS = 32;
-
-export interface SessionHubHost {
-  list(): Promise<unknown>;
-  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl>;
-  dispose(control: SessionControl): Promise<void>;
-}
-export class SessionHub {
-  private readonly controls = new Map<string, SessionControl>();
-  private readonly opening = new Set<Promise<SessionControl>>();
-  private readonly resuming = new Map<string, Promise<SessionControl>>();
-  private readonly closing = new Map<string, Promise<void>>();
-  private reserved = 0;
-  private closed = false;
-  private disposal: Promise<void> | undefined;
-  private readonly host: SessionHubHost;
-  readonly initial: SessionControl;
-  constructor(initial: SessionControl, host: SessionHubHost) {
-    this.initial = initial; this.host = host; this.controls.set(initial.threadId, initial);
-  }
-  get(threadId: string): SessionControl {
-    if (this.closed || this.closing.has(threadId)) throw Error("session hub or thread is closing");
-    const control = this.controls.get(threadId);
-    if (!control) throw Error("unknown or closed threadId; resume the session first");
-    return control;
-  }
-  async list(): Promise<unknown> { if (this.closed) throw Error("session hub is closing"); return this.host.list(); }
-  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl> {
-    if (this.closed) return Promise.reject(Error("session hub is closing; no new session was admitted"));
-    const captured = structuredClone(params);
-    // Coalesce resume only. Two explicit new/fork requests create two distinct sessions.
-    const key = kind === "resume" ? JSON.stringify(captured) : "";
-    const pending = key ? this.resuming.get(key) : undefined;
-    if (pending) return pending;
-    const requested = captured["session"];
-    const known = kind === "resume" && [...this.controls.values()].some(control => !this.closing.has(control.threadId)
-      && [control.threadId, control.session.config.logDir, basename(control.session.config.logDir)].includes(String(requested)));
-    if (!known && this.controls.size + this.reserved >= MAX_LIVE_SESSIONS) return Promise.reject(Error("live session limit reached; close a session first"));
-    if (!known) this.reserved++;
-    const operation = (async () => {
-      try {
-        const control = await this.host.open(kind, captured), existing = this.controls.get(control.threadId);
-        if (this.closing.has(control.threadId) || !existing && this.controls.size >= MAX_LIVE_SESSIONS) {
-          if (existing !== control) await this.host.dispose(control);
-          throw Error("thread is closing or the live session limit was reached");
-        }
-        if (existing && existing !== control) { await this.host.dispose(control); if (this.closed) throw Error("session hub closed during opening"); return existing; }
-        this.controls.set(control.threadId, control);
-        if (this.closed) throw Error("session hub closed during opening; the admitted owner will be drained");
-        return control;
-      } finally { if (!known) this.reserved--; }
-    })();
-    this.opening.add(operation); if (key) this.resuming.set(key, operation);
-    // Observe rejected opens without changing the caller's promise or leaking unhandled cleanup rejections.
-    void operation.finally(() => { this.opening.delete(operation); if (key) this.resuming.delete(key); }).catch(() => {});
-    return operation;
-  }
-  close(threadId: string): Promise<void> {
-    const pending = this.closing.get(threadId); if (pending) return pending;
-    const control = this.controls.get(threadId); if (!control) return Promise.reject(Error("unknown or closed threadId"));
-    const operation = (async () => {
-      if (control.activeTurnId) control.interrupt(control.activeTurnId);
-      await control.whenIdle().catch(() => {});
-      await this.host.dispose(control); this.controls.delete(threadId);
-    })();
-    this.closing.set(threadId, operation);
-    void operation.then(() => { if (this.closing.get(threadId) === operation) this.closing.delete(threadId); }, () => {});
-    return operation;
-  }
-  dispose(): Promise<void> {
-    if (this.disposal) return this.disposal;
-    this.closed = true;
-    return this.disposal = (async () => {
-      // Every kind is tracked; late publication belongs to this same draining generation.
-      await Promise.allSettled([...this.opening]);
-      const results = await Promise.allSettled([...this.controls.keys()].map(id => this.close(id)));
-      if (results.some(result => result.status === "rejected")) throw Error("session cleanup could not be confirmed");
-    })();
-  }
-}

package/src/runtime/stream-idle.ts

@@ -1,80 +0,0 @@
-/**
- * Abandons one attempt whose stream has gone silent.
- *
- * Without this a stream the network silently dropped waits until the user
- * presses Escape (Horizyn 2026-10-12: a request sat 5m39s before the socket
- * error surfaced). OpenAI's Codex CLI (`stream_idle_timeout_ms`, default
- * 300000) and Claude Code (300s) both cut a stream that delivers nothing for
- * five minutes against the same backends, so a live stream -- extended
- * thinking included -- is not that quiet. The limit is theirs, not measured
- * here (feat-stream-idle-watchdog).
- *
- * The clock starts when the request is sent, so it also bounds the wait for
- * the first byte, and restarts on anything received: body bytes where the
- * adapter owns fetch, stream events (pings included) where an SDK does.
- */
-
-export const STREAM_IDLE_MS = 300_000;
-
-/** retry.ts recognises this by name, so it need not import an adapter. */
-export class StreamIdleError extends Error {
-  constructor(ms: number) {
-    super(`no data from the provider for ${Math.round(ms / 1000)}s; the stream was abandoned`);
-    this.name = "StreamIdleError";
-  }
-}
-
-export class IdleWatch {
-  /** Pass this, not the caller's, to the request: it also aborts on silence. */
-  readonly signal: AbortSignal;
-  private readonly controller = new AbortController();
-  private timer: ReturnType<typeof setTimeout> | undefined;
-  private expired = false;
-  private readonly outer: AbortSignal | undefined;
-  private readonly ms: number;
-
-  constructor(outer: AbortSignal | undefined, ms: number = STREAM_IDLE_MS) {
-    this.outer = outer; this.ms = ms;
-    this.signal = outer === undefined ? this.controller.signal : AbortSignal.any([outer, this.controller.signal]);
-    this.touch();
-  }
-
-  touch(): void {
-    if (this.expired) return;
-    clearTimeout(this.timer);
-    this.timer = setTimeout(() => {
-      this.expired = true;
-      this.controller.abort(new StreamIdleError(this.ms));
-    }, this.ms);
-  }
-
-  /** A body that restarts the clock on every chunk. */
-  body(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-    return stream.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
-      transform: (chunk, sink) => { this.touch(); sink.enqueue(chunk); },
-    }));
-  }
-
-  /** An event stream that restarts the clock on every event. */
-  async *events<T>(source: AsyncIterable<T>): AsyncGenerator<T> {
-    for await (const event of source) { this.touch(); yield event; }
-  }
-
-  /**
-   * Whatever the abort surfaced as -- AbortError, a closed body, the SDK's
-   * own wrapper -- silence becomes StreamIdleError. The caller's own abort
-   * stays an abort: Escape must not start another attempt.
-   */
-  rethrow(error: unknown): never {
-    if (this.expired && this.outer?.aborted !== true) throw new StreamIdleError(this.ms);
-    throw error;
-  }
-
-  dispose(): void { clearTimeout(this.timer); }
-}
-
-/** Runs one attempt under its own idle watch, cleared however it ends. */
-export async function watchIdle<T>(outer: AbortSignal | undefined, ms: number | undefined, run: (idle: IdleWatch) => Promise<T>): Promise<T> {
-  const idle = new IdleWatch(outer, ms);
-  try { return await run(idle); } catch (error) { return idle.rethrow(error); } finally { idle.dispose(); }
-}

package/src/runtime/tool-broker.ts

@@ -1,137 +0,0 @@
-/** Pi A / D8 / D11: direct and nested execution share one admitted, durable call contract. */
-import type { AssistantBlock, ToolInvocationEvent } from "../core/events.ts";
-import { failureDiagnostic, NOT_STARTED, UNKNOWN_EFFECT, ToolFault } from "../core/tool-failure.ts";
-import { executionOutcome } from "../core/outcome.ts";
-import { finishToolResult, nativeCommandContext, NATIVE_COMMAND_NAME, normalizeToolInput, type ToolContext, type ToolResult, type NestedInvocationOptions } from "./tools.ts";
-import { ToolQueue } from "./tool-queue.ts";
-
-export type BrokerCall = Extract<AssistantBlock, { type: "tool_use" }>;
-type Mode = "parallel" | "exclusive";
-/** Inherits the existing extension limit, now shared by the entire invocation tree. */
-export const MAX_NESTED_CALLS = 32;
-export const MAX_NESTED_DEPTH = 32;
-/** Assumed per-call composition budget; direct large edits retain their existing interface. */
-export const MAX_NESTED_ARGUMENT_BYTES = 64 * 1024;
-/** Assumed log metadata bound; complete structured results are independent artifacts. */
-export const MAX_INLINE_RESULT_DATA_BYTES = 64 * 1024;
-
-export interface BrokerHost<Result extends ToolResult> {
-  parallelLimit: number;
-  callId(): string;
-  mode(call: BrokerCall): Mode;
-  invocation(call: BrokerCall, ctx: ToolContext, parent: ToolInvocationEvent | undefined): Promise<ToolInvocationEvent>;
-  /** Receives normalized input and must still apply admission, including Session-owned tools. */
-  prepare(call: BrokerCall, ctx: ToolContext): Promise<Result | (() => Promise<Result>)>;
-  /** Session annotations and branch receipts are accepted before their result becomes evidence. */
-  settle(result: Result): Promise<void>;
-  result(invocation: ToolInvocationEvent, result: Result): Promise<void>;
-}
-export interface BrokerReceipt<Result extends ToolResult> {
-  value: Result;
-  invocation: ToolInvocationEvent;
-  settle(): Promise<void>;
-  commit(): Promise<void>;
-}
-export type BrokerExecution<Result extends ToolResult> = (() => Promise<BrokerReceipt<Result>>) & { close(): Promise<void> };
-type Budget = { calls: number };
-type Parent = { invocation: ToolInvocationEvent; budget: Budget; depth: number };
-
-/** Scheduling belongs to a live scope; immutable requests/results belong to the host log. */
-export class ToolBroker<Result extends ToolResult = ToolResult> {
-  private readonly host: BrokerHost<Result>;
-  constructor(host: BrokerHost<Result>) { this.host = host; }
-
-  async prepare(call: BrokerCall, context: ToolContext, parent?: Parent): Promise<BrokerExecution<Result>> {
-    let actual = call;
-    let invalid: ToolResult | undefined;
-    try {
-      // Extension argument preparation cannot rewrite the already-recorded model
-      // request. Hooks receive the exact immutable value archived for admission.
-      actual = { ...call, input: freezeInput(structuredClone(normalizeToolInput(context, call.name, structuredClone(call.input)))) };
-    }
-    catch (error) { invalid = error instanceof ToolFault ? finishToolResult({ ok: false, content: error.message, diagnostic: error.diagnostic }) : refused(`Invalid ${call.name} arguments: ${String(error)}`); }
-    const invocation = await this.host.invocation(actual, context, parent?.invocation);
-    if (parent && invocation.input === undefined) invalid = refused("nested arguments exceed the inline composition budget or are not JSON; pass a bounded request or use the direct tool");
-    const budget = parent?.budget ?? { calls: 0 }, depth = (parent?.depth ?? 0) + 1;
-    const children = new ToolQueue(this.host.parallelLimit);
-    const pending = new Set<Promise<ToolResult>>();
-    const failures: string[] = [];
-    let incomplete = false;
-    const mode = this.host.mode(actual);
-    let open = true;
-    const invoke = (name: string, input: unknown, options?: NestedInvocationOptions, native = false): Promise<ToolResult> => {
-      if (!open) return Promise.resolve(refused("tool scope is closed; no invocation started"));
-      if (mode !== "exclusive") return Promise.resolve(refused("only an exclusive composing tool may request nested execution"));
-      if (depth >= MAX_NESTED_DEPTH || budget.calls >= MAX_NESTED_CALLS) return Promise.resolve(refused("nested tool budget exhausted; no invocation started"));
-      // Capture at submission, before an asynchronous queue can observe a
-      // caller's later mutation of the same object.
-      try { input = structuredClone(input); }
-      catch { return Promise.resolve(refused("nested arguments must be serializable; no invocation started")); }
-      budget.calls++;
-      const nested: BrokerCall = { type: "tool_use", call_id: this.host.callId(), name, input };
-      const signals = [ctx.signal, options?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
-      const nestedContext: ToolContext = native ? nativeCommandContext(ctx, options?.signal) : { ...ctx,
-        ...(signals.length ? { signal: AbortSignal.any(signals) } : {}) };
-      const result = children.submit(this.host.mode(nested), async () => {
-        const execute = await this.prepare(nested, nestedContext, { invocation, budget, depth });
-        return async () => {
-          const receipt = await execute();
-          await receipt.settle(); await receipt.commit();
-          if (!receipt.value.ok) failures.push(`nested call ${receipt.invocation.call_id} failed`);
-          return { ...receipt.value, invocation: { call_id: receipt.invocation.call_id, event: receipt.invocation.id } };
-        };
-      });
-      pending.add(result);
-      // The broker owns the lifetime even when extension code drops the promise.
-      void result.then(() => pending.delete(result), error => { incomplete = true; failures.push(`nested execution or persistence failed: ${String(error)}`); pending.delete(result); });
-      return result;
-    };
-    const ctx: ToolContext = { ...context, callId: call.call_id,
-      ...(parent ? { parentCallId: parent.invocation.call_id } : {}),
-      invoke: (name, input, options) => invoke(name, input, options),
-      runOwnedCommand: execute => children.submit("exclusive", async () => execute),
-      drainNested: () => children.whenIdle(),
-      invokeHost: (input, signal) => invoke(NATIVE_COMMAND_NAME, input, signal ? { signal } : {}, true) };
-    let closing: Promise<void> | undefined;
-    const close = () => {
-      open = false;
-      return closing ??= (async () => { await children.close(); await Promise.allSettled(pending); })();
-    };
-    let prepared: ToolResult | (() => Promise<Result>);
-    try { prepared = invalid ?? await this.host.prepare(actual, ctx); }
-    catch (error) { prepared = finishToolResult({ ok: false, content: String(error), diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }); }
-    return Object.assign(async () => {
-      let value: Result;
-      try { value = (typeof prepared === "function" ? await prepared() : prepared) as Result; }
-      catch (error) {
-        value = finishToolResult({ ok: false, content: `tool ${call.name} failed: ${String(error)}`,
-          diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }) as Result;
-      } finally {
-        await close();
-      }
-      if (failures.length) value = { ...value, warnings: [...(value.warnings ?? []),
-        failureDiagnostic("unknown_effect", `${failures.length} nested failures; inspect the original invocation receipts. ${failures[0]}`, UNKNOWN_EFFECT)] };
-      if (incomplete) value = { ...value, ok: false, outcome: executionOutcome("unknown"),
-        diagnostic: failureDiagnostic("unknown_effect", "nested execution or persistence did not produce a complete receipt", UNKNOWN_EFFECT) };
-      let settled: Promise<void> | undefined, committed: Promise<void> | undefined;
-      const settle = () => settled ??= this.host.settle(value);
-      return { value, invocation, settle,
-        commit: () => committed ??= settle().then(() => this.host.result(invocation, value)) };
-    }, { close });
-  }
-}
-
-function refused(message: string): ToolResult {
-  return finishToolResult({ ok: false, content: message, diagnostic: failureDiagnostic("invalid_input", message, NOT_STARTED) });
-}
-
-function freezeInput(value: unknown, ancestors = new Set<unknown>()): unknown {
-  if (value !== null && typeof value === "object") {
-    if (ancestors.has(value)) throw new Error("cyclic tool arguments are not JSON");
-    ancestors.add(value);
-    for (const child of Object.values(value)) freezeInput(child, ancestors);
-    ancestors.delete(value);
-    Object.freeze(value);
-  }
-  return value;
-}

package/src/runtime/tool-discovery.ts

@@ -1,58 +0,0 @@
-/** R11: a harness-owned discovery entry shares normal Session admission and result persistence. */
-import { createHash } from "node:crypto";
-import { discoverTools, MAX_DISCOVERY_QUERY, MAX_DISCOVERY_RESULTS, type DeclarationRequest } from "../core/tool-discovery.ts";
-import { decideWithSessionRules } from "../core/permissions.ts";
-import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
-import type { ToolSchema } from "./provider.ts";
-import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
-
-export const DISCOVERY_TOOL_NAME = "tool_search";
-export const DISCOVERY_TOOL: ToolDefinition = {
-  name: DISCOVERY_TOOL_NAME,
-  description: "Find optional registered tools by name or purpose. Reads the local catalog without connecting to services or executing tools. Returns purpose, important input types and declaration status. Matching permitted tools become declared only after the complete tool batch, for the next model request; then call them with their actual schema. Discovery does not grant execution permission or prove service health. Example: {\"query\":\"issue tracker\",\"limit\":3}.",
-  input_schema: { type: "object", properties: {
-    query: { type: "string", minLength: 1, maxLength: MAX_DISCOVERY_QUERY },
-    limit: { type: "integer", minimum: 1, maximum: MAX_DISCOVERY_RESULTS, description: "Maximum matches to request; defaults to 5." },
-  }, required: ["query"] },
-  access: "read", execution: "exclusive", branch: "none",
-  run: async () => ({ ok: false, content: "Tool discovery requires a live Session checkpoint." }),
-};
-
-/** Bind a request to the observed contract; an edited/replaced registration needs another lookup. */
-export function discoveryFingerprint(tool: ToolSchema): string {
-  return createHash("sha256").update(JSON.stringify({ name: tool.name, description: tool.description, input_schema: tool.input_schema })).digest("hex");
-}
-export function discoveryPermitted(ctx: ToolContext, name: string): boolean {
-  if (ctx.workflowMode === "plan" && ctx.extensions?.get(name)?.access !== "read") return false;
-  return decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], { tool: name }) !== "deny";
-}
-/** A directory entry without its matching live implementation is unavailable, regardless of history. */
-export function currentDeferredTools(ctx: ToolContext): readonly ToolSchema[] {
-  return (ctx.deferredTools ?? []).filter(tool => {
-    const definition = ctx.extensions?.get(tool.name);
-    return definition !== undefined && discoveryFingerprint(definition) === discoveryFingerprint(tool);
-  });
-}
-export function searchDeferredTools(ctx: ToolContext, input: Record<string, unknown>, declared: readonly string[]): ToolResult {
-  const catalog = currentDeferredTools(ctx);
-  let matches;
-  try { matches = discoverTools(catalog, input["query"] as string, input["limit"] as number | undefined); }
-  catch {
-    const content = "Discovery requires a nonblank query of at most 256 characters and an integer limit from 1 to 8.";
-    return { ok: false, content, diagnostic: failureDiagnostic("invalid_input", content, NOT_STARTED) };
-  }
-  const requested: DeclarationRequest[] = [];
-  const result = matches.map(match => {
-    const tool = catalog.find(item => item.name === match.name)!;
-    const permitted = discoveryPermitted(ctx, match.name);
-    const status = !permitted ? "permission_denied" : declared.includes(match.name) ? "declared" : "requested_for_next_request";
-    if (status === "requested_for_next_request") requested.push({ name: tool.name, fingerprint: discoveryFingerprint(tool) });
-    const health = ctx.extensions?.get(match.name)?.integrationHealth?.();
-    return { ...match, declaration: status, service_health: health?.state ?? "not_checked", ...(health ? { service_observation: health } : {}) };
-  });
-  return { ok: true, content: JSON.stringify({ matches: result, note: result.length
-    ? "Only declared tools can run. Requested schemas become available after the current batch at a checkpoint; execution permissions still apply."
-    : "No matching tools in the currently permitted discovery catalog. No service was contacted." }),
-    // Keep only small, original requests inline so cold recovery never depends on a generated summary.
-    data: { kind: "tool_discovery", version: 1, requested: requested.map(item => ({ ...item })) } };
-}

package/src/runtime/tool-queue.ts

@@ -1,77 +0,0 @@
-/** Pi A / O.5: ordered admission, bounded readers and an exclusive write barrier. */
-import { schedulingWindow } from "../core/scheduling.ts";
-
-type Mode = "parallel" | "exclusive";
-type Job = { mode: Mode; prepare(): Promise<() => Promise<unknown>>; resolve(value: unknown): void; reject(error: unknown): void };
-
-/**
- * A composing call owns an exclusive slot in its parent queue and gives its
- * children a fresh queue. Re-entering the held parent slot would deadlock.
- * Only exclusive tools may compose; concurrent readers therefore cannot each
- * multiply the session's parallel limit with another queue.
- */
-export class ToolQueue {
-  private readonly limit: number;
-  private readonly pending: Job[] = [];
-  private active = 0;
-  private exclusive = false;
-  private pumping = false;
-  private readonly idle = new Set<() => void>();
-  private closed = false;
-
-  constructor(limit: number) {
-    schedulingWindow([], 0, limit);
-    this.limit = limit;
-  }
-
-  submit<T>(mode: Mode, prepare: () => Promise<() => Promise<T>>): Promise<T> {
-    if (this.closed) return Promise.reject(new Error("tool scope is closed; no invocation started"));
-    const result = new Promise<T>((resolve, reject) => {
-      this.pending.push({ mode, prepare, resolve: value => resolve(value as T), reject });
-    });
-    this.kick();
-    return result;
-  }
-
-  private kick(): void { if (!this.pumping) { this.pumping = true; void this.pump(); } }
-
-  private async pump(): Promise<void> {
-    try {
-      while (this.pending.length > 0) {
-        const next = this.pending[0]!;
-        const occupied: Mode[] = Array.from({ length: this.active }, () => this.exclusive ? "exclusive" : "parallel");
-        if (schedulingWindow([...occupied, next.mode], 0, this.limit) <= this.active) break;
-        const job = this.pending.shift()!;
-        this.active++; this.exclusive = job.mode === "exclusive";
-        const finished = () => { this.active--; if (job.mode === "exclusive") this.exclusive = false; this.kick(); };
-        try {
-          const execute = await job.prepare();
-          void Promise.resolve().then(execute).then(job.resolve, job.reject).finally(finished);
-        } catch (error) { job.reject(error); this.active--; this.exclusive = false; }
-      }
-    } finally {
-      this.pumping = false;
-      if (this.active === 0 && this.pending.length === 0) { for (const resolve of this.idle) resolve(); this.idle.clear(); }
-    }
-  }
-
-  /** A generator can retain its slot across admission/display yields without executing early. */
-  acquire(mode: Mode): Promise<() => void> {
-    return new Promise((resolve, reject) => {
-      let release!: () => void;
-      const done = new Promise<void>(finish => { release = finish; });
-      void this.submit(mode, async () => async () => { resolve(release); await done; }).catch(reject);
-    });
-  }
-
-  whenIdle(): Promise<void> {
-    if (!this.pumping && this.active === 0 && this.pending.length === 0) return Promise.resolve();
-    return new Promise(resolve => this.idle.add(resolve));
-  }
-
-  /** Accepted jobs drain even when their caller forgot to await their promises. */
-  async close(): Promise<void> {
-    this.closed = true;
-    await this.whenIdle();
-  }
-}