@sayknow-cli/coding-agent 0.3.12 → 0.3.13

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

@@ -1,95 +0,0 @@
-/**
- * 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 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;
-    /** 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;
-}
-/**
- * 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. If it carries a `coalesceKey` matching a queued item in
-     * the same `(sessionId, lane)`, the queued payload is replaced (latest
-     * wins) and FIFO position is preserved; otherwise it is appended.
-     */
-    submit(item: RateLimitItem<T>): void;
-    /**
-     * Grant as many queued items as tokens allow at `nowMs`. Items are selected
-     * by lane priority, then round-robin across sessions within a lane (so no
-     * single session monopolises a lane), consuming one token each.
-     */
-    drain(nowMs?: number): RateLimitItem<T>[];
-    /** Remove queued items matching `predicate` without consuming tokens. Returns removed items in lane/FIFO order. */
-    removeWhere(predicate: (item: RateLimitItem<T>) => boolean): RateLimitItem<T>[];
-    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

@@ -1,39 +0,0 @@
-/** 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

@@ -1,53 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-/**
- * 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

@@ -1,90 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-#!/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

@@ -1,28 +0,0 @@
-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 {};

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

@@ -1,64 +0,0 @@
-/**
- * Telegram daemon controller + owner-scoped control-request helpers.
- *
- * Reload is a hybrid: an owner-scoped control-request file records auditable
- * intent, SIGTERM is the wakeup that aborts the in-flight long poll, and a
- * fresh daemon is spawned only after the old pid is dead / has exited. This
- * keeps the single-poller invariant (no Telegram getUpdates 409 overlap) and
- * never steals a still-live owner.
- */
-import type { Settings } from "../config/settings";
-import type { BuiltInDaemonController, DaemonOperationOptions, DaemonOperationResult, DaemonStatus } from "../daemon/control-types";
-import { type TelegramDaemonDeps, type TelegramDaemonFs } from "./telegram-daemon";
-export interface TelegramDaemonControlRequest {
-    version: 1;
-    requestId: string;
-    action: "reload" | "stop";
-    ownerId: string;
-    pid: number;
-    createdAt: number;
-}
-export declare function telegramControlRequestPath(agentDir: string): string;
-export declare function readTelegramControlRequest(settings: Settings, fsImpl?: TelegramDaemonFs): Promise<TelegramDaemonControlRequest | undefined>;
-export declare function writeTelegramControlRequest(settings: Settings, request: TelegramDaemonControlRequest, fsImpl?: TelegramDaemonFs): Promise<void>;
-export declare function clearTelegramControlRequest(settings: Settings, requestId?: string, fsImpl?: TelegramDaemonFs): Promise<void>;
-export interface TelegramDaemonControlDeps {
-    fs?: TelegramDaemonFs;
-    now?: () => number;
-    pidAlive?: (pid: number) => boolean;
-    sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
-    spawn?: TelegramDaemonDeps["spawn"];
-    execPath?: string;
-    /**
-     * Stable process id encoded into freshly-spawned daemon owner ids.
-     *
-     * The daemon-internal entrypoint rejects numeric owner ids whose process is
-     * already gone. `skc daemon reload` is a short-lived CLI process, so using its
-     * own pid can race the child startup and make the replacement exit immediately.
-     */
-    ownerPid?: number;
-    randomId?: () => string;
-    sleep?: (ms: number) => Promise<void>;
-    waitStepMs?: number;
-}
-export declare class TelegramDaemonController implements BuiltInDaemonController {
-    private readonly settings;
-    private readonly deps;
-    readonly kind: "telegram";
-    private readonly fsImpl;
-    private readonly now;
-    private readonly pidAlive;
-    private readonly sendSignal;
-    private readonly waitStepMs;
-    constructor(settings: Settings, deps?: TelegramDaemonControlDeps);
-    private runtimeInfo;
-    status(): Promise<DaemonStatus>;
-    private spawnDeps;
-    private sleep;
-    private waitForPidDeath;
-    private result;
-    reload(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
-    stop(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
-    private stopOrReload;
-    private clearOwnRequest;
-}