/** * Persistent, bridge-independent ownership for Telegram action runners. * * AgenticRunner supports repeated run() calls, but its event subscription API * has no unsubscribe operation. This registry binds one permanent dispatcher * when a runner is created, then routes events only to the active lease. A * bridge can therefore reuse a runner without adding one listener per turn. */ export interface TelegramActionSessionTarget { /** Existing Telegram chat/thread session key. */ readonly chatSessionKey: string; /** Stable user or other principal key within that chat. */ readonly principalKey: string; } export interface TelegramActionSessionRunner { run(task: string, context?: string, actualUserGoal?: string): Promise; abort(): void; onEvent(handler: (event: TEvent) => void): void; } export interface TelegramActionSessionCreateContext { readonly key: string; readonly target: TelegramActionSessionTarget; readonly generation: number; /** Stable dispatcher suitable for AgenticRunnerOptions.onTypedEvent. */ readonly onTypedEvent: (event: TTypedEvent) => void; } export interface TelegramActionSessionResource { readonly runner: TRunner; /** Optional cleanup for resources not covered by runner.abort(). */ readonly dispose?: () => void; } export type TelegramActionSessionEvictionReason = "ttl" | "lru" | "incompatible" | "shutdown"; export interface TelegramActionSessionRegistryOptions> { readonly create: (context: TelegramActionSessionCreateContext) => TelegramActionSessionResource; readonly ttlMs?: number; readonly maxEntries?: number; readonly now?: () => number; readonly onEvict?: (snapshot: TelegramActionSessionSnapshot, reason: TelegramActionSessionEvictionReason) => void; } export interface TelegramActionSessionAcquireOptions { readonly target: TelegramActionSessionTarget; readonly ownerId: string; /** * Fingerprint of runner-static configuration: model, endpoint, surface, * tool policy, state root, session id, and stable prompt contract version. */ readonly compatibilityKey: string; readonly onEvent?: (event: TEvent, token: TelegramActionSessionLeaseToken) => void; readonly onTypedEvent?: (event: TTypedEvent, token: TelegramActionSessionLeaseToken) => void; } export interface TelegramActionSessionRunInput { readonly task: string; /** Current-turn context. Do not put changing conversation state in the compatibility key. */ readonly context?: string; readonly actualUserGoal?: string; /** Configure current-turn tools or working directory immediately before run(). */ readonly prepare?: (runner: TRunner) => void | Promise; } export interface TelegramActionSessionLeaseToken { readonly key: string; readonly generation: number; readonly leaseId: number; readonly ownerId: string; } export type TelegramActionSessionReleaseStatus = "released" | "running" | "stale"; export interface TelegramActionSessionLease { readonly token: TelegramActionSessionLeaseToken; readonly target: TelegramActionSessionTarget; run(input: TelegramActionSessionRunInput): Promise; abort(): boolean; release(): TelegramActionSessionReleaseStatus; } export type TelegramActionSessionAcquireFailureStatus = "busy" | "capacity" | "closed"; export type TelegramActionSessionAcquireResult = { readonly status: "acquired"; readonly lease: TelegramActionSessionLease; } | { readonly status: TelegramActionSessionAcquireFailureStatus; readonly reason: string; readonly current?: TelegramActionSessionSnapshot; }; export interface TelegramActionSessionSnapshot { readonly key: string; readonly target: TelegramActionSessionTarget; readonly generation: number; readonly compatibilityKey: string; readonly createdAtMs: number; readonly lastUsedAtMs: number; readonly busy: boolean; readonly ownerId?: string; readonly leaseId?: number; readonly runStarted: boolean; } export type TelegramActionSessionLeaseErrorCode = "stale_lease" | "already_started"; export declare class TelegramActionSessionLeaseError extends Error { readonly code: TelegramActionSessionLeaseErrorCode; constructor(code: TelegramActionSessionLeaseErrorCode, message: string); } export declare function createTelegramActionSessionTarget(target: TelegramActionSessionTarget): TelegramActionSessionTarget; export declare function telegramActionSessionKey(targetInput: TelegramActionSessionTarget): string; /** * A bounded registry for reusable AgenticRunner-compatible action sessions. * It owns only in-memory runner resources. AgenticRunner stateDir/sessionId * remain the durable continuity authority. */ export declare class TelegramActionSessionRegistry = TelegramActionSessionRunner> { private readonly entries; private readonly create; private readonly ttlMs; private readonly maxEntries; private readonly now; private readonly onEvict?; private generationSequence; private leaseSequence; private closed; constructor(options: TelegramActionSessionRegistryOptions); get size(): number; acquire(options: TelegramActionSessionAcquireOptions): TelegramActionSessionAcquireResult; pruneExpired(): number; snapshot(): readonly TelegramActionSessionSnapshot[]; /** Abort active work, dispose every cached resource, and reject new leases. */ shutdown(): void; private createEntry; private runLease; private abortLease; private releaseLease; private finishLease; private ownedEntry; private dispatchEvent; private dispatchTypedEvent; private pruneExpiredAt; private evictLeastRecentlyUsedIdle; private evictEntry; private snapshotEntry; private readNow; }