laohuang 0.3.2 → 0.4.0

package/dist/project-instructions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Project instruction discovery and rendering, owned by the agent layer.
+ *
+ * Discovery walks from the project root to the startup cwd inclusively; each
+ * directory may contribute AGENTS.md and/or CLAUDE.md (AGENTS.md first, both
+ * only when their trimmed contents differ). Only regular UTF-8 text files
+ * inside the project root are read; symlinks resolving outside the root are
+ * skipped. The renderer owns the complete `<system-reminder>` wrapper and
+ * escapes any literal closing tag inside file content or displayed paths, so
+ * repository-controlled instruction text can never close the wrapper or be
+ * treated as higher-authority system text.
+ *
+ * Rendering honors a per-file byte cap and a total byte budget. Under budget
+ * pressure whole broad files are omitted before the most specific retained
+ * file is truncated; omissions and truncations leave a visible notice.
+ *
+ * `ProjectInstructionState` is private bookkeeping (never model-visible): it
+ * records the loaded scope and a content digest per visible instruction file
+ * so later phases can skip already-loaded scopes and diff for append-only
+ * replacement/removal reminders.
+ */
+/** Candidate instruction file names, in per-directory precedence order. */
+export declare const INSTRUCTION_FILENAMES: readonly string[];
+export declare const DEFAULT_PER_FILE_CAP_BYTES: number;
+export declare const DEFAULT_TOTAL_BUDGET_BYTES: number;
+export interface ProjectInstructionOptions {
+    perFileCapBytes?: number;
+    totalBudgetBytes?: number;
+}
+/** Bookkeeping record for one visible instruction file. */
+export interface InstructionFileRecord {
+    /** Root-relative directory scope ("" is the project root). */
+    readonly scope: string;
+    /** Root-relative display path with "/" separators. */
+    readonly displayPath: string;
+    /** SHA-256 hex digest of the loaded file bytes. */
+    readonly digest: string;
+}
+/**
+ * Private bookkeeping for loaded instruction scopes. Never model-visible and
+ * never alters committed history; later phases diff against these digests to
+ * emit append-only replacement/removal reminders.
+ */
+export declare class ProjectInstructionState {
+    private readonly records;
+    /** True when any instruction file from this directory scope was loaded. */
+    hasScope(scope: string): boolean;
+    /** Record a loaded instruction file (keyed by its display path). */
+    record(record: InstructionFileRecord): void;
+    /** The record for one display path, if that file was loaded. */
+    entry(displayPath: string): InstructionFileRecord | undefined;
+    get loadedPaths(): readonly string[];
+}
+/** One discovered instruction file, before budget rendering. */
+export interface DiscoveredInstructionFile {
+    readonly record: InstructionFileRecord;
+    readonly text: string;
+    /** True when the file exceeded the per-file cap and was cut. */
+    readonly truncated: boolean;
+}
+/** Result of baseline discovery: the rendered message plus bookkeeping. */
+export interface BaselineInstructions {
+    /** The complete wrapped reminder, or "" when no instruction file exists. */
+    readonly rendered: string;
+    readonly state: ProjectInstructionState;
+}
+/**
+ * The nearest ancestor of `startCwd` (inclusive) containing a `.git` entry;
+ * `fallbackRoot` when no ancestor has one.
+ */
+export declare function findProjectRoot(startCwd: string, fallbackRoot: string): string;
+/**
+ * Discover instruction files in `scopeDirs` (broad-to-specific order), read
+ * them under the per-file cap, and record them in `state` when given.
+ * Directories whose scope is already represented in `state` are skipped.
+ */
+export declare function discoverInstructions(root: string, scopeDirs: readonly string[], options?: ProjectInstructionOptions, state?: ProjectInstructionState): DiscoveredInstructionFile[];
+/**
+ * Render discovered files under the complete `<system-reminder>` wrapper,
+ * broad-to-specific, within `totalBudgetBytes`. Under pressure whole broad
+ * files are omitted before the most specific retained file is truncated;
+ * both cases leave a visible notice.
+ */
+export declare function renderInstructions(files: readonly DiscoveredInstructionFile[], totalBudgetBytes?: number): string;
+/**
+ * Render dynamically discovered files as an additional reminder, appended
+ * after paired tool results and before the next model request.
+ */
+export declare function renderAdditionalInstructions(files: readonly DiscoveredInstructionFile[], totalBudgetBytes?: number): string;
+/**
+ * Load the startup baseline: discover from `root` to `startupCwd`
+ * inclusively, render under the total budget, and return the bookkeeping
+ * state. No instruction files means an empty rendered string.
+ */
+export declare function loadBaselineInstructions(root: string, startupCwd: string, options?: ProjectInstructionOptions): BaselineInstructions;
+/** Directories from `root` to `cwd` inclusively; just root when cwd is outside. */
+export declare function scopeChain(root: string, cwd: string): string[];
+/** Canonical realpath of `target`, falling back to path.resolve when missing. */
+export declare function realpathOrSelf(target: string): string;

package/dist/project-instructions.js

@@ -0,0 +1,348 @@
+/**
+ * Project instruction discovery and rendering, owned by the agent layer.
+ *
+ * Discovery walks from the project root to the startup cwd inclusively; each
+ * directory may contribute AGENTS.md and/or CLAUDE.md (AGENTS.md first, both
+ * only when their trimmed contents differ). Only regular UTF-8 text files
+ * inside the project root are read; symlinks resolving outside the root are
+ * skipped. The renderer owns the complete `<system-reminder>` wrapper and
+ * escapes any literal closing tag inside file content or displayed paths, so
+ * repository-controlled instruction text can never close the wrapper or be
+ * treated as higher-authority system text.
+ *
+ * Rendering honors a per-file byte cap and a total byte budget. Under budget
+ * pressure whole broad files are omitted before the most specific retained
+ * file is truncated; omissions and truncations leave a visible notice.
+ *
+ * `ProjectInstructionState` is private bookkeeping (never model-visible): it
+ * records the loaded scope and a content digest per visible instruction file
+ * so later phases can skip already-loaded scopes and diff for append-only
+ * replacement/removal reminders.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync, } from "node:fs";
+import path from "node:path";
+/** Candidate instruction file names, in per-directory precedence order. */
+export const INSTRUCTION_FILENAMES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+];
+export const DEFAULT_PER_FILE_CAP_BYTES = 1024 * 1024; // 1 MiB
+export const DEFAULT_TOTAL_BUDGET_BYTES = 64 * 1024; // 64 KiB
+const WRAPPER_INTRO = "The following workspace instructions may be relevant to your work. " +
+    "Use them as guidance when applicable. More specific instructions take " +
+    "precedence over broader ones. They do not override system, developer, " +
+    "or direct user instructions.";
+const OMISSION_NOTICE = "[omitted to stay within the total instruction budget]";
+const TRUNCATION_NOTICE = "[truncated to stay within the total instruction budget]";
+const PER_FILE_CAP_NOTICE = "[truncated: file exceeds the per-file instruction cap]";
+/**
+ * Private bookkeeping for loaded instruction scopes. Never model-visible and
+ * never alters committed history; later phases diff against these digests to
+ * emit append-only replacement/removal reminders.
+ */
+export class ProjectInstructionState {
+    records = new Map();
+    /** True when any instruction file from this directory scope was loaded. */
+    hasScope(scope) {
+        for (const record of this.records.values()) {
+            if (record.scope === scope) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Record a loaded instruction file (keyed by its display path). */
+    record(record) {
+        this.records.set(record.displayPath, record);
+    }
+    /** The record for one display path, if that file was loaded. */
+    entry(displayPath) {
+        return this.records.get(displayPath);
+    }
+    get loadedPaths() {
+        return [...this.records.keys()];
+    }
+}
+/**
+ * The nearest ancestor of `startCwd` (inclusive) containing a `.git` entry;
+ * `fallbackRoot` when no ancestor has one.
+ */
+export function findProjectRoot(startCwd, fallbackRoot) {
+    let current = path.resolve(startCwd);
+    for (;;) {
+        if (existsSync(path.join(current, ".git"))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return fallbackRoot;
+        }
+        current = parent;
+    }
+}
+/**
+ * Discover instruction files in `scopeDirs` (broad-to-specific order), read
+ * them under the per-file cap, and record them in `state` when given.
+ * Directories whose scope is already represented in `state` are skipped.
+ */
+export function discoverInstructions(root, scopeDirs, options = {}, state) {
+    const resolved = resolveOptions(options);
+    const rootReal = realpathOrSelf(root);
+    const found = [];
+    for (const directory of scopeDirs) {
+        const scope = displayRelative(root, directory);
+        if (state?.hasScope(scope)) {
+            continue;
+        }
+        for (const name of INSTRUCTION_FILENAMES) {
+            const candidate = path.join(directory, name);
+            const file = readInstructionFile(rootReal, candidate, resolved);
+            if (file === null) {
+                continue;
+            }
+            // Same-directory dedupe: identical trimmed content keeps only the
+            // higher-precedence (earlier) candidate.
+            if (found.some((other) => other.text.trim() === file.text.trim())) {
+                continue;
+            }
+            const discovered = {
+                record: {
+                    scope,
+                    displayPath: displayRelative(root, candidate),
+                    digest: file.digest,
+                },
+                text: file.text,
+                truncated: file.truncated,
+            };
+            found.push(discovered);
+            state?.record(discovered.record);
+        }
+    }
+    return found;
+}
+/**
+ * Render discovered files under the complete `<system-reminder>` wrapper,
+ * broad-to-specific, within `totalBudgetBytes`. Under pressure whole broad
+ * files are omitted before the most specific retained file is truncated;
+ * both cases leave a visible notice.
+ */
+export function renderInstructions(files, totalBudgetBytes = DEFAULT_TOTAL_BUDGET_BYTES) {
+    return renderWrapped(files, totalBudgetBytes, "Instructions from:");
+}
+/**
+ * Render dynamically discovered files as an additional reminder, appended
+ * after paired tool results and before the next model request.
+ */
+export function renderAdditionalInstructions(files, totalBudgetBytes = DEFAULT_TOTAL_BUDGET_BYTES) {
+    return renderWrapped(files, totalBudgetBytes, "Additional instructions from:");
+}
+function renderWrapped(files, totalBudgetBytes, sectionHeader) {
+    if (files.length === 0) {
+        return "";
+    }
+    const sections = files.map((file) => ({
+        displayPath: escapeClosingReminder(file.record.displayPath),
+        body: escapeClosingReminder(file.text.trim()) +
+            (file.truncated ? `\n\n${PER_FILE_CAP_NOTICE}` : ""),
+        omitted: false,
+    }));
+    const render = () => {
+        const body = sections
+            .map((section) => `${sectionHeader} ${section.displayPath}\n\n` +
+            (section.omitted ? OMISSION_NOTICE : section.body))
+            .join("\n\n");
+        return `<system-reminder>\n${WRAPPER_INTRO}\n\n${body}\n</system-reminder>`;
+    };
+    let rendered = render();
+    while (byteLength(rendered) > totalBudgetBytes) {
+        const retained = sections.filter((section) => !section.omitted);
+        if (retained.length > 1) {
+            const broadest = retained[0];
+            if (broadest === undefined) {
+                break;
+            }
+            broadest.omitted = true;
+            rendered = render();
+            continue;
+        }
+        const last = retained[0];
+        if (last === undefined) {
+            break;
+        }
+        const overhead = byteLength(rendered) - byteLength(last.body);
+        const notice = `\n\n${TRUNCATION_NOTICE}`;
+        const allowed = Math.max(0, totalBudgetBytes - overhead - byteLength(notice));
+        last.body = truncateToBytes(last.body, allowed) + notice;
+        rendered = render();
+        break;
+    }
+    if (byteLength(rendered) > totalBudgetBytes) {
+        // Last-resort clamp for pathologically small budgets: keep the closing
+        // wrapper tag intact even if a notice must be cut.
+        const closing = "\n</system-reminder>";
+        rendered =
+            truncateToBytes(rendered, Math.max(0, totalBudgetBytes - byteLength(closing))) + closing;
+    }
+    return rendered;
+}
+/**
+ * Load the startup baseline: discover from `root` to `startupCwd`
+ * inclusively, render under the total budget, and return the bookkeeping
+ * state. No instruction files means an empty rendered string.
+ */
+export function loadBaselineInstructions(root, startupCwd, options = {}) {
+    const resolved = resolveOptions(options);
+    const state = new ProjectInstructionState();
+    const files = discoverInstructions(root, scopeChain(root, startupCwd), resolved, state);
+    return {
+        rendered: renderInstructions(files, resolved.totalBudgetBytes),
+        state,
+    };
+}
+// --- Internals ---------------------------------------------------------------
+function resolveOptions(options) {
+    return {
+        perFileCapBytes: options.perFileCapBytes ?? DEFAULT_PER_FILE_CAP_BYTES,
+        totalBudgetBytes: options.totalBudgetBytes ?? DEFAULT_TOTAL_BUDGET_BYTES,
+    };
+}
+/** Directories from `root` to `cwd` inclusively; just root when cwd is outside. */
+export function scopeChain(root, cwd) {
+    const relative = path.relative(root, cwd);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return [root];
+    }
+    const dirs = [root];
+    let current = root;
+    for (const part of relative.split(path.sep)) {
+        if (part === "") {
+            continue;
+        }
+        current = path.join(current, part);
+        dirs.push(current);
+    }
+    return dirs;
+}
+/**
+ * Read one candidate as a regular UTF-8 text file inside the root, capped at
+ * `options.perFileCapBytes`. Returns null for missing, non-regular,
+ * non-UTF-8, or out-of-root-symlink candidates.
+ */
+function readInstructionFile(rootReal, candidate, options) {
+    let stats;
+    try {
+        stats = lstatSync(candidate);
+    }
+    catch {
+        return null;
+    }
+    let resolved = candidate;
+    if (stats.isSymbolicLink()) {
+        try {
+            resolved = realpathSync(candidate);
+        }
+        catch {
+            return null;
+        }
+        if (!isInsideRoot(rootReal, resolved)) {
+            return null;
+        }
+        try {
+            if (!statSync(resolved).isFile()) {
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    else if (!stats.isFile()) {
+        return null;
+    }
+    const capped = readCapped(resolved, options.perFileCapBytes);
+    if (capped === null) {
+        return null;
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(capped.bytes);
+    }
+    catch {
+        return null;
+    }
+    return {
+        text,
+        truncated: capped.truncated,
+        digest: createHash("sha256").update(capped.bytes).digest("hex"),
+    };
+}
+function readCapped(filePath, cap) {
+    let handle;
+    try {
+        handle = openSync(filePath, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fstatSync(handle).size;
+        const length = Math.min(size, cap);
+        const buffer = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const count = readSync(handle, buffer, offset, length - offset, offset);
+            if (count <= 0) {
+                break;
+            }
+            offset += count;
+        }
+        return { bytes: buffer.subarray(0, offset), truncated: size > cap };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+function isInsideRoot(rootReal, target) {
+    const relative = path.relative(rootReal, target);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+/** Canonical realpath of `target`, falling back to path.resolve when missing. */
+export function realpathOrSelf(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+/** Root-relative path with "/" separators for display and scope keys. */
+function displayRelative(root, target) {
+    return path.relative(root, target).split(path.sep).join("/");
+}
+/**
+ * Neutralize any literal wrapper-closing tag inside repository-controlled
+ * text (file content or display paths) so it cannot close the reminder.
+ */
+function escapeClosingReminder(text) {
+    return text.split("</system-reminder>").join("<\\/system-reminder>");
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** Cut a string to at most `maxBytes` UTF-8 bytes without splitting a character. */
+function truncateToBytes(text, maxBytes) {
+    if (byteLength(text) <= maxBytes) {
+        return text;
+    }
+    const sliced = Buffer.from(text, "utf8")
+        .subarray(0, maxBytes)
+        .toString("utf8");
+    // A multi-byte character split at the cut point decodes to U+FFFD.
+    return sliced.replace(/�+$/, "");
+}
+//# sourceMappingURL=project-instructions.js.map

package/dist/project-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-instructions.js","sourceRoot":"","sources":["../src/project-instructions.ts"],"names":[],"mappings":"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"}

package/dist/providers.d.ts

@@ -0,0 +1,9 @@
+/** Built-in model provider presets. */
+export interface Provider {
+    readonly name: string;
+    readonly defaultModel: string | null;
+    readonly baseUrl: string | null;
+    readonly suggestedModels: readonly string[];
+}
+export declare function getProvider(name: string): Provider;
+export declare function providerNames(): string[];

package/dist/providers.js

@@ -0,0 +1,26 @@
+/** Built-in model provider presets. */
+const PROVIDERS = {
+    deepseek: {
+        name: "deepseek",
+        defaultModel: "deepseek-v4-flash",
+        baseUrl: "https://api.deepseek.com",
+        suggestedModels: ["deepseek-v4-flash", "deepseek-v4-pro"],
+    },
+    openai: {
+        name: "openai",
+        defaultModel: null,
+        baseUrl: null,
+        suggestedModels: [],
+    },
+};
+export function getProvider(name) {
+    const provider = PROVIDERS[name];
+    if (!provider) {
+        throw new Error(`Unknown provider: ${name}`);
+    }
+    return provider;
+}
+export function providerNames() {
+    return Object.keys(PROVIDERS).sort();
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,uCAAuC;AASvC,MAAM,SAAS,GAA6B;IAC1C,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,YAAY,EAAE,mBAAmB;QACjC,OAAO,EAAE,0BAA0B;QACnC,eAAe,EAAE,CAAC,mBAAmB,EAAE,iBAAiB,CAAC;KAC1D;IACD,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,IAAI;QACb,eAAe,EAAE,EAAE;KACpB;CACF,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;AACvC,CAAC"}

package/dist/routing.d.ts

@@ -0,0 +1,170 @@
+/** Deterministic routing, task registry, and runtime input queues. */
+import { CancelToken } from "./cancellation.ts";
+import { type AnyEventEnvelope } from "./events.ts";
+export declare const TaskState: {
+    readonly RunningModel: "running_model";
+    readonly RunningTools: "running_tools";
+    readonly Cancelling: "cancelling";
+    readonly Cancelled: "cancelled";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+};
+export type TaskState = (typeof TaskState)[keyof typeof TaskState];
+export interface TaskRecord {
+    readonly taskId: string;
+    readonly state: TaskState;
+    readonly cancelToken: CancelToken;
+    readonly result: string | null;
+    readonly error: string | null;
+}
+export interface RegisterTaskOptions {
+    state?: TaskState;
+    cancelToken?: CancelToken;
+    activate?: boolean;
+}
+export interface TransitionOptions {
+    result?: string;
+    error?: string;
+}
+/** Task records with at most one active task. */
+export declare class TaskRegistry {
+    private readonly tasks;
+    private activeTaskIdValue;
+    get activeTaskId(): string | null;
+    register(taskId: string, options?: RegisterTaskOptions): TaskRecord;
+    get(taskId: string): TaskRecord | null;
+    active(): TaskRecord | null;
+    transition(taskId: string, state: TaskState, options?: TransitionOptions): TaskRecord;
+    records(): TaskRecord[];
+}
+export type RouteStrategy = "execute" | "steer" | "follow_up" | "cancel" | "reject";
+export type RouteDestination = "new_task" | "current_task" | "pending" | "held" | "control" | "drop";
+export type RouteTiming = "immediate" | "safe_point" | "after_cancel";
+export interface RouteDecision {
+    readonly taskId: string | null;
+    readonly destination: RouteDestination;
+    readonly timing: RouteTiming;
+    readonly strategy: RouteStrategy;
+    readonly confidence: number;
+    readonly reason: string;
+    readonly layer: number;
+}
+export interface RoutedEvent {
+    readonly event: AnyEventEnvelope;
+    readonly decision: RouteDecision;
+}
+/** Provider-neutral conservative token estimate without a tokenizer. */
+export declare function estimateTokens(text: string): number;
+export interface DeadLetter {
+    readonly event: AnyEventEnvelope;
+    readonly reason: string;
+}
+/** Bounded inspection queue for events rejected by routing or capacity. */
+export declare class DeadLetterQueue {
+    readonly maxItems: number;
+    private items;
+    constructor(maxItems?: number);
+    put(event: AnyEventEnvelope, reason: string): void;
+    drain(): DeadLetter[];
+    snapshot(): DeadLetter[];
+    clear(): number;
+    get size(): number;
+}
+/** Verdict shapes accepted from a semantic classifier function. */
+export type SemanticClassifierVerdict = RouteDecision | RouteStrategy | (string & {}) | null | undefined;
+export type SemanticClassifierFn = (event: AnyEventEnvelope, active: TaskRecord | null) => SemanticClassifierVerdict | Promise<SemanticClassifierVerdict>;
+/** Object-shaped classifier, e.g. SmallModelSemanticClassifier. */
+export interface SemanticClassifierObject {
+    classify(event: AnyEventEnvelope, active: TaskRecord | null): RouteDecision | null | Promise<RouteDecision | null>;
+}
+export type SemanticClassifier = SemanticClassifierFn | SemanticClassifierObject;
+export type SafetyPolicy = (event: AnyEventEnvelope, decision: RouteDecision) => RouteDecision | boolean | null | undefined;
+export interface EventRouterOptions {
+    semanticClassifier?: SemanticClassifier | null;
+    safetyPolicy?: SafetyPolicy | null;
+}
+/**
+ * Four-layer router with deterministic safety as the final arbiter.
+ *
+ * Layers one through three short-circuit after obtaining a decision. Layer
+ * four always runs, so an injected semantic classifier can never override
+ * cancellation, invalid task ownership, or a custom safety policy.
+ */
+export declare class EventRouter {
+    readonly taskRegistry: TaskRegistry;
+    private readonly semanticClassifier;
+    private readonly safetyPolicy;
+    constructor(taskRegistry: TaskRegistry, options?: EventRouterOptions);
+    route(event: AnyEventEnvelope): Promise<RoutedEvent>;
+    private metadataMatch;
+    private deterministicRules;
+    private semanticClassification;
+    private static defaultDecision;
+    private safetyArbiter;
+}
+/** Raised when a bounded queue exceeds its item or token budget. */
+export declare class QueueOverflowError extends Error {
+    constructor(message: string);
+}
+export interface BoundedQueueOptions {
+    maxEstimatedTokens?: number;
+}
+export interface DrainCompatibleOptions {
+    taskId?: string | null;
+    strategy?: RouteStrategy | null;
+    timing?: RouteTiming | null;
+}
+/** FIFO queue with atomic compatible-batch snapshots. */
+export declare class PendingQueue {
+    readonly maxItems: number;
+    readonly maxEstimatedTokens: number;
+    private items;
+    private estimatedTokensValue;
+    constructor(maxItems?: number, options?: BoundedQueueOptions);
+    put(event: RoutedEvent): void;
+    /** Atomically remove all currently eligible events in source order. */
+    drainCompatible(options?: DrainCompatibleOptions): RoutedEvent[];
+    /** Atomically remove every strategy bucket belonging to a task. */
+    drainTask(taskId: string): RoutedEvent[];
+    get estimatedTokens(): number;
+    snapshot(): RoutedEvent[];
+    clear(): number;
+    get size(): number;
+}
+export interface DrainHeldOptions {
+    taskId?: string | null;
+}
+/** Inputs retained while the active task is cancelling. */
+export declare class HeldQueue {
+    readonly maxItems: number;
+    readonly maxEstimatedTokens: number;
+    private items;
+    private estimatedTokensValue;
+    constructor(maxItems?: number, options?: BoundedQueueOptions);
+    put(event: RoutedEvent): void;
+    drain(options?: DrainHeldOptions): RoutedEvent[];
+    get estimatedTokens(): number;
+    clear(): number;
+    get size(): number;
+}
+export interface ScheduleResult {
+    readonly immediate: readonly RoutedEvent[];
+    readonly queued: boolean;
+    readonly rejected: boolean;
+    readonly reason: string;
+}
+export interface SchedulerOptions {
+    pending?: PendingQueue;
+    held?: HeldQueue;
+    deadLetters?: DeadLetterQueue;
+}
+export declare class Scheduler {
+    readonly pending: PendingQueue;
+    readonly held: HeldQueue;
+    readonly deadLetters: DeadLetterQueue;
+    constructor(options?: SchedulerOptions);
+    schedule(event: RoutedEvent): ScheduleResult;
+    safePoint(taskId: string): RoutedEvent[];
+}
+/** Combine a pending snapshot into one model input without losing IDs. */
+export declare function combineInput(events: Iterable<RoutedEvent>): string;