@driftengine/ai 3.61.0

package/src/bridges/navigation.ts

@@ -0,0 +1,207 @@
+/**
+ * An agent that can be asked to go somewhere, and a guard that knows whether it still can.
+ *
+ * **This is the first tool in this package whose guard says something.** A buffered intent is a
+ * proposal authored against one snapshot and executed later, and until now the strongest `admits`
+ * a consumer could write was "the entity still exists". Navigation can do better: a bridge that
+ * dropped, a door that closed, a region that streamed out all make a destination unreachable
+ * between the moment a model chose it and the moment the agent acts on it. `navigate@1` runs the
+ * search in its guard and the intent is discarded, with the policy floor covering — which is what
+ * the package already promises for every other kind of stale proposal.
+ *
+ * **What the engine owns here is the graph and the search; what it does not own is the agent.**
+ * `tools/registry.ts` says a guard is "the consumer's sentence, written against the consumer's
+ * world", and that stays true: the three functions of `NavigationAdapter` are the consumer's, and
+ * everything above them is this file's. A tool that knew which entity was which, or how an agent
+ * moves, would be a particular game's engine.
+ *
+ * ## What it costs
+ *
+ * **Three searches per navigation intent that is accepted and applied**, and the third was a
+ * correction: this header said two until the demo was wired and the real path counted. `take` runs
+ * the guard when the buffered intent drains, `applyCommand` runs it **again** on the way in — which
+ * `apply.ts` argues for at length, because those are two different moments and a snapshot is never
+ * authority — and `execute` runs a third.
+ *
+ * Caching a route between any two of them would key it on nothing stable, since the world changing
+ * between them is the entire reason the guard exists. A guard that trusted the previous answer
+ * would be the guard `apply.ts` refuses to be.
+ *
+ * `nearestNavNode` is a linear scan over `nodeCount`, and both endpoints need one, so a navigation
+ * intent is `O(nodes)` six times plus three A*. At the sizes these graphs are built at that is tens
+ * of microseconds against an intent that happens on the order of once a second per agent. It is
+ * written down here so a consumer profiling a thousand agents knows where to look rather than
+ * discovering it.
+ */
+
+import { NavSearch, nearestNavNode } from '@driftengine/core';
+import type { NavGraph, NavPath } from '@driftengine/core';
+import type { ToolDefinition } from '../tools/registry.ts';
+
+/** What the consumer answers, because only the consumer knows what an agent is. */
+export interface NavigationAdapter<W> {
+  /** The graph this agent navigates. A world may have several. Null means it cannot navigate. */
+  graphOf(world: W, agentId: string): NavGraph | null;
+  /** Where the agent is now, written into `out` as x, y, z. False when the agent is gone. */
+  positionOf(world: W, agentId: string, out: Float32Array): boolean;
+  /**
+   * The route object this agent follows.
+   *
+   * The consumer's and not the bridge's, deliberately: they already own its lifetime, its capacity
+   * and its steering options, and a second one owned here would be a second answer to where the
+   * agent is going.
+   */
+  pathOf(world: W, agentId: string): NavPath | null;
+}
+
+export interface NavigationBridgeOptions {
+  /**
+   * How far a destination may be from the nearest graph node and still count as that node.
+   *
+   * Infinite by default, which snaps to the nearest node however far away it is. A consumer with a
+   * sparse graph over a large world wants a real number here: without one, "go to the roof" routes
+   * to the nearest node on the ground and the agent walks confidently to the wrong place.
+   */
+  readonly snapDistance?: number;
+  /** Longest route the bridge will hold, in nodes. */
+  readonly maxNodes?: number;
+}
+
+export interface NavigateArgs {
+  readonly agentId: string;
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+
+export interface NavigateResult {
+  readonly found: boolean;
+  /** Nodes in the route, or 0. */
+  readonly nodes: number;
+  /**
+   * Route length in metres, or 0.
+   *
+   * Here because `Intent.expectedExtentMs` drives the continuation watermark, and a navigation
+   * intent is the one case where the engine knows the extent better than the policy that proposed
+   * it: a caller with a speed can turn this into a time. Ignoring it costs nothing.
+   */
+  readonly lengthM: number;
+}
+
+const NO_ROUTE: NavigateResult = { found: false, nodes: 0, lengthM: 0 };
+
+/**
+ * Build the navigation tools for a consumer's world.
+ *
+ * Named `navigationBridge` deliberately: `docs/CAPABILITIES.md` carries a sentinel matching this
+ * symbol, so the day this file exists the documentation gate fails and the row that calls this
+ * capability absent has to be rewritten. A bridge named something else would have landed the
+ * capability and left the guard quiet, which is worse than the stale prose it replaces.
+ */
+export function navigationBridge<W>(
+  adapter: NavigationAdapter<W>,
+  options: NavigationBridgeOptions = {},
+): readonly ToolDefinition<NavigateArgs, NavigateResult, W>[] {
+  const snap = options.snapDistance ?? Infinity;
+  const maxNodes = Math.max(2, options.maxNodes ?? 512);
+
+  /*
+   * One scratch route and one search per graph, reused across every call.
+   *
+   * `NavSearch` allocates five arrays sized by the graph, so building one per intent would be an
+   * allocation proportional to the world on a path the fixed step reaches. Keyed by graph because a
+   * world may have several and a search is bound to the one it was built for.
+   */
+  const route = new Uint32Array(maxNodes);
+  const here = new Float32Array(3);
+  const searches = new WeakMap<NavGraph, NavSearch>();
+
+  const searchFor = (graph: NavGraph): NavSearch => {
+    let search = searches.get(graph);
+    if (search === undefined) {
+      search = new NavSearch(graph);
+      searches.set(graph, search);
+    }
+    return search;
+  };
+
+  /**
+   * The route this request would produce, or 0 nodes.
+   *
+   * Shared by the guard and the action so they cannot disagree about what "reachable" means. They
+   * each call it once, which is the two searches the header prices.
+   */
+  const solve = (world: W, args: NavigateArgs): { graph: NavGraph; count: number } | null => {
+    const graph = adapter.graphOf(world, args.agentId);
+    if (graph === null) return null;
+    if (!adapter.positionOf(world, args.agentId, here)) return null;
+
+    const from = nearestNavNode(graph, here[0] ?? 0, here[1] ?? 0, here[2] ?? 0, snap);
+    if (from < 0) return null;
+    const to = nearestNavNode(graph, args.x, args.y, args.z, snap);
+    if (to < 0) return null;
+
+    return { graph, count: searchFor(graph).find(from, to, route) };
+  };
+
+  const navigate: ToolDefinition<NavigateArgs, NavigateResult, W> = {
+    id: 'navigate@1',
+    description:
+      'Move an agent to a world position along the navigation graph. Fails when no route exists.',
+    schema: {
+      kind: 'object',
+      fields: {
+        agentId: { kind: 'string' },
+        x: { kind: 'number' },
+        y: { kind: 'number' },
+        z: { kind: 'number' },
+      },
+    },
+    /*
+     * **Not idempotent, and the distinction is not pedantic.** Calling it twice re-runs the search
+     * against wherever the agent has moved to, which is a different route from the same arguments.
+     */
+    idempotent: false,
+    rateClass: 'navigation',
+
+    admits(args: NavigateArgs, world: W): boolean {
+      const solved = solve(world, args);
+      return solved !== null && solved.count > 1;
+    },
+
+    execute(args: NavigateArgs, world: W): NavigateResult {
+      const path = adapter.pathOf(world, args.agentId);
+      if (path === null) return NO_ROUTE;
+      const solved = solve(world, args);
+      if (solved === null || solved.count < 2) {
+        /*
+         * Cleared rather than left alone. A failed navigate that leaves the previous route in place
+         * is an agent that keeps walking to somewhere nobody asked for any more, which reads as the
+         * tool having worked.
+         */
+        path.clear();
+        return NO_ROUTE;
+      }
+      path.set(route, solved.count);
+      return { found: true, nodes: solved.count, lengthM: path.lengthM };
+    },
+  };
+
+  return [navigate];
+}
+
+/**
+ * Whether a route exists for this agent right now, without writing one.
+ *
+ * The guard, as a question. `navigate@1` answers it as a side effect of doing the thing, so a
+ * caller wanting to *ask* had to route and then undo. `drift/ai.reachable` is this, and so is any
+ * consumer's own policy that wants to score a destination before proposing it.
+ */
+export function reachableBy<W>(
+  tools: readonly ToolDefinition<NavigateArgs, NavigateResult, W>[],
+  args: NavigateArgs,
+  world: W,
+): boolean {
+  const navigate = tools.find((tool) => tool.id === 'navigate@1');
+  return navigate !== undefined && navigate.admits(args, world);
+}

package/src/budget/budget.ts

@@ -0,0 +1,73 @@
+import type { AiUsage } from '../session/usage.ts';
+
+export interface BudgetLimits {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly requests?: number;
+  readonly costMicros?: number;
+  readonly wallMs?: number;
+}
+
+const COUNTED = ['inputTokens', 'outputTokens', 'requests', 'costMicros'] as const;
+
+/**
+ * A ceiling on what an agent may spend, enforced here rather than asked for in a prompt.
+ *
+ * **Exhaustion degrades.** `charge` past a limit returns normally and latches
+ * `exhausted`; the session stops issuing continuations and the policy floor keeps
+ * producing intents. Throwing would put an exception inside a fixed step, which is
+ * worse than the overspend it prevents.
+ *
+ * *What it costs:* an agent that goes over is quietly less capable, and a consumer
+ * that never reads `reason` will not know why. *What would make it wrong:* if a
+ * consumer needs to know at the moment it happens rather than by polling, this needs
+ * a callback — deliberately not added until something asks, because a callback firing
+ * inside a fixed step has the same hazard the throw did.
+ */
+export class Budget {
+  private readonly limits: BudgetLimits;
+  private latched = false;
+  private latchedReason = '';
+  private startedAtMs = -1;
+
+  constructor(limits: BudgetLimits) {
+    this.limits = limits;
+  }
+
+  get exhausted(): boolean {
+    return this.latched;
+  }
+
+  /** The sentence a consumer reports. Empty while not exhausted. */
+  get reason(): string {
+    return this.latchedReason;
+  }
+
+  charge(usage: Readonly<AiUsage>, nowMs: number): void {
+    if (this.startedAtMs < 0) this.startedAtMs = nowMs;
+    if (this.latched) return;
+
+    for (const key of COUNTED) {
+      const limit = this.limits[key];
+      if (limit !== undefined && usage[key] > limit) {
+        this.latch(key, limit, usage[key]);
+        return;
+      }
+    }
+
+    const wall = this.limits.wallMs;
+    if (wall !== undefined && nowMs - this.startedAtMs > wall) {
+      this.latch('wallMs', wall, nowMs - this.startedAtMs);
+    }
+  }
+
+  /*
+   * Latched rather than recomputed. A budget derived from current usage comes back to
+   * life the moment a consumer resets a counter, and the agent resumes spending
+   * against a limit somebody has already hit.
+   */
+  private latch(name: string, limit: number, actual: number): void {
+    this.latched = true;
+    this.latchedReason = `budget exhausted: ${name} limit ${limit}, reached ${actual}`;
+  }
+}

package/src/command/apply.ts

@@ -0,0 +1,52 @@
+import type { ToolRegistry } from '../tools/registry.ts';
+import type { AiCommand } from './log.ts';
+
+export type ApplyOutcome =
+  { readonly ok: true; readonly result: unknown } | { readonly ok: false; readonly reason: string };
+
+/**
+ * Run an accepted command at a tick boundary, revalidating on the way in.
+ *
+ * The tool's own guard ran once already, when the buffered intent drained. It runs
+ * **again** here, because those are two different moments and a snapshot is never
+ * authority — the buffer widens the gap on purpose, and admission proves the plan was
+ * true when it was taken up rather than that it is true now.
+ *
+ * Not the execution policy, which ran at acceptance. Running that twice would charge
+ * the rate limit twice for one call.
+ *
+ * **Returns on every path.** A caller inside `fixedUpdate` never needs a `try`, and a
+ * consumer's tool throwing must not become an exception halfway through a tick.
+ */
+export function applyCommand<W>(
+  registry: ToolRegistry<W>,
+  world: W,
+  command: AiCommand,
+  _tick: number,
+): ApplyOutcome {
+  const tool = registry.get(command.toolId);
+  if (tool === undefined) {
+    return { ok: false, reason: `unknown tool "${command.toolId}" — it is not registered` };
+  }
+
+  let admitted: boolean;
+  try {
+    admitted = tool.admits(command.args as never, world);
+  } catch {
+    return { ok: false, reason: `the guard for "${command.toolId}" threw, so the call is refused` };
+  }
+
+  if (!admitted) {
+    return {
+      ok: false,
+      reason: `"${command.toolId}" no longer admits: the world changed between acceptance and application`,
+    };
+  }
+
+  try {
+    return { ok: true, result: tool.execute(command.args as never, world) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, reason: `"${command.toolId}" failed while running: ${message}` };
+  }
+}

package/src/command/log.ts

@@ -0,0 +1,81 @@
+export interface AiCommand {
+  readonly kind: 'command';
+  readonly toolId: string;
+  readonly args: unknown;
+  readonly agentId: string;
+  /** The tick the model was asked. */
+  readonly issuedAtTick: number;
+  /** The tick the command crossed into the simulation. */
+  readonly acceptedAtTick: number;
+}
+
+/**
+ * An observation that ended the current intent early.
+ *
+ * Recorded for the same reason a command is: it cannot be recomputed. The floor is
+ * deterministic and replays by rerunning, but an observation is *external input* —
+ * the same class of thing as a keypress — and nothing in the simulation derives it.
+ * Without this, a replay reruns the floor past the moment it was interrupted and
+ * diverges from there on.
+ */
+export interface AiPreemption {
+  readonly kind: 'preemption';
+  readonly agentId: string;
+  readonly acceptedAtTick: number;
+}
+
+export type LogEntry = AiCommand | AiPreemption;
+
+/**
+ * What was accepted, and when — beside `TickTrace` rather than inside it.
+ *
+ * `TickTrace` is `Float32Array` channels plus a `Uint8Array` of flags, sampled per
+ * tick. A command carries a string id and structured arguments, and boxing those into
+ * float channels is not a design, it is a defeat. This borrows the ring-buffer
+ * discipline and the tick indexing and shares nothing else, which answers the question
+ * §33 of the parent design left open for AI-2.
+ *
+ * *What it costs:* two ring buffers where a reader might expect one place to look.
+ * *What would make it wrong:* if a consumer needed one ordered stream of both, this
+ * would need a merge read rather than a merged store — the storage shapes have no
+ * common representation worth finding.
+ */
+export class CommandLog {
+  private readonly entries: (LogEntry | undefined)[];
+  private cursor = 0;
+  private filled = 0;
+
+  constructor(capacity = 256) {
+    this.entries = new Array<LogEntry | undefined>(Math.max(1, capacity | 0));
+  }
+
+  /** How many commands are still retained, not how many were ever recorded. */
+  get length(): number {
+    return this.filled;
+  }
+
+  record(entry: LogEntry): void {
+    this.entries[this.cursor] = entry;
+    this.cursor = (this.cursor + 1) % this.entries.length;
+    if (this.filled < this.entries.length) this.filled++;
+  }
+
+  /**
+   * Commands accepted at exactly this tick, in acceptance order, written into `out`.
+   *
+   * Returns the count written. Reading a tick allocates nothing, because a replay
+   * reads every tick and a per-tick array would put an allocation on that path.
+   */
+  at(tick: number, out: LogEntry[]): number {
+    let written = 0;
+    const size = this.entries.length;
+    const start = this.filled < size ? 0 : this.cursor;
+
+    for (let i = 0; i < this.filled; i++) {
+      const entry = this.entries[(start + i) % size];
+      if (entry === undefined || entry.acceptedAtTick !== tick) continue;
+      out[written++] = entry;
+    }
+    return written;
+  }
+}

package/src/context/assemble.ts

@@ -0,0 +1,104 @@
+import type { ToolSchema } from '../tools/registry.ts';
+
+/**
+ * A read-only snapshot the model is told about.
+ *
+ * Context and tools are separate surfaces and the separation improves behaviour:
+ * nearby objects are context, inspecting one in detail is a tool, moving is a tool.
+ */
+export interface ContextProvider<T> {
+  /** Stable and versioned, like a tool id: `project.visible@5`. */
+  readonly id: string;
+  readonly priority: number;
+  readonly maxItems?: number;
+  describe(): { readonly title: string; readonly schema: ToolSchema };
+  sample(subject: string): T;
+}
+
+export interface ContextSection {
+  readonly id: string;
+  readonly title: string;
+  readonly items: unknown;
+  readonly estimatedTokens: number;
+  /** True when `maxItems` cut the sample, so a reader can tell short from truncated. */
+  readonly truncated: boolean;
+}
+
+export interface AssembledContext {
+  readonly capturedAtTick: number;
+  readonly sections: readonly ContextSection[];
+  readonly estimatedTokens: number;
+  /**
+   * Section ids left out, and why they are named rather than merely absent.
+   *
+   * A budget that silently truncates reads as coverage. A model told nothing about
+   * nearby objects behaves as though there are none, and a consumer reading a trace
+   * cannot tell that from a world that was empty.
+   */
+  readonly dropped: readonly string[];
+}
+
+/**
+ * Never send the scene graph.
+ *
+ * Sections are taken in descending priority until the budget is spent, and what did
+ * not fit is named. The estimate is deliberately crude — a provider-specific tokenizer
+ * may sharpen it, but requiring one would make the core abstraction depend on whichever
+ * provider happened to be configured.
+ */
+export function assembleContext(
+  providers: readonly ContextProvider<unknown>[],
+  subject: string,
+  tick: number,
+  tokenBudget: number,
+): AssembledContext {
+  const ordered = [...providers].sort((a, b) => b.priority - a.priority);
+  const sections: ContextSection[] = [];
+  const dropped: string[] = [];
+  let spent = 0;
+
+  for (const provider of ordered) {
+    let items: unknown;
+    let truncated = false;
+    try {
+      items = provider.sample(subject);
+    } catch {
+      /* One bad context provider must not silence an agent. It is named in `dropped`,
+         which is the difference between a section that failed and one that was empty. */
+      dropped.push(provider.id);
+      continue;
+    }
+
+    const limit = provider.maxItems;
+    if (limit !== undefined && Array.isArray(items) && items.length > limit) {
+      items = items.slice(0, limit);
+      truncated = true;
+    }
+
+    const cost = estimateTokens(items);
+    if (spent + cost > tokenBudget) {
+      dropped.push(provider.id);
+      continue;
+    }
+
+    spent += cost;
+    sections.push({
+      id: provider.id,
+      title: provider.describe().title,
+      items,
+      estimatedTokens: cost,
+      truncated,
+    });
+  }
+
+  return { capturedAtTick: tick, sections, estimatedTokens: spent, dropped };
+}
+
+/** Four characters to a token, which is close enough to budget with and cheap to compute. */
+function estimateTokens(value: unknown): number {
+  try {
+    return Math.ceil(JSON.stringify(value ?? null).length / 4);
+  } catch {
+    return 0;
+  }
+}

package/src/context/continuation.ts

@@ -0,0 +1,39 @@
+import { hasKnownExtent } from '../policy/types.ts';
+import type { Intent } from '../policy/types.ts';
+
+/**
+ * Tell the model when its answer will be used.
+ *
+ * Three lines. Without them the model answers as though acting immediately, proposes
+ * what is right now and wrong in a second and a half, and the lookahead becomes lag
+ * that is still paid for. The whole value of asking early is lost to not saying so.
+ *
+ * *What it costs:* three lines of every continuation's context budget. *What would
+ * make it wrong:* a provider that ignores framing of this kind entirely, at which
+ * point the lead should shrink toward zero rather than the preamble being dropped —
+ * the fix for a model that cannot reason about the future is to stop asking it to.
+ */
+export function continuationPreamble(current: Intent, remainingMs: number): string {
+  const doing = describeIntent(current);
+  const when = hasKnownExtent(current)
+    ? `~${(Math.max(0, remainingMs) / 1000).toFixed(1)}s after this snapshot`
+    : 'unknown — this action has no predictable duration';
+
+  return [
+    `You are currently:    ${doing}`,
+    `Expected to finish:   ${when}`,
+    `Your answer applies:  when that finishes, not now`,
+  ].join('\n');
+}
+
+/**
+ * What the agent is doing, in the model's terms.
+ *
+ * A floor intent is described exactly like a model intent. Telling the model the
+ * engine improvised would invite it to treat the current behaviour as provisional,
+ * and the floor's choice is as real as any other — it is what the agent is doing.
+ */
+function describeIntent(intent: Intent): string {
+  if (intent.toolIds.length === 0) return `${intent.id} (no tool calls)`;
+  return `${intent.id} (${intent.toolIds.join(', ')})`;
+}