@sayknow-cli/coding-agent 0.3.13 → 0.3.16

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;
+}

package/dist/types/notifications/recent-activity.d.ts

@@ -0,0 +1,39 @@
+/** One ranked recent-session entry surfaced to the picker. */
+export interface RecentSessionEntry {
+    /** Session id (the `.jsonl` file stem). */
+    sessionId: string;
+    /** Working directory / repo path, when recoverable from the header. */
+    path?: string;
+    /** Branch, when recoverable from the header. */
+    branch?: string;
+    /** A short title (first user message), when recoverable. */
+    title?: string;
+    /** Absolute path of the session history (state) file. */
+    sessionStateFile: string;
+    /** Last-activity epoch-millis (history file mtime). */
+    mtimeMs: number;
+    /** True when a terminal breadcrumb points at this session file. */
+    currentTerminal?: boolean;
+    /** True when this history is an internal helper/sub-agent session. */
+    internal?: boolean;
+}
+export interface RecentActivityDeps {
+    /** Root holding `<encoded-cwd>/<sessionId>.jsonl` history files. */
+    sessionsRoot: string;
+    /** Optional breadcrumb session-file paths (current terminals). */
+    breadcrumbPaths?: string[];
+    /** Max entries to return (default 20). */
+    limit?: number;
+    /** Include internal helper/sub-agent sessions (default true). */
+    includeInternal?: boolean;
+    /** Injection seam for tests. */
+    readInitialLines?: (file: string, maxLines: number) => string[];
+}
+/**
+ * List recent sessions ranked by history-file mtime (newest first).
+ *
+ * Scans `<sessionsRoot>/<encoded-cwd>/<sessionId>.jsonl`, stats each file, and
+ * returns up to `limit` entries enriched with header metadata and a
+ * `currentTerminal` flag for any breadcrumb-referenced session file.
+ */
+export declare function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry[];

package/dist/types/notifications/reply-sent-store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Index of rich messages the daemon sent, mapping `${chat_id}:${message_id}` to
+ * the original markdown. Telegram does not echo a `sendRichMessage` message's
+ * text in a reply's `reply_to_message`, so a user replying to a rich final
+ * answer would otherwise strand the agent without the quoted context. The daemon
+ * records the markdown on every promoted send and looks it up on inbound replies
+ * to restore that context.
+ *
+ * Fail-closed and off-path-neutral: nothing is recorded unless a send was
+ * actually promoted to rich, `record` is a no-op on any error (the in-memory map
+ * is only mutated after the atomic persist succeeds), and `lookup` returns
+ * undefined on any miss or error, so a bad index write/read never kills the
+ * daemon.
+ */
+import * as fs from "node:fs";
+/**
+ * Minimal async filesystem surface the store needs. Structurally a subset of the
+ * daemon's `TelegramDaemonFs`, so the daemon can pass its own `fs` straight
+ * through and tests can inject a fake.
+ */
+export interface ReplySentStoreFs {
+    mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<unknown>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, opts?: fs.WriteFileOptions): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+export declare class ReplySentStore {
+    #private;
+    constructor(input: {
+        agentDir: string;
+        fs?: ReplySentStoreFs;
+        now?: () => number;
+    });
+    /** Restore the persisted index into memory. No-op on a missing or corrupt file. */
+    load(): Promise<void>;
+    /**
+     * Record the original markdown of a rich message the daemon just sent. The
+     * text is capped at {@link MAX_TEXT_LENGTH}; the index is capped at
+     * {@link MAX_ENTRIES} (oldest-by-timestamp evicted). No-op on any failure: the
+     * in-memory map is only replaced after the atomic persist succeeds.
+     */
+    record(input: {
+        chatId: string | number;
+        messageId: number;
+        text: string;
+    }): Promise<void>;
+    /** Look up the original markdown for a message the daemon sent. undefined on miss or failure. */
+    lookup(input: {
+        chatId: string | number;
+        messageId: number;
+    }): string | undefined;
+}

package/dist/types/notifications/rich-draft.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Opt-in rich-draft streaming for a turn's in-progress preview.
+ *
+ * When the operator opts in (`richDraft.enabled`) the daemon streams LIVE turn
+ * markdown to the Bot API `sendRichMessageDraft` method as a debounced preview.
+ * Every failure is a harmless no-op (warn once, keep the daemon alive), and when
+ * off no draft call is ever made — so the off-state request bodies stay
+ * byte-identical.
+ */
+import type { BotApi } from "./telegram-daemon";
+import type { ThreadedSend } from "./threaded-render";
+/** Minimum gap between two draft sends for one session (debounce floor). */
+export declare const DRAFT_DEBOUNCE_MS = 1500;
+/**
+ * Wrap raw markdown + a monotonic draft id in the `sendRichMessageDraft` request
+ * payload shape: mirrors `buildRichMessage`'s proven `rich_message.markdown`
+ * content wrapper, with a top-level `draft_id` selecting the draft revision to
+ * update (a routing param, like `message_thread_id`).
+ */
+export declare function buildRichDraft(draftId: number, raw: string): {
+    draft_id: number;
+    rich_message: {
+        markdown: string;
+    };
+};
+/**
+ * Whether a granted send should stream a rich draft. Fail-closed: every clause
+ * must hold, otherwise no draft is sent. Mirrors `shouldPromoteRich` but targets
+ * the LIVE lane and the live-only `richDraftMarkdown` marker (set by
+ * `renderThreadedFrame` for non-finalized turn frames).
+ */
+export declare function shouldStreamDraft(input: {
+    enabled?: boolean;
+    send: ThreadedSend;
+}): boolean;
+/**
+ * Per-session debounce + monotonic draft-id state for draft streaming. Skips a
+ * draft when less than `debounceMs` has elapsed since the session's last SENT
+ * draft (the rate-limit pool already coalesces live frames to the latest, so a
+ * skipped frame is naturally superseded by the next one). `reset` clears a
+ * session's window when its turn finalizes so the next turn starts fresh.
+ */
+export declare class DraftStreamState {
+    #private;
+    constructor(debounceMs?: number);
+    /**
+     * If enough time has elapsed since the session's last draft, record `now` as
+     * the new last-sent time and return the next monotonic draft id; otherwise
+     * return `undefined` (debounced — the caller skips this frame).
+     */
+    tryClaim(sessionId: string, now: number): number | undefined;
+    /** Clear a session's debounce window (called when its turn finalizes). The
+     * global draft id keeps incrementing so ids are never reused across turns. */
+    reset(sessionId: string): void;
+}
+/**
+ * Best-effort delivery of a rich draft. Never throws and has no HTML fallback: a
+ * draft is a purely additive preview, so on any failure (a thrown transport
+ * error or an `{ ok: false }` JSON response — the transport returns `res.json()`
+ * for JSON methods, so `ok:false` does not throw) it warns exactly once and
+ * returns; the unchanged live HTML send still carries the content.
+ */
+export declare function deliverDraft(botApi: BotApi, base: {
+    chat_id: string | number;
+    message_thread_id?: number;
+}, draftId: number, raw: string, log?: {
+    warn(msg: string): void;
+}): Promise<void>;

package/dist/types/notifications/rich-render.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Rich-message promotion for stable non-editable Telegram text sends.
+ *
+ * When enabled, the daemon promotes eligible finalized `sendMessage` payloads
+ * carrying raw markdown to the Bot API `sendRichMessage` method. On any miss or
+ * failure the daemon keeps the unchanged HTML `sendMessage` path, so the
+ * off-state request bodies are byte-identical.
+ */
+import type { BotApi } from "./telegram-daemon";
+import type { ThreadedSend } from "./threaded-render";
+/**
+ * Telegram's hard per-message character ceiling (4096). Surfaced here purely as
+ * documentation and a marker for a future native rich-message splitter — it is
+ * intentionally NON-BEHAVIORAL and MUST stay that way: nothing in the rich path
+ * branches on this value.
+ *
+ * Overflow is already safe without it. The production final-answer text is capped
+ * at 3500 chars upstream (`summaryFromMessage(..., 3500)`), so a promoted
+ * `sendRichMessage` never approaches this ceiling; and if the Bot API ever rejects
+ * an oversized rich payload it returns `{ ok: false }`, which
+ * `deliverRichWithFallback` (below) turns into the chunked HTML `splitTelegramHtml`
+ * fallback (each chunk ≤ TELEGRAM_MESSAGE_LIMIT). This constant only marks where a
+ * future rich splitter would read its ceiling; wiring it into a branch would change
+ * byte-for-byte behavior and is out of scope.
+ */
+export declare const RICH_MESSAGE_LIMIT = 4096;
+/** Wrap raw markdown in the `sendRichMessage` request payload shape. */
+export declare function buildRichMessage(raw: string, extras?: {
+    reply_markup?: unknown;
+}): {
+    rich_message: {
+        markdown: string;
+    };
+    reply_markup?: unknown;
+};
+/**
+ * Whether a granted send should be promoted to `sendRichMessage`. Fail-closed
+ * and class-aware: every clause must hold, otherwise the daemon keeps the HTML path.
+ */
+export declare function shouldPromoteRich(input: {
+    enabled?: boolean;
+    send: ThreadedSend;
+}): boolean;
+/**
+ * Deliver the promoted rich message, falling back to `fallbackDeliver` (the
+ * unchanged HTML `sendMessage` loop) on any failure. A failure is either a
+ * thrown transport error or a `{ ok: false }` JSON response (the transport
+ * returns `res.json()` for JSON methods, so `ok:false` does not throw). On
+ * failure exactly one diagnostic is logged before the fallback runs; on success
+ * the fallback never runs.
+ *
+ * Returns the sent message's `message_id` on success (when the response carries
+ * one), otherwise `undefined` — including every failure/fallback path and a
+ * success whose response omits `result.message_id`. Callers that ignore the
+ * return value are unaffected.
+ */
+export declare function deliverRichWithFallback(botApi: BotApi, base: {
+    chat_id: string | number;
+    message_thread_id?: number;
+}, send: ThreadedSend, fallbackDeliver: () => Promise<void>, log?: {
+    warn(msg: string): void;
+}): Promise<number | undefined>;
+/**
+ * Deliver an action-needed (ask/idle) message via `sendRichMessage`, falling
+ * back to the unchanged HTML chunk loop on any failure. Mirrors
+ * {@link deliverRichWithFallback} but takes an explicit markdown body plus an
+ * optional top-level `reply_markup` (probe-confirmed: `sendRichMessage` accepts
+ * `reply_markup` alongside `rich_message`), and surfaces a structured outcome so
+ * the daemon can route inbound replies to the resulting message id.
+ *
+ * On rich success: returns `{ messageId, usedRich: true, usedFallback: false }`
+ * where `messageId` is `res.result.message_id` when present. On a `{ ok:false }`
+ * response or a thrown transport error: warns exactly once, runs `htmlFallback`,
+ * and returns `{ messageId, usedRich: false, usedFallback: true }` where
+ * `messageId` is the fallback's return value (the last HTML chunk's id).
+ */
+export declare function deliverRichActionWithFallback(botApi: BotApi, base: {
+    chat_id: string | number;
+    message_thread_id?: number;
+}, opts: {
+    markdown: string;
+    replyMarkup?: unknown;
+    requireMessageId?: boolean;
+}, htmlFallback: () => Promise<number | undefined>, log?: {
+    warn(msg: string): void;
+}): Promise<{
+    messageId?: number;
+    usedRich: boolean;
+    usedFallback: boolean;
+}>;

package/dist/types/notifications/telegram-cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/**
+ * Reference CLI for the notifications SDK Telegram client.
+ *
+ * Bridges a running SKC session's notification endpoint to a Telegram bot so you
+ * can answer asks / see idle pings from your phone — no RPC mode required. This
+ * is an EXAMPLE/template (the SDK contract is in `docs/notifications-sdk.md`);
+ * Discord/Slack clients are written the same way.
+ *
+ * Usage:
+ *   bun run packages/coding-agent/src/notifications/telegram-cli.ts \
+ *     --bot-token <token> [--chat-id <id>] [--endpoint-file <path> | --session-id <id>] [--repo <dir>]
+ *
+ * Env fallbacks: SKC_TG_BOT_TOKEN, SKC_TG_CHAT_ID.
+ * If --chat-id is omitted it is auto-resolved from getUpdates (message the bot once).
+ * If neither --endpoint-file nor --session-id is given, the newest endpoint file
+ * under <repo>/.skc/state/notifications/ is used.
+ */
+export {};

package/dist/types/notifications/telegram-daemon-cli.d.ts

@@ -0,0 +1,28 @@
+import type { Settings } from "../config/settings";
+import type { TelegramDaemonOptions } from "./telegram-daemon";
+type TelegramDaemonRunner = {
+    run(): Promise<void>;
+    requestStop(reason?: "reload" | "signal" | "stop"): void;
+};
+type TelegramDaemonConstructor = new (opts: TelegramDaemonOptions) => TelegramDaemonRunner;
+export interface RunDaemonInternalDeps {
+    SettingsImpl?: {
+        init: (options?: {
+            agentDir?: string;
+        }) => Promise<Pick<Settings, "get" | "getAgentDir">>;
+    };
+    DaemonImpl?: TelegramDaemonConstructor;
+    processPid?: number;
+    pidAlive?: (pid: number) => boolean;
+}
+export declare function createLightweightDaemonSettings(input: {
+    agentDir: string;
+    rawConfig?: unknown;
+}): Pick<Settings, "get" | "getAgentDir">;
+export declare function loadLightweightDaemonSettings(agentDir: string): Promise<Pick<Settings, "get" | "getAgentDir">>;
+export declare function ownerPidFromOwnerId(ownerId: string): number | undefined;
+export declare function runDaemonSmoke(opts?: {
+    agentDir?: string;
+}): Promise<void>;
+export declare function runDaemonInternal(argv: string[], deps?: RunDaemonInternalDeps): Promise<void>;
+export {};