@driftengine/ai 3.61.0

package/src/describe/manifest.ts

@@ -0,0 +1,148 @@
+import type { AiProvider } from '../provider/types.ts';
+import type { ContextProvider } from '../context/assemble.ts';
+import type { ToolRegistry, ToolSchema } from '../tools/registry.ts';
+import { validateArgs } from '../tools/validate.ts';
+
+/**
+ * What an agent is, written down.
+ *
+ * Describes the *agent* rather than its connection: the tools and context are the
+ * agent's, and `providerId` is null when nothing is attached. An agent with no provider
+ * is still a fully described agent — it runs on its floor — and a manifest that
+ * required a connection would have nothing to say about the case this package was
+ * built to make ordinary.
+ */
+export interface AiManifest {
+  readonly tools: readonly { id: string; description: string; schema: ToolSchema }[];
+  readonly context: readonly { id: string; title: string; schema: ToolSchema }[];
+  readonly providerId: string | null;
+  /** Effects a `@deterministic` function may still have, for a reader of a trace. */
+  readonly determinismBoundary: readonly string[];
+  /** Surfaces this engine refuses in writing, so a reader learns the shape of the hole. */
+  readonly refused: readonly { id: string; waitsOn: string }[];
+}
+
+const DETERMINISM_BOUNDARY: readonly string[] = [
+  'pure',
+  'clock.read',
+  'scene.read',
+  'scene.write',
+  'ecs.read',
+  'ecs.write',
+  'physics.read',
+  'physics.write',
+];
+
+/**
+ * The two bridges Track O refuses, named so a coding assistant learns them.
+ *
+ * A manifest that listed only what works teaches a reader to ask for the rest, and the
+ * answer arrives as a failure rather than as a sentence. `docs/CAPABILITIES.md` carries
+ * a sentinel for each, so the day either is built is the day this list is wrong and the
+ * suite says so.
+ */
+/*
+ * **Empty since 2026-09-05, and the emptiness is the point rather than an oversight.**
+ *
+ * Both entries that were here — the navigation bridge and the network authority — were refused for
+ * reasons that stopped being true on 2026-09-03, and neither this list nor `CAPABILITIES.md` had
+ * re-read them. `navigationBridge` and `AuthoritativeAgent` are built, so a refusal naming either
+ * would be this file telling a model a capability is absent while a consumer registers it.
+ *
+ * An empty list is a supported state and not a broken one: `describeAgent` simply says nothing is
+ * refused. What must not happen is an entry outliving the thing it waited on, which is what the
+ * gate above catches and what both of these did for two days.
+ */
+const REFUSED: readonly { id: string; waitsOn: string }[] = [];
+
+export function describeAgent<W>(
+  tools: ToolRegistry<W>,
+  context: readonly ContextProvider<unknown>[],
+  provider: AiProvider | null,
+): AiManifest {
+  return {
+    tools: tools.ids().map((id) => {
+      const tool = tools.get(id);
+      return {
+        id,
+        description: tool?.description ?? '',
+        schema: tool?.schema ?? { kind: 'object', fields: {} },
+      };
+    }),
+    context: context.map((entry) => {
+      const described = entry.describe();
+      return { id: entry.id, title: described.title, schema: described.schema };
+    }),
+    providerId: provider?.id ?? null,
+    determinismBoundary: DETERMINISM_BOUNDARY,
+    refused: REFUSED,
+  };
+}
+
+export type StructuredResult =
+  { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string };
+
+/**
+ * Ask for output shaped like a schema, or refuse before spending anything.
+ *
+ * A provider declaring no structured output is refused **before** the request. Sending
+ * it anyway and hoping the text parses is the silent-downgrade failure wearing a
+ * different hat: it works often enough to ship and fails on the input nobody tested.
+ */
+export function requireStructuredOutput(
+  provider: AiProvider | null,
+  schema: ToolSchema,
+  value: unknown,
+): StructuredResult {
+  if (provider === null) {
+    return { ok: false, reason: 'no provider is attached, so nothing can be asked for' };
+  }
+  if (!provider.capabilities.structuredOutput) {
+    return {
+      ok: false,
+      reason: `provider "${provider.id}" declares no structured output — asking anyway and parsing the text is a downgrade, not a fallback`,
+    };
+  }
+
+  const validation = validateArgs(schema, value);
+  if (validation.ok) return { ok: true, value: validation.value };
+  return { ok: false, reason: `${validation.path}: ${validation.reason}` };
+}
+
+export interface DevelopmentManifest extends AiManifest {
+  /** What this package will not do, in the words a reader needs to stop asking. */
+  readonly refusals: readonly { id: string; waitsOn: string }[];
+  /** The properties everything else here exists to make cheap. */
+  readonly guarantees: readonly string[];
+}
+
+/**
+ * The manifest a coding assistant reads.
+ *
+ * Carries what the runtime manifest carries **plus the refusals**, because a
+ * description listing only what works teaches a reader to ask for the rest — and the
+ * answer arrives as a failure rather than as a sentence. The parent design's §43 asks
+ * for exactly this, and gives that reason.
+ *
+ * The refusal ids are the sentinel names in `docs/CAPABILITIES.md`, and a test asserts
+ * the two agree. Two descriptions of one thing will drift, and this is the pair that
+ * would.
+ */
+export function describeForDevelopment<W>(
+  tools: ToolRegistry<W>,
+  context: readonly ContextProvider<unknown>[],
+  provider: AiProvider | null,
+): DevelopmentManifest {
+  const manifest = describeAgent(tools, context, provider);
+  return {
+    ...manifest,
+    refusals: REFUSED,
+    guarantees: [
+      'an agent is never without a current intent, whether or not a provider is attached',
+      'exactly one provider request is in flight per agent',
+      'a buffered intent is revalidated at the drain and discarded, never deferred',
+      'budget exhaustion degrades to the policy floor and throws nothing',
+      'accepted commands and preemptions are recorded, so a run replays exactly',
+    ],
+  };
+}

package/src/entities/context.ts

@@ -0,0 +1,112 @@
+import {
+  entityGeneration,
+  entityIndex,
+  packEntity,
+  type Entity,
+  type World,
+} from '@driftengine/entities';
+import type { ComponentType } from '@driftengine/entities';
+import type { ContextProvider } from '../context/assemble.ts';
+import type { ToolDefinition, ToolSchema } from '../tools/registry.ts';
+
+/**
+ * Context and tools over an entity world.
+ *
+ * This is the half of AI-6 that links. The other half — a bridge that moves something
+ * along a path — is refused in writing, because nothing pathfinds and `drift/navigation`
+ * waits on no track at all. A seam with no implementation behind it is what R1 withdrew.
+ */
+
+/** A stable, printable name for an entity, and the only form a model ever sees. */
+export function entityRef(entity: Entity): string {
+  return `e${entityIndex(entity)}.${entityGeneration(entity)}`;
+}
+
+/**
+ * Read a reference back, or `null` when it is not one.
+ *
+ * A model inventing an identifier is ordinary rather than exceptional — the parent
+ * design's identity constraints say so in words — so this returns rather than throws,
+ * and the caller's guard turns it into a refusal.
+ */
+export function parseEntityRef(ref: string, world: World): Entity | null {
+  const match = /^e(\d+)\.(\d+)$/.exec(ref);
+  if (match === null) return null;
+
+  /* Rebuilt and asked, rather than searched for. `alive` compares the generation, so a
+     handle whose slot has been reused answers false — which is the whole reason a
+     reference carries one. */
+  const entity = packEntity(Number(match[1]), Number(match[2]));
+  return world.alive(entity) ? entity : null;
+}
+
+export interface EntityContextOptions {
+  readonly id: string;
+  readonly title: string;
+  readonly priority: number;
+  readonly maxItems?: number;
+  readonly components: readonly ComponentType[];
+}
+
+/**
+ * A context provider that samples a query into a list of references.
+ *
+ * **This allocates, and that is correct here.** A reference is a string and a sample is
+ * a list, so neither can be free. What matters is where it runs: context is assembled
+ * once per *request*, not once per tick, and a request already costs a network round
+ * trip. The floor is the per-tick path and it is the one with the allocation floor.
+ *
+ * What wrapping the cursor must not do is make *iteration* allocate — that property is
+ * `@driftengine/entities`' and is floored in its own suite — so the loop reads the
+ * cursor directly rather than materialising it first.
+ */
+export function entityContext(
+  world: World,
+  options: EntityContextOptions,
+): ContextProvider<readonly string[]> {
+  const schema: ToolSchema = { kind: 'array', of: { kind: 'string' } };
+  const limit = options.maxItems ?? Number.POSITIVE_INFINITY;
+  const [a, b, c, d] = options.components;
+
+  return {
+    id: options.id,
+    priority: options.priority,
+    maxItems: options.maxItems,
+    describe: () => ({ title: options.title, schema }),
+    sample: (): readonly string[] => {
+      const out: string[] = [];
+      if (a === undefined) return out;
+      for (const entity of world.query(a, b, c, d)) {
+        if (out.length >= limit) break;
+        out.push(entityRef(entity));
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * A tool addressing an entity, whose guard checks the **generation** and not only the index.
+ *
+ * The staleness case the buffer makes likely rather than rare: an entity is destroyed
+ * and its slot is reused, so an index that still resolves resolves to something else
+ * entirely. A guard checking only the index would let a plan made about one thing run
+ * against another, which is worse than the plan failing.
+ */
+export function entityTool<R>(
+  world: World,
+  id: string,
+  description: string,
+  execute: (entity: Entity, world: World) => R,
+): ToolDefinition<{ target: string }, R | null, World> {
+  return {
+    id,
+    description,
+    schema: { kind: 'object', fields: { target: { kind: 'string' } } },
+    admits: (args) => parseEntityRef(args.target, world) !== null,
+    execute: (args, w) => {
+      const entity = parseEntityRef(args.target, world);
+      return entity === null ? null : execute(entity, w);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Drift AI — provider-neutral intelligence sessions.
+ *
+ * The abstraction is not "an LLM-controlled character". It is typed intelligence
+ * sessions over consumer-defined capabilities, which is what makes it an engine
+ * package rather than a game feature: the same runtime serves a game exposing
+ * movement and dialogue tools, a site exposing camera and material tools, and an
+ * editor exposing selection and transform tools.
+ *
+ * The one property worth stating at the barrel: **an agent is never without a
+ * purpose**. A deterministic policy floor runs inside the simulation whether or
+ * not a provider exists, and the request for the next intent is issued while the
+ * current one is still executing. A provider that is slow, absent, or over budget
+ * costs quality, never motion.
+ */
+
+export { Budget } from './budget/budget.ts';
+export type { BudgetLimits } from './budget/budget.ts';
+export { createAiProvider } from './provider/create.ts';
+export { hasKnownExtent, UNKNOWN_EXTENT, validateIntent } from './policy/types.ts';
+export type {
+  AgentPolicy,
+  Intent,
+  IntentCheck,
+  PolicyContext,
+  PolicyOption,
+} from './policy/types.ts';
+export { UtilityPolicy } from './policy/utility.ts';
+export {
+  describeAgent,
+  describeForDevelopment,
+  requireStructuredOutput,
+} from './describe/manifest.ts';
+export type { AiManifest, DevelopmentManifest, StructuredResult } from './describe/manifest.ts';
+export { entityContext, entityRef, entityTool, parseEntityRef } from './entities/context.ts';
+export type { EntityContextOptions } from './entities/context.ts';
+export { createRealtimeSession } from './realtime/session.ts';
+export type { RealtimeOptions, RealtimeResult } from './realtime/session.ts';
+export { createLocalProvider } from './adapters/local.ts';
+export type { LocalProviderConfig } from './adapters/local.ts';
+export { createProxyProvider } from './adapters/proxy.ts';
+export type { ProxyProviderConfig } from './adapters/proxy.ts';
+export { assembleContext } from './context/assemble.ts';
+export type { AssembledContext, ContextProvider, ContextSection } from './context/assemble.ts';
+export { continuationPreamble } from './context/continuation.ts';
+export { applyCommand } from './command/apply.ts';
+export type { ApplyOutcome } from './command/apply.ts';
+export { CommandLog } from './command/log.ts';
+export type { AiCommand, AiPreemption, LogEntry } from './command/log.ts';
+export { ReplaySession } from './session/replay.ts';
+export type { ReplaySource } from './session/replay.ts';
+export { AgentSession } from './session/agent.ts';
+export type { AgentSessionOptions, Observation, WhileBusy } from './session/agent.ts';
+export { nextState } from './session/states.ts';
+export type { AgentState, AgentTransition } from './session/states.ts';
+export { admitToolCall, RateWindows } from './tools/policy.ts';
+export type { Admission, ExecutionPolicy } from './tools/policy.ts';
+export { ToolRegistry } from './tools/registry.ts';
+export type { ToolDefinition, ToolSchema } from './tools/registry.ts';
+
+/* The two bridges. Both are factories over a consumer's adapter, because the engine owns the graph
+   and the replication and the consumer owns what an agent is. */
+export type {
+  NavigateArgs,
+  NavigateResult,
+  NavigationAdapter,
+  NavigationBridgeOptions,
+} from './bridges/navigation.ts';
+export { navigationBridge, reachableBy } from './bridges/navigation.ts';
+export type { AgentRole, AuthoritativeAgentOptions, DecisionChannel } from './bridges/authority.ts';
+export {
+  AI_NETWORK_AUTHORITY,
+  AuthoritativeAgent,
+  loopbackDecisionChannel,
+} from './bridges/authority.ts';
+export { validateArgs } from './tools/validate.ts';
+export type { ValidationResult } from './tools/validate.ts';
+export { LatencyEstimator } from './provider/latency.ts';
+export { chargeUsage, createUsage, noteAbort, notePreemption } from './session/usage.ts';
+export type { AiUsage } from './session/usage.ts';
+export { DeterministicProvider } from './testing/deterministic.ts';
+export type { DeterministicScript } from './testing/deterministic.ts';
+export type {
+  AiEvent,
+  AiProvider,
+  AiProviderCapabilities,
+  AiProviderConfig,
+  AiProviderResult,
+  AiRequest,
+  AiSession,
+  AiSessionOptions,
+  AssembledContextLike,
+} from './provider/types.ts';

package/src/policy/types.ts

@@ -0,0 +1,70 @@
+/**
+ * What an agent is doing, and the seam that decides it when nothing else can.
+ */
+
+/** An intent whose extent is unknown. The watermark reads it as "ask immediately". */
+export const UNKNOWN_EXTENT = -1;
+
+export interface Intent {
+  readonly id: string;
+  readonly priority: number;
+  readonly toolIds: readonly string[];
+  readonly args: readonly unknown[];
+  /**
+   * How long this is expected to take, in milliseconds, or `UNKNOWN_EXTENT`.
+   *
+   * The continuation watermark subtracts the provider's measured p90 from this to
+   * decide when to ask what comes next. An unknown extent asks immediately, which is
+   * the behaviour a design that waited would have had and is correct for a one-shot.
+   */
+  readonly expectedExtentMs: number;
+  readonly source: 'floor' | 'model';
+}
+
+export interface PolicyContext {
+  readonly tick: number;
+  readonly agentId: string;
+  /** Milliseconds the current intent has been running. */
+  readonly elapsedMs: number;
+}
+
+export interface PolicyOption {
+  /**
+   * Pre-built and reused, never constructed per tick.
+   *
+   * The floor claims it allocates nothing per tick, and selecting among N existing
+   * objects makes that true by construction rather than by care.
+   */
+  readonly intent: Intent;
+  score(context: PolicyContext): number;
+}
+
+export interface AgentPolicy {
+  select(context: PolicyContext): Intent;
+}
+
+export function hasKnownExtent(intent: Intent): boolean {
+  return intent.expectedExtentMs > UNKNOWN_EXTENT;
+}
+
+export type IntentCheck = { readonly ok: true } | { readonly ok: false; readonly reason: string };
+
+/**
+ * Whether an intent is internally coherent.
+ *
+ * Only the pairing of tools to arguments, because that is the one an intent can get
+ * wrong on its own. Whether the tools *exist* is the registry's question and whether
+ * the call is *permitted* is the policy's; asking all three here would put three
+ * failures behind one message.
+ */
+export function validateIntent(intent: Intent): IntentCheck {
+  if (intent.toolIds.length !== intent.args.length) {
+    return {
+      ok: false,
+      reason:
+        `intent "${intent.id}" names ${intent.toolIds.length} tools but carries ` +
+        `${intent.args.length} argument sets`,
+    };
+  }
+  return { ok: true };
+}

package/src/policy/utility.ts

@@ -0,0 +1,53 @@
+import type { AgentPolicy, Intent, PolicyContext, PolicyOption } from './types.ts';
+
+/**
+ * The default floor: score every option, take the highest.
+ *
+ * Small on purpose. The seam is the deliverable and this is a convenience that has to
+ * earn its place by being used. *What it costs:* every consumer links a scorer it may
+ * not want. *What would make it wrong:* if consumers universally replace it, it is
+ * dead weight and belongs behind its own export rather than in the barrel.
+ *
+ * **Allocates nothing per tick.** `select` returns one of the options' pre-built
+ * intents — the same object identity every time that option wins. That is what makes
+ * the claim true by construction, and `utility.alloc.test.ts` is what keeps it true.
+ */
+export class UtilityPolicy implements AgentPolicy {
+  private readonly options: readonly PolicyOption[];
+
+  constructor(options: readonly PolicyOption[]) {
+    if (options.length === 0) {
+      /*
+       * At construction rather than at `select`. A floor with nothing to do is a
+       * configuration error, and discovering it inside a fixed step is discovering it
+       * at the worst possible moment — the one where there is nothing to fall back to.
+       */
+      throw new Error(
+        'a UtilityPolicy needs at least one option — a floor with nothing to do is not a floor',
+      );
+    }
+    this.options = options;
+  }
+
+  select(context: PolicyContext): Intent {
+    let best = 0;
+    let bestScore = Number.NEGATIVE_INFINITY;
+
+    for (let i = 0; i < this.options.length; i++) {
+      const option = this.options[i];
+      if (option === undefined) continue;
+      const score = option.score(context);
+      /* Strictly greater, so a tie goes to the earlier declaration. Declaration order
+         is something a consumer controls and can read off the file; any other
+         tie-break is a rule they would have to be told. */
+      if (score > bestScore) {
+        bestScore = score;
+        best = i;
+      }
+    }
+
+    const chosen = this.options[best];
+    if (chosen === undefined) throw new Error('unreachable: options is non-empty');
+    return chosen.intent;
+  }
+}

package/src/provider/create.ts

@@ -0,0 +1,70 @@
+import type {
+  AiProvider,
+  AiProviderCapabilities,
+  AiProviderConfig,
+  AiProviderResult,
+} from './types.ts';
+
+/**
+ * Accept a provider only if it declares what was asked of it, and say so either way.
+ *
+ * Renderer creation already works this way: `createRenderer` reports which backend it
+ * took and why, and `probeDevice` refuses in the device's own words. A provider is the
+ * same shape of decision with a bigger bill attached — a request to a provider that
+ * cannot do the thing costs latency and tokens before it fails, where a refusal here
+ * costs a string comparison.
+ *
+ * **There is no fallback path.** A downgrade from a local model to a paid remote one
+ * changes where a user's data goes, and a package that does it quietly makes every
+ * privacy notice written against it wrong. A caller wanting a second choice asks for
+ * it explicitly, having read the first refusal.
+ */
+export async function createAiProvider(
+  config: AiProviderConfig,
+  required: Partial<AiProviderCapabilities>,
+): Promise<AiProviderResult> {
+  const provider = config.provider;
+  if (provider === undefined) {
+    return {
+      provider: null,
+      reason: `no provider was supplied for kind "${config.kind}" — build one with its own factory and pass it in`,
+    };
+  }
+
+  const missing = unsupported(provider, required);
+  if (missing.length > 0) {
+    return {
+      provider: null,
+      reason:
+        `provider "${provider.id}" is unsupported for this request: ` +
+        `it declares no ${missing.join(', no ')}`,
+    };
+  }
+
+  return {
+    provider,
+    reason: `provider "${provider.id}" ready, declaring ${declared(provider).join(', ')}`,
+  };
+}
+
+/**
+ * Only the capabilities that were asked for *and* are absent.
+ *
+ * Naming a satisfied requirement in a refusal sends a reader looking for a fault in
+ * the half that worked, which is how a message costs more time than no message.
+ */
+function unsupported(provider: AiProvider, required: Partial<AiProviderCapabilities>): string[] {
+  const missing: string[] = [];
+  for (const key of Object.keys(required) as (keyof AiProviderCapabilities)[]) {
+    if (required[key] === true && provider.capabilities[key] !== true) missing.push(key);
+  }
+  return missing;
+}
+
+function declared(provider: AiProvider): string[] {
+  const names: string[] = [];
+  for (const key of Object.keys(provider.capabilities) as (keyof AiProviderCapabilities)[]) {
+    if (provider.capabilities[key]) names.push(key);
+  }
+  return names.length > 0 ? names : ['nothing'];
+}

package/src/provider/latency.ts

@@ -0,0 +1,57 @@
+/**
+ * A p90 that revises as it measures, and says so before it knows.
+ *
+ * The continuation watermark issues the next request when the current intent's
+ * remaining extent falls to this number. Measuring it rather than configuring it is
+ * what removes the tuning constant that would be wrong on every device, and wrong
+ * again the moment a consumer switched providers.
+ *
+ * **p90 rather than p50 or p99.** At p50 half the continuations land late and the
+ * agent visibly drops to its floor mid-behaviour. At p99 the lead is long enough that
+ * the context goes stale for the tail. *What would make this wrong:* a provider whose
+ * latency is bimodal — a cache hit at 40ms and a miss at 3s — has a p90 that describes
+ * neither, and the answer there is a per-request estimate from the request's own
+ * shape, not a different percentile.
+ */
+export class LatencyEstimator {
+  private readonly window: Float64Array;
+  private readonly scratch: Float64Array;
+  private readonly minSamples: number;
+
+  private cursor = 0;
+  private filled = 0;
+
+  constructor(capacity = 64, minSamples = 8) {
+    const slots = Math.max(1, capacity | 0);
+    this.window = new Float64Array(slots);
+    /* Sorted into a buffer owned once rather than allocated per read. The watermark
+       asks for this on the tick an intent starts, which is a per-intent path. */
+    this.scratch = new Float64Array(slots);
+    this.minSamples = Math.max(1, minSamples | 0);
+  }
+
+  get samples(): number {
+    return this.filled;
+  }
+
+  /** `-1` until `minSamples` are in, which the watermark reads as "issue immediately". */
+  get p90(): number {
+    if (this.filled < this.minSamples) return -1;
+
+    for (let i = 0; i < this.filled; i++) {
+      const value = this.window[i];
+      this.scratch[i] = value === undefined ? 0 : value;
+    }
+    const view = this.scratch.subarray(0, this.filled);
+    view.sort();
+
+    const index = Math.min(this.filled - 1, Math.ceil(this.filled * 0.9) - 1);
+    return view[Math.max(0, index)] ?? -1;
+  }
+
+  record(ms: number): void {
+    this.window[this.cursor] = ms;
+    this.cursor = (this.cursor + 1) % this.window.length;
+    if (this.filled < this.window.length) this.filled++;
+  }
+}