@driftengine/ai 3.61.0

package/dist/command/apply.d.ts

@@ -0,0 +1,24 @@
+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 declare function applyCommand<W>(registry: ToolRegistry<W>, world: W, command: AiCommand, _tick: number): ApplyOutcome;

package/dist/command/apply.js

@@ -0,0 +1,40 @@
+/**
+ * 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(registry, world, command, _tick) {
+    const tool = registry.get(command.toolId);
+    if (tool === undefined) {
+        return { ok: false, reason: `unknown tool "${command.toolId}" — it is not registered` };
+    }
+    let admitted;
+    try {
+        admitted = tool.admits(command.args, 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, world) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `"${command.toolId}" failed while running: ${message}` };
+    }
+}

package/dist/command/log.d.ts

@@ -0,0 +1,55 @@
+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 declare class CommandLog {
+    private readonly entries;
+    private cursor;
+    private filled;
+    constructor(capacity?: number);
+    /** How many commands are still retained, not how many were ever recorded. */
+    get length(): number;
+    record(entry: LogEntry): void;
+    /**
+     * 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;
+}

package/dist/command/log.js

@@ -0,0 +1,50 @@
+/**
+ * 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 {
+    entries;
+    cursor = 0;
+    filled = 0;
+    constructor(capacity = 256) {
+        this.entries = new Array(Math.max(1, capacity | 0));
+    }
+    /** How many commands are still retained, not how many were ever recorded. */
+    get length() {
+        return this.filled;
+    }
+    record(entry) {
+        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, out) {
+        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/dist/context/assemble.d.ts

@@ -0,0 +1,48 @@
+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 declare function assembleContext(providers: readonly ContextProvider<unknown>[], subject: string, tick: number, tokenBudget: number): AssembledContext;

package/dist/context/assemble.js

@@ -0,0 +1,55 @@
+/**
+ * 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, subject, tick, tokenBudget) {
+    const ordered = [...providers].sort((a, b) => b.priority - a.priority);
+    const sections = [];
+    const dropped = [];
+    let spent = 0;
+    for (const provider of ordered) {
+        let items;
+        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) {
+    try {
+        return Math.ceil(JSON.stringify(value ?? null).length / 4);
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/context/continuation.d.ts

@@ -0,0 +1,14 @@
+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 declare function continuationPreamble(current: Intent, remainingMs: number): string;

package/dist/context/continuation.js

@@ -0,0 +1,36 @@
+import { hasKnownExtent } from '../policy/types.js';
+/**
+ * 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, remainingMs) {
+    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) {
+    if (intent.toolIds.length === 0)
+        return `${intent.id} (no tool calls)`;
+    return `${intent.id} (${intent.toolIds.join(', ')})`;
+}

package/dist/describe/manifest.d.ts

@@ -0,0 +1,70 @@
+import type { AiProvider } from '../provider/types.ts';
+import type { ContextProvider } from '../context/assemble.ts';
+import type { ToolRegistry, ToolSchema } from '../tools/registry.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;
+    }[];
+}
+export declare function describeAgent<W>(tools: ToolRegistry<W>, context: readonly ContextProvider<unknown>[], provider: AiProvider | null): AiManifest;
+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 declare function requireStructuredOutput(provider: AiProvider | null, schema: ToolSchema, value: unknown): StructuredResult;
+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 declare function describeForDevelopment<W>(tools: ToolRegistry<W>, context: readonly ContextProvider<unknown>[], provider: AiProvider | null): DevelopmentManifest;

package/dist/describe/manifest.js

@@ -0,0 +1,99 @@
+import { validateArgs } from '../tools/validate.js';
+const DETERMINISM_BOUNDARY = [
+    '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 = [];
+export function describeAgent(tools, context, provider) {
+    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,
+    };
+}
+/**
+ * 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, schema, value) {
+    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}` };
+}
+/**
+ * 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(tools, context, provider) {
+    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/dist/entities/context.d.ts

@@ -0,0 +1,52 @@
+import { type Entity, type World } from '@driftengine/entities';
+import type { ComponentType } from '@driftengine/entities';
+import type { ContextProvider } from '../context/assemble.ts';
+import type { ToolDefinition } 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 declare function entityRef(entity: Entity): string;
+/**
+ * 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 declare function parseEntityRef(ref: string, world: World): 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 declare function entityContext(world: World, options: EntityContextOptions): ContextProvider<readonly string[]>;
+/**
+ * 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 declare function entityTool<R>(world: World, id: string, description: string, execute: (entity: Entity, world: World) => R): ToolDefinition<{
+    target: string;
+}, R | null, World>;

package/dist/entities/context.js

@@ -0,0 +1,83 @@
+import { entityGeneration, entityIndex, packEntity, } from '@driftengine/entities';
+/**
+ * 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) {
+    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, world) {
+    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;
+}
+/**
+ * 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, options) {
+    const schema = { 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: () => {
+            const out = [];
+            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(world, id, description, execute) {
+    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);
+        },
+    };
+}