@driftengine/ai 3.61.0

package/src/session/replay.ts

@@ -0,0 +1,96 @@
+import type { AgentPolicy, Intent, PolicyContext } from '../policy/types.ts';
+import type { LogEntry } from '../command/log.ts';
+
+export interface ReplaySource {
+  at(tick: number, out: LogEntry[]): number;
+}
+
+/**
+ * Replay accepted commands at their original boundaries. Calls no provider, ever.
+ *
+ * **A buffered agent replays exactly**, and the floor is why. Model decisions are
+ * replayed from the log; floor decisions are *recomputed*, because the floor is
+ * deterministic and runs inside the simulation. So the log carries only what could not
+ * be derived, and a thousand-tick recording is a handful of entries rather than a
+ * thousand.
+ *
+ * The design that waited could not promise this. There, the *timing* of a response was
+ * itself part of the behaviour — an agent stood still for however long the provider
+ * took — and timing is the one thing a live provider will not reproduce.
+ */
+export class ReplaySession {
+  private readonly source: ReplaySource;
+  private readonly policy: AgentPolicy;
+  private readonly scratch: LogEntry[] = [];
+  private readonly context = { tick: 0, agentId: '', elapsedMs: 0 };
+
+  private currentIntent: Intent | null = null;
+  private startedAtMs = 0;
+  private replayed = 0;
+
+  constructor(source: ReplaySource, policy: AgentPolicy, agentId: string) {
+    this.source = source;
+    this.policy = policy;
+    this.context.agentId = agentId;
+  }
+
+  get current(): Intent | null {
+    return this.currentIntent;
+  }
+
+  /** Model intents taken from the log rather than recomputed. */
+  get replayedIntents(): number {
+    return this.replayed;
+  }
+
+  tick(tickNumber: number, nowMs: number): Intent {
+    this.context.tick = tickNumber;
+    this.context.elapsedMs = nowMs - this.startedAtMs;
+
+    const count = this.source.at(tickNumber, this.scratch);
+    const toolIds: string[] = [];
+    const args: unknown[] = [];
+    let issuedAt = tickNumber;
+    let preempted = false;
+
+    for (let i = 0; i < count; i++) {
+      const entry = this.scratch[i];
+      if (entry === undefined) continue;
+      if (entry.kind === 'preemption') {
+        preempted = true;
+        continue;
+      }
+      toolIds.push(entry.toolId);
+      args.push(entry.args);
+      issuedAt = entry.issuedAtTick;
+    }
+
+    if (preempted) {
+      /* The intent was cut short by external input. Force the floor to choose again
+         on this tick, exactly as the recording did. */
+      this.currentIntent = null;
+    }
+
+    if (toolIds.length > 0) {
+      this.replayed++;
+      this.currentIntent = {
+        id: `model:${issuedAt}`,
+        priority: 50,
+        toolIds,
+        args,
+        expectedExtentMs: -1,
+        source: 'model',
+      };
+      this.startedAtMs = nowMs;
+      return this.currentIntent;
+    }
+
+    const current = this.currentIntent;
+    if (current !== null && current.expectedExtentMs < 0) return current;
+    if (current !== null && nowMs - this.startedAtMs < current.expectedExtentMs) return current;
+
+    this.currentIntent = this.policy.select(this.context as PolicyContext);
+    this.startedAtMs = nowMs;
+    return this.currentIntent;
+  }
+}

package/src/session/states.ts

@@ -0,0 +1,63 @@
+/**
+ * Four states, and a second request that has no edge to arrive on.
+ *
+ * ```text
+ *             intent completes, buffer empty
+ *         ┌───────────────────────────────────────┐
+ *         ▼                                       │
+ *       IDLE ── floor supplies ──▶ RUNNING ───────┤
+ *                                     │           │
+ *                     remaining ≈ p90 latency     │
+ *                                     ▼           │
+ *                                   AHEAD         │
+ *                                     │           │
+ *                         response lands          │
+ *                                     ▼           │
+ *                                   READY ────────┘
+ *                                           intent completes,
+ *                                           buffer drains
+ * ```
+ *
+ * **`continuationIssued` is legal only from `running`.** That is the whole of the
+ * one-request-in-flight guarantee: a counter can be violated by any path that forgets
+ * to check it, where an edge that does not exist cannot be taken.
+ */
+export type AgentState = 'idle' | 'running' | 'ahead' | 'ready';
+
+export type AgentTransition =
+  'floorSupplied' | 'continuationIssued' | 'responseLanded' | 'intentCompleted' | 'preempted';
+
+const TABLE: Readonly<Record<AgentState, Partial<Record<AgentTransition, AgentState>>>> = {
+  idle: {
+    floorSupplied: 'running',
+    preempted: 'idle',
+  },
+  running: {
+    continuationIssued: 'ahead',
+    /* Nothing is buffered and no request is out, so the next intent has to come from
+       the floor — which is what `idle` means here: not "doing nothing", but "owing
+       the floor a decision on the next tick". */
+    intentCompleted: 'idle',
+    preempted: 'idle',
+  },
+  ahead: {
+    responseLanded: 'ready',
+    /*
+     * To `idle`, not to `ready`. The response has not landed, so the floor supplies
+     * the next intent — and the request is still outstanding against an intent that
+     * is now over. The session abandons it rather than buffering an answer to a
+     * question nobody is asking any more.
+     */
+    intentCompleted: 'idle',
+    preempted: 'idle',
+  },
+  ready: {
+    intentCompleted: 'running',
+    preempted: 'idle',
+  },
+};
+
+/** The next state, or `null` when the transition is illegal from here. */
+export function nextState(state: AgentState, transition: AgentTransition): AgentState | null {
+  return TABLE[state][transition] ?? null;
+}

package/src/session/usage.ts

@@ -0,0 +1,66 @@
+import type { AiEvent } from '../provider/types.ts';
+
+/**
+ * What an agent has spent.
+ *
+ * Mutated in place. A session charges per event, and allocating a usage object per
+ * event would put an allocation on the path a streaming response takes hundreds of
+ * times per request.
+ */
+export interface AiUsage {
+  inputTokens: number;
+  outputTokens: number;
+  requests: number;
+  /**
+   * Requests aborted because a higher-priority observation arrived.
+   *
+   * The token price of responsiveness, and the number a consumer tunes its priority
+   * thresholds against. Separate from `abortedRequests` because disposal and hot
+   * reload also abort, and no threshold a consumer can set changes those.
+   */
+  preemptedRequests: number;
+  abortedRequests: number;
+  costMicros: number;
+  latencyMsP90: number;
+}
+
+export function createUsage(): AiUsage {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    requests: 0,
+    preemptedRequests: 0,
+    abortedRequests: 0,
+    costMicros: 0,
+    latencyMsP90: 0,
+  };
+}
+
+/** Tokens only. Who aborted, and why, is something the session knows and an event does not. */
+export function chargeUsage(usage: AiUsage, event: AiEvent): void {
+  if (event.kind !== 'usage') return;
+  usage.inputTokens += event.inputTokens;
+  usage.outputTokens += event.outputTokens;
+}
+
+/**
+ * Record an abort, whatever caused it.
+ *
+ * Counted where the session aborts rather than where the `done` event arrives. Reading
+ * it off the event double-counts every abort the session also has a reason for, and an
+ * aborted request produces a `done` *and* a decision — one abort, two places that
+ * could increment.
+ */
+export function noteAbort(usage: AiUsage): void {
+  usage.abortedRequests++;
+}
+
+/**
+ * Record that the abort being taken is a preemption.
+ *
+ * Only the narrow counter. `noteAbort` moves the broad one, so a preemption increments
+ * both by going through both — and neither function has to know what the other did.
+ */
+export function notePreemption(usage: AiUsage): void {
+  usage.preemptedRequests++;
+}

package/src/testing/deterministic.ts

@@ -0,0 +1,204 @@
+import type {
+  AiEvent,
+  AiProvider,
+  AiProviderCapabilities,
+  AiRequest,
+  AiSession,
+  AiSessionOptions,
+} from '../provider/types.ts';
+
+/**
+ * A provider that answers after a stated number of ticks, or never.
+ *
+ * **This is not a mock capability provider.** R1 withdrew mocks standing in for engine
+ * capabilities that did not exist, on the reasoning that a mock is a second
+ * implementation of a contract with no first implementation to check it against. This
+ * stands in for a *provider* — a thing that is genuinely remote, genuinely slow and
+ * genuinely variable — and it exists so that timing can be asserted rather than
+ * observed.
+ *
+ * **Nothing here runs on a real timer.** A response is due at an absolute tick, and a
+ * tick only happens when a caller says so. Every timing property Track O claims is
+ * measured against this, and on a real clock each of those measurements would be a
+ * race that passes on a fast machine.
+ *
+ * *What it costs:* a test must remember to call `advance`, and one that forgets sees
+ * an agent that never gets an answer. *What would make it wrong:* if a provider adapter
+ * ever needed wall-clock behaviour to be exercised — a retry backoff, say — this could
+ * not exercise it, and that adapter would need its own harness rather than a change here.
+ */
+export interface DeterministicScript {
+  /** Ticks between the request and its first event. `'never'` answers nothing, ever. */
+  readonly latencyTicks: number | 'never';
+  readonly events: readonly AiEvent[];
+}
+
+interface Pending {
+  dueTick: number;
+  events: readonly AiEvent[];
+  settled: boolean;
+  outcome: 'due' | 'aborted' | null;
+  message: string;
+  wake: (() => void) | null;
+}
+
+const CAPABILITIES: AiProviderCapabilities = {
+  text: true,
+  streamingText: true,
+  structuredOutput: true,
+  toolCalling: true,
+  realtimeAudio: false,
+  imageInput: false,
+  local: true,
+};
+
+export class DeterministicProvider implements AiProvider {
+  readonly id = 'deterministic';
+  readonly capabilities = CAPABILITIES;
+
+  /*
+   * Reused with a count rather than emptied. `array.length = 0` makes V8 re-grow the
+   * backing store, which is a per-iteration allocation in loops this provider is
+   * deliberately driven through ten thousand times.
+   */
+  private readonly pending: Pending[] = [];
+  private pendingCount = 0;
+
+  private readonly script: (requestIndex: number) => DeterministicScript;
+  private latencyOverride: number | 'never' | null = null;
+
+  private now = 0;
+  private requests = 0;
+  private aborted = 0;
+  private live = 0;
+  private peak = 0;
+
+  constructor(script: DeterministicScript | ((requestIndex: number) => DeterministicScript)) {
+    this.script = typeof script === 'function' ? script : () => script;
+  }
+
+  get requestCount(): number {
+    return this.requests;
+  }
+
+  get abortedCount(): number {
+    return this.aborted;
+  }
+
+  /** A high-water mark, never a current count. */
+  get peakConcurrency(): number {
+    return this.peak;
+  }
+
+  /** Applies to requests made after this call, never to one already in flight. */
+  setLatencyTicks(ticks: number | 'never'): void {
+    this.latencyOverride = ticks;
+  }
+
+  /** Drives the fake clock. Nothing resolves without it. */
+  advance(tick: number): void {
+    this.now = tick;
+    for (let i = 0; i < this.pendingCount; i++) {
+      const entry = this.pending[i];
+      if (entry === undefined || entry.settled) continue;
+      if (entry.dueTick > tick) continue;
+      entry.settled = true;
+      entry.outcome = 'due';
+      this.live--;
+      entry.wake?.();
+    }
+  }
+
+  createSession(_options: AiSessionOptions): AiSession {
+    const owned: Pending[] = [];
+
+    return {
+      run: (request: AiRequest): AsyncIterable<AiEvent> => {
+        const entry = this.begin(request);
+        owned.push(entry);
+        return this.drain(entry);
+      },
+      abort: (reason?: string): void => {
+        for (const entry of owned) this.settleAborted(entry, reason ?? 'aborted');
+      },
+    };
+  }
+
+  /**
+   * Registered eagerly, before the generator's body runs.
+   *
+   * An async generator does not execute until its first `next()`, so building the
+   * entry inside `drain` would leave `peakConcurrency` reading zero for a request that
+   * had been made — the exact number the one-in-flight tests are asserting against.
+   *
+   * It is released when the request *settles*, not when the generator is drained. A
+   * request that has been answered or aborted is no longer outstanding whether or not
+   * its consumer has read it yet, and several fixed steps can run in one frame with no
+   * microtask between them — which made an aborted request go on counting.
+   */
+  private begin(request: AiRequest): Pending {
+    const script = this.script(this.requests);
+    this.requests++;
+
+    const latency = this.latencyOverride ?? script.latencyTicks;
+    const entry: Pending = {
+      dueTick: latency === 'never' ? Number.POSITIVE_INFINITY : this.now + latency,
+      events: script.events,
+      settled: false,
+      outcome: null,
+      message: '',
+      wake: null,
+    };
+
+    if (this.pendingCount < this.pending.length) this.pending[this.pendingCount] = entry;
+    else this.pending.push(entry);
+    this.pendingCount++;
+
+    this.live++;
+    if (this.live > this.peak) this.peak = this.live;
+
+    if (request.signal.aborted) this.settleAborted(entry, 'signal');
+    else request.signal.addEventListener('abort', () => this.settleAborted(entry, 'signal'));
+
+    return entry;
+  }
+
+  private settleAborted(entry: Pending, message: string): void {
+    if (entry.settled) return;
+    entry.settled = true;
+    entry.outcome = 'aborted';
+    entry.message = message;
+    this.aborted++;
+    this.live--;
+    entry.wake?.();
+  }
+
+  private async *drain(entry: Pending): AsyncIterable<AiEvent> {
+    try {
+      if (!entry.settled) {
+        await new Promise<void>((resolve) => {
+          entry.wake = resolve;
+        });
+      }
+
+      if (entry.outcome === 'aborted') {
+        yield { kind: 'done', reason: 'aborted', message: entry.message };
+        return;
+      }
+
+      for (const event of entry.events) yield event;
+    } finally {
+      this.forget(entry);
+    }
+  }
+
+  private forget(entry: Pending): void {
+    for (let i = 0; i < this.pendingCount; i++) {
+      if (this.pending[i] !== entry) continue;
+      const last = this.pending[this.pendingCount - 1];
+      if (last !== undefined) this.pending[i] = last;
+      this.pendingCount--;
+      return;
+    }
+  }
+}

package/src/tools/policy.ts

@@ -0,0 +1,114 @@
+import type { Budget } from '../budget/budget.ts';
+import type { ToolRegistry } from './registry.ts';
+import { validateArgs } from './validate.ts';
+
+export interface ExecutionPolicy {
+  /** Tool ids this agent may call at all. Absent means every registered tool. */
+  readonly allow?: readonly string[];
+  /** Calls per rate class, per second. */
+  readonly rateLimits?: Readonly<Record<string, number>>;
+  /** Tools a human has to say yes to. Refused here rather than queued. */
+  readonly requireApproval?: readonly string[];
+}
+
+export type Admission = { readonly ok: true } | { readonly ok: false; readonly reason: string };
+
+const OK: Admission = { ok: true };
+
+/**
+ * Rate state, owned by whoever owns the agent.
+ *
+ * **Not module-level.** A shared map keyed by class name would make two unrelated
+ * agents share one limit, so a busy one would silence a quiet one — and worse, a test
+ * would carry state into the next test. The session owns one of these; the limit is
+ * per agent, which is the only scope a consumer can reason about.
+ *
+ * Timestamps live in a reused array with a count, because `array.length = 0` re-grows
+ * V8's backing store and this is touched on every accepted call.
+ */
+export class RateWindows {
+  private readonly byClass = new Map<string, { at: number[]; count: number }>();
+
+  /** Records the call and reports whether it fits. */
+  admit(rateClass: string, limit: number, nowMs: number): boolean {
+    let window = this.byClass.get(rateClass);
+    if (window === undefined) {
+      window = { at: [], count: 0 };
+      this.byClass.set(rateClass, window);
+    }
+
+    let kept = 0;
+    for (let i = 0; i < window.count; i++) {
+      const stamp = window.at[i];
+      if (stamp !== undefined && nowMs - stamp < 1000) window.at[kept++] = stamp;
+    }
+    window.count = kept;
+
+    if (window.count >= limit) return false;
+
+    if (window.count < window.at.length) window.at[window.count] = nowMs;
+    else window.at.push(nowMs);
+    window.count++;
+    return true;
+  }
+
+  clear(): void {
+    this.byClass.clear();
+  }
+}
+
+/**
+ * Whether a proposed tool call may be accepted.
+ *
+ * **The order is fixed and the first failure wins.** A call that is both unknown and
+ * over budget always reports that it is unknown, because a consumer chasing a message
+ * that changes between runs finds nothing wrong with either check. Order: exists,
+ * permitted, needs approval, arguments valid, within rate, within budget — cheapest
+ * and most specific first, so the message names the thing a reader can act on.
+ *
+ * This is the *acceptance* check. It does not run the tool's own `admits` guard: that
+ * runs at the tick boundary where the call is applied, because a snapshot is never
+ * authority and a buffered intent widens the gap between the two moments.
+ */
+export function admitToolCall<W>(
+  registry: ToolRegistry<W>,
+  policy: ExecutionPolicy,
+  budget: Budget,
+  toolId: string,
+  args: unknown,
+  nowMs: number,
+  rates: RateWindows = new RateWindows(),
+): Admission {
+  const tool = registry.get(toolId);
+  if (tool === undefined) {
+    return { ok: false, reason: `unknown tool "${toolId}" — it is not registered` };
+  }
+
+  if (policy.allow !== undefined && !policy.allow.includes(toolId)) {
+    return { ok: false, reason: `tool "${toolId}" is not permitted by this agent's policy` };
+  }
+
+  if (policy.requireApproval?.includes(toolId) === true) {
+    return { ok: false, reason: `tool "${toolId}" requires approval, which was not given` };
+  }
+
+  const validation = validateArgs(tool.schema, args);
+  if (!validation.ok) {
+    return { ok: false, reason: `${validation.path}: ${validation.reason}` };
+  }
+
+  const rateClass = tool.rateClass;
+  const limit = rateClass === undefined ? undefined : policy.rateLimits?.[rateClass];
+  if (rateClass !== undefined && limit !== undefined) {
+    if (!rates.admit(rateClass, limit, nowMs)) {
+      return {
+        ok: false,
+        reason: `rate class "${rateClass}" is over its limit of ${limit} per second`,
+      };
+    }
+  }
+
+  if (budget.exhausted) return { ok: false, reason: budget.reason };
+
+  return OK;
+}

package/src/tools/registry.ts

@@ -0,0 +1,122 @@
+/**
+ * Tools an agent may call, and the guards that decide whether a proposal is still true.
+ *
+ * A tool schema is generated from the same contracts the language type-checks against,
+ * so it cannot drift from the implementation. That is what makes this different from
+ * writing a prompt that describes some functions.
+ */
+
+/**
+ * What a model may be asked to produce.
+ *
+ * Schema-expressible types only. Anything a schema cannot describe cannot be asked
+ * for, validated, or recorded in a trace, and a tool taking one would be a tool whose
+ * arguments are checked by hope.
+ */
+export type ToolSchema =
+  | { readonly kind: 'string' }
+  | { readonly kind: 'number' }
+  | { readonly kind: 'boolean' }
+  | { readonly kind: 'enum'; readonly values: readonly string[] }
+  | { readonly kind: 'array'; readonly of: ToolSchema }
+  | { readonly kind: 'object'; readonly fields: Readonly<Record<string, ToolSchema>> };
+
+const EXPRESSIBLE = new Set(['string', 'number', 'boolean', 'enum', 'array', 'object']);
+
+/**
+ * `W` is the consumer's world view, and this package never constrains it.
+ *
+ * An engine package that knew what a world contained would be an engine package that
+ * knew what game it was in. A guard asking `world.exists(id)` is the consumer's
+ * sentence, written against the consumer's world.
+ */
+export interface ToolDefinition<A, R, W> {
+  /** Stable and versioned — `inspect@1`. Never renumbered once shipped. */
+  readonly id: string;
+  readonly description: string;
+  readonly schema: ToolSchema;
+  readonly rateClass?: string;
+  readonly idempotent?: boolean;
+  /**
+   * Whether this call is still true of the world.
+   *
+   * Declared once, at registration, by the tool. The model never writes one: a
+   * model-authored precondition on a model-authored action is the model marking its
+   * own homework.
+   */
+  admits(args: A, world: W): boolean;
+  execute(args: A, world: W): R;
+}
+
+export class ToolRegistry<W> {
+  private readonly byId = new Map<string, ToolDefinition<never, never, W>>();
+  private readonly order: string[] = [];
+
+  register<A, R>(tool: ToolDefinition<A, R, W>): void {
+    if (this.byId.has(tool.id)) {
+      throw new Error(`a tool is already registered as "${tool.id}"`);
+    }
+    if (!/@\d+$/.test(tool.id)) {
+      throw new Error(
+        `tool id "${tool.id}" carries no version — ids are versioned as "name@1" so a ` +
+          `recorded trace stays readable after the tool's shape changes`,
+      );
+    }
+
+    const bad = inexpressible(tool.schema, '');
+    if (bad !== null) {
+      throw new Error(`tool "${tool.id}" has a schema field a schema cannot express: ${bad}`);
+    }
+
+    this.byId.set(tool.id, tool as unknown as ToolDefinition<never, never, W>);
+    this.order.push(tool.id);
+  }
+
+  /** Registration order, so a prompt's tool list is stable and a trace stays comparable. */
+  ids(): readonly string[] {
+    return this.order;
+  }
+
+  get(id: string): ToolDefinition<never, never, W> | undefined {
+    return this.byId.get(id);
+  }
+
+  /**
+   * Whether every tool an intent names still admits its arguments.
+   *
+   * A plain loop rather than a `map` and an `every`: this runs at the moment a
+   * buffered intent drains, which is inside a fixed step.
+   */
+  admits(toolIds: readonly string[], args: readonly unknown[], world: W): boolean {
+    for (let i = 0; i < toolIds.length; i++) {
+      const id = toolIds[i];
+      if (id === undefined) return false;
+      const tool = this.byId.get(id);
+      if (tool === undefined) return false;
+      try {
+        if (!tool.admits(args[i] as never, world)) return false;
+      } catch {
+        /* A consumer bug in a guard must not become an exception inside a tick. It
+           becomes a refusal, the intent is discarded, and the policy floor covers. */
+        return false;
+      }
+    }
+    return true;
+  }
+}
+
+/** The dotted path of the first field no schema can express, or `null`. */
+function inexpressible(schema: ToolSchema, path: string): string | null {
+  if (!EXPRESSIBLE.has(schema.kind)) return path === '' ? schema.kind : path;
+
+  if (schema.kind === 'array') return inexpressible(schema.of, path === '' ? 'of' : `${path}.of`);
+
+  if (schema.kind === 'object') {
+    for (const [name, field] of Object.entries(schema.fields)) {
+      const found = inexpressible(field, path === '' ? name : `${path}.${name}`);
+      if (found !== null) return found;
+    }
+  }
+
+  return null;
+}