@driftengine/ai 3.61.0

package/dist/bridges/authority.d.ts

@@ -0,0 +1,153 @@
+/**
+ * One machine decides what an agent does, and everybody else is replaying it.
+ *
+ * **A model is not a function of the simulation.** It is slow, variable and metered, and two peers
+ * running the same agent loop over the same world do not agree. So a decision is taken on the
+ * authority and reaches a participant as a fact it does not re-take.
+ *
+ * ## There is no second mechanism here, and that is the design
+ *
+ * `CommandLog` records what a model decided and when it crossed into the simulation;
+ * `ReplaySession` reads that log, recomputes floor intents and **calls no provider, ever**. The
+ * floor is deterministic and replays by rerunning, so the log carries only what cannot be derived.
+ *
+ * **A participant is therefore a replay whose log arrives over a network instead of from a
+ * recording**, and a rewind is a replay of the same log. Replicating an intent id on the input path
+ * instead would have solved a problem this package had already solved, and `inputLog.ts` refuses
+ * variable-length payloads in writing anyway.
+ *
+ * What is left for this file is the part that is genuinely about networking: which side decides,
+ * getting decisions onto the wire, and noticing when one arrives for a tick already run.
+ *
+ * ## A late decision is a rewind, and this file will not perform one
+ *
+ * A command can land after the participant has already stepped the tick it belongs to. That
+ * participant used its floor where the authority used a model, and the two worlds differ. The
+ * correction is Track J's rewind and it belongs to the consumer, who owns the `RewindLoop`, the
+ * snapshot and the decision about how far back is worth going. `earliestLateTick` reports the
+ * oldest such tick and this file does nothing else about it: performing a rewind from inside an
+ * agent would be an AI package deciding when a whole simulation goes backwards.
+ *
+ * ## What a script may not see
+ *
+ * Nothing here is bound to `drift/ai` beyond `deciding`. A capability handing a script the tools or
+ * arguments a model chose would let a `@deterministic` system branch on a provider's answer, and the
+ * replay would take the other branch.
+ */
+import type { AiCommand, CommandLog } from '../command/log.ts';
+import type { Intent } from '../policy/types.ts';
+import type { AgentSession } from '../session/agent.ts';
+import type { ReplaySession } from '../session/replay.ts';
+/**
+ * The sentinel's own name, exported so the documentation gate fires when this file arrives.
+ *
+ * `docs/CAPABILITIES.md` matches `AI_NETWORK_AUTHORITY|replicateDecision`, and a bridge named around
+ * the pattern would have landed the capability and left the guard quiet — leaving the document
+ * refusing in writing a thing that exists, which is worse than the stale prose it replaces.
+ */
+export declare const AI_NETWORK_AUTHORITY = "ai-network-authority@1";
+/**
+ * How a decision crosses. The consumer's, because packing and transport are theirs.
+ *
+ * A command is a tool id, structured arguments and two tick numbers. It is **not** a simulation
+ * input: `inputLog.ts` is fixed-width per participant per tick and refuses variable-length payloads
+ * by design, and an agent's decision is exactly the shape it refuses. So this rides whatever
+ * reliable channel the consumer already has.
+ */
+export interface DecisionChannel {
+    /** Authority side. Called once per accepted command, never for a floor intent. */
+    replicateDecision(command: AiCommand): void;
+    /**
+     * Participant side. Hand over everything that has arrived since the last call.
+     *
+     * Returns how many were delivered. Draining rather than a callback registration so the consumer
+     * decides when decisions enter the simulation, which on a fixed step must be at a tick boundary.
+     */
+    drain(into: (command: AiCommand) => void): number;
+}
+export type AgentRole = 'authority' | 'participant';
+export interface AuthoritativeAgentOptions {
+    /**
+     * Which side this is, asked every tick.
+     *
+     * A function and not a flag because authority can move, and a wrapper that cached the answer at
+     * construction would keep deciding after it stopped being allowed to.
+     */
+    role(): AgentRole;
+    channel: DecisionChannel;
+    /**
+     * The log both sides read.
+     *
+     * On the authority the session writes it and this publishes from it; on a participant the channel
+     * fills it and the replay reads it. One structure, because a second one would be a second answer
+     * to what the agent decided.
+     */
+    log: CommandLog;
+}
+/**
+ * An agent whose model decisions are taken in one place.
+ *
+ * Wraps the two sessions the package already has and picks between them. It adds no policy, no
+ * provider handling and no replay logic; all three exist and are reused.
+ */
+export declare class AuthoritativeAgent {
+    private readonly session;
+    private readonly replay;
+    private readonly options;
+    private readonly scratch;
+    /** Ticks whose commands have been put on the wire. Nothing before this is published twice. */
+    private publishedThrough;
+    private lastTick;
+    private late;
+    private published;
+    private accepted;
+    constructor(session: AgentSession<unknown>, replay: ReplaySession, options: AuthoritativeAgentOptions);
+    /** Decisions this peer put on the wire. Zero on a participant, always. */
+    get publishedDecisions(): number;
+    /** Decisions taken off the wire. Zero on the authority, always. */
+    get acceptedDecisions(): number;
+    /**
+     * The oldest tick a decision arrived for after that tick had already run, or -1.
+     *
+     * A consumer holding a `RewindLoop` reads this, rewinds to it and replays. Cleared by
+     * `clearLate` once they have.
+     */
+    get earliestLateTick(): number;
+    clearLate(): void;
+    /**
+     * Advance one tick and return what the agent is doing.
+     *
+     * Arriving decisions are drained **before** the tick runs, so a command for this tick is in the
+     * log by the time the replay reads it. A command for an earlier tick is recorded anyway — the log
+     * is keyed by acceptance tick, so it lands where a later rewind will find it — and noted in
+     * `earliestLateTick`.
+     */
+    tick(tickNumber: number, nowMs: number): Intent;
+    private drain;
+    /**
+     * Put this tick's accepted commands on the wire.
+     *
+     * Read back out of the log rather than intercepted on the way in, so what crosses is exactly what
+     * a replay of this authority would see. A second path that built its own message could disagree
+     * with the log, and the disagreement would only show up as a participant that drifts.
+     */
+    private publish;
+}
+/**
+ * A channel with both ends in this process, for a test or a single-process host.
+ *
+ * **Not a mock.** R1 withdrew mocks standing in for engine capabilities that did not exist; this
+ * stands in for a *transport*, which is a thing `AGENTS.md` says is a caller's to supply, and it
+ * delivers real commands with a real ordering. `packages/network`'s seeded loopback is the same
+ * shape of object for the same reason.
+ *
+ * Delivery is deferred to the next `drain` rather than immediate, because a channel that delivered
+ * inside `replicateDecision` would let a decision reach a participant in the same tick it was taken,
+ * which no real link does and which would hide every late-arrival bug this bridge exists to notice.
+ */
+export declare function loopbackDecisionChannel(): {
+    authority: DecisionChannel;
+    participant: DecisionChannel;
+    /** How many are waiting. A test asserting a decision has *not* arrived yet reads this. */
+    pending(): number;
+};

package/dist/bridges/authority.js

@@ -0,0 +1,179 @@
+/**
+ * One machine decides what an agent does, and everybody else is replaying it.
+ *
+ * **A model is not a function of the simulation.** It is slow, variable and metered, and two peers
+ * running the same agent loop over the same world do not agree. So a decision is taken on the
+ * authority and reaches a participant as a fact it does not re-take.
+ *
+ * ## There is no second mechanism here, and that is the design
+ *
+ * `CommandLog` records what a model decided and when it crossed into the simulation;
+ * `ReplaySession` reads that log, recomputes floor intents and **calls no provider, ever**. The
+ * floor is deterministic and replays by rerunning, so the log carries only what cannot be derived.
+ *
+ * **A participant is therefore a replay whose log arrives over a network instead of from a
+ * recording**, and a rewind is a replay of the same log. Replicating an intent id on the input path
+ * instead would have solved a problem this package had already solved, and `inputLog.ts` refuses
+ * variable-length payloads in writing anyway.
+ *
+ * What is left for this file is the part that is genuinely about networking: which side decides,
+ * getting decisions onto the wire, and noticing when one arrives for a tick already run.
+ *
+ * ## A late decision is a rewind, and this file will not perform one
+ *
+ * A command can land after the participant has already stepped the tick it belongs to. That
+ * participant used its floor where the authority used a model, and the two worlds differ. The
+ * correction is Track J's rewind and it belongs to the consumer, who owns the `RewindLoop`, the
+ * snapshot and the decision about how far back is worth going. `earliestLateTick` reports the
+ * oldest such tick and this file does nothing else about it: performing a rewind from inside an
+ * agent would be an AI package deciding when a whole simulation goes backwards.
+ *
+ * ## What a script may not see
+ *
+ * Nothing here is bound to `drift/ai` beyond `deciding`. A capability handing a script the tools or
+ * arguments a model chose would let a `@deterministic` system branch on a provider's answer, and the
+ * replay would take the other branch.
+ */
+/**
+ * The sentinel's own name, exported so the documentation gate fires when this file arrives.
+ *
+ * `docs/CAPABILITIES.md` matches `AI_NETWORK_AUTHORITY|replicateDecision`, and a bridge named around
+ * the pattern would have landed the capability and left the guard quiet — leaving the document
+ * refusing in writing a thing that exists, which is worse than the stale prose it replaces.
+ */
+export const AI_NETWORK_AUTHORITY = 'ai-network-authority@1';
+/**
+ * An agent whose model decisions are taken in one place.
+ *
+ * Wraps the two sessions the package already has and picks between them. It adds no policy, no
+ * provider handling and no replay logic; all three exist and are reused.
+ */
+export class AuthoritativeAgent {
+    session;
+    replay;
+    options;
+    scratch = [];
+    /** Ticks whose commands have been put on the wire. Nothing before this is published twice. */
+    publishedThrough = -1;
+    lastTick = -1;
+    late = -1;
+    published = 0;
+    accepted = 0;
+    constructor(session, replay, options) {
+        this.session = session;
+        this.replay = replay;
+        this.options = options;
+    }
+    /** Decisions this peer put on the wire. Zero on a participant, always. */
+    get publishedDecisions() {
+        return this.published;
+    }
+    /** Decisions taken off the wire. Zero on the authority, always. */
+    get acceptedDecisions() {
+        return this.accepted;
+    }
+    /**
+     * The oldest tick a decision arrived for after that tick had already run, or -1.
+     *
+     * A consumer holding a `RewindLoop` reads this, rewinds to it and replays. Cleared by
+     * `clearLate` once they have.
+     */
+    get earliestLateTick() {
+        return this.late;
+    }
+    clearLate() {
+        this.late = -1;
+    }
+    /**
+     * Advance one tick and return what the agent is doing.
+     *
+     * Arriving decisions are drained **before** the tick runs, so a command for this tick is in the
+     * log by the time the replay reads it. A command for an earlier tick is recorded anyway — the log
+     * is keyed by acceptance tick, so it lands where a later rewind will find it — and noted in
+     * `earliestLateTick`.
+     */
+    tick(tickNumber, nowMs) {
+        this.drain(tickNumber);
+        this.lastTick = tickNumber;
+        if (this.options.role() === 'participant') {
+            /* No provider is reachable from here. `ReplaySession` has none, which is the property that
+               makes "a participant never decides" true by construction rather than by care. */
+            return this.replay.tick(tickNumber, nowMs);
+        }
+        const intent = this.session.tick(tickNumber, nowMs);
+        this.publish(tickNumber);
+        return intent;
+    }
+    drain(tickNumber) {
+        this.options.channel.drain((command) => {
+            this.options.log.record(command);
+            this.accepted++;
+            if (command.acceptedAtTick < tickNumber && this.lastTick >= command.acceptedAtTick) {
+                if (this.late < 0 || command.acceptedAtTick < this.late)
+                    this.late = command.acceptedAtTick;
+            }
+        });
+    }
+    /**
+     * Put this tick's accepted commands on the wire.
+     *
+     * Read back out of the log rather than intercepted on the way in, so what crosses is exactly what
+     * a replay of this authority would see. A second path that built its own message could disagree
+     * with the log, and the disagreement would only show up as a participant that drifts.
+     */
+    publish(tickNumber) {
+        if (tickNumber <= this.publishedThrough)
+            return;
+        const count = this.options.log.at(tickNumber, this.scratch);
+        for (let i = 0; i < count; i++) {
+            const entry = this.scratch[i];
+            if (entry === undefined || entry.kind !== 'command')
+                continue;
+            this.options.channel.replicateDecision(entry);
+            this.published++;
+        }
+        this.publishedThrough = tickNumber;
+    }
+}
+/**
+ * A channel with both ends in this process, for a test or a single-process host.
+ *
+ * **Not a mock.** R1 withdrew mocks standing in for engine capabilities that did not exist; this
+ * stands in for a *transport*, which is a thing `AGENTS.md` says is a caller's to supply, and it
+ * delivers real commands with a real ordering. `packages/network`'s seeded loopback is the same
+ * shape of object for the same reason.
+ *
+ * Delivery is deferred to the next `drain` rather than immediate, because a channel that delivered
+ * inside `replicateDecision` would let a decision reach a participant in the same tick it was taken,
+ * which no real link does and which would hide every late-arrival bug this bridge exists to notice.
+ */
+export function loopbackDecisionChannel() {
+    const queue = [];
+    return {
+        authority: {
+            replicateDecision(command) {
+                queue.push(command);
+            },
+            drain() {
+                return 0;
+            },
+        },
+        participant: {
+            replicateDecision() {
+                /* A participant never publishes. Silent rather than throwing, because this is reached from
+                   a fixed step and `AGENTS.md` forbids throwing in one; `AuthoritativeAgent` never calls
+                   it, so a call arriving here is a consumer's own wiring and their assertion to make. */
+            },
+            drain(into) {
+                const count = queue.length;
+                for (let i = 0; i < count; i++)
+                    into(queue[i]);
+                queue.length = 0;
+                return count;
+            },
+        },
+        pending() {
+            return queue.length;
+        },
+    };
+}

package/dist/bridges/navigation.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare function navigationBridge<W>(adapter: NavigationAdapter<W>, options?: NavigationBridgeOptions): readonly ToolDefinition<NavigateArgs, NavigateResult, W>[];
+/**
+ * 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 declare function reachableBy<W>(tools: readonly ToolDefinition<NavigateArgs, NavigateResult, W>[], args: NavigateArgs, world: W): boolean;

package/dist/bridges/navigation.js

@@ -0,0 +1,139 @@
+/**
+ * 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';
+const NO_ROUTE = { 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(adapter, options = {}) {
+    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();
+    const searchFor = (graph) => {
+        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, args) => {
+        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 = {
+        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, world) {
+            const solved = solve(world, args);
+            return solved !== null && solved.count > 1;
+        },
+        execute(args, world) {
+            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(tools, args, world) {
+    const navigate = tools.find((tool) => tool.id === 'navigate@1');
+    return navigate !== undefined && navigate.admits(args, world);
+}

package/dist/budget/budget.d.ts

@@ -0,0 +1,34 @@
+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;
+}
+/**
+ * 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 declare class Budget {
+    private readonly limits;
+    private latched;
+    private latchedReason;
+    private startedAtMs;
+    constructor(limits: BudgetLimits);
+    get exhausted(): boolean;
+    /** The sentence a consumer reports. Empty while not exhausted. */
+    get reason(): string;
+    charge(usage: Readonly<AiUsage>, nowMs: number): void;
+    private latch;
+}

package/dist/budget/budget.js

@@ -0,0 +1,57 @@
+const COUNTED = ['inputTokens', 'outputTokens', 'requests', 'costMicros'];
+/**
+ * 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 {
+    limits;
+    latched = false;
+    latchedReason = '';
+    startedAtMs = -1;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    get exhausted() {
+        return this.latched;
+    }
+    /** The sentence a consumer reports. Empty while not exhausted. */
+    get reason() {
+        return this.latchedReason;
+    }
+    charge(usage, nowMs) {
+        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.
+     */
+    latch(name, limit, actual) {
+        this.latched = true;
+        this.latchedReason = `budget exhausted: ${name} limit ${limit}, reached ${actual}`;
+    }
+}