@driftengine/ai 3.61.0

package/dist/session/agent.d.ts

@@ -0,0 +1,217 @@
+import type { AiProvider } from '../provider/types.ts';
+import type { AgentPolicy, Intent } from '../policy/types.ts';
+import type { Budget } from '../budget/budget.ts';
+import type { ToolRegistry } from '../tools/registry.ts';
+import type { CommandLog } from '../command/log.ts';
+import type { AiUsage } from './usage.ts';
+import type { AgentState } from './states.ts';
+export interface AgentSessionOptions<W = unknown> {
+    readonly agentId: string;
+    readonly policy: AgentPolicy;
+    /** Absent is a supported configuration, not a degraded one. The floor is enough. */
+    readonly provider?: AiProvider;
+    readonly budget?: Budget;
+    readonly model?: string;
+    /** Tools, and the admission guards they declared. Absent admits everything. */
+    readonly tools?: ToolRegistry<W>;
+    /** The consumer's world, handed to a guard unchanged. */
+    readonly world?: W;
+    /**
+     * What an observation arriving while a request is out does.
+     *
+     * `queue` and `replace pending` are deliberately absent. Both described what to do
+     * with a *second* request, and there is never one — the state machine has no edge
+     * on which it could be issued.
+     */
+    readonly whileBusy?: WhileBusy;
+    readonly maxPendingObservations?: number;
+    readonly dedupeWindowMs?: number;
+    /** Where accepted model commands are recorded, so a run can be replayed exactly. */
+    readonly log?: CommandLog;
+    /**
+     * A ceiling on how long any one intent may hold the slot, in milliseconds.
+     *
+     * An intent with an unknown extent ends when the consumer says so, which is the
+     * contract — the consumer is the thing that knows whether the walk finished. But a
+     * consumer that forgets leaves the agent on one intent forever, which is the blocked
+     * agent arriving through the back door.
+     *
+     * Off by default, because a default here would be a guess about behaviours this
+     * package cannot see, and a wrong one would cut short a legitimately long action.
+     * *What it costs when set:* a genuinely long intent is reclaimed by the floor.
+     * *What would make it wrong:* a consumer whose intents legitimately outlast any
+     * figure worth writing down, which should set nothing and call `complete`.
+     */
+    readonly maxIntentMs?: number;
+    /**
+     * A second, faster provider asked only when something interrupts.
+     *
+     * §46's tiering: a small or local model answers "something happened, react now" in
+     * well under the strong model's latency, while the strong one is still composing the
+     * next intent. Additive — absent, preemption behaves exactly as it does without it.
+     *
+     * *What it costs:* a second provider to configure and a second bill. *What would
+     * make it wrong:* an interrupt model slow enough that the floor beats it to the
+     * answer, at which point it is buying nothing the floor did not already give.
+     */
+    readonly interruptProvider?: AiProvider;
+}
+export type WhileBusy = 'coalesce' | 'preempt' | 'drop';
+export interface Observation {
+    readonly id: string;
+    readonly priority: number;
+    readonly text: string;
+}
+/**
+ * One agent: a floor that always runs, and one slot holding what comes next.
+ *
+ * **The current slot is never empty.** When an intent finishes, the buffer drains into
+ * it; when the buffer is empty, the policy floor supplies. An agent with no provider
+ * configured behaves exactly as one whose provider is slow — less cleverly, and
+ * without ever standing still.
+ *
+ * `tick` is the whole surface a consumer needs inside its fixed step. It returns the
+ * intent to execute and never returns null.
+ */
+export declare class AgentSession<W = unknown> {
+    readonly agentId: string;
+    private readonly policy;
+    private readonly provider;
+    private readonly budget;
+    private readonly model;
+    private readonly tools;
+    private readonly whileBusy;
+    private readonly observations;
+    private readonly log;
+    private readonly maxIntentMs;
+    private readonly interruptProvider;
+    private readonly world;
+    private readonly latency;
+    private readonly usageState;
+    private agentState;
+    private currentIntent;
+    private bufferedIntent;
+    private startedAtMs;
+    private disposedReason;
+    private inFlight;
+    private inFlightAt;
+    /** When the pending response's request went out, or -1 when nothing has landed. */
+    private landedAtMs;
+    private discarded;
+    private issuedAtTick;
+    private inFlightGeneration;
+    private readonly context;
+    constructor(options: AgentSessionOptions<W>);
+    /**
+     * Something happened that the agent may care about.
+     *
+     * Never acted on here — an observation taken mid-tick would mutate the simulation
+     * halfway through a step. It waits for the next `tick`.
+     */
+    observe(observation: Observation): void;
+    get state(): AgentState;
+    /** Never null once `tick` has run once. */
+    get current(): Intent | null;
+    get buffered(): Intent | null;
+    get usage(): Readonly<AiUsage>;
+    /**
+     * Advance one fixed step and return the intent to execute.
+     *
+     * Never returns null. That is the track's whole claim and it is asserted directly.
+     */
+    tick(tickNumber: number, nowMs: number): Intent;
+    /** The consumer says the current intent is over, ahead of its expected extent. */
+    complete(nowMs: number): void;
+    /**
+     * End the current intent and fill the slot again.
+     *
+     * **Aborts a request that is still in flight.** `ahead -> intentCompleted -> idle`
+     * abandons the question, and a request nobody will read is a request that should
+     * stop costing money — but more than that, leaving it open means the next intent
+     * issues a second one and two are outstanding at once, which is the guarantee the
+     * state machine is shaped to make impossible. The state machine cannot see the
+     * provider; this is where the two are kept in agreement.
+     */
+    private finish;
+    dispose(reason?: string): void;
+    /**
+     * Fill the current slot: from the buffer if something is there, from the floor if not.
+     *
+     * The order matters and only in one direction — a buffered intent is a model's
+     * answer to the question the floor would otherwise be answering, so it wins when it
+     * exists. There is no case where the floor should override a fresh proposal, because
+     * a proposal the floor should override is one the admission guards discard.
+     */
+    private take;
+    /**
+     * Whether a buffered intent is still true of the world.
+     *
+     * Composed from the guards the *tools* declared, never from anything the model
+     * wrote. With no registry configured every intent admits: a consumer that has not
+     * described its world cannot have its plans checked against it, and pretending
+     * otherwise would be a check that always passes wearing the shape of one that means
+     * something.
+     */
+    private admits;
+    /**
+     * Take the most important observation waiting, and act on it if it outranks now.
+     *
+     * At the tick boundary, never mid-tick. Nothing mutates the simulation halfway
+     * through a step, which is the boundary §33 of the parent design already runs.
+     */
+    private drainObservations;
+    /**
+     * Throw away the current intent, the buffer and the request, and let the floor cover.
+     *
+     * *Cost, stated:* one in-flight request is discarded. That is the token price of
+     * responsiveness, bounded by the preemption rate, which the consumer sets through
+     * priorities — so `usage.preemptedRequests` reports it. A number nobody reports is a
+     * number nobody tunes.
+     */
+    private preempt;
+    private askInterrupt;
+    private consumeInterrupt;
+    /**
+     * Write an admitted model intent into the command log.
+     *
+     * Only model intents. The floor is deterministic and recomputes identically on
+     * replay, so recording its decisions would store what can be derived — and a
+     * thousand-tick recording would be a thousand entries instead of a handful.
+     */
+    private record;
+    /** True once a budget is exhausted: still moving, no longer asking. */
+    get degraded(): boolean;
+    /** The budget's own sentence, or empty while nothing is exhausted. */
+    get degradedReason(): string;
+    /** Buffered intents discarded because their guard had gone false. */
+    get discardedIntents(): number;
+    private finished;
+    /**
+     * Issue the continuation, if this is the tick to issue it on.
+     *
+     * The watermark itself is `leadMs`. This only decides whether the state machine
+     * has an edge available, which is where one-request-in-flight actually lives.
+     */
+    private maybeContinue;
+    /** The lead the watermark uses: the provider's measured p90, or -1 before it knows. */
+    get leadMs(): number;
+    /**
+     * Charge the latency of a response, measured to the tick that observed it.
+     *
+     * A response lands in a microtask, where there is no simulation clock to read. So
+     * the landing is flagged and priced on the next `tick`, which measures the latency a
+     * fixed-step consumer *experiences* rather than the one a wall clock would report.
+     * Those differ by up to one step, and the one that matters for deciding when to ask
+     * again is this one.
+     *
+     * *What it costs:* a response landing just after a tick is charged nearly a whole
+     * step more than it took. *What would make it wrong:* a consumer stepping far more
+     * slowly than its provider answers, where a step's rounding would dominate the
+     * measurement — at which point the session needs a clock rather than a flag.
+     */
+    private recordLanding;
+    private issue;
+    private consume;
+    private abortInFlight;
+    private transition;
+}