@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/sdk/bus/chat-effect-journal.d.ts

@@ -0,0 +1,85 @@
+import { type ConversationRecord, type ConversationStoreFs } from "./conversation-store";
+export declare const CHAT_EFFECT_JOURNAL_VERSION = 1;
+export declare const MAX_TERMINAL_CHAT_EFFECTS = 128;
+export declare function chatEffectJournalPath(agentDir: string, transport: "discord" | "slack"): string;
+export type ChatEffectState = "pending" | "leased" | "accepted" | "uncertain" | "terminal";
+/** Provider receipts are identifiers/status only. Never put request or response bodies here. */
+export interface ChatEffectReceipt {
+    provider?: string;
+    messageId?: string;
+    channelId?: string;
+    threadId?: string;
+    timestamp?: string;
+    status?: string;
+}
+/**
+ * A protected, generation-bound provider-visible effect. Payload is deliberately
+ * owned by this journal; conversation mappings may retain only `effectId`.
+ */
+export interface ChatEffect<TPayload = unknown> extends ConversationRecord {
+    id: string;
+    kind: string;
+    transport: "discord" | "slack";
+    sessionId?: string;
+    endpointGeneration: number;
+    payload: TPayload;
+    state: ChatEffectState;
+    owner?: string;
+    leaseExpiresAt?: number;
+    epoch: number;
+    createdAt: number;
+    updatedAt: number;
+    receipt?: ChatEffectReceipt;
+}
+export interface EnqueueChatEffect<TPayload> {
+    id: string;
+    kind: string;
+    transport: "discord" | "slack";
+    sessionId?: string;
+    endpointGeneration: number;
+    payload: TPayload;
+    receipt?: ChatEffectReceipt;
+}
+export interface ChatEffectLease {
+    owner: string;
+    epoch: number;
+}
+/**
+ * One journal per transport. It uses the same 0600, fsynced atomic persistence
+ * and cross-process exclusive locking as mappings, but stores payloads in a
+ * separate protected file (`effects.json`). Terminal history is compacted only
+ * after terminal state is durably recorded; nonterminal effects are never evicted.
+ */
+export declare class ChatEffectJournal {
+    #private;
+    constructor(input: {
+        agentDir: string;
+        transport: "discord" | "slack";
+        fs?: ConversationStoreFs;
+        now?: () => number;
+        pid?: number;
+        pidAlive?: (pid: number) => boolean;
+        pidIncarnation?: (pid: number) => string | undefined;
+        sleep?: (ms: number) => Promise<void>;
+        lockTimeoutMs?: number;
+        maxTerminalEffects?: number;
+    });
+    get filePath(): string;
+    read<TPayload = unknown>(id: string): Promise<ChatEffect<TPayload> | undefined>;
+    list(): Promise<ChatEffect[]>;
+    replayable(transport: "discord" | "slack", endpointGeneration: number): Promise<ChatEffect[]>;
+    enqueue<TPayload>(input: EnqueueChatEffect<TPayload>): Promise<ChatEffect<TPayload>>;
+    /**
+     * Inserts an effect directly into a live lease. Recovery can never observe a
+     * newly persisted effect as claimable before its owner has authority to act.
+     * Existing effects are left untouched and report no acquired lease.
+     */
+    enqueueAndClaim<TPayload>(input: EnqueueChatEffect<TPayload>, owner: string, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
+    claim<TPayload = unknown>(id: string, owner: string, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
+    renew<TPayload = unknown>(id: string, lease: ChatEffectLease, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
+    /** Persists provider progress without releasing the owner/epoch fence. */
+    recordReceipt<TPayload = unknown>(id: string, lease: ChatEffectLease, receipt: ChatEffectReceipt): Promise<ChatEffect<TPayload> | undefined>;
+    record<TPayload = unknown>(id: string, lease: ChatEffectLease, state: Exclude<ChatEffectState, "pending" | "leased">, receipt?: ChatEffectReceipt): Promise<ChatEffect<TPayload> | undefined>;
+    /** Irreversibly rejects an effect whose mapping never accepted its authority. */
+    terminalize(id: string, receipt: ChatEffectReceipt, lease?: ChatEffectLease): Promise<ChatEffect | undefined>;
+}

package/dist/types/sdk/bus/config-commands.d.ts

@@ -0,0 +1,77 @@
+/**
+ * In-thread configuration slash commands for the threaded session surface.
+ *
+ * Replies are thread-native now (the old `/answer <sessionId> …` command is
+ * removed), but the user can still adjust per-surface behaviour from inside a
+ * session thread with small slash commands:
+ *
+ * - `/verbose`            switch the mirror to bounded tool-owned summaries + provider-displayable reasoning summaries
+ * - `/lean`               switch back to lean (assistant text + tool names)
+ * - `/verbosity lean|verbose`
+ * - `/redact on|off`      toggle redaction of streamed content
+ *
+ * This parser is pure so the command grammar is unit-testable; the daemon maps
+ * the returned change onto a `config_command` frame / settings update.
+ */
+/** A parsed in-thread configuration change. */
+export interface ConfigCommandChange {
+    verbosity?: "lean" | "verbose";
+    redact?: boolean;
+}
+export type TelegramControlCommandName = "reasoning" | "usage" | "context" | "compact" | "model";
+export type TelegramControlCommand = {
+    name: "reasoning";
+    action: "cycle" | "status" | "set" | "show" | "hide";
+    level?: string;
+    global?: boolean;
+} | {
+    name: "usage";
+} | {
+    name: "context";
+} | {
+    name: "compact";
+    instructions?: string;
+} | {
+    name: "model";
+    action: "list" | "set";
+    selector?: string;
+};
+export type TelegramControlCommandParseResult = {
+    kind: "none";
+} | {
+    kind: "ignored";
+    commandName: TelegramControlCommandName;
+} | {
+    kind: "command";
+    command: TelegramControlCommand;
+} | {
+    kind: "invalid";
+    commandName: TelegramControlCommandName;
+    usage: string;
+};
+export declare function telegramControlCommandUsage(commandName: TelegramControlCommandName): string;
+/** Parse deterministic Telegram session-control commands. Recognised roots fail closed. */
+export declare function parseTelegramControlCommand(text: string, botUsername?: string): TelegramControlCommandParseResult;
+/**
+ * Parse an in-thread config command. Returns the requested change, or
+ * `undefined` when the text is not a recognised config command (so the daemon
+ * can fall through to treating it as a free-text injection).
+ */
+export declare function parseInThreadConfigCommand(text: string): ConfigCommandChange | undefined;
+/**
+ * Parse a `/rich on|off` toggle. Returns `true`/`false` for a recognised
+ * on/off argument, or `undefined` otherwise (not a `/rich` command, or `/rich`
+ * with a missing/invalid argument). This is intentionally SEPARATE from
+ * `parseInThreadConfigCommand`: `/verbose`/`/redact` are producer/session config
+ * forwarded over the WS, whereas rich is Telegram-daemon delivery policy handled
+ * daemon-locally, so it never becomes a `config_command` frame or a user turn.
+ */
+export declare function parseRichToggleCommand(text: string): boolean | undefined;
+/**
+ * Parse a `/toolactivity on|off` toggle for Telegram tool-activity delivery.
+ *
+ * This is daemon-local delivery policy rather than a host-session config
+ * command, so it works without a connected session and persists globally.
+ * Addressed commands are accepted only for the exact current bot username.
+ */
+export declare function parseToolActivityToggleCommand(text: string, botUsername?: string): boolean | undefined;

package/dist/types/sdk/bus/config.d.ts

@@ -0,0 +1,307 @@
+import * as z from "zod/v4";
+import { type LoadResult } from "../../config/config-file";
+/**
+ * Env marker set by SKC's own programmatic separate-process child spawn sites
+ * (team workers, harness RPC owners) and carrying the spawning session id.
+ *
+ * Presence — not the value — marks a session as SKC-spawned. It is consumed
+ * (read once, then deleted from the child's own env) at startup so it is
+ * per-spawn rather than dynastic: a grandchild is marked only if its own spawn
+ * site marks it, never by inheriting a marked ancestor's environment.
+ */
+export declare const SPAWN_PROVENANCE_ENV = "SKC_SPAWNED_BY_SESSION";
+export type TelegramActivationState = "inactive" | "blocked";
+export type TelegramActivationReason = "saved_inactive" | "identity_mismatch";
+/** Non-secret, identity-specific durable Telegram activation state. */
+export interface TelegramActivationMarker {
+    identity: string;
+    state: TelegramActivationState;
+    updatedAt: string;
+    reason?: TelegramActivationReason;
+}
+export type TelegramActivationMarkers = Record<string, TelegramActivationMarker>;
+/** Validate and clone activation markers crossing the settings boundary. */
+export declare function readTelegramActivationMarkers(value?: unknown): TelegramActivationMarkers;
+export interface NotificationSettingsSnapshot {
+    enabled: boolean;
+    telegram: {
+        botToken?: string;
+        chatId?: string;
+        activation?: Record<string, unknown>;
+        btw: {
+            enabled: boolean;
+        };
+        rich: {
+            enabled: boolean;
+        };
+        richDraft: {
+            enabled: boolean;
+        };
+        toolActivity: {
+            enabled: boolean;
+        };
+        streaming: {
+            enabled: boolean;
+        };
+        topics: {
+            nameTemplate?: string;
+        };
+    };
+    discord: {
+        botToken?: string;
+        applicationId?: string;
+        guildId?: string;
+        parentChannelId?: string;
+    };
+    slack: {
+        botToken?: string;
+        appToken?: string;
+        workspaceId?: string;
+        channelId?: string;
+        authorizedUserId?: string;
+    };
+    redact: boolean;
+    verbosity: "lean" | "verbose";
+    sessionScope: "all" | "primary";
+    idleTimeoutMs: number;
+}
+/**
+ * Narrow settings boundary for remote notification identity and behavior.
+ * Implementations must return only user-global values, with schema defaults
+ * applied; project settings and runtime overrides are intentionally excluded.
+ */
+export interface NotificationSettingsReader {
+    getNotificationSettingsSnapshot(): NotificationSettingsSnapshot;
+    getAgentDir(): string;
+}
+/**
+ * Validate and snapshot the raw global notification configuration used by both
+ * the interactive host and the lightweight daemon process.
+ */
+export declare function parseNotificationSettingsSnapshot(rawConfig?: unknown): NotificationSettingsSnapshot;
+export interface NotificationConfig {
+    enabled: boolean;
+    botToken?: string;
+    activation?: TelegramActivationMarkers;
+    chatId?: string;
+    discord: {
+        botToken?: string;
+        applicationId?: string;
+        guildId?: string;
+        parentChannelId?: string;
+    };
+    slack: {
+        botToken?: string;
+        appToken?: string;
+        workspaceId?: string;
+        channelId?: string;
+        authorizedUserId?: string;
+    };
+    redact: boolean;
+    verbosity: "lean" | "verbose";
+    /**
+     * Which sessions may register a notification endpoint. `all` (default)
+     * preserves historical behavior; `primary` suppresses SKC-spawned children
+     * (those carrying {@link SPAWN_PROVENANCE_ENV}) unless they explicitly opt in.
+     */
+    sessionScope: "all" | "primary";
+    idleTimeoutMs: number;
+    btw: {
+        enabled: boolean;
+    };
+    rich: {
+        enabled: boolean;
+    };
+    richDraft: {
+        enabled: boolean;
+    };
+    toolActivity: {
+        enabled: boolean;
+    };
+    streaming: {
+        enabled: boolean;
+    };
+    topics: {
+        /**
+         * Optional Telegram forum-topic name template with `{repo}`, `{branch}`,
+         * and `{title}` placeholders. Unset preserves the built-in
+         * `{repo}/{branch} - {title}` composition (with its title/repo/branch
+         * fallbacks).
+         */
+        nameTemplate?: string;
+    };
+}
+/** Read typed global-only notification config from a narrow settings reader. */
+export declare function getNotificationConfig(settings: NotificationSettingsReader): NotificationConfig;
+declare const notificationConfigSchema: z.ZodObject<{
+    notifications: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        discord: z.ZodOptional<z.ZodObject<{
+            botToken: z.ZodOptional<z.ZodString>;
+            applicationId: z.ZodOptional<z.ZodString>;
+            guildId: z.ZodOptional<z.ZodString>;
+            parentChannelId: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        slack: z.ZodOptional<z.ZodObject<{
+            botToken: z.ZodOptional<z.ZodString>;
+            appToken: z.ZodOptional<z.ZodString>;
+            workspaceId: z.ZodOptional<z.ZodString>;
+            channelId: z.ZodOptional<z.ZodString>;
+            authorizedUserId: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        redact: z.ZodOptional<z.ZodBoolean>;
+        verbosity: z.ZodOptional<z.ZodEnum<{
+            lean: "lean";
+            verbose: "verbose";
+        }>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type NotificationConfigFile = z.infer<typeof notificationConfigSchema>;
+/** Read daemon settings through the canonical validated config-file boundary. */
+export declare function loadNotificationConfigFile(agentDir: string): LoadResult<NotificationConfigFile>;
+export declare function notificationConfigFromFile(value: NotificationConfigFile): Pick<NotificationConfig, "enabled" | "discord" | "slack" | "redact" | "verbosity">;
+export declare function hasNonBlankValue(value: string | undefined): boolean;
+/**
+ * Resolve live assistant streaming independently of generic notification
+ * lifecycle enablement. Explicit environment values override the durable
+ * Telegram preference; otherwise streaming is available only to an active
+ * configured Telegram identity.
+ */
+export declare function isNotificationStreamingEnabled(input: {
+    cfg: NotificationConfig;
+    env: NodeJS.ProcessEnv;
+}): boolean;
+/** Is Telegram configured with usable non-blank boundary credentials? */
+export declare function isTelegramConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+    botToken: string;
+    chatId: string;
+};
+/** Is Discord configured with all credentials and routing identifiers required by its daemon. */
+export declare function isDiscordConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+    discord: {
+        botToken: string;
+        applicationId: string;
+        guildId: string;
+        parentChannelId: string;
+    };
+};
+/** Is Slack configured with both SDK tokens and its workspace/channel routing identifiers. */
+export declare function isSlackConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+    slack: {
+        botToken: string;
+        appToken: string;
+        workspaceId: string;
+        channelId: string;
+    };
+};
+/** Is global config sufficient for auto-on (enabled + at least one configured adapter)? */
+export declare function isGloballyConfigured(cfg: NotificationConfig): boolean;
+/**
+ * Per-run opt-out for completion notifications, honored before settings lookups.
+ *
+ * `SKC_NOTIFY=off` (also `0` / `false`, case-insensitive) suppresses the
+ * completion notification surface for this process only. `config.yml` is
+ * untouched and child processes inherit the env var, which lets non-interactive
+ * fleet runs (`skc -p --no-session`) stay silent even when a user-level/global
+ * completion notification configuration is enabled.
+ */
+export declare function completionNotifyDisabledByEnv(env: NodeJS.ProcessEnv): boolean;
+/** Canonical host eligibility for the dormant notification session surface. */
+export interface NotificationHostEligibilityInput {
+    env: NodeJS.ProcessEnv;
+    /** False for host modes that cannot own a notification session endpoint. */
+    hostModeSupported?: boolean;
+    /** Task recursion depth; helper/subagent sessions must not own remote surfaces. */
+    taskDepth?: number;
+    /** Parent subagent id/prefix; present for helper/subagent sessions even when depth is omitted. */
+    parentTaskPrefix?: string;
+    /** Role-agent type/name; present for task sessions even if depth metadata is lost. */
+    currentAgentType?: string;
+    /** Canonical global session scope; absent preserves the default `all` behavior. */
+    sessionScope?: NotificationConfig["sessionScope"];
+    /** Whether this process was spawned by one of SKC's marked child spawn sites. */
+    spawnedBySkc?: boolean;
+}
+/**
+ * Resolve whether this host may receive the dormant notification controller.
+ * This intentionally says nothing about whether an adapter is configured: an
+ * eligible unconfigured host still gets a zero-side-effect control surface.
+ */
+export declare function isNotificationHostEligible(input: NotificationHostEligibilityInput): boolean;
+/**
+ * Legacy compatibility helper for callers that require both host eligibility
+ * and a currently configured or explicit notification runtime.
+ */
+export declare function shouldRegisterNotificationsExtension(input: {
+    env: NodeJS.ProcessEnv;
+    cfg?: NotificationConfig;
+    /** Task recursion depth; helper/subagent sessions must not spawn remote surfaces. */
+    taskDepth?: number;
+    /** Parent subagent id/prefix; present for helper/subagent sessions even when depth is omitted. */
+    parentTaskPrefix?: string;
+    /** Role-agent type/name; present for task sessions even if depth metadata is lost. */
+    currentAgentType?: string;
+    /**
+     * True when this session was launched by one of SKC's own programmatic
+     * separate-process child spawn sites (marked via {@link SPAWN_PROVENANCE_ENV}).
+     * Under `notifications.sessionScope = "primary"` such children are suppressed
+     * unless they explicitly opt in, so an interactive parent that fans out work
+     * does not flood the paired chat with topics for children the user never
+     * asked for. User-opened sessions (CLI/tmux/headless) never carry the marker.
+     */
+    spawnedBySkc?: boolean;
+}): boolean;
+/**
+ * Resolve whether THIS session should run notifications.
+ * Precedence (highest first):
+ *  1) env.SKC_NOTIFICATIONS === "0"  -> false (hard opt-out)
+ *  2) sessionDisabled === true       -> false (local /notify off)
+ *  3) env.SKC_NOTIFICATIONS === "1" || env.SKC_NOTIFICATIONS_TOKEN present -> true (legacy explicit)
+ *  4) spawned SKC child with `sessionScope=primary` -> false
+ *  5) isGloballyConfigured(cfg)      -> true (global auto-on)
+ *  6) otherwise false
+ */
+export declare function isSessionNotificationsEnabled(input: {
+    cfg: NotificationConfig;
+    env: NodeJS.ProcessEnv;
+    sessionDisabled: boolean;
+    /** This process was programmatically spawned by SKC (consumed at SDK startup). */
+    spawnedBySkc?: boolean;
+}): boolean;
+/** Mask a bot token for display: first 4 chars + "…" + "(len N)"; "(unset)" when undefined/empty. Never reveal full token. */
+export declare function maskToken(token: string | undefined): string;
+/** Stable non-reversible fingerprint of a token: sha256 hex, first 12 chars. */
+export declare function tokenFingerprint(token: string): string;
+/** Deterministic non-secret key for one Telegram token/chat identity. */
+export declare function telegramActivationIdentity(botToken: string, chatId: string): string;
+/** Return the durable marker for the currently configured Telegram identity, if any. */
+export declare function getCurrentTelegramActivationMarker(cfg: NotificationConfig): TelegramActivationMarker | undefined;
+/** Short session tag for display, e.g. last 6 chars of sessionId. */
+export declare function sessionTag(sessionId: string): string;
+export interface RedactableAction {
+    id: string;
+    kind: string;
+    sessionId: string;
+    /** Durable workflow-gate correlation metadata; never generic reply authority. */
+    workflowGateId?: string;
+    question?: string;
+    options?: string[];
+    summary?: string;
+}
+/**
+ * When redact is true, strip sensitive content for remote delivery:
+ *  - ask: NOT redacted. An ask is an interactive prompt the human must read and
+ *    answer on the remote surface; redacting its question/options would make it
+ *    unanswerable, defeating remote answering. Asks are returned unchanged.
+ *  - idle: summary removed, (no question/options).
+ * When redact is false, return the action unchanged.
+ *
+ * Redaction still applies to streamed content frames (turn_stream, context_update,
+ * image_attachment) which are suppressed at their emit sites, not here. Explicit
+ * `telegram_send` file attachments are rejected before the file is read or forwarded.
+ */
+export declare function buildRedactedAction(action: RedactableAction, opts: {
+    redact: boolean;
+    sessionTag: string;
+}): RedactableAction;
+export {};

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

@@ -0,0 +1,72 @@
+export declare const CONVERSATION_STORE_VERSION = 1;
+export declare const MAX_DEDUPE_IDS = 128;
+export interface ConversationRecord {
+    generation: number;
+}
+export interface ConversationStoreDocument<T extends ConversationRecord> {
+    version: typeof CONVERSATION_STORE_VERSION;
+    conversations: Record<string, T>;
+}
+export interface ConversationStoreFileHandle {
+    sync(): Promise<void>;
+    close(): Promise<void>;
+    writeFile(data: string, encoding: "utf8"): Promise<void>;
+}
+/** Minimal persistence seam; callers can inject it to make durability failures deterministic. */
+export interface ConversationStoreFs {
+    mkdir(directory: string, options: {
+        recursive: true;
+        mode: number;
+    }): Promise<unknown>;
+    chmod(target: string, mode: number): Promise<void>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    writeFile(file: string, data: string, options: {
+        mode: number;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(file: string): Promise<void>;
+    open(file: string, flags: string): Promise<ConversationStoreFileHandle>;
+    stat?(file: string): Promise<{
+        mtimeMs: number;
+    }>;
+}
+export declare class ConversationLockTimeoutError extends Error {
+    readonly lockFile: string;
+    readonly timeoutMs: number;
+    constructor(lockFile: string, timeoutMs: number);
+}
+export declare function conversationStorePath(agentDir: string, kind: string, fileName?: string): string;
+export declare function boundedDedupe(ids: readonly string[], limit?: number): string[];
+/**
+ * Durable, per-transport mapping store. Every mutation takes an exclusive
+ * lock file shared across processes and reloads the on-disk document before
+ * applying its monotonic-generation compare-and-swap, preventing either stale
+ * writers or unrelated-key updates from replacing newer mappings.
+ */
+export declare class ConversationStore<T extends ConversationRecord> {
+    #private;
+    constructor(input: {
+        agentDir: string;
+        kind: string;
+        fileName?: string;
+        fs?: ConversationStoreFs;
+        now?: () => number;
+        pid?: number;
+        pidIncarnation?: (pid: number) => string | undefined;
+        pidAlive?: (pid: number) => boolean;
+        sleep?: (ms: number) => Promise<void>;
+        lockTimeoutMs?: number;
+    });
+    get filePath(): string;
+    load(): Promise<ConversationStoreDocument<T>>;
+    read(key: string): Promise<T | undefined>;
+    /**
+     * Atomically write one mapping when its observed generation still matches.
+     * `undefined` only creates an absent mapping; successful writes must advance
+     * the generation by exactly one.
+     */
+    write(key: string, expectedGeneration: number | undefined, record: T): Promise<boolean>;
+    delete(key: string, expectedGeneration: number): Promise<boolean>;
+    /** Apply a synchronous update under the mapping lock, retrying no stale state. */
+    transact(key: string, update: (current: T | undefined) => T | undefined): Promise<T | undefined>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Owner heartbeat freshness window. A daemon ownership record older than this
+ * (without a live pid) is considered stale. Lives here, in the lightweight
+ * paths module, so secret-safe consumers (e.g. the notification service) can
+ * reuse it without importing the heavy daemon runtime.
+ */
+export declare const HEARTBEAT_TTL_MS = 20000;
+export interface DaemonPaths {
+    dir: string;
+    lock: string;
+    state: string;
+    ownership: string;
+    roots: string;
+    steal: string;
+    aliases: string;
+    seenUpdates: string;
+}
+export declare function daemonPaths(agentDir: string): DaemonPaths;

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

@@ -0,0 +1,58 @@
+import { type ConversationRecord } from "./conversation-store";
+/** Identifier-only reference to an inbound effect whose payload and lifecycle live in ChatEffectJournal. */
+export interface DiscordInboundDispatchReceipt {
+    key: string;
+    eventId: string;
+    interactionId?: string;
+    kind: "action" | "command";
+    actionId?: string;
+    actionNonce?: string;
+    endpointGeneration: number;
+    effectId: string;
+    idempotencyKey: string;
+}
+export type DiscordConversationState = "absent" | "creating" | "active" | "archived" | "resuming" | "closed" | "error";
+/** Durable Discord mapping. It deliberately contains identifiers only: never endpoint tokens or message bodies. */
+export interface DiscordConversation extends ConversationRecord {
+    state: DiscordConversationState;
+    appId: string;
+    guildId: string;
+    parentChannelId: string;
+    threadId?: string;
+    sessionId?: string;
+    createNonce?: string;
+    /** A lease makes thread creation exclusive across daemon processes. */
+    createOwner?: string;
+    createLeaseExpiresAt?: number;
+    endpointGeneration?: number;
+    /** Immutable lineage for archive and resume provider effects. */
+    effectIncarnationId?: string;
+    /** Current archive operation authority. */
+    archiveOccurrenceId?: string;
+    archiveEffectId?: string;
+    /** Current resume operation authority. */
+    resumeOccurrenceId?: string;
+    resumeEffectId?: string;
+    /** Action authority only; action bodies and endpoint credentials are never persisted. */
+    pendingActionId?: string;
+    /** Immutable per-publication action authority, bound to component routes and inbound effects. */
+    pendingActionNonce?: string;
+    /** Durable journal identity for the immutable outbound action publication intent. */
+    pendingActionEffectId?: string;
+    /** Replayable durable receipts for acknowledged inbound effects. */
+    inboundDispatches?: DiscordInboundDispatchReceipt[];
+    updatedAt: number;
+    archivedAt?: number;
+    closedAt?: number;
+    supersededByThreadId?: string;
+    seenEventIds: string[];
+    seenInteractionIds: string[];
+}
+export declare function discordConversationKey(input: {
+    appId: string;
+    guildId: string;
+    parentChannelId: string;
+    threadId: string;
+}): string;
+export declare function normalizeDiscordConversation(record: DiscordConversation): DiscordConversation;
+export declare function acceptsDiscordInbound(record: DiscordConversation, threadId: string, endpointGeneration: number): boolean;

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

@@ -0,0 +1,50 @@
+import { type DiscordConversation } from "./discord-conversation";
+import type { DiscordInboundEvent, DiscordProvider } from "./discord-provider";
+export declare class DiscordEndpointBindingError extends Error {
+    constructor(message?: string);
+}
+/** A captured live SDK transport. `isCurrent` must fail closed after replacement or removal. */
+export interface DiscordEndpointBinding {
+    generation: number;
+    isCurrent(): boolean;
+    send(frame: Record<string, unknown>): void | Promise<void>;
+}
+export interface DiscordLeaseRecoveryScheduler {
+    setTimeout(callback: () => void | Promise<void>, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface DiscordNotificationDaemonOptions {
+    agentDir: string;
+    repo: string;
+    guildId: string;
+    parentChannelId: string;
+    provider: DiscordProvider;
+    now?: () => number;
+    leaseRecoveryScheduler?: DiscordLeaseRecoveryScheduler;
+    resolveEndpoint: (sessionId: string, expectedGeneration?: number) => Promise<DiscordEndpointBinding | null>;
+    onCommand?: (sessionId: string, content: string, endpoint: DiscordEndpointBinding, idempotencyKey: string) => Promise<boolean>;
+}
+export interface DiscordNotificationInput {
+    sessionId: string;
+    endpointGeneration: number;
+    content: string;
+    threadName?: string;
+    actionId?: string;
+    options?: string[];
+}
+/** SDK-only Discord threaded notification daemon. It owns no AgentSession and never retains endpoint credentials. */
+export declare class DiscordNotificationDaemon {
+    #private;
+    private readonly options;
+    constructor(options: DiscordNotificationDaemonOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    notify(input: DiscordNotificationInput): Promise<DiscordConversation>;
+    /** Posts a safe command outcome to the active mapped conversation. */
+    postCommandResult(sessionId: string, content: string): Promise<boolean>;
+    close(sessionId: string): Promise<void>;
+    archive(sessionId: string): Promise<void>;
+    resume(sessionId: string, endpointGeneration: number): Promise<DiscordConversation | undefined>;
+    resolveAction(sessionId: string, actionId: string): Promise<void>;
+    handleInbound(event: DiscordInboundEvent): Promise<void>;
+}