@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/sdk/bus/rate-limit-pool.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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;
+}
+export type RateLimitDisposition = "queued" | "sending" | "accepted" | "rejected" | "ambiguous" | "removed" | "expired";
+export interface RateLimitHandle {
+    itemId: string;
+    settled: Promise<Exclude<RateLimitDisposition, "queued" | "sending">>;
+}
+/** 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 readonly settlements;
+    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>): RateLimitHandle;
+    /** Settle a stable item after its external transport effect has a known outcome. */
+    settle(itemId: string, disposition: Exclude<RateLimitDisposition, "queued" | "sending">): void;
+    /** Mark a granted item as owned by an external transport effect. */
+    markSending(itemId: string): void;
+    private handle;
+    /**
+     * 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, disposition?: Exclude<RateLimitDisposition, "queued" | "sending">): 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/sdk/bus/recent-activity.d.ts

@@ -0,0 +1,48 @@
+/** One ranked recent-session entry surfaced to the picker. */
+export interface RecentSessionEntry {
+    /** Session id from the validated managed candidate header. */
+    sessionId: string;
+    /** Validated workspace path recorded by the managed candidate. */
+    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 {
+    /** Workspace whose managed sessions will be listed readonly. */
+    cwd: string;
+    /** Agent directory used to resolve the managed session scope. */
+    agentDir?: string;
+    /** Explicit managed root for isolated tests. */
+    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;
+    /** Search every validated v2 workspace scope below the session root (default false). */
+    allWorkspaces?: boolean;
+    /** Injection seam for tests. */
+    readInitialLines?: (file: string, maxLines: number) => string[];
+}
+/** Lists readonly managed candidates, optionally across every validated v2 workspace scope, ranked by history-file mtime. */
+export type ListRecentSessionsResult = {
+    kind: "complete";
+    entries: RecentSessionEntry[];
+    warnings: readonly string[];
+} | {
+    kind: "error";
+    code: "scope_unavailable" | "managed_scan_failed";
+    message: string;
+};
+export declare function listRecentSessions(deps: RecentActivityDeps): Promise<ListRecentSessionsResult>;

package/dist/types/sdk/bus/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/sdk/bus/rich-document.d.ts

@@ -0,0 +1,7 @@
+export type RichEligibility = {
+    kind: "eligible";
+} | {
+    kind: "ineligible";
+};
+/** Conservatively recognize `/btw` Markdown that can be represented as rich content. */
+export declare function parseRichEligibility(markdown: string): RichEligibility;

package/dist/types/sdk/bus/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/sdk/bus/rich-render.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Rich-message promotion for stable non-editable Telegram text sends.
+ *
+ * When enabled, the daemon promotes eligible finalized `sendMessage` payloads
+ * carrying raw markdown to Bot API `sendRichMessage`. Only an explicit
+ * `{ ok: false }` response selects the unchanged HTML path; ambiguous transport
+ * outcomes remain single-attempt and never fall back.
+ */
+import type { BotApi } from "./telegram-daemon";
+import type { ThreadedSend } from "./threaded-render";
+/**
+ * Telegram's hard per-message character ceiling (4096). Final-answer promotion
+ * uses this value to keep oversized Markdown on the existing chunked HTML path.
+ * `/btw` eligibility has its own 32,768-scalar route guard; only a definite
+ * rich rejection may select the correlated HTML path.
+ */
+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;
+        skip_entity_detection: true;
+    };
+    reply_markup?: unknown;
+};
+/** Whether `/btw` Markdown may use Bot API 10.1 rich delivery. */
+export declare function isBtwRichEligible(markdown: string): boolean;
+/**
+ * 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` only
+ * after an explicit `{ ok: false }` response. Transport errors and malformed or
+ * ambiguous responses are logged but never retried or sent again through HTML.
+ */
+export declare function deliverRichWithFallback(botApi: BotApi, base: {
+    chat_id: string | number;
+    message_thread_id?: number;
+}, send: ThreadedSend, signal: AbortSignal, 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 only after an explicit `{ ok:false }`
+ * response. Other outcomes are ambiguous, are logged, and preserve the single
+ * physical rich delivery.
+ */
+export declare function deliverRichActionWithFallback(botApi: BotApi, base: {
+    chat_id: string | number;
+    message_thread_id?: number;
+}, opts: {
+    markdown: string;
+    replyMarkup?: unknown;
+}, signal: AbortSignal, htmlFallback: () => Promise<number | undefined>, log?: {
+    warn(msg: string): void;
+}): Promise<{
+    messageId?: number;
+    usedRich: boolean;
+    usedFallback: boolean;
+}>;

package/dist/types/sdk/bus/session-control.d.ts

@@ -0,0 +1,86 @@
+import { type NotificationConfig } from "./config";
+/** Minimal session-manager surface shared by extension, TUI, and headless hosts. */
+export interface NotificationSessionContext {
+    sessionManager: {
+        getCwd(): string;
+        getSessionId(): string;
+    };
+}
+/** A snapshot of the current session, resolved from the session manager per operation. */
+export interface BoundNotificationSession<Context extends NotificationSessionContext = NotificationSessionContext> {
+    readonly context: Context;
+    readonly cwd: string;
+    readonly sessionId: string;
+    unbind(): void;
+}
+export type NotificationEndpointStartResult = "started" | "already" | "disabled" | "failed";
+export type TelegramDaemonPreflightResult = "ready" | "blocked_identity" | "failed";
+/**
+ * The endpoint implementation is deliberately injected. The controller owns
+ * policy and session-local state while the extension continues to own its
+ * concrete NotificationServer resources.
+ */
+export interface NotificationSessionRuntime<Context extends NotificationSessionContext = NotificationSessionContext> {
+    isRunning(binding: BoundNotificationSession<Context>): boolean;
+    start(binding: BoundNotificationSession<Context>): Promise<NotificationEndpointStartResult>;
+    stop(binding: BoundNotificationSession<Context>): Promise<boolean>;
+    /**
+     * Proves the complete Telegram owner identity before a generic endpoint can
+     * emit a frame. `blocked_identity` is fail-closed and starts nothing.
+     */
+    ensureTelegramDaemon?(binding: BoundNotificationSession<Context>): Promise<TelegramDaemonPreflightResult>;
+    /** Refresh mutable delivery policy from the same configuration snapshot used for reconciliation. */
+    refreshPolicy?(binding: BoundNotificationSession<Context>, policy: NotificationRuntimePolicy): void;
+    /** Enables delivery only after the controller has committed a stable policy. */
+    activate?(binding: BoundNotificationSession<Context>): void;
+}
+export interface NotificationSessionStatus {
+    eligible: boolean;
+    locallyEnabled: boolean;
+    effectiveEnabled: boolean;
+    running: boolean;
+    environment: "off" | "explicit" | "token" | "default";
+}
+export interface NotificationSessionReconcileResult {
+    outcome: NotificationEndpointStartResult | "stopped";
+    status: NotificationSessionStatus;
+}
+export interface NotificationRuntimePolicy {
+    redact: boolean;
+    verbosity: NotificationConfig["verbosity"];
+    stream: boolean;
+    mode: "provisional" | "committed";
+}
+export interface NotificationSessionControllerOptions {
+    /** Gate A result, resolved once by the SDK from the canonical host predicate. */
+    eligible: boolean;
+    /** Reads the global-only, schema-default-resolved notification configuration. */
+    getConfig(): NotificationConfig;
+    /** Kept as a reference so test and embedding hosts can supply their own environment. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class NotificationSessionController {
+    #private;
+    constructor(options: NotificationSessionControllerOptions);
+    /** Attach the concrete generic endpoint implementation used by this host. */
+    attachRuntime<Context extends NotificationSessionContext>(runtime: NotificationSessionRuntime<Context>): () => void;
+    /**
+     * Bind a fresh session snapshot. Callers should not cache it: cwd and session
+     * id may change on `/new`, fork, or resume.
+     */
+    bind<Context extends NotificationSessionContext>(context: Context): BoundNotificationSession<Context>;
+    /** Preserve session-local safety state and pending-operation ownership across a session rekey. */
+    rekeySession(previousSessionId: string, nextSessionId: string): void;
+    query<Context extends NotificationSessionContext>(context: Context): NotificationSessionStatus;
+    /** Stop the current endpoint during host shutdown without changing local preference. */
+    stopCurrentSession<Context extends NotificationSessionContext>(context: Context): Promise<boolean>;
+    /**
+     * Hold this session's endpoint inactive after a foreign-daemon identity race.
+     * The block remains until an explicit same-identity reconnect or CAS restore clears it.
+     */
+    enterBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<boolean>;
+    /** Clear a block only after the caller has verified a safe same-identity reconnect or restore. */
+    clearBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<void>;
+    setLocalEnabled<Context extends NotificationSessionContext>(context: Context, enabled: boolean): Promise<NotificationSessionReconcileResult>;
+    reconcileCurrentSession<Context extends NotificationSessionContext>(context: Context): Promise<NotificationSessionReconcileResult>;
+}

package/dist/types/sdk/bus/slack-conversation.d.ts

@@ -0,0 +1,56 @@
+import { type ConversationRecord } from "./conversation-store";
+export interface SlackInboundDispatchReceipt {
+    key: string;
+    eventId: string;
+    interactionId: string;
+    retryKey: string;
+    eventContext?: string;
+    kind: "action" | "command";
+    actionId?: string;
+    /** The endpoint generation and SDK effect captured before Socket Mode ACK. */
+    endpointGeneration: number;
+    /** Identifier of the protected journal payload; mappings never retain message bodies. */
+    effectId: string;
+    idempotencyKey: string;
+}
+export type SlackConversationState = "absent" | "posting_root" | "active" | "closed_marker" | "resumed_root" | "error";
+/** Durable Slack mapping. It contains identifiers and receipt metadata only; protected journal effects own message bodies. */
+export interface SlackConversation extends ConversationRecord {
+    state: SlackConversationState;
+    teamId: string;
+    channelId: string;
+    rootTs?: string;
+    sessionId?: string;
+    endpointGeneration?: number;
+    clientMsgId?: string;
+    /** Exclusive, expiring authority for provider reconciliation/publication of the root intent. */
+    rootPublicationOwner?: string;
+    rootPublicationLeaseExpiresAt?: number;
+    /** Monotonic fencing token; stale root publishers may not commit after takeover. */
+    rootPublicationFence?: number;
+    /** Exclusive, expiring authority for provider reconciliation/publication of the outbound action intent. */
+    outboundActionOwner?: string;
+    outboundActionLeaseExpiresAt?: number;
+    /** Monotonic fencing token; stale action publishers may not commit after takeover. */
+    outboundActionFence?: number;
+    /** Action authority only; action bodies and endpoint credentials are never persisted. */
+    pendingActionId?: string;
+    /** Durable, unpublished action intent. The action body is supplied only by the caller. */
+    outboundActionId?: string;
+    outboundActionClientMsgId?: string;
+    lastError?: string;
+    updatedAt: number;
+    seenEventIds: string[];
+    seenContextIds: string[];
+    seenRetryKeys: string[];
+    seenInteractionIds: string[];
+    /** Durable inbound effect identifiers. The protected journal owns replay payloads. */
+    inboundDispatches?: SlackInboundDispatchReceipt[];
+}
+export declare function slackConversationKey(input: {
+    teamId: string;
+    channelId: string;
+    rootTs: string;
+}): string;
+export declare function normalizeSlackConversation(record: SlackConversation): SlackConversation;
+export declare function acceptsSlackInbound(record: SlackConversation, rootTs: string, endpointGeneration: number): boolean;

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

@@ -0,0 +1,60 @@
+import { type SdkSessionEndpoint } from "../client/discovery";
+import { ConversationStore } from "./conversation-store";
+import { type SlackConversation } from "./slack-conversation";
+export declare class SlackEndpointBindingError extends Error {
+    constructor(message?: string);
+}
+import type { SlackProvider, SlackSocketEnvelope } from "./slack-provider";
+export interface SlackEndpoint extends SdkSessionEndpoint {
+    generation: number;
+}
+export interface SlackSdkClient {
+    send(frame: Record<string, unknown>): void;
+}
+export interface SlackNotificationDaemonOptions {
+    agentDir: string;
+    repo: string;
+    teamId: string;
+    channelId: string;
+    provider: SlackProvider;
+    botUserId?: string;
+    /** Fail-closed authorization for the paired Slack principal. */
+    authorizeActor?: (actorId: string) => boolean | Promise<boolean>;
+    store?: ConversationStore<SlackConversation>;
+    now?: () => number;
+    randomId?: () => string;
+    /** Stable identity for the process attempting durable provider publication. */
+    publicationOwnerId?: string;
+    publicationLeaseMs?: number;
+    resolveEndpoint?: (sessionId: string) => Promise<SlackEndpoint | null>;
+    createClient: (endpoint: SlackEndpoint) => SlackSdkClient;
+    onCommand?: (sessionId: string, content: string, endpoint: SlackEndpoint, idempotencyKey: string) => Promise<boolean>;
+}
+/**
+ * Slack Socket Mode notification daemon. Accepted inbound SDK effects are
+ * persisted before acknowledgement, including their replay payload and captured
+ * endpoint generation; endpoint credentials and Socket Mode cursors are never
+ * written to disk.
+ */
+export declare class SlackNotificationDaemon {
+    #private;
+    private readonly options;
+    readonly store: ConversationStore<SlackConversation>;
+    constructor(options: SlackNotificationDaemonOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Accepted inbound effects are durably claimed before their Socket Mode ACK. */
+    handleEnvelope(envelope: SlackSocketEnvelope): Promise<boolean>;
+    postRoot(sessionId: string, body: string, endpointGeneration?: number): Promise<SlackConversation>;
+    /** Deliver a notification into the mapped root thread, creating that root once. */
+    notify(sessionId: string, body: string, actionId?: string, endpointGeneration?: number): Promise<SlackConversation>;
+    /** Posts a safe command outcome to the active mapped root thread. */
+    postCommandResult(sessionId: string, content: string): Promise<boolean>;
+    resolveAction(sessionId: string, actionId: string): Promise<void>;
+    close(sessionId: string, marker?: string): Promise<boolean>;
+    resume(sessionId: string, body: string, endpointGeneration?: number): Promise<SlackConversation>;
+    findSession(sessionId: string, includeInactive: boolean): Promise<{
+        key: string;
+        record: SlackConversation;
+    } | undefined>;
+}

package/dist/types/sdk/bus/slack-live-provider.d.ts

@@ -0,0 +1,59 @@
+import type { SlackMessageSearchResult, SlackPostedMessage, SlackProviderClient, SlackSocketEnvelope } from "./slack-provider";
+export type SlackProviderErrorCode = "connection" | "protocol" | "web_api" | "rate_limited";
+/** A Slack transport failure whose fields are safe to surface without credentials. */
+export declare class SlackProviderError extends Error {
+    readonly code: SlackProviderErrorCode;
+    readonly operation: string;
+    readonly status?: number | undefined;
+    readonly retryAfterMs?: number | undefined;
+    /** The server may have accepted the request before its response became unusable. */
+    readonly mayHaveBeenAccepted: boolean;
+    readonly retryable: boolean;
+    constructor(code: SlackProviderErrorCode, operation: string, status?: number | undefined, retryAfterMs?: number | undefined, 
+    /** The server may have accepted the request before its response became unusable. */
+    mayHaveBeenAccepted?: boolean);
+}
+export interface SlackWebSocket {
+    readonly readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    send(data: string): void;
+    close(): void;
+}
+export interface SlackLiveProviderOptions {
+    appToken: string;
+    botToken: string;
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    webSocket?: (url: string) => SlackWebSocket;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    reconnectDelayMs?: number;
+    maxRateLimitRetries?: number;
+    maxRetryAfterMs?: number;
+    activityTimeoutMs?: number;
+}
+/**
+ * Production Socket Mode and Web API client. It keeps all connection state in
+ * memory and deliberately never maintains a Slack cursor.
+ */
+export declare class SlackLiveProvider implements SlackProviderClient {
+    #private;
+    get transportHealthy(): boolean;
+    constructor(options: SlackLiveProviderOptions);
+    start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    ack(envelopeId: string): Promise<void>;
+    postMessage(input: {
+        channel: string;
+        text: string;
+        threadTs?: string;
+        clientMsgId: string;
+    }): Promise<SlackPostedMessage>;
+    findMessageByClientMsgId(input: {
+        channel: string;
+        clientMsgId: string;
+        threadTs?: string;
+    }): Promise<SlackMessageSearchResult | null>;
+}