@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -0,0 +1,856 @@
+import * as fs from "node:fs";
+import type { Settings } from "../../config/settings";
+import type { DaemonRuntimeInfo } from "../../daemon/control-types";
+import { HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { type DaemonTransitionLock, type NotificationEndpointFile, type NotificationEndpointFileIdentity, type NotificationExactUnlinkResult } from "./notification-service";
+import { type DaemonProcessReference } from "./telegram-daemon-control";
+export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION } from "./telegram-daemon-contract";
+import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
+import type { OrchestratorDeps } from "./lifecycle-orchestrator";
+import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
+import { type AliasTable, type CallbackRoute } from "./telegram-reference";
+export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
+/** Detailed result for orchestration that must distinguish a #2028 handoff from a fresh spawn. */
+export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attached" | "disabled" | "blocked_identity";
+export type TelegramDaemonOwnershipPhase = "provisional" | "ready" | "retired";
+export interface DaemonState {
+    pid: number;
+    /** OS process-start provenance; mandatory for PID-authorized ownership actions. */
+    incarnation: string;
+    ownerId: string;
+    /** Unique, durable identity for one ownership acquisition. */
+    acquisitionId?: string;
+    /** A provisional owner is physical-live but MUST NOT be attached as ready. */
+    ownershipPhase?: TelegramDaemonOwnershipPhase;
+    tokenFingerprint: string;
+    chatId: string;
+    startedAt: number;
+    heartbeatAt: number;
+    roots: string[];
+    /**
+     * Present only for the Windows source-launch handoff. `pid` starts as this
+     * short-lived launcher PID and may be rebound exactly once to the daemon PID.
+     */
+    launcherPid?: number;
+    version: 1;
+    /**
+     * Operational daemon generation of the process that owns the lock, distinct
+     * from both the persisted state-schema {@link DaemonState.version} and the
+     * notification wire protocol version. Absent on pre-generation state.
+     */
+    generation?: number;
+    stoppedAt?: number;
+}
+export interface TelegramDaemonFs {
+    mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<void>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, opts?: fs.WriteFileOptions): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    open(path: string, flags: string, mode?: number): Promise<{
+        close(): Promise<void>;
+    }>;
+    readdir(path: string): Promise<string[]>;
+    chmod(path: string, mode: number): Promise<void>;
+    stat?(path: string): Promise<{
+        mtimeMs: number;
+    }>;
+    readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(path: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
+}
+export interface SpawnResult {
+    pid?: number;
+    unref?: () => void;
+}
+export interface TelegramDaemonDeps {
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    pidAlive?: (pid: number) => boolean;
+    /** Opens an identity-stable process authority for destructive lifecycle operations. */
+    processReference?: (pid: number) => DaemonProcessReference | undefined;
+    /** Returns immutable process-start provenance, or undefined when unsupported. */
+    pidIncarnation?: (pid: number) => string | undefined;
+    spawn?: (command: string, args: string[], opts: {
+        detached: boolean;
+        stdio: "ignore";
+        logPath?: string;
+    }) => SpawnResult;
+    execPath?: string;
+    /** Injectable platform seam for source-linked Windows daemon spawning. */
+    platform?: NodeJS.Platform;
+    randomId?: () => string;
+    /**
+     * Signal delivery + poll timing for the stale-generation reload handoff in
+     * {@link ensureTelegramDaemonRunning}. Defaults use real signals/timers; tests
+     * inject them to drive the handoff deterministically.
+     */
+    sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    /** Bounded startup-readiness timeout; injectable for deterministic handoff tests. */
+    readinessTimeoutMs?: number;
+}
+export declare const HEARTBEAT_INTERVAL_MS = 5000;
+export { HEARTBEAT_TTL_MS };
+export declare const DAEMON_VERSION = 1;
+/** Capability token advertised when the server supports app-level ping/pong. */
+export declare const CLIENT_PING_PONG_CAPABILITY = "client_ping_pong";
+/** Capability required for typed controls and semantic Selected acknowledgement frames. */
+export declare const ASK_SELECTED_ACK_CAPABILITY = "ask_selected_ack_v1";
+export declare const ASK_CONTROLS_CAPABILITY = "ask_controls_v1";
+/** Capability required for tool lifecycle and reasoning-summary frames. */
+export declare const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v1";
+export declare const BTW_QUESTION_MAX_UNICODE_SCALARS = 4096;
+export declare const BTW_QUESTION_MAX_UTF8_BYTES = 16384;
+export declare function endpointAuthorityDigest(url: string, token: string, connectionIdentity?: string): string;
+export { type DaemonPaths, daemonPaths } from "./daemon-paths";
+export declare function deriveLifecycleAuditRedactionKey(botToken: string): Uint8Array;
+/**
+ * Attach session-lifecycle control (create/close/resume) to the running daemon.
+ *
+ * Wires an already-started, authenticated control server to the lifecycle
+ * orchestrator with real daemon-side effects (tmux launcher / force-close /
+ * resume), a durable fsynced idempotency ledger + audit JSONL under the agent
+ * notifications dir, and strict paired-chat gating. The control server itself
+ * (NotificationControlServer) is owned/started by the daemon process; this
+ * function only connects it to policy. Returns the orchestrator deps for tests.
+ */
+export declare function startDaemonLifecycleControl(input: {
+    controlServer: ControlServerLike;
+    pairedChatId: string;
+    agentDir: string;
+    auditRedactionKey: Uint8Array;
+    env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps;
+export declare function tryCreateOwnershipLock(fsImpl: TelegramDaemonFs, file: string, initialization: OwnershipLockMetadata): Promise<boolean>;
+type OwnershipLockMetadata = {
+    pid: number;
+    incarnation: string;
+    ownerId?: string;
+    acquisitionId?: string;
+    startedAt: number;
+};
+type LegacyOwnershipLockMetadata = {
+    pid: number;
+    incarnation?: string;
+    startedAt: number;
+};
+type OwnershipLockRead = {
+    kind: "missing";
+} | {
+    kind: "malformed";
+    raw: string;
+    mtimeMs?: number;
+} | {
+    kind: "legacy";
+    metadata: LegacyOwnershipLockMetadata;
+} | {
+    kind: "valid";
+    metadata: OwnershipLockMetadata;
+};
+/** Read lock provenance without treating a corrupt legacy artifact as a filesystem failure. */
+export declare function readOwnershipLock(fsImpl: TelegramDaemonFs, file: string): Promise<OwnershipLockRead>;
+/**
+ * A live initializer lock only proves that a concurrent publisher is active.
+ * It never proves a ready daemon: legacy or unavailable provenance remains
+ * blocked, while a canonical mismatch proves PID reuse and can be reclaimed
+ * under the transition lock.
+ */
+export declare function liveOwnershipLockDecision(input: {
+    lock: OwnershipLockRead;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+}): {
+    acquired: false;
+    attached: false;
+    blocked: true;
+} | {
+    acquired: false;
+    attached: false;
+    provisional: true;
+} | undefined;
+export declare function registerNotificationRoot(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+    fs?: TelegramDaemonFs;
+}): Promise<string>;
+export interface UnregisterNotificationRootResult {
+    root: string;
+    remainingRoots: number;
+}
+/** Remove one session's Telegram scan root without disturbing other live session roots. */
+export declare function unregisterNotificationRoot(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+    fs?: TelegramDaemonFs;
+}): Promise<UnregisterNotificationRootResult>;
+export declare function hasSafeDaemonStateShape(state: unknown): state is DaemonState;
+/** True for a physically live owner with this configuration, including legacy generations. */
+export declare function isPhysicalMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only for a signalable legacy owner or this generation's ready bound child. */
+export declare function isSignalableMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+export declare function isFreshLiveOwner(input: {
+    state: DaemonState | undefined;
+    now: number;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only when a physically live matching owner can serve this build's daemon lifecycle contract. */
+export declare function isCurrentCompatibleOwner(input: {
+    state: DaemonState | undefined;
+    now: number;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+export declare function acquireDaemonOwnership(input: {
+    settings: Settings;
+    roots?: string[];
+    tokenFingerprint: string;
+    chatId: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    randomId?: () => string;
+    /** Permit one Windows source launcher PID to daemon PID handoff. */
+    allowPidRebind?: boolean;
+    /** A caller-supplied opaque owner identity, used when the launcher PID is not durable. */
+    ownerId?: string;
+}): Promise<{
+    acquired: boolean;
+    ownerId?: string;
+    acquisitionId?: string;
+    attached?: boolean;
+    blocked?: boolean;
+    provisional?: boolean;
+    reason?: "identity_mismatch";
+    reloadRequired?: boolean;
+}>;
+export declare function renewDaemonHeartbeat(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+}): Promise<boolean>;
+/** Acquire the lifecycle transition lock with bounded retry for bind/retire races. */
+export declare function acquireTransitionLock(input: {
+    fs: TelegramDaemonFs;
+    path: string;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    retries?: number;
+    retryDelayMs?: number;
+}): Promise<DaemonTransitionLock | undefined>;
+/** Retire only the unchanged provisional acquisition after bounded readiness fails. */
+export declare function retireProvisionalDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    pidIncarnation?: (pid: number) => string | undefined;
+    pidAlive?: (pid: number) => boolean;
+    /** Detached child PID, when the launcher successfully reported it. */
+    pid: number;
+    /** PID which created the provisional reservation before the child was bound. */
+    launcherPid?: number;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+    /** Only no-child confirmation may retire a ready-like launcher publication. */
+    allowReadyWithoutChildPid?: boolean;
+}): Promise<boolean>;
+/** Wait for a matching current-generation daemon to publish a ready state. */
+export declare function waitForTelegramDaemonReady(input: {
+    settings: Settings;
+    ownerId?: string;
+    acquisitionId?: string;
+    pid?: number;
+    excludedPid?: number;
+    tokenFingerprint: string;
+    chatId: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
+}): Promise<boolean>;
+/** Confirm the provisional owner or retire only its unchanged acquisition. */
+export declare function confirmTelegramDaemonSpawn(input: {
+    settings: Settings;
+    spawned: TelegramSpawnOwnerResult;
+    tokenFingerprint: string;
+    chatId: string;
+    pid: number;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
+}): Promise<boolean>;
+export declare function releaseDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+}): Promise<void>;
+/** Read the persisted daemon ownership state (or undefined when absent). */
+export declare function readDaemonState(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
+/** Read the persisted notification roots list. */
+export declare function readDaemonRoots(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<string[]>;
+export interface TelegramSpawnOwnerInput {
+    settings: Settings;
+    roots?: string[];
+    tokenFingerprint: string;
+    chatId: string;
+}
+export interface TelegramSpawnAcquisition {
+    readonly ownerId: string;
+    readonly acquisitionId: string;
+    /** PID of the launcher which reserved provisional ownership before spawn. */
+    readonly launcherPid?: number;
+    /** Actual detached child which must publish the ready owner state. */
+    readonly pid?: number;
+}
+export type TelegramSpawnOwnerResult = {
+    result: "owner_spawned";
+    acquisition: TelegramSpawnAcquisition;
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+} | {
+    result: "attached";
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+    reloadRequired?: boolean;
+} | {
+    result: "blocked";
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+    reloadRequired?: boolean;
+};
+/**
+ * Build the detached spawn command/args for the daemon-internal entrypoint.
+ * Source mode prepends the entry script so the respawn loads edited source;
+ * a compiled binary self-spawns its own subcommand directly.
+ */
+export declare function buildTelegramDaemonSpawnArgs(input: {
+    execPath?: string;
+    ownerId: string;
+    agentDir: string;
+}): {
+    command: string;
+    args: string[];
+    runtime: DaemonRuntimeInfo;
+};
+/**
+ * Acquire ownership for the given Telegram identity and, if acquired, spawn a
+ * fresh detached daemon process. Does NOT register notification roots; callers
+ * that own a session (autostart) register roots separately, while reload reuses
+ * already-persisted roots.
+ */
+export declare function spawnTelegramDaemonOwner(input: TelegramSpawnOwnerInput, deps?: TelegramDaemonDeps): Promise<TelegramSpawnOwnerResult>;
+/**
+ * Ensure a configured daemon owns this session root, preserving ownership safety
+ * while exposing whether a #2028 generation handoff was required.
+ */
+export declare function ensureTelegramDaemonRunningDetailed(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+}, deps?: TelegramDaemonDeps): Promise<EnsureTelegramDaemonDetailedResult>;
+/**
+ * Legacy compatibility mapping for callers that only distinguish ownership from
+ * attachment. New orchestration should use {@link ensureTelegramDaemonRunningDetailed}.
+ */
+export declare function ensureTelegramDaemonRunning(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+}, deps?: TelegramDaemonDeps): Promise<EnsureDaemonResult>;
+export interface BotApi {
+    call(method: string, body: unknown, opts?: {
+        signal?: AbortSignal;
+        noRetry?: boolean;
+    }): Promise<unknown>;
+}
+export interface TelegramTransportOptions {
+    botToken: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    setTimeoutImpl?: typeof setTimeout;
+}
+/** Telegram Bot API transport: HTTP JSON/multipart details stay out of daemon orchestration. */
+export declare class TelegramBotTransport implements BotApi {
+    #private;
+    constructor(opts: TelegramTransportOptions);
+    call(method: string, body: unknown, opts?: {
+        signal?: AbortSignal;
+        noRetry?: boolean;
+    }): Promise<unknown>;
+}
+export type TelegramUpdateOutcome = "consumed" | "retry";
+export type TelegramPollResult = {
+    kind: "success";
+    updateCount: number;
+} | {
+    kind: "aborted";
+} | {
+    kind: "getUpdates_failed";
+    error: string;
+} | {
+    kind: "api_failure";
+    errorCode?: number;
+    description: string;
+} | {
+    kind: "conflict";
+    description: string;
+    backoffMs: number;
+};
+export interface TelegramUpdatePollerOptions {
+    botApi: BotApi;
+    runtime: NotificationOperatorRuntime;
+    backoff: OperatorBackoffPolicy;
+    processUpdate: (update: unknown) => Promise<TelegramUpdateOutcome>;
+    health?: TelegramPollHealth;
+}
+export declare class TelegramPollHealth {
+    #private;
+    record(result: TelegramPollResult): void;
+}
+/** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
+export declare class TelegramUpdatePoller {
+    #private;
+    constructor(opts: TelegramUpdatePollerOptions);
+    pollOnce(signal?: AbortSignal): Promise<number>;
+    pollOnceResult(signal?: AbortSignal): Promise<TelegramPollResult>;
+}
+/** Mutable dispatch state shared by session frames and inbound Telegram updates. */
+export declare class TelegramEventDispatchState {
+    readonly busy: Set<string>;
+    readonly inboundReactions: Map<number, {
+        messageId: number;
+    }>;
+    readonly seenUpdateIds: Set<number>;
+}
+/**
+ * Cooperative control seam for the daemon run loop. Implemented by the
+ * daemon-internal CLI / controller against the owner-scoped control-request
+ * file so the daemon does not import the control module directly.
+ */
+export interface DaemonControlHooks {
+    /** Returns true when a stop/reload has been requested for this owner. */
+    shouldStop(ownerId: string): Promise<boolean>;
+    /** Clear a consumed control request (best-effort). */
+    clear?(ownerId: string): Promise<void>;
+}
+export interface TelegramDaemonOptions {
+    settings: Settings;
+    ownerId: string;
+    botToken: string;
+    chatId: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    fs?: TelegramDaemonFs;
+    WebSocketImpl?: typeof WebSocket;
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+    btw?: {
+        enabled: boolean;
+    };
+    idleTimeoutMs?: number;
+    scanIntervalMs?: number;
+    pid?: number;
+    /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    botApi?: BotApi;
+    control?: DaemonControlHooks;
+    /**
+     * Factory for the session-lifecycle control server. Defaults to the real
+     * native NotificationControlServer; tests inject a fake to verify the
+     * owner-bound start/stop lifecycle without a socket. When `undefined` AND no
+     * default applies (e.g. lifecycle control disabled), no control server starts.
+     */
+    createLifecycleControlServer?: LifecycleControlServerFactory | null;
+    /**
+     * Test seam for observing the exact production lifecycle dependency input.
+     * Production defaults to {@link buildOrchestratorDeps}.
+     */
+    createLifecycleOrchestratorDeps?: (input: {
+        pairedChatId: string;
+        agentNotificationsDir: string;
+        sessionsRoot: string;
+        auditRedactionKey: Uint8Array;
+    }) => OrchestratorDeps;
+    /** Rich text promotion (enabled by default; see rich-render.ts). */
+    rich?: {
+        enabled: boolean;
+    };
+    /** Opt-in rich-draft streaming of live turn previews (off by default; see rich-draft.ts). */
+    richDraft?: {
+        enabled: boolean;
+    };
+    /** Tool start/completion messages (enabled by default). */
+    toolActivity?: {
+        enabled: boolean;
+    };
+    /**
+     * Per-session Telegram forum-topic naming. `nameTemplate` supports the
+     * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
+     * built-in `{repo}/{branch} - {title}` composition and its fallbacks.
+     */
+    topics?: {
+        nameTemplate?: string;
+    };
+}
+interface SessionSocket {
+    /** Immutable key of the transport endpoint that owns this socket. */
+    sessionId: string;
+    /** Current logical session carried by valid threaded frames on this transport. */
+    logicalSessionId: string;
+    token: string;
+    endpointKey: string;
+    endpointDigest: string;
+    hostGeneration: number;
+    ws: WebSocket;
+    pending: Map<string, {
+        sessionId: string;
+        actionId: string;
+    }>;
+    /** True once the server advertised the `client_ping_pong` capability. */
+    capable: boolean;
+    ephemeralCapable: boolean;
+    /** Timestamp (via opts.now) of the last received pong; seeds the TTL window. */
+    lastPongAt: number;
+    /** Nonce of the most recent in-flight ping, if any. */
+    awaitingNonce: string | undefined;
+    /** Per-session liveness interval handle (only set for capable sessions). */
+    pingTimer: ReturnType<typeof setInterval> | undefined;
+    /** Correlation id for the startup replay barrier. */
+    replayId: string;
+    /** Queues live frames until startup replay is applied. */
+    replayPending: boolean;
+    replayQueue: Record<string, unknown>[];
+}
+export declare class TelegramNotificationDaemon {
+    #private;
+    private readonly opts;
+    readonly aliasTable: AliasTable;
+    readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+    /** Telegram message id backing each streamed `${sessionId}:${coalesceKey}`, for in-place edits. */
+    private readonly liveMessages;
+    /** Endpoint-bound ownership for visible or dispatching tool bubbles. */
+    private readonly toolActivityOwners;
+    private readonly revokedToolEndpoints;
+    private readonly unresolvedToolTerminalizations;
+    private toolTerminalizationChain;
+    private toolActivityPolicyEpoch;
+    private toolActivityStopping;
+    private readonly replayToolActivityEpochs;
+    private toolShutdownBarrier;
+    private toolActivityAmbiguous;
+    readonly sessions: Map<string, SessionSocket>;
+    private readonly runtime;
+    private readonly sessionRouter;
+    private readonly pollConflictBackoff;
+    private readonly loopBackoff;
+    private running;
+    private readonly fsImpl;
+    private readonly botApi;
+    private readonly effects;
+    private readonly topics;
+    /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
+    private topicsPersistQueue;
+    /** Daemon edit attempts that can race an accepted user service message. */
+    private readonly daemonRenameAttempts;
+    private readonly selectedAckPending;
+    private readonly pool;
+    private readonly poller;
+    private readonly dispatchState;
+    /** Original markdown of rich messages we sent (chat+message_id), for restoring reply context on inbound replies. */
+    private readonly replyStore;
+    /** Per-session debounce + monotonic draft-id state for opt-in draft streaming. */
+    private readonly draftStream;
+    /** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
+    private readonly topicOwnerByIdentity;
+    /** Non-identity frames held until identity creates the correct thread. */
+    private readonly pendingThreadedFrames;
+    /** Endpoint generation tombstones for sessions that already sent session_closed. */
+    private readonly closedEndpointKeys;
+    /** True once the daemon has nudged the user to enable Threaded Mode. */
+    private threadedFallbackNoticeSent;
+    /** Sessions whose identity header was already sent flat (Threaded Mode off). */
+    private readonly flatIdentitySent;
+    /** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
+    private pairedChatPrivate;
+    /** Bot username from getMe, cached once at owner startup for group/forum command targeting. */
+    private botUsername;
+    /** Sessions whose agent loop is currently busy (drives the typing indicator). */
+    private get busy();
+    /** Inbound update id → originating Telegram message, for delivery reactions. */
+    private get inboundReactions();
+    /**
+     * The owner-bound session-lifecycle control server (create/close/resume).
+     * Started in {@link run} after ownership is confirmed (so exactly one owner
+     * ever runs one), stopped in run()'s finally on any exit path.
+     */
+    private controlServer;
+    /** True while lifecycle control is active, so the loop keeps polling at idle. */
+    private lifecycleControlActive;
+    /** Control token (in-memory) the loopback client presents; never persisted/logged. */
+    private controlToken;
+    /** Loopback WS client to the daemon's own control endpoint (Option A real wire path). */
+    private controlClient;
+    /** Pending lifecycle responses awaiting a control-endpoint reply, by requestId. */
+    private readonly pendingLifecycle;
+    /** Monotonic counter for unique lifecycle request ids. */
+    private lifecycleSeq;
+    /** Attempt tombstones live for the daemon lifetime so a commit key can never send twice. */
+    private readonly selectedAckCache;
+    private cacheSelectedAck;
+    private getCachedSelectedAck;
+    private finishSelectedAck;
+    /**
+     * Cooperatively stop the daemon: set the stop flag and abort the in-flight
+     * long poll so the run loop wakes immediately instead of waiting out the
+     * ~25s getUpdates timeout. Safe to call from a signal handler.
+     */
+    requestStop(_reason?: "reload" | "stop" | "signal"): void;
+    /**
+     * Start the owner-bound lifecycle control server and wire it to the
+     * orchestrator. Called from {@link run} ONLY after ownership is confirmed, so
+     * exactly one owner ever starts exactly one control server (no second poller
+     * / 409). A control-server failure degrades gracefully: the daemon keeps
+     * serving notifications without lifecycle control. Returns true when started.
+     */
+    private startLifecycleControl;
+    /** Stop the lifecycle control server (idempotent); called from run()'s finally. */
+    private stopLifecycleControl;
+    /**
+     * Connect the loopback control client and resolve responses by requestId.
+     * Resolves true once the socket is OPEN (bounded), false on error/timeout, so
+     * the caller only marks lifecycle control active when commands can be sent.
+     */
+    private connectControlClient;
+    /** Send a lifecycle frame over the loopback client and await the response. */
+    private submitLifecycleFrame;
+    private nextLifecycleRequestId;
+    /** Build an authenticated lifecycle frame from a parsed command + identity. */
+    private buildLifecycleFrame;
+    /**
+     * Handle a paired-chat /session_* command: validate (shared validator),
+     * route to the control endpoint, and reply with the outcome. Returns true
+     * when the message was a lifecycle command (so the caller stops processing).
+     */
+    private handleLifecycleCommand;
+    private refreshBotIdentity;
+    /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
+    private formatLifecycleResponse;
+    constructor(opts: TelegramDaemonOptions);
+    private createSessionRouter;
+    loadAliases(): Promise<void>;
+    persistAliases(): Promise<void>;
+    loadSeenUpdateIds(): Promise<void>;
+    persistSeenUpdateIds(): Promise<void>;
+    private pruneSeenUpdateIds;
+    private rememberSeenUpdateId;
+    private reserveSeenUpdateId;
+    scanRoots(): Promise<void>;
+    connectSession(sessionId: string, url: string, token: string): void;
+    /**
+     * Start ack-based liveness for a session whose server advertised the
+     * `client_ping_pong` capability. Each interval drops the session when no pong
+     * has arrived within the TTL (the half-open case the socket never signals via
+     * `close`), otherwise sends a fresh application-level ping. The timer is bound
+     * to this exact session object.
+     */
+    private startLiveness;
+    /**
+     * Idempotent, identity-guarded session teardown. Clears the liveness timer,
+     * removes the map entry only when it still points at this exact session object
+     * (so a delayed old close cannot delete a replacement), and best-effort closes
+     * the socket. `scanRoots()` then reconnects the session.
+     */
+    private enqueueToolTerminalization;
+    private scheduleVisibleToolTerminalization;
+    private beginToolActivityShutdown;
+    private dropSession;
+    private deleteMessageRoutes;
+    private static readonly THREADED_FRAMES;
+    private topicNameFor;
+    /**
+     * Render the operator-configured topic name template, or `undefined` when no
+     * usable template applies so the caller uses the built-in composition. The
+     * template is honored only if it is non-blank AND every placeholder it
+     * references (`{repo}`, `{branch}`, `{title}`) has a value for this session,
+     * which preserves the default title/repo/branch fallbacks and prevents
+     * half-filled names with dangling separators. Unknown placeholders are left
+     * verbatim.
+     */
+    private renderTopicNameTemplate;
+    private topicIdentityKey;
+    private topicIdentityBase;
+    private topicOwnerForIdentity;
+    private sessionCanClaimIdentity;
+    private toolActivityOwner;
+    private toolActivityAuthorityIsCurrent;
+    private submitThreadedFrame;
+    private existingTopicForPrivateChat;
+    private topicAuthorityLease;
+    private topicAuthorityLeaseFromRegistry;
+    private topicLeaseIsCurrent;
+    /** Best-effort re-assertion for a durable user-owned topic name. */
+    private reconcileUserTopicName;
+    private rememberPendingThreadedFrame;
+    private flushPendingThreadedFrames;
+    /**
+     * Resolve (creating once via `createForumTopic`) the forum topic for a
+     * session. On capability failure (e.g. Threaded Mode off) this returns
+     * `undefined`; callers then flat-deliver to a private paired chat (with a
+     * one-time nudge) or drop fail-closed for a non-private chat.
+     */
+    private ensureTopic;
+    private topicPastOrphanGrace;
+    private observeOrphanedTopic;
+    /** Best-effort delete of a session topic once its local notification endpoint shuts down. */
+    private deleteTopic;
+    private persistTopics;
+    loadTopics(): Promise<void>;
+    /** Download a Telegram file by its file_path (from getFile) into memory. */
+    private downloadTelegramFile;
+    /**
+     * Per-session private temp directories (mode 0700) holding inbound non-image
+     * attachments. Keyed by session id and reused across transient reconnects;
+     * removed when the daemon stops (see {@link cleanupAllAttachmentDirs}).
+     */
+    private readonly attachmentDirs;
+    /** Lazily create a private, unguessable 0700 temp dir for `sessionId`. */
+    private ensureAttachmentDir;
+    /** Remove all per-session attachment directories. Called on daemon shutdown. */
+    private cleanupAllAttachmentDirs;
+    /**
+     * Resolve an inbound attachment to inline image bytes (forwarded as images) or
+     * a securely-saved file path note (non-images). Non-image bytes are written
+     * into a private per-session temp dir (0700) under an unguessable name via an
+     * exclusive 0600 create (`wx`), so the files are not world-readable and the
+     * write never follows a pre-existing symlink. The directory is removed when the
+     * daemon stops. Returns base64 images to inline plus human-readable file notes
+     * to append to the injected text.
+     */
+    private resolveInboundAttachment;
+    /**
+     * Serialize all pool flushes. Every caller (`submitThreadedFrame`, the flat
+     * fallback, the drain timer's `void this.flushPool()`, topic teardown) goes
+     * through one promise chain, so two flushes never interleave — a live send can
+     * never be in-flight while a finalized flush reads `liveMessages` and decides
+     * to post a fresh (duplicate) final. Errors are swallowed so one failed flush
+     * never poisons the queue (each flush is already best-effort internally).
+     */
+    private flushChain;
+    private flushPool;
+    /** Drain the shared rate-limit pool and deliver each granted send to its topic. */
+    private submitPool;
+    private flushPoolInner;
+    /**
+     * Track the Telegram message id backing a streamed `(sessionId, coalesceKey)`
+     * so later live/finalized frames edit it in place. Evicts this session's stale
+     * same-category entries (e.g. prior turns) so the map stays bounded.
+     */
+    private recordLiveMessage;
+    /**
+     * Threaded Mode is unavailable (the bot owner has not enabled forum topics in
+     * @BotFather, so `createForumTopic` fails). Deliver the rendered frame flat to
+     * the paired chat instead of dropping it, and nudge the user once. Flat delivery
+     * is gated on the paired chat being a private chat: for a group/supergroup/channel
+     * (e.g. a legacy or hand-edited `chatId`) we keep dropping fail-closed so session
+     * content never lands in a shared chat. Identity headers are sent at most once per
+     * session in flat mode.
+     */
+    private deliverFlatFallback;
+    /**
+     * Resolve (and cache definitive resolution of) whether the paired `chatId` is
+     * a private chat. Topic and flat delivery are only safe in a private DM; an
+     * indeterminate `getChat` result fails closed for this attempt and is retried
+     * later.
+     */
+    private resolvePairedChatPrivacy;
+    /** Keep existing outbound callers fail-closed for indeterminate privacy. */
+    private pairedChatIsPrivate;
+    /** Tell the user once (per daemon run) how to enable Threaded Mode. */
+    private notifyThreadedFallback;
+    private startFlushTimer;
+    private stopFlushTimer;
+    private renewOwnershipHeartbeat;
+    /**
+     * Ownership must be renewed independently of Telegram's 25-second long poll:
+     * the ownership TTL is shorter than a single poll request.
+     */
+    private startOwnershipHeartbeatTimer;
+    private stopOwnershipHeartbeatTimer;
+    /** Run a root scan, guarding against overlapping scans from the timer + loop. */
+    private runScan;
+    private startScanTimer;
+    private stopScanTimer;
+    /** Send a single `typing` chat action into a busy session's topic (best-effort). */
+    private sendTyping;
+    /** Set a native reaction on an inbound thread message (best-effort). */
+    private setReaction;
+    private startTypingTimer;
+    private stopTypingTimer;
+    handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
+    private answerCallbackQueryBestEffort;
+    private sendStaleGuidance;
+    /** Consume Telegram forum-topic rename service messages before text routing. */
+    private handleForumTopicEdited;
+    private processTelegramUpdate;
+    handleTelegramUpdate(update: unknown): Promise<void>;
+    pollOnce(signal?: AbortSignal): Promise<number>;
+    /** Sync the bot's Telegram command menu to what the daemon actually handles. */
+    registerBotCommands(): Promise<void>;
+    run(): Promise<void>;
+    /** True when a signal-driven stop or an owner-scoped control request asks the loop to exit. */
+    private controlStopRequested;
+}