@driftengine/ai 3.61.0

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/*! 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';
+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/dist/index.js

@@ -0,0 +1,40 @@
+/*! 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.js';
+export { createAiProvider } from './provider/create.js';
+export { hasKnownExtent, UNKNOWN_EXTENT, validateIntent } from './policy/types.js';
+export { UtilityPolicy } from './policy/utility.js';
+export { describeAgent, describeForDevelopment, requireStructuredOutput, } from './describe/manifest.js';
+export { entityContext, entityRef, entityTool, parseEntityRef } from './entities/context.js';
+export { createRealtimeSession } from './realtime/session.js';
+export { createLocalProvider } from './adapters/local.js';
+export { createProxyProvider } from './adapters/proxy.js';
+export { assembleContext } from './context/assemble.js';
+export { continuationPreamble } from './context/continuation.js';
+export { applyCommand } from './command/apply.js';
+export { CommandLog } from './command/log.js';
+export { ReplaySession } from './session/replay.js';
+export { AgentSession } from './session/agent.js';
+export { nextState } from './session/states.js';
+export { admitToolCall, RateWindows } from './tools/policy.js';
+export { ToolRegistry } from './tools/registry.js';
+export { navigationBridge, reachableBy } from './bridges/navigation.js';
+export { AI_NETWORK_AUTHORITY, AuthoritativeAgent, loopbackDecisionChannel, } from './bridges/authority.js';
+export { validateArgs } from './tools/validate.js';
+export { LatencyEstimator } from './provider/latency.js';
+export { chargeUsage, createUsage, noteAbort, notePreemption } from './session/usage.js';
+export { DeterministicProvider } from './testing/deterministic.js';

package/dist/policy/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare 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 declare function hasKnownExtent(intent: Intent): boolean;
+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 declare function validateIntent(intent: Intent): IntentCheck;

package/dist/policy/types.js

@@ -0,0 +1,26 @@
+/**
+ * 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 function hasKnownExtent(intent) {
+    return intent.expectedExtentMs > UNKNOWN_EXTENT;
+}
+/**
+ * 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) {
+    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/dist/policy/utility.d.ts

@@ -0,0 +1,18 @@
+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 declare class UtilityPolicy implements AgentPolicy {
+    private readonly options;
+    constructor(options: readonly PolicyOption[]);
+    select(context: PolicyContext): Intent;
+}

package/dist/policy/utility.js

@@ -0,0 +1,47 @@
+/**
+ * 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 {
+    options;
+    constructor(options) {
+        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) {
+        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/dist/provider/create.d.ts

@@ -0,0 +1,16 @@
+import type { 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 declare function createAiProvider(config: AiProviderConfig, required: Partial<AiProviderCapabilities>): Promise<AiProviderResult>;

package/dist/provider/create.js

@@ -0,0 +1,57 @@
+/**
+ * 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, required) {
+    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, required) {
+    const missing = [];
+    for (const key of Object.keys(required)) {
+        if (required[key] === true && provider.capabilities[key] !== true)
+            missing.push(key);
+    }
+    return missing;
+}
+function declared(provider) {
+    const names = [];
+    for (const key of Object.keys(provider.capabilities)) {
+        if (provider.capabilities[key])
+            names.push(key);
+    }
+    return names.length > 0 ? names : ['nothing'];
+}

package/dist/provider/latency.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare class LatencyEstimator {
+    private readonly window;
+    private readonly scratch;
+    private readonly minSamples;
+    private cursor;
+    private filled;
+    constructor(capacity?: number, minSamples?: number);
+    get samples(): number;
+    /** `-1` until `minSamples` are in, which the watermark reads as "issue immediately". */
+    get p90(): number;
+    record(ms: number): void;
+}

package/dist/provider/latency.js

@@ -0,0 +1,52 @@
+/**
+ * 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 {
+    window;
+    scratch;
+    minSamples;
+    cursor = 0;
+    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() {
+        return this.filled;
+    }
+    /** `-1` until `minSamples` are in, which the watermark reads as "issue immediately". */
+    get p90() {
+        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) {
+        this.window[this.cursor] = ms;
+        this.cursor = (this.cursor + 1) % this.window.length;
+        if (this.filled < this.window.length)
+            this.filled++;
+    }
+}

package/dist/provider/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The provider seam. Provider-specific concerns stay behind adapters.
+ *
+ * Capability is **declared rather than assumed**, so a session refuses an
+ * unsupported requirement early and in words instead of discovering it in
+ * production at whatever a failed request costs.
+ */
+/**
+ * What a provider says it can do.
+ *
+ * Declared by the adapter rather than probed, except where a probe is cheap and
+ * honest — `createLocalProvider` runs one, because a local model's availability is
+ * a property of the device rather than of the configuration.
+ */
+export interface AiProviderCapabilities {
+    readonly text: boolean;
+    readonly streamingText: boolean;
+    readonly structuredOutput: boolean;
+    readonly toolCalling: boolean;
+    readonly realtimeAudio: boolean;
+    readonly imageInput: boolean;
+    readonly local: boolean;
+}
+/**
+ * Context assembled for one request.
+ *
+ * Declared minimally here and widened where it is built. What the seam needs is
+ * the capture tick: a model must be able to know its snapshot may be stale, and a
+ * buffered agent widens that gap on purpose.
+ */
+export interface AssembledContextLike {
+    readonly capturedAtTick: number;
+}
+export type AiEvent = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'toolCall';
+    readonly callId: string;
+    readonly toolId: string;
+    readonly args: unknown;
+} | {
+    readonly kind: 'usage';
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+} | {
+    readonly kind: 'done';
+    readonly reason: 'complete' | 'aborted' | 'error';
+    readonly message?: string;
+};
+export interface AiRequest {
+    readonly preamble: string;
+    readonly context: AssembledContextLike;
+    readonly toolIds: readonly string[];
+    readonly signal: AbortSignal;
+}
+export interface AiSessionOptions {
+    readonly model: string;
+    readonly systemPrompt?: string;
+    readonly maxOutputTokens?: number;
+    readonly temperature?: number;
+}
+export interface AiSession {
+    run(request: AiRequest): AsyncIterable<AiEvent>;
+    abort(reason?: string): void;
+}
+export interface AiProvider {
+    readonly id: string;
+    readonly capabilities: AiProviderCapabilities;
+    createSession(options: AiSessionOptions): AiSession;
+}
+export interface AiProviderConfig {
+    readonly kind: 'proxy' | 'local' | 'deterministic';
+    readonly session: AiSessionOptions;
+    /**
+     * The provider itself, where the caller already has one.
+     *
+     * Adapters that must be constructed — a local model that has to probe the device —
+     * are built by their own factory and handed here, so this function does one job:
+     * comparing what is declared against what is required.
+     */
+    readonly provider?: AiProvider;
+    /** Adapter-specific, and never a credential — see `adapters/proxy.ts`. */
+    readonly adapter?: Readonly<Record<string, unknown>>;
+}
+export interface AiProviderResult {
+    readonly provider: AiProvider | null;
+    /** Always a sentence, on both paths. An empty reason is the silent no-op. */
+    readonly reason: string;
+}

package/dist/provider/types.js

@@ -0,0 +1,8 @@
+/**
+ * The provider seam. Provider-specific concerns stay behind adapters.
+ *
+ * Capability is **declared rather than assumed**, so a session refuses an
+ * unsupported requirement early and in words instead of discovering it in
+ * production at whatever a failed request costs.
+ */
+export {};

package/dist/realtime/session.d.ts

@@ -0,0 +1,35 @@
+import type { AiProvider, AiSession } from '../provider/types.ts';
+/**
+ * A realtime transport, emitting the same events every other session emits.
+ *
+ * **Additive.** Nothing downstream branches on transport: the buffered loop, the floor,
+ * the admission guards and the command log all see the same `AiEvent` union they
+ * already see. A session with realtime configured still has exactly one request in
+ * flight, because the state machine does not know what a transport is.
+ *
+ * **Audio stays bridged, not coupled.** This module imports nothing from
+ * `@driftengine/audio`, and the package declares no dependency on it. A consumer wires
+ * its own microphone and speaker to whatever this yields, because the moment an AI
+ * package owned an audio graph it would be an AI package that knew what a mix was.
+ */
+export interface RealtimeOptions {
+    readonly model: string;
+    /** Frames a consumer pushes in. Text here, because audio is the consumer's to carry. */
+    readonly input?: AsyncIterable<string>;
+}
+export type RealtimeResult = {
+    readonly session: AiSession;
+    readonly reason: string;
+} | {
+    readonly session: null;
+    readonly reason: string;
+};
+/**
+ * Open a realtime session, or refuse before connecting.
+ *
+ * Refused **before** any transport is opened, in the shape §32 requires of every other
+ * provider decision: a socket opened against a provider that cannot hold a realtime
+ * conversation is a socket that fails later and more expensively than a string
+ * comparison.
+ */
+export declare function createRealtimeSession(provider: AiProvider, options: RealtimeOptions): RealtimeResult;

package/dist/realtime/session.js

@@ -0,0 +1,34 @@
+/**
+ * Open a realtime session, or refuse before connecting.
+ *
+ * Refused **before** any transport is opened, in the shape §32 requires of every other
+ * provider decision: a socket opened against a provider that cannot hold a realtime
+ * conversation is a socket that fails later and more expensively than a string
+ * comparison.
+ */
+export function createRealtimeSession(provider, options) {
+    if (!provider.capabilities.realtimeAudio) {
+        return {
+            session: null,
+            reason: `provider "${provider.id}" declares no realtime transport — a session cannot be opened against it`,
+        };
+    }
+    const inner = provider.createSession({ model: options.model });
+    let disposed = false;
+    return {
+        session: {
+            run(request) {
+                return inner.run(request);
+            },
+            abort(reason) {
+                /* A second disposal is a no-op rather than an error. Disposal races a scene
+                   replacement and a hot reload, and both may reach the same session. */
+                if (disposed)
+                    return;
+                disposed = true;
+                inner.abort(reason ?? 'realtime session disposed');
+            },
+        },
+        reason: `realtime session open against "${provider.id}"`,
+    };
+}