@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/notifications/lifecycle-commands.d.ts

@@ -0,0 +1,69 @@
+import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
+export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+/** A parsed, validated lifecycle command (transport identity added by caller). */
+export type ParsedLifecycleCommand = {
+    kind: "create";
+    target: SessionCreateTarget;
+    modelPreset?: string;
+} | {
+    kind: "close";
+    target: SessionCloseTarget;
+} | {
+    kind: "resume";
+    target: SessionResumeTarget;
+} | {
+    kind: "recent";
+    which: "create" | "resume" | "all";
+} | {
+    kind: "usage";
+    message: string;
+} | {
+    kind: "reject";
+    reason: "invalid_target" | "prompt_unsupported";
+    message: string;
+} | {
+    kind: "none";
+};
+/** True when the text begins with any /session_* token, regardless of addressability. */
+export declare function isLifecycleCommandLikeText(text: string | undefined): boolean;
+/** True when the text begins an addressable /session_* command (cheap pre-gate). */
+export declare function isLifecycleCommandText(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): boolean;
+/**
+ * Parse a paired-chat message into a lifecycle command. Returns `none` for
+ * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
+ * a validated `create`/`close`/`resume`/`recent` intent.
+ *
+ * The caller MUST have already enforced paired-chat authorization; this function
+ * performs grammar + target validation only.
+ */
+export declare function parseLifecycleCommand(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): ParsedLifecycleCommand;
+/** The canonical usage text (exported for the daemon's help replies). */
+export declare function lifecycleUsage(): string;
+/**
+ * Shared target validator reused at the policy/effect boundary (after paired-chat
+ * auth, before any side effect). Returns null when valid, or an `invalid_target`
+ * reason. The orchestrator remains authoritative; this is a defensive pre-check
+ * the parser and any other entry point share.
+ */
+export declare function validateLifecycleTarget(verb: LifecycleCommandVerb, target: SessionCreateTarget | SessionCloseTarget | SessionResumeTarget): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_target";
+    message: string;
+};
+export declare function normalizeLifecyclePath(value: string): string | undefined;
+/**
+ * Map a lifecycle response/error to a user-facing Telegram message (G010).
+ *
+ * Only derives text from sessionId, mode, reason, a safe message, and candidate
+ * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
+ * actionable copy; an "in progress" pending response is surfaced distinctly.
+ */
+export declare function formatLifecycleOutcome(r: SessionLifecycleResponse): string;

package/dist/types/notifications/lifecycle-control-runtime.d.ts

@@ -0,0 +1,107 @@
+import { type OwnerIsolationProbe } from "../skc-runtime/tmux-owner-isolation";
+import { type SkcTmuxSessionStatus } from "../skc-runtime/tmux-sessions";
+import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
+import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
+/** Minimal view of the native control server this runtime depends on. */
+export interface ControlServerLike {
+    onLifecycleRequest(cb: (err: Error | null, req: {
+        kind: string;
+        requestId: string;
+        payloadJson: string;
+    }) => void): void;
+    respond(responseJson: string): void;
+}
+/**
+ * A startable control server (the native NotificationControlServer, or a fake in
+ * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
+ * daemon owns.
+ */
+export interface LifecycleControlServer extends ControlServerLike {
+    start(): Promise<unknown>;
+    stop(): void;
+}
+/** Factory the daemon uses to construct a control server bound to its ownership. */
+export type LifecycleControlServerFactory = (input: {
+    token: string;
+    ownerId: string;
+    agentDir: string;
+}) => LifecycleControlServer;
+export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
+/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
+export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
+/** Simple per-chat sliding-window create rate limiter. */
+export declare function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean;
+/** Build the `skc` argv for a create target (existing path / worktree / dir).
+ *
+ *  The launched session id is carried via `SKC_SESSION_ID` in the child env (see
+ *  {@link daemonSpawnCreate}); the root `skc` launcher has no `--session-id`
+ *  flag, so it must never appear in argv. Only flags the launch parser actually
+ *  supports are emitted (`--worktree <branch>` for worktree targets,
+ *  `--mpreset <profile>` for model presets). */
+export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}): {
+    cwd: string;
+    args: string[];
+};
+/** Real daemon-safe tmux launcher: canonical owner-isolation plan + SKC tags. */
+export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv, opts?: {
+    ownerIsolationProbe?: OwnerIsolationProbe;
+}): (frame: SessionCreateFrame, ids: {
+    lifecycleRequestId: string;
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}) => Promise<CreateEffectResult>;
+/** Real force-close effect (SKC-managed only, id-matched). */
+export declare function daemonCloseSession(env?: NodeJS.ProcessEnv, deps?: {
+    forceClose?: (name: string, env: NodeJS.ProcessEnv, expectedSessionId?: string, sessionStateFile?: string) => Promise<void>;
+    findSession?: (name: string, env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus | undefined;
+}): (target: {
+    sessionId: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+}) => Promise<{
+    processGone: boolean;
+}>;
+/** Real resume effect: reattach if a live SKC session matches; else resolve the
+ *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
+ *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
+export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
+    sessionsRoot?: string;
+    listSessions?: (env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus[];
+    ownerIsolationProbe?: OwnerIsolationProbe;
+}): (target: {
+    sessionIdOrPrefix: string;
+    path?: string;
+}) => Promise<ResumeEffectResult | {
+    ambiguous: ResumeCandidate[];
+} | {
+    notFound: true;
+}>;
+/** Translate an orchestrator outcome into a wire response frame. */
+export declare function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse;
+/**
+ * Wire a control server's lifecycle requests through the orchestrator.
+ *
+ * Handlers run on a single serial queue (a promise chain): the daemon owns the
+ * one control endpoint, so serializing here makes each request's ledger
+ * read -> classify -> write atomic with respect to every other request. Two
+ * identical updates that arrive nearly simultaneously can no longer both
+ * classify as `new` and both spawn — the second sees the first's persisted
+ * `in_progress`/`success` entry and re-acks instead.
+ */
+export declare function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void;
+/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
+export declare function buildOrchestratorDeps(input: {
+    pairedChatId: string;
+    agentNotificationsDir: string;
+    /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
+    sessionsRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps;
+/**
+ * Default production factory: a real native NotificationControlServer bound to
+ * the daemon's control token, owner id, and agent dir.
+ */
+export declare const createNativeControlServer: LifecycleControlServerFactory;

package/dist/types/notifications/lifecycle-orchestrator.d.ts

@@ -0,0 +1,144 @@
+import type { LifecycleErrorReason, ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest } from "./index";
+/** Durable idempotency state for a single lifecycle request. */
+export type LedgerState = "in_progress" | "success" | "failure" | "terminal_uncertain";
+/** One persisted idempotency entry, keyed by `chatId:updateId`. */
+export interface LedgerEntry {
+    requestHash: string;
+    state: LedgerState;
+    requestId: string;
+    verb: SessionLifecycleRequest["type"];
+    intendedSessionId?: string;
+    startupPromptRef?: string;
+    createdAt: number;
+    updatedAt: number;
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+    endpointUrl?: string;
+    /** Close effect outcome: whether the tmux process is confirmed gone. */
+    processGone?: boolean;
+    reason?: LifecycleErrorReason;
+}
+/** The full on-disk ledger document. */
+export interface LedgerDoc {
+    version: 1;
+    entries: Record<string, LedgerEntry>;
+}
+/** Persistence boundary: atomic + fsynced read/write of the ledger document. */
+export interface LedgerStore {
+    read(): Promise<LedgerDoc>;
+    /** Write atomically (temp + fsync + rename) under a per-ledger lock. */
+    write(doc: LedgerDoc): Promise<void>;
+}
+/** One audit line. Tokens and raw prompts are NEVER included. */
+export interface AuditEvent {
+    ts: string;
+    event: "accepted" | "rejected" | "duplicate_reack" | "rate_limited" | "spawn_started" | "recovered_in_progress" | "success" | "failure" | "terminal_uncertain";
+    chatId: string;
+    updateId: number;
+    requestId: string;
+    requestHash: string;
+    verb: SessionLifecycleRequest["type"];
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    reason?: LifecycleErrorReason;
+    /** Prompt byte length only (never the prompt text). */
+    promptBytes?: number;
+    /** Prompt content hash only (never the prompt text). */
+    promptHash?: string;
+}
+export interface CreateEffectResult {
+    sessionId: string;
+    tmuxSession: string;
+    sessionStateFile?: string;
+    endpointUrl: string;
+    topicThreadId: string;
+}
+export interface ResumeEffectResult extends CreateEffectResult {
+    mode: "reattached" | "cold_restarted";
+}
+/** Injected effects + policy. Pure orchestration calls into these. */
+export interface OrchestratorDeps {
+    /** The single paired chat id. Anything else is rejected before parsing. */
+    pairedChatId: string;
+    now: () => number;
+    store: LedgerStore;
+    audit: (event: AuditEvent) => Promise<void> | void;
+    /** Per-chat create rate limiter: returns true when allowed. */
+    allowCreate: (chatId: string, nowMs: number) => boolean;
+    /** Persist the once-consumed 0600 startup-prompt file; returns its ref. */
+    writeStartupPrompt: (requestId: string, prompt: string | undefined) => Promise<string | undefined>;
+    /** Spawn a session for a create/cold-restart. */
+    spawnCreate: (frame: SessionCreateFrame, ids: {
+        lifecycleRequestId: string;
+        intendedSessionId: string;
+        startupPromptRef?: string;
+    }) => Promise<CreateEffectResult>;
+    closeSession: (target: {
+        sessionId: string;
+        tmuxSession?: string;
+        sessionStateFile?: string;
+    }) => Promise<{
+        processGone: boolean;
+    }>;
+    resumeSession: (target: {
+        sessionIdOrPrefix: string;
+        path?: string;
+    }) => Promise<ResumeEffectResult | {
+        ambiguous: ResumeCandidate[];
+    } | {
+        notFound: true;
+    }>;
+    newLifecycleRequestId: () => string;
+    newSessionId: () => string;
+}
+/** A redaction-safe summary of a request target (never includes the token). */
+export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
+/**
+ * Stable request hash over the meaningful (non-token) request content. Used to
+ * detect a duplicate update id reused with a DIFFERENT body (conflict).
+ */
+export declare function requestHash(frame: SessionLifecycleRequest): string;
+export declare function ledgerKey(chatId: string, updateId: number): string;
+/** How a freshly-arrived request relates to the durable ledger. */
+export type DuplicateClass = {
+    kind: "new";
+} | {
+    kind: "reack_success";
+    entry: LedgerEntry;
+} | {
+    kind: "reack_failure";
+    entry: LedgerEntry;
+} | {
+    kind: "in_progress";
+    entry: LedgerEntry;
+} | {
+    kind: "terminal_uncertain";
+    entry: LedgerEntry;
+} | {
+    kind: "conflict";
+    entry: LedgerEntry;
+};
+/** Classify a request against an existing ledger entry (pure). */
+export declare function classifyDuplicate(existing: LedgerEntry | undefined, hash: string): DuplicateClass;
+/** The structured outcome the daemon translates into a wire response frame. */
+export type LifecycleOutcome = {
+    status: "ok";
+    entry: LedgerEntry;
+    mode?: "reattached" | "cold_restarted";
+} | {
+    status: "error";
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+} | {
+    status: "pending";
+    entry: LedgerEntry;
+};
+/**
+ * Handle one authenticated lifecycle request. Enforces paired-chat gating,
+ * idempotency, and rate limiting BEFORE any side effect, then dispatches.
+ */
+export declare function handleLifecycleRequest(frame: SessionLifecycleRequest, deps: OrchestratorDeps): Promise<LifecycleOutcome>;

package/dist/types/notifications/managed-daemon.d.ts

@@ -0,0 +1,48 @@
+import type { Settings } from "../config/settings";
+import { RateLimitPool } from "./rate-limit-pool";
+import { type ThreadedSend } from "./threaded-render";
+export interface ManagedNotificationDaemonFs {
+    readdir(path: string): Promise<string[]>;
+}
+export interface ManagedSessionSocket {
+    sessionId: string;
+    token: string;
+    ws: WebSocket;
+    pending: Map<string, {
+        sessionId: string;
+        actionId: string;
+    }>;
+    capable: boolean;
+    lastPongAt: number;
+    awaitingNonce: string | undefined;
+    pingTimer: ReturnType<typeof setInterval> | undefined;
+}
+export interface ManagedNotificationDaemonOptions {
+    settings: Settings;
+    fs: ManagedNotificationDaemonFs;
+    WebSocketImpl?: typeof WebSocket;
+    now?: () => number;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+    rateLimitPool?: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+}
+export declare abstract class ManagedNotificationDaemon {
+    protected readonly opts: ManagedNotificationDaemonOptions;
+    readonly sessions: Map<string, ManagedSessionSocket>;
+    readonly pool: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+    protected constructor(opts: ManagedNotificationDaemonOptions);
+    scanRoots(): Promise<void>;
+    connectSession(sessionId: string, url: string, token: string): ManagedSessionSocket;
+    protected handleSessionMessage(session: ManagedSessionSocket, msg: Record<string, unknown>): Promise<boolean>;
+    protected renderFrame(frame: Record<string, unknown>): ThreadedSend | undefined;
+    protected dropSession(session: ManagedSessionSocket): void;
+    protected abstract readRoots(): Promise<string[]>;
+    private sendHello;
+    private startLiveness;
+}

package/dist/types/notifications/notification-service.d.ts

@@ -0,0 +1,144 @@
+import type { Settings } from "../config/settings";
+/**
+ * Strip secrets from a human-facing diagnostic string. Redacts the configured
+ * bot token (exact match) and any token-shaped substring so health/test details
+ * can never leak a credential regardless of where the string originated.
+ */
+export declare function sanitizeDiagnostic(text: string, token?: string): string;
+/** Minimal filesystem surface the service needs; injectable for tests. */
+export interface NotificationServiceFs {
+    readdir(dir: string): Promise<string[]>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    unlink(file: string): Promise<void>;
+    /**
+     * Atomically create `file` with O_EXCL semantics: resolves `true` when this
+     * call created it, `false` when it already existed. Used to hold the daemon
+     * steal-mutex ({@link DaemonPaths.steal}) during owner-bound lock removal so
+     * recovery and a concurrent daemon takeover are mutually exclusive.
+     */
+    createExclusive(file: string): Promise<boolean>;
+}
+/** Injectable dependencies shared across service operations. */
+export interface NotificationServiceDeps {
+    fs?: NotificationServiceFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    fetchImpl?: typeof fetch;
+    apiBase?: string;
+}
+export interface AdapterConfigView {
+    botTokenMasked: string;
+    channel: string | undefined;
+    configured: boolean;
+}
+export interface NotificationStatusReport {
+    enabled: boolean;
+    redact: boolean;
+    verbosity: "lean" | "verbose";
+    globallyConfigured: boolean;
+    telegram: AdapterConfigView & {
+        tokenFingerprint: string | undefined;
+    };
+    discord: AdapterConfigView;
+    slack: AdapterConfigView;
+}
+/** Build a secret-safe structured status snapshot from settings. */
+export declare function buildNotificationStatusReport(settings: Settings): NotificationStatusReport;
+/** Render a status report as human-readable lines (no secrets). */
+export declare function formatNotificationStatusReport(report: NotificationStatusReport): string;
+export type HealthLevel = "ok" | "warn" | "error";
+export interface HealthCheck {
+    name: string;
+    level: HealthLevel;
+    detail: string;
+}
+export interface DaemonHealth {
+    present: boolean;
+    ownerId: string | undefined;
+    pid: number | undefined;
+    alive: boolean;
+    heartbeatFresh: boolean;
+    identityMatches: boolean;
+    stopped: boolean;
+}
+export interface EndpointHealth {
+    total: number;
+    live: number;
+    dead: number;
+    unknown: number;
+    unreadable: number;
+}
+export interface NotificationHealthReport {
+    overall: HealthLevel;
+    configured: boolean;
+    checks: HealthCheck[];
+    daemon: DaemonHealth;
+    endpoints: EndpointHealth;
+    reachability: {
+        probed: boolean;
+        ok: boolean;
+        detail: string;
+    };
+}
+export interface HealthOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+    /** When true and Telegram is configured, probe the Bot API (getMe) for reachability. */
+    probe?: boolean;
+}
+/** Structural (offline-by-default) health of the notification subsystem. */
+export declare function checkNotificationHealth(opts: HealthOptions): Promise<NotificationHealthReport>;
+/** Render a health report as human-readable lines (no secrets). */
+export declare function formatNotificationHealthReport(report: NotificationHealthReport): string;
+export interface NotificationTestResult {
+    ok: boolean;
+    adapter: "telegram";
+    chatId: string | undefined;
+    detail: string;
+}
+export interface TestOptions {
+    settings: Settings;
+    deps?: NotificationServiceDeps;
+    text?: string;
+}
+/** Send a one-off test notification through the configured Telegram adapter. */
+export declare function sendNotificationTest(opts: TestOptions): Promise<NotificationTestResult>;
+/** Render a test result as a single human-readable line (no secrets). */
+export declare function formatNotificationTestResult(result: NotificationTestResult): string;
+export interface RecoveredEndpoint {
+    sessionId: string;
+    pid: number | undefined;
+    reason: "stale-flag" | "dead-pid";
+}
+export type DaemonRecoveryAction = "none" | "cleared-dead-owner-lock" | "left-active" | "left-contended" | "owner-superseded" | "orphan-lock-left";
+export interface NotificationRecoveryReport {
+    endpointsScanned: number;
+    endpointsRemoved: RecoveredEndpoint[];
+    endpointsKept: number;
+    endpointsUnreadable: number;
+    daemon: {
+        action: DaemonRecoveryAction;
+        detail: string;
+        ownerId: string | undefined;
+        pid: number | undefined;
+    };
+}
+export interface RecoveryOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+}
+/**
+ * Ownership-protected cleanup. Removes only DEAD-owner artifacts:
+ * per-session endpoint files with positive proof of death (a stale tombstone or
+ * a dead recorded pid), and a daemon lock whose recorded owner is confirmed
+ * dead. A PID-less endpoint is treated as unknown (not dead) and kept. The
+ * daemon lock is removed through {@link removeDeadOwnerLock}, an owner-bound
+ * primitive that re-checks ownership under the daemon steal-mutex so it can
+ * never race a concurrent takeover. Never removes a live owner's lock, never
+ * deletes unreadable files, and never kills a process.
+ */
+export declare function recoverNotifications(opts: RecoveryOptions): Promise<NotificationRecoveryReport>;
+/** Render a recovery report as human-readable lines (no secrets). */
+export declare function formatNotificationRecoveryReport(report: NotificationRecoveryReport): string;

package/dist/types/notifications/operator-runtime.d.ts

@@ -0,0 +1,52 @@
+export interface NotificationOperatorTimerDeps {
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+}
+export interface NotificationOperatorRuntimeState {
+    running: boolean;
+    stopRequested: boolean;
+    activeAbort: boolean;
+}
+export interface OperatorBackoffOptions {
+    initialMs: number;
+    maxMs: number;
+    factor?: number;
+}
+export declare class OperatorBackoffPolicy {
+    #private;
+    constructor(opts: OperatorBackoffOptions);
+    next(): number;
+    reset(): void;
+    get currentMs(): number;
+}
+export interface OperatorRoute<TContext> {
+    name: string;
+    matches(event: Record<string, unknown>): boolean;
+    handle(context: TContext, event: Record<string, unknown>): Promise<void> | void;
+}
+export declare class OperatorEventRouter<TContext> {
+    readonly routes: OperatorRoute<TContext>[];
+    add(input: OperatorRoute<TContext>): this;
+    dispatch(context: TContext, event: Record<string, unknown>): Promise<boolean>;
+}
+export declare class NotificationOperatorRuntime {
+    #private;
+    constructor(deps?: NotificationOperatorTimerDeps);
+    get state(): NotificationOperatorRuntimeState;
+    start(): void;
+    stop(): void;
+    requestStop(): void;
+    get running(): boolean;
+    get stopRequested(): boolean;
+    createAbortController(): AbortController;
+    clearAbortController(controller: AbortController): void;
+    startInterval(name: string, intervalMs: number, tick: () => void): void;
+    stopInterval(name: string): void;
+    stopAllIntervals(): void;
+    runExclusive(name: string, fn: () => Promise<void>): Promise<void>;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    now(): number;
+}

package/dist/types/notifications/rate-limit-pool.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Host-wide shared Telegram rate-limit pool for the threaded session surface.
+ *
+ * Multiple SKC sessions on one host share a single bot token and paired chat.
+ * Telegram enforces per-bot/per-chat limits (~1 message/sec, bursts up to ~20),
+ * so the singleton notifications daemon owns ONE pool that all per-session
+ * threads draw from. The pool provides:
+ *
+ * - a token bucket (burst capacity + steady refill) modelling the chat limit;
+ * - priority lanes (`ask` > `finalized` > `live` > `idle`) so urgent frames
+ *   win scarce tokens;
+ * - per-session round-robin fairness within a lane so one session's live-edit
+ *   stream cannot starve other sessions;
+ * - coalescing of live edits that share a `coalesceKey` (the latest rendered
+ *   text replaces the queued one) so throttled edit storms collapse.
+ *
+ * The core is a pull-based scheduler with an injectable clock so fairness,
+ * starvation, and burst behaviour are deterministically unit-testable without
+ * real time or a live Bot API.
+ */
+/** Delivery lanes in descending priority. */
+export type RateLimitLane = "ask" | "finalized" | "live" | "idle";
+/** Lanes ordered from highest to lowest priority. */
+export declare const LANE_PRIORITY: readonly RateLimitLane[];
+/** A unit of work competing for a send slot. */
+export interface RateLimitItem<T = unknown> {
+    /** Owning session id (used for per-session fairness). */
+    sessionId: string;
+    /** Priority lane. */
+    lane: RateLimitLane;
+    /**
+     * Optional coalesce key. Submitting another unidentifiable item with the
+     * same `(sessionId, lane, coalesceKey)` replaces the queued payload with
+     * the newer one instead of enqueuing a duplicate (used for live edits).
+     */
+    coalesceKey?: string;
+    /** Optional stable identifier for exact queued-item removal. Identified items never coalesce. */
+    itemId?: string;
+    /** Absolute Unix timestamp in ms. The item expires when `now >= deadlineAt`. */
+    deadlineAt?: number;
+    /** Opaque payload the caller maps to an actual Telegram send. */
+    payload: T;
+}
+/** Options for {@link RateLimitPool}. */
+export interface RateLimitPoolOptions {
+    /** Burst capacity (max tokens). Default 20 (Telegram per-chat burst). */
+    capacity?: number;
+    /** Steady refill rate in tokens per second. Default 1 (~1 msg/sec/chat). */
+    refillPerSec?: number;
+    /** Injectable clock in ms. Default `Date.now`. */
+    now?: () => number;
+}
+/** The deterministic result of draining queued work at a point in time. */
+export interface RateLimitDrainResult<T = unknown> {
+    /** Items granted a token and ready to send. */
+    granted: RateLimitItem<T>[];
+    /** Items removed because their absolute deadline has elapsed. */
+    expired: RateLimitItem<T>[];
+}
+/**
+ * A deterministic, pull-based shared rate-limit scheduler.
+ *
+ * Callers {@link submit} work and periodically {@link drain} (e.g. on a timer
+ * or after each submit); `drain` returns the items granted a send slot, in the
+ * order they should be sent.
+ */
+export declare class RateLimitPool<T = unknown> {
+    private readonly capacity;
+    private readonly refillPerSec;
+    private readonly now;
+    /** Per-lane FIFO queues; each lane holds items across sessions. */
+    private readonly lanes;
+    /** Rotating session cursor per lane for round-robin fairness. */
+    private readonly laneCursor;
+    private tokens;
+    private lastRefill;
+    private seqCounter;
+    constructor(options?: RateLimitPoolOptions);
+    /** Number of items currently queued across all lanes. */
+    get pending(): number;
+    /** Current available token count (after refill at `now`). */
+    availableTokens(nowMs?: number): number;
+    /**
+     * Submit an item. Unidentified items with a `coalesceKey` matching a queued
+     * item in the same `(sessionId, lane)` replace its payload (latest wins)
+     * while preserving FIFO position; identified items are always appended.
+     */
+    submit(item: RateLimitItem<T>): void;
+    /**
+     * Grant as many queued items as tokens allow at `nowMs`. This compatibility
+     * wrapper discards items that expired during the drain.
+     */
+    drain(nowMs?: number): RateLimitItem<T>[];
+    /**
+     * Deterministically expire elapsed-deadline items, then grant as many live
+     * items as tokens allow. Expired items never consume tokens or receive a
+     * grant; both result lists preserve their deterministic queue ordering.
+     */
+    drainWithExpired(nowMs?: number): RateLimitDrainResult<T>;
+    /** Remove queued items matching `predicate` without consuming tokens. Returns removed items in lane/FIFO order. */
+    removeWhere(predicate: (item: RateLimitItem<T>) => boolean): RateLimitItem<T>[];
+    /** Remove exactly one queued item by its stable id without consuming a token. */
+    removeById(itemId: string): RateLimitItem<T> | undefined;
+    private refill;
+    /** Pop the next item by lane priority + per-session round-robin fairness. */
+    private takeNext;
+    /**
+     * Choose the index to serve from a lane queue using round-robin over the
+     * distinct session ids present, starting just after the last-served
+     * session. Falls back to FIFO (index 0) when only one session is queued.
+     */
+    private pickFairIndex;
+}