@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/text.d.ts

@@ -0,0 +1,2 @@
+/** Limit UTF-16 length without splitting a surrogate pair at the boundary. */
+export declare function clipText(text: string, limit: number): string;

package/dist/src/text.js

@@ -0,0 +1,8 @@
+/** Limit UTF-16 length without splitting a surrogate pair at the boundary. */
+export function clipText(text, limit) {
+    let end = limit;
+    const before = text.charCodeAt(end - 1), after = text.charCodeAt(end);
+    if (before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff)
+        end--;
+    return text.slice(0, end);
+}

package/dist/src/timers.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Self-wake timers armed by the agent's `set_timer` tool. The owning session
+ * drains them into live steering or an idle composer; this module only tracks
+ * deadlines and never decides where a fired prompt goes.
+ * @module timers
+ */
+/** Shortest delay the registry accepts, in seconds. */
+export declare const MIN_TIMER_SECONDS = 1;
+/** Longest delay the registry accepts, in seconds (one day). */
+export declare const MAX_TIMER_SECONDS = 86400;
+/** Ceiling on simultaneously armed timers, so a looping agent cannot flood the queue. */
+export declare const MAX_TIMERS = 20;
+/** Longest self-wake prompt the registry stores. */
+export declare const MAX_TIMER_PROMPT_CHARS = 4000;
+/**
+ * How long a wake that is put back waits before it may be tried again, once its deadline has passed.
+ *
+ * A returned deadline is already in the past, and `schedule` clamps a non-positive delay to a millisecond, so
+ * a wake handed straight back is due again immediately. The engine that returns one is busy with something
+ * else, and a sweep that takes it, fails and returns it every millisecond is a hot loop that spends the
+ * process while the engine is busy. The deadline is a floor on when a prompt may be given, not a promise about
+ * when it is given, so waiting a beat before the next attempt costs nothing the wake was owed.
+ */
+/**
+ * How long a wake that came due and could not be delivered waits before it is tried again.
+ *
+ * Exported because anything sweeping for the next deadline must not look at such a wake any sooner than the
+ * registry itself will: a deadline that has passed stays passed, and a sweep that reads the same failure every
+ * millisecond spends the process while the condition it is waiting on clears.
+ */
+export declare const WAKE_RETRY_MS = 5000;
+/**
+ * The execution selections of the run that armed a wake.
+ *
+ * A wake is a continuation of the conversation its arming run was working in, so its delivery should run under
+ * the selections that run was started with. Left to the deadline, a per-project graph or model, a per-run
+ * thinking effort, and a per-run input/state scope would all be replaced by whatever the configuration says at
+ * that moment, and the delayed continuation would be different work - different tools, behavior and cost - than
+ * the one the agent was promised. Each value is stored as it was selected, never as a resolved id, so putting it
+ * back re-resolves the way the arming request did. A wake armed by a surface with no run of its own carries
+ * nothing, and its delivery resolves as a plain new task would.
+ */
+export interface WakeCarry {
+    graph?: string;
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+    /** Set when the arming run overrode every node's model, so the continuation runs the same one. */
+    overrideAllNodes?: boolean;
+    /**
+     * Set when the arming run's panel browser operations go through the desktop relay.
+     *
+     * The wake is delivered by the same engine that armed it, so an engine that does not own the
+     * session's panel browser still does not own it on the deadline: without this the continuation
+     * builds its tool without a relay and browses a second, invisible browser instead of the tabs
+     * and login state the user is watching.
+     */
+    panelBrowserRelay?: boolean;
+    input?: Record<string, unknown>;
+    state?: Record<string, unknown>;
+}
+export interface ArmedTimer {
+    id: string;
+    /** The prompt delivered when the timer fires, exactly as the agent submitted it. */
+    prompt: string;
+    seconds: number;
+    /** Wall-clock epoch milliseconds the prompt becomes due. */
+    fireAt: number;
+    /**
+     * The session the wake belongs to, when the caller tagged it.
+     *
+     * A CLI owns one registry per live session and never needs the tag. An app-server engine holds one
+     * registry for every session it has served, so a wake has to say whose it is — otherwise a wait would
+     * be shown on the wrong row, and a drain could deliver one session's prompt into another's run.
+     */
+    owner?: string;
+    /** What the run that armed this wake was started with, so its delivery can start the same kind of run. */
+    carry?: WakeCarry;
+    /**
+     * Earliest epoch milliseconds at which a drain may take this wake, set when a delivery hands it back.
+     *
+     * A returned wake's deadline is already in the past, and a drain looks for exactly that, so without a floor of
+     * its own the next sweep takes the same wake again the millisecond it looks at it. The wake's own one-shot
+     * already waits {@link WAKE_RETRY_MS} before it asks for a pass; this is what makes every *other* path into the
+     * registry — an engine's shared check, another session's callback — wait the same beat, instead of reading the
+     * same failure over and over while the condition it is waiting on clears.
+     */
+    notBefore?: number;
+}
+/**
+ * Pending self-wake prompts for one session.
+ *
+ * Each timer owns one unref'd `setTimeout`, so an armed prompt never holds the
+ * process open. {@link takeDue} is the authoritative drain: it reaps by
+ * `fireAt`, so prompts that came due while a busy event loop delayed their own
+ * callback are still collected, and a timer only leaves the registry once its
+ * prompt has been taken.
+ */
+export declare class TimerRegistry {
+    private readonly armed;
+    /** Invoked when a timer's own callback fires, so a live session can deliver immediately. */
+    onDue?: () => void;
+    /**
+     * Invoked when a wake is armed, so the engine holding the registry can publish what another
+     * engine's reaper pass cannot see: the wake itself lives only in this process. The CLI, whose
+     * registry serves one session surface, leaves it unset.
+     */
+    onArmed?: (timer: ArmedTimer) => void;
+    /**
+     * Timers still waiting, soonest first — optionally only the ones owned by one session.
+     *
+     * Omitting the owner keeps a single-session CLI reading, where one registry is one session. An engine
+     * that serves several sessions passes it, because a wake armed by a task in one session is not
+     * another's to show as waiting.
+     *
+     * A wake a surface has taken for delivery ({@link takeDueOne}) is still listed: it has not been delivered,
+     * and the session is still owed the prompt. That is what lets a client that reloads mid-delivery see the
+     * wait it is still waiting on — and, for an engine, that it still owns the wake the run has not yet carried.
+     */
+    list(owner?: string): ArmedTimer[];
+    /** A wake in hand: taken for delivery, and still owed until {@link settle} or {@link restore} says otherwise. */
+    private held;
+    /** The earliest epoch milliseconds at which a drain may take this wake again. */
+    private nextTakeAt;
+    arm(seconds: number, prompt: string, owner?: string, carry?: WakeCarry): ArmedTimer;
+    /**
+     * Arm (or re-arm) the one wake-up for a timer.
+     *
+     * The callback deliberately does not remove the entry: `takeDue` is the only drain, so a
+     * prompt cannot be lost between the timer firing and the session collecting it. A relative
+     * timeout can fire while the wall clock still precedes `fireAt` — an NTP correction stepped
+     * the clock backward — and in that case the entry must keep a live wake-up as well as
+     * staying armed, or an idle session would never learn the prompt came due.
+     */
+    private schedule;
+    /**
+     * The soonest wake whose deadline has passed and which is not waiting out a retry, taken for delivery.
+     *
+     * `takeDue` hands over every due prompt at once, which is what a session collecting its own wakes wants
+     * and what an engine delivering them one run at a time must not use: a pass that stops partway — because
+     * the run it just started now has the engine — would be holding prompts it never delivered, and a wake
+     * held that way is gone with the process. Taking one keeps every undelivered wake armed and on the clock.
+     *
+     * The wake that comes back is *held*, not removed: it stays in {@link list} until the caller says what
+     * became of it with {@link settle} (delivered or spent) or {@link restore} (put back). A wake in hand is
+     * still owed, and a client that asks in that moment must be told it is still waiting. For an engine that
+     * answers for a session the moment its deadline passes and the run only later, this is the difference between
+     * a reload finding the wake it must keep routing to that engine, and a reload concluding nothing is owed.
+     */
+    takeDueOne(now?: number, owner?: string): ArmedTimer | undefined;
+    /**
+     * Say a taken wake has been delivered or spent: it is no longer owed, and no longer waits.
+     *
+     * The counterpart of {@link takeDueOne}. Removing the wake here is what finally stops a row from drawing the
+     * clock — which is why the delivery says it only once a run really carries the prompt, rather than the moment
+     * its deadline was reached.
+     */
+    settle(id: string): boolean;
+    /**
+     * Put back a wake this process had taken, unchanged: the same id, prompt and deadline.
+     *
+     * A delivery the engine could not make has spent nothing. A deadline says the earliest a prompt may be
+     * given, and a deadline that has passed stays passed — so the row keeps saying the session is waiting,
+     * which is still the truth. A wake that is already due is tried again after {@link RESTORE_RETRY_MS} rather
+     * than the millisecond its own deadline would give it, because the process returning one is busy, and a
+     * sweep that retried it every millisecond would spend the process while it stays busy. That wait is recorded
+     * as the wake's own floor, so it holds for every path into the registry and not only for the one-shot armed
+     * here. Re-arming goes through the same one-shot as any other wake, so the surface holding the registry is
+     * told to look again. The cap on armed timers is not re-checked here: this wake was already counted when it
+     * was armed, and a restore that refused would throw away a prompt the session is still owed.
+     */
+    restore(timer: ArmedTimer, retryAfterMs?: number): void;
+    cancel(id: string): boolean;
+    /**
+     * Every timer whose deadline has passed and which is not waiting out a retry or in another surface's hand,
+     * soonest first, removed from the registry.
+     *
+     * An owner narrows the drain to one session's wakes. Without it a drain takes every due prompt in the
+     * process, which is right for a single-session CLI and wrong for an engine serving several.
+     */
+    takeDue(now?: number, owner?: string): ArmedTimer[];
+    /**
+     * Drop every pending timer without delivering anything, or only one owner's when one is given.
+     *
+     * Deleting a session goes through the scoped form: a wake whose session is gone has nothing to return
+     * to, and leaving it armed would keep a row that no longer exists looking like it is still waiting.
+     */
+    clear(owner?: string): void;
+}

package/dist/src/timers.js

@@ -0,0 +1,244 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Self-wake timers armed by the agent's `set_timer` tool. The owning session
+ * drains them into live steering or an idle composer; this module only tracks
+ * deadlines and never decides where a fired prompt goes.
+ * @module timers
+ */
+/** Shortest delay the registry accepts, in seconds. */
+export const MIN_TIMER_SECONDS = 1;
+/** Longest delay the registry accepts, in seconds (one day). */
+export const MAX_TIMER_SECONDS = 86_400;
+/** Ceiling on simultaneously armed timers, so a looping agent cannot flood the queue. */
+export const MAX_TIMERS = 20;
+/** Longest self-wake prompt the registry stores. */
+export const MAX_TIMER_PROMPT_CHARS = 4_000;
+/**
+ * The largest delay `setTimeout` accepts before Node clamps it to 1 ms. A re-arm after a
+ * backward wall-clock step computes its delay from the stored deadline, which can exceed
+ * this after a large clock correction, so the delay is clamped the way `deadline.ts` clamps
+ * a long budget.
+ */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * How long a wake that is put back waits before it may be tried again, once its deadline has passed.
+ *
+ * A returned deadline is already in the past, and `schedule` clamps a non-positive delay to a millisecond, so
+ * a wake handed straight back is due again immediately. The engine that returns one is busy with something
+ * else, and a sweep that takes it, fails and returns it every millisecond is a hot loop that spends the
+ * process while the engine is busy. The deadline is a floor on when a prompt may be given, not a promise about
+ * when it is given, so waiting a beat before the next attempt costs nothing the wake was owed.
+ */
+/**
+ * How long a wake that came due and could not be delivered waits before it is tried again.
+ *
+ * Exported because anything sweeping for the next deadline must not look at such a wake any sooner than the
+ * registry itself will: a deadline that has passed stays passed, and a sweep that reads the same failure every
+ * millisecond spends the process while the condition it is waiting on clears.
+ */
+export const WAKE_RETRY_MS = 5_000;
+const RESTORE_RETRY_MS = WAKE_RETRY_MS;
+/**
+ * Pending self-wake prompts for one session.
+ *
+ * Each timer owns one unref'd `setTimeout`, so an armed prompt never holds the
+ * process open. {@link takeDue} is the authoritative drain: it reaps by
+ * `fireAt`, so prompts that came due while a busy event loop delayed their own
+ * callback are still collected, and a timer only leaves the registry once its
+ * prompt has been taken.
+ */
+export class TimerRegistry {
+    armed = new Map();
+    /** Invoked when a timer's own callback fires, so a live session can deliver immediately. */
+    onDue;
+    /**
+     * Invoked when a wake is armed, so the engine holding the registry can publish what another
+     * engine's reaper pass cannot see: the wake itself lives only in this process. The CLI, whose
+     * registry serves one session surface, leaves it unset.
+     */
+    onArmed;
+    /**
+     * Timers still waiting, soonest first — optionally only the ones owned by one session.
+     *
+     * Omitting the owner keeps a single-session CLI reading, where one registry is one session. An engine
+     * that serves several sessions passes it, because a wake armed by a task in one session is not
+     * another's to show as waiting.
+     *
+     * A wake a surface has taken for delivery ({@link takeDueOne}) is still listed: it has not been delivered,
+     * and the session is still owed the prompt. That is what lets a client that reloads mid-delivery see the
+     * wait it is still waiting on — and, for an engine, that it still owns the wake the run has not yet carried.
+     */
+    list(owner) {
+        const waiting = [...this.armed.values()].map(entry => entry.timer);
+        return (owner === undefined ? waiting : waiting.filter(timer => timer.owner === owner))
+            .sort((left, right) => left.fireAt - right.fireAt);
+    }
+    /** A wake in hand: taken for delivery, and still owed until {@link settle} or {@link restore} says otherwise. */
+    held(timer) {
+        return this.armed.get(timer.id)?.held === true;
+    }
+    /** The earliest epoch milliseconds at which a drain may take this wake again. */
+    nextTakeAt(timer) {
+        return Math.max(timer.fireAt, timer.notBefore ?? 0);
+    }
+    arm(seconds, prompt, owner, carry) {
+        if (typeof seconds !== 'number' || !Number.isSafeInteger(seconds) || seconds < MIN_TIMER_SECONDS || seconds > MAX_TIMER_SECONDS) {
+            throw new Error(`seconds must be an integer from ${MIN_TIMER_SECONDS} to ${MAX_TIMER_SECONDS}`);
+        }
+        if (typeof prompt !== 'string' || !prompt.trim().length || prompt.includes('\0'))
+            throw new Error('prompt must be a nonempty string without NUL bytes');
+        if (prompt.length > MAX_TIMER_PROMPT_CHARS)
+            throw new Error(`prompt must be at most ${MAX_TIMER_PROMPT_CHARS} characters`);
+        if (this.armed.size >= MAX_TIMERS)
+            throw new Error(`At most ${MAX_TIMERS} timers may be armed at once`);
+        // Cloned, because the run keeps working with the objects it handed here: a wake must not see a scope that
+        // its arming run mutated after the prompt was armed.
+        const stored = carry === undefined || Object.keys(carry).length === 0 ? undefined : structuredClone(carry);
+        const timer = { id: randomUUID(), prompt: prompt.trim(), seconds, fireAt: Date.now() + seconds * 1_000, ...(owner === undefined ? {} : { owner }), ...(stored === undefined ? {} : { carry: stored }) };
+        const entry = { timer };
+        this.schedule(timer, entry, seconds * 1_000);
+        this.armed.set(timer.id, entry);
+        this.onArmed?.(timer);
+        return timer;
+    }
+    /**
+     * Arm (or re-arm) the one wake-up for a timer.
+     *
+     * The callback deliberately does not remove the entry: `takeDue` is the only drain, so a
+     * prompt cannot be lost between the timer firing and the session collecting it. A relative
+     * timeout can fire while the wall clock still precedes `fireAt` — an NTP correction stepped
+     * the clock backward — and in that case the entry must keep a live wake-up as well as
+     * staying armed, or an idle session would never learn the prompt came due.
+     */
+    schedule(timer, entry, delayMs) {
+        const remaining = delayMs ?? timer.fireAt - Date.now();
+        entry.handle = setTimeout(() => {
+            if (timer.fireAt - Date.now() > 0) {
+                this.schedule(timer, entry);
+                return;
+            }
+            this.onDue?.();
+        }, Math.min(Math.max(remaining, 1), MAX_TIMER_DELAY_MS));
+        entry.handle.unref?.();
+    }
+    /**
+     * The soonest wake whose deadline has passed and which is not waiting out a retry, taken for delivery.
+     *
+     * `takeDue` hands over every due prompt at once, which is what a session collecting its own wakes wants
+     * and what an engine delivering them one run at a time must not use: a pass that stops partway — because
+     * the run it just started now has the engine — would be holding prompts it never delivered, and a wake
+     * held that way is gone with the process. Taking one keeps every undelivered wake armed and on the clock.
+     *
+     * The wake that comes back is *held*, not removed: it stays in {@link list} until the caller says what
+     * became of it with {@link settle} (delivered or spent) or {@link restore} (put back). A wake in hand is
+     * still owed, and a client that asks in that moment must be told it is still waiting. For an engine that
+     * answers for a session the moment its deadline passes and the run only later, this is the difference between
+     * a reload finding the wake it must keep routing to that engine, and a reload concluding nothing is owed.
+     */
+    takeDueOne(now = Date.now(), owner) {
+        const next = this.list(owner).find(timer => this.nextTakeAt(timer) <= now && !this.held(timer));
+        if (next === undefined)
+            return undefined;
+        const entry = this.armed.get(next.id);
+        if (entry !== undefined) {
+            if (entry.handle)
+                clearTimeout(entry.handle);
+            // Held, so no other drain hands the same prompt out twice while this one is being delivered.
+            entry.held = true;
+        }
+        return next;
+    }
+    /**
+     * Say a taken wake has been delivered or spent: it is no longer owed, and no longer waits.
+     *
+     * The counterpart of {@link takeDueOne}. Removing the wake here is what finally stops a row from drawing the
+     * clock — which is why the delivery says it only once a run really carries the prompt, rather than the moment
+     * its deadline was reached.
+     */
+    settle(id) {
+        const entry = this.armed.get(id);
+        if (entry === undefined)
+            return false;
+        if (entry.handle)
+            clearTimeout(entry.handle);
+        this.armed.delete(id);
+        return true;
+    }
+    /**
+     * Put back a wake this process had taken, unchanged: the same id, prompt and deadline.
+     *
+     * A delivery the engine could not make has spent nothing. A deadline says the earliest a prompt may be
+     * given, and a deadline that has passed stays passed — so the row keeps saying the session is waiting,
+     * which is still the truth. A wake that is already due is tried again after {@link RESTORE_RETRY_MS} rather
+     * than the millisecond its own deadline would give it, because the process returning one is busy, and a
+     * sweep that retried it every millisecond would spend the process while it stays busy. That wait is recorded
+     * as the wake's own floor, so it holds for every path into the registry and not only for the one-shot armed
+     * here. Re-arming goes through the same one-shot as any other wake, so the surface holding the registry is
+     * told to look again. The cap on armed timers is not re-checked here: this wake was already counted when it
+     * was armed, and a restore that refused would throw away a prompt the session is still owed.
+     */
+    restore(timer, retryAfterMs = RESTORE_RETRY_MS) {
+        const existing = this.armed.get(timer.id);
+        // Already waiting on its own clock: nothing was handed back. A wake held for delivery is different — the
+        // delivery is over and the wake is owed again, so the held flag goes away with this call.
+        if (existing !== undefined && !existing.held)
+            return;
+        const now = Date.now();
+        // A wake still in the future keeps its own deadline; a due one waits a beat before it is tried again.
+        const remaining = timer.fireAt - now;
+        const notBefore = Math.max(timer.notBefore ?? 0, remaining > 0 ? 0 : now + retryAfterMs);
+        const stored = { ...timer, ...(notBefore > 0 ? { notBefore } : {}) };
+        const entry = { timer: stored };
+        this.armed.set(timer.id, entry);
+        this.schedule(stored, entry, remaining > 0 ? remaining : retryAfterMs);
+    }
+    cancel(id) {
+        const entry = this.armed.get(id);
+        if (!entry)
+            return false;
+        if (entry.handle)
+            clearTimeout(entry.handle);
+        this.armed.delete(id);
+        return true;
+    }
+    /**
+     * Every timer whose deadline has passed and which is not waiting out a retry or in another surface's hand,
+     * soonest first, removed from the registry.
+     *
+     * An owner narrows the drain to one session's wakes. Without it a drain takes every due prompt in the
+     * process, which is right for a single-session CLI and wrong for an engine serving several.
+     */
+    takeDue(now = Date.now(), owner) {
+        const due = [];
+        for (const [id, entry] of this.armed) {
+            if (owner !== undefined && entry.timer.owner !== owner)
+                continue;
+            // A wake an engine is mid-delivery with is not this surface's to hand out, and a wake that came back is
+            // waiting out the beat it came back for. Both stay put.
+            if (entry.held)
+                continue;
+            if (this.nextTakeAt(entry.timer) > now)
+                continue;
+            if (entry.handle)
+                clearTimeout(entry.handle);
+            this.armed.delete(id);
+            due.push(entry.timer);
+        }
+        return due.sort((left, right) => left.fireAt - right.fireAt);
+    }
+    /**
+     * Drop every pending timer without delivering anything, or only one owner's when one is given.
+     *
+     * Deleting a session goes through the scoped form: a wake whose session is gone has nothing to return
+     * to, and leaving it armed would keep a row that no longer exists looking like it is still waiting.
+     */
+    clear(owner) {
+        for (const [id, entry] of [...this.armed]) {
+            if (owner !== undefined && entry.timer.owner !== owner)
+                continue;
+            if (entry.handle)
+                clearTimeout(entry.handle);
+            this.armed.delete(id);
+        }
+    }
+}

package/dist/src/todos.d.ts

@@ -0,0 +1,12 @@
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+export interface TodoItem {
+    id: string;
+    text: string;
+    status: TodoStatus;
+}
+/** One graph run's plan. Snapshots are defensive copies, never shared mutable arrays. */
+export declare class TodoStore {
+    private items;
+    snapshot(): TodoItem[];
+    update(value: unknown, maxSerializedChars?: number): TodoItem[];
+}

package/dist/src/todos.js

@@ -0,0 +1,33 @@
+/** One graph run's plan. Snapshots are defensive copies, never shared mutable arrays. */
+export class TodoStore {
+    items = [];
+    snapshot() { return this.items.map(item => ({ ...item })); }
+    update(value, maxSerializedChars = 12_000) {
+        if (!Array.isArray(value) || value.length < 1 || value.length > 100)
+            throw new Error('todos must contain 1-100 items');
+        const ids = new Set();
+        const next = value.map((item) => {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                throw new Error('Each todo must be an object');
+            const todo = item;
+            if (Object.keys(todo).some(key => !['id', 'text', 'status'].includes(key))
+                || typeof todo.id !== 'string' || !todo.id.trim() || todo.id.length > 80
+                || typeof todo.text !== 'string' || !todo.text.trim() || todo.text.length > 500
+                || typeof todo.status !== 'string' || !['pending', 'in_progress', 'completed'].includes(todo.status)) {
+                throw new Error('Each todo requires id (1-80 characters), text (1-500 characters), and status pending, in_progress, or completed');
+            }
+            const id = todo.id.trim();
+            if (ids.has(id))
+                throw new Error(`Duplicate todo id: ${id}`);
+            ids.add(id);
+            return { id, text: todo.text.trim(), status: todo.status };
+        });
+        // Count the escaped representation used inside a serialized model message,
+        // not just source characters (control characters can expand sixfold).
+        if (JSON.stringify(JSON.stringify(next)).length > maxSerializedChars) {
+            throw new Error(`Serialized todos exceed ${maxSerializedChars} characters; publish a shorter plan`);
+        }
+        this.items = next;
+        return this.snapshot();
+    }
+}

package/dist/src/token-rate.d.ts

@@ -0,0 +1,119 @@
+import type { GenerateRequest } from './types.js';
+/**
+ * Estimate the tokens in a streamed fragment: four ASCII characters to a token, the common
+ * rate for English prose and code, and one token per character outside ASCII, which CJK text
+ * comes close to. Only a live reading uses it; the provider's count replaces it on completion.
+ */
+export declare function estimateStreamedTokens(text: string): number;
+export declare class TokenRateMeter {
+    private readonly clock;
+    /** When each in-flight model request began, oldest first; the pairing fallback for starts and completions that carry no id. See {@link MAX_IN_FLIGHT}. */
+    private open;
+    /**
+     * In-flight requests that arrived with the executor's `invocationId`, keyed by it.
+     *
+     * Concurrent requests - branch workers, parallel graph copies, subagents - finish in an
+     * order no queue can predict: a later start can complete first. Keying by the id the
+     * executor stamps on both the start event and the usage delta pairs each completion with
+     * the window its own request opened.
+     */
+    private openById;
+    /** Output tokens summed over every request measured by its request window since the last reset. */
+    private tokens;
+    /** Request-window time summed over the same requests, in milliseconds. */
+    private milliseconds;
+    /** Output tokens summed over every request whose adapter measured a decode window. */
+    private decodedTokens;
+    /** Decode windows summed over the same requests, in milliseconds. */
+    private decodeMilliseconds;
+    /**
+     * Requests streaming right now, keyed by `invocationId` (`''` without one): the estimated
+     * tokens so far and the arrival times of the first and the latest fragment.
+     */
+    private live;
+    constructor(clock?: () => number);
+    /**
+     * Mark the start of a model request, so its eventual tokens are measured over this window.
+     *
+     * Every concurrent request gets its own entry: `src/graph-runner.ts` runs branch workers
+     * side by side, and a single slot would have a later start overwrite the first request's
+     * timestamp and the first completion clear it, leaving every later completion without a
+     * window of its own.
+     */
+    beginRequest(invocationId?: string): void;
+    /**
+     * Record provider-reported tokens for one finished model request.
+     *
+     * A completion carrying the executor's `invocationId` closes exactly the window that id's
+     * start opened, so concurrent requests finishing out of order each measure over their own
+     * generation. Without an id on either side, each completion is paired with the oldest
+     * request still in flight - the one that has been generating longest - which is the best a
+     * start with no identity allows; what matters is that every completion gets a real window
+     * rather than the synthetic fallback.
+     *
+     * Only a delta that carries tokens closes a window. The adapters also report pure transport
+     * bookkeeping through this callback - the HTTP adapter counts every attempt, retries
+     * included, as `requests: 1` with zero tokens - and pairing a completion with the *wrong*
+     * window is worse than the synthetic fallback: an attempt delta popping a window would leave
+     * the real completion to pair with an older request's start or with none at all. A window
+     * whose call never reports tokens (a request that failed or was aborted) is dropped by the
+     * {@link MAX_IN_FLIGHT} valve instead.
+     *
+     * The delta that closes a request arrives flagged `final`. A final delta without tokens is
+     * an unmeasured completion - a provider that omits usage - and it closes its request all
+     * the same, but the cumulative totals stay: they describe the requests that did report, and
+     * the average on screen remains their measurement until the next completion or a reset.
+     * An attempt delta keeps its early return: it reports zero tokens by design, and it must
+     * neither steal a window nor disturb the average the real completion will extend.
+     * @param tokens - output tokens the provider reported for that one request.
+     * @param invocationId - request identity from the executor, when the caller has one.
+     * @param final - true when this delta closes its request (the response accounting), as
+     * opposed to per-attempt transport bookkeeping.
+     * @param decodeMs - the adapter's measured decode window for the request, when it has one;
+     * it replaces the request window as the time the tokens are credited with.
+     */
+    report(tokens: number, invocationId?: string, final?: boolean, decodeMs?: number): void;
+    /**
+     * Take the window a completion closes: the one its `invocationId` opened, or - when the
+     * request carried no id, or the id never opened one - the oldest still in flight. Returns
+     * undefined when nothing is in flight and the caller falls back to the synthetic window.
+     */
+    private takeWindow;
+    /**
+     * Credit a streamed fragment of a request that has not finished yet.
+     *
+     * The estimate counts toward the reading over the stream's own decode window - first
+     * fragment to latest - so a pause in the stream (a tool call's arguments, which do not
+     * stream as text) holds the reading rather than decaying it.
+     */
+    stream(text: string, invocationId?: string): void;
+    /** Drop a request's live estimate: its attempt failed, was retried, or was aborted. */
+    endStream(invocationId?: string): void;
+    /**
+     * The tokens per second the footer shows: the average decoding speed over every request
+     * measured since the last reset, with any request still streaming blended in.
+     *
+     * Decode-measured requests and live streams are preferred; the request-window totals answer
+     * only when neither exists. Between completions the reading holds - no window drains and
+     * nothing decays. It moves as a stream grows or a completion lands, and resets to 0 with
+     * {@link reset}.
+     */
+    rate(): number;
+    /** Forget everything measured so far; the caller resets it when the graph switches nodes. */
+    reset(): void;
+}
+/** Where a metered request's stream goes: the terminal's speed readout. */
+export interface StreamMeterSink {
+    noteStreamedOutput(text: string, invocationId?: string): void;
+    noteStreamEnded(invocationId?: string): void;
+}
+/**
+ * Route a model request's streamed fragments into the speed readout, keeping the caller's hooks.
+ *
+ * Only a request carrying the executor's `invocationId` is metered: its usage delta reports under
+ * the same id and replaces the estimate. A call made outside the runtime - a graph health probe,
+ * whose usage only feeds the probe bookkeeping - has no completion that would ever retire its
+ * estimate, which would then blend into every later reading, so it passes through untouched.
+ * Each new attempt drops the estimate the previous one left.
+ */
+export declare function meterStreamedRequest(request: GenerateRequest, sink: StreamMeterSink): GenerateRequest;