@sayknow-cli/coding-agent 0.4.2 → 0.4.4

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

@@ -0,0 +1,136 @@
+/**
+ * Telegram **reference** client for the Sayknow-CLI SDK.
+ *
+ * This is an example/template, NOT an upstream-owned integration: it implements
+ * the documented WS protocol (see `docs/sdk.md`) so you can copy it
+ * to build Discord/Slack/etc. clients with zero upstream changes. The Bot API
+ * transport shape is salvaged from the removed `telegram-remote` package.
+ *
+ * Flow: read the endpoint discovery file -> connect to the session WS -> render
+ * `action_needed` to a Telegram chat (inline keyboard for options) -> map button
+ * taps / text replies to `reply` frames -> reflect `action_resolved` /
+ * `reply_rejected`.
+ *
+ * Dependency-free: uses global `fetch` and `WebSocket` (Bun/Node 22+).
+ */
+/** One inline-keyboard button. */
+export interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+/** Typed action controls are protocol data, never inferred from option labels. */
+export interface TelegramActionControl {
+    id: "navigation_forward";
+    kind: "navigation";
+    label: "Next" | "Done";
+    enabled: boolean;
+}
+export type TelegramCallbackAnswer = number | string | {
+    controlId: TelegramActionControl["id"];
+};
+/** A rendered Telegram message for an `action_needed`. */
+export interface RenderedMessage {
+    text: string;
+    inline_keyboard?: InlineButton[][];
+}
+type TelegramSend = (method: string, body: unknown) => Promise<Response>;
+/** Encode `actionId` + option `index` into Telegram callback_data (<=64 bytes). */
+export declare function encodeCallbackData(actionId: string, index: number): string;
+/** Decode callback_data produced by {@link encodeCallbackData}. */
+export declare function decodeCallbackData(data: string): {
+    id: string;
+    index: number;
+} | null;
+/** Encode a typed control independently from option labels. */
+export declare function encodeControlCallbackData(actionId: string, controlId: TelegramActionControl["id"]): string;
+export declare function decodeControlCallbackData(data: string): {
+    id: string;
+    controlId: TelegramActionControl["id"];
+} | null;
+export interface CallbackRoute {
+    sessionId: string;
+    actionId: string;
+    answer: TelegramCallbackAnswer;
+}
+export interface SerializedAliasTable {
+    version: 1;
+    next: number;
+    routes: Record<string, CallbackRoute>;
+}
+export interface AliasTable {
+    put(route: CallbackRoute): string;
+    get(alias: string): CallbackRoute | undefined;
+    delete(alias: string): boolean;
+    serialize(): SerializedAliasTable;
+    load(json: unknown): void;
+    entries(): Array<[string, CallbackRoute]>;
+}
+/** Create a compact, durable callback alias table. Serialized data contains routing ids only. */
+export declare function createAliasTable(): AliasTable;
+/** Render an `action_needed` payload into a Telegram message. */
+export declare function buildActionMessage(action: {
+    kind: "ask" | "idle";
+    id: string;
+    question?: string;
+    options?: string[];
+    controls?: readonly TelegramActionControl[];
+    summary?: string;
+}): RenderedMessage;
+/** Render an `action_needed` body as raw markdown (rich-message source; the HTML fallback stays on buildActionMessage). */
+export declare function buildActionMarkdown(action: {
+    kind: "ask" | "idle";
+    question?: string;
+    options?: string[];
+    summary?: string;
+}): string;
+/** Send Telegram HTML text chunks sequentially so long messages preserve order. */
+export declare function sendTelegramHtmlChunks(send: TelegramSend, chatId: string, text: string, inlineKeyboard?: InlineButton[][]): Promise<void>;
+/** A protocol `reply` frame the client should send to the server. */
+export interface ReplyFrame {
+    type: "reply";
+    id: string;
+    answer: TelegramCallbackAnswer;
+    token: string;
+}
+/**
+ * Map a Telegram update into a reply frame, given the most recent pending ask id
+ * (for free-text replies). Returns `null` when the update is not actionable.
+ */
+export declare function telegramUpdateToReply(update: unknown, token: string, latestPendingAskId: string | undefined): ReplyFrame | null;
+export type RouteDecision = ({
+    kind: "reply";
+} & CallbackRoute) | {
+    kind: "stale";
+    reason: string;
+} | {
+    kind: "ignore";
+};
+export interface RouteInboundContext {
+    aliasTable: Pick<AliasTable, "get">;
+    messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+    pairedChatId: string;
+}
+/** Route a Telegram update to a session/action without I/O. Fail closed under ambiguity. */
+export declare function routeInboundUpdate(update: unknown, ctx: RouteInboundContext): RouteDecision;
+/** Read `{url, token, pid?, stale?}` from an endpoint discovery file. */
+export declare function readEndpoint(path: string): {
+    url: string;
+    token: string;
+    pid?: number;
+    stale?: boolean;
+};
+/** Options for {@link runTelegramReferenceClient}. */
+export interface TelegramReferenceOptions {
+    botToken: string;
+    chatId: string;
+    endpointFile: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Run the reference bridge until the WebSocket closes. Sends `action_needed` to
+ * the chat and forwards taps/text as replies. This is a minimal example loop;
+ * production clients add reconnection, multi-chat routing, and persistence.
+ */
+export declare function runTelegramReferenceClient(opts: TelegramReferenceOptions): Promise<void>;
+export {};

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

@@ -0,0 +1,128 @@
+export declare const DEFAULT_TELEGRAM_SETUP_API_BASE = "https://api.telegram.org";
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_TIMEOUT_MS = 60000;
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_INTERVAL_MS = 1000;
+export type TelegramThreadedModeState = "enabled" | "disabled" | "unknown";
+export type TelegramThreadedModeLabel = "verified" | "unverified" | "unknown";
+export type TelegramSetupPairingSource = "discovered" | "provided" | "reused";
+export type TelegramSetupFailureStatus = "error" | "cancelled" | "requires_explicit_chat" | "ownership_lost" | "aborted";
+export interface TelegramSetupTimers {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export interface TelegramSetupDeps {
+    fetchImpl: typeof fetch;
+    apiBase?: string;
+    timers?: TelegramSetupTimers;
+}
+/** Current daemon ownership facts collected by the caller before setup starts. */
+export interface TelegramSetupPreflight {
+    storedChatId?: string;
+    daemon?: {
+        live: boolean;
+        tokenFingerprint?: string;
+        /** Required with a live daemon so reuse verifies the complete token/chat identity. */
+        chatId?: string;
+    };
+}
+export type TelegramSetupPollingPolicy = {
+    kind: "discover";
+} | {
+    kind: "reuse_stored_chat";
+    chatId: string;
+} | {
+    kind: "validate_explicit_chat";
+    chatId: string;
+} | {
+    kind: "requires_explicit_chat";
+} | {
+    kind: "cancel_foreign_or_unknown_owner";
+    identity: "foreign" | "unknown";
+};
+export type TelegramSetupEvent = {
+    kind: "token_validated";
+    message: string;
+} | {
+    kind: "threaded_mode_guidance";
+    message: string;
+} | {
+    kind: "rejected_chat";
+    message: string;
+};
+export interface TelegramSetupSuccess {
+    ok: true;
+    chatId: string;
+    tokenFingerprint: string;
+    threadedMode: TelegramThreadedModeState;
+    threadedLabel: TelegramThreadedModeLabel;
+    pairingSource: TelegramSetupPairingSource;
+}
+export interface TelegramSetupFailure {
+    ok: false;
+    status: TelegramSetupFailureStatus;
+    detail: string;
+}
+export type TelegramSetupResult = TelegramSetupSuccess | TelegramSetupFailure;
+export interface TelegramBot {
+    id: number;
+    isBot?: boolean;
+    firstName?: string;
+    username?: string;
+    hasTopicsEnabled?: boolean;
+    allowsUsersToCreateTopics?: boolean;
+}
+export type TelegramTokenValidationResult = {
+    ok: true;
+    bot: TelegramBot;
+    threadedMode: TelegramThreadedModeState;
+} | TelegramSetupFailure;
+export type TelegramPrivateChatValidationResult = {
+    ok: true;
+    chatId: string;
+} | TelegramSetupFailure;
+export interface RunTelegramSetupInput {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    /**
+     * Re-reads daemon ownership immediately before any `getUpdates` call. It is
+     * mandatory for discovery because an earlier preflight cannot own Telegram's
+     * single-poller slot.
+     */
+    revalidatePreflight?: (signal?: AbortSignal) => Promise<TelegramSetupPreflight>;
+    chatId?: string;
+    interactive: boolean;
+    threadedModePrompt?: (message: string) => Promise<string>;
+    pollTimeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onEvent?: (event: TelegramSetupEvent) => void;
+    deps: TelegramSetupDeps;
+}
+export declare function withTelegramSetupLease<T>(token: string, operation: () => Promise<T>): Promise<T>;
+/** Validate a token with getMe without exposing it in diagnostics or results. */
+export declare function validateTelegramBotToken(input: {
+    token: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramTokenValidationResult>;
+/** Validate that a supplied or stored chat is an actual Telegram private chat. */
+export declare function validateTelegramPrivateChat(input: {
+    token: string;
+    chatId: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramPrivateChatValidationResult>;
+/**
+ * Decide whether setup may call getUpdates. Any live daemon is a hard polling
+ * boundary: only a verified complete token/chat identity may reuse the stored
+ * chat; setup never polls while any live owner exists.
+ */
+export declare function resolveTelegramSetupPollingPolicy(input: {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    chatId?: string;
+}): TelegramSetupPollingPolicy;
+/**
+ * Validate a token, assess Threaded Mode, and obtain a private chat according
+ * to the daemon poller-contention policy. No settings are written here.
+ */
+export declare function runTelegramSetup(input: RunTelegramSetupInput): Promise<TelegramSetupResult>;

package/dist/types/sdk/bus/threaded-inbound.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Fail-closed routing for inbound Telegram updates in threaded session mode.
+ *
+ * In the threaded surface, a free-text reply inside a session's forum topic
+ * injects a new user turn into that session (steering it at any time). That is
+ * remote control of the agent, so every inbound path must fail closed:
+ *
+ * - the update must come from the single paired chat id;
+ * - it must carry a `message_thread_id` (topic) that maps to a KNOWN session;
+ * - its `update_id` must not have been seen before (idempotency / replay guard);
+ * - the text must be non-empty.
+ *
+ * Anything ambiguous or unmapped is ignored with a reason rather than guessed.
+ * This module is pure (the dedupe set and topic map are injected) so the
+ * security rules are exhaustively unit-testable without a live Bot API.
+ */
+/** Minimal shape of the inbound Telegram message we route on. */
+export interface InboundUpdate {
+    update_id?: unknown;
+    message?: {
+        message_id?: unknown;
+        text?: unknown;
+        caption?: unknown;
+        photo?: unknown;
+        document?: unknown;
+        video?: unknown;
+        audio?: unknown;
+        voice?: unknown;
+        animation?: unknown;
+        chat?: {
+            id?: unknown;
+        };
+        message_thread_id?: unknown;
+    };
+}
+/** A downloadable media attachment referenced by an inbound message. */
+export interface InboundAttachment {
+    /** Telegram file_id to resolve via getFile. */
+    fileId: string;
+    /** Source media kind; "photo" is always an image. */
+    kind: "photo" | "document" | "video" | "audio" | "voice" | "animation";
+    /** MIME type when Telegram provides one. */
+    mime?: string;
+    /** Original file name when provided. */
+    fileName?: string;
+}
+/** Context for {@link decideThreadedInbound}. All lookups are injected. */
+export interface ThreadedInboundCtx {
+    /** The single paired chat id (string-compared). */
+    pairedChatId: string;
+    /** Resolve a topic/thread id to its owning session id, or undefined. */
+    topicToSession: (threadId: string) => string | undefined;
+    /** Whether this `update_id` has already been processed. */
+    isDuplicate: (updateId: number) => boolean;
+}
+/** Outcome of routing an inbound update. */
+export type ThreadedInboundDecision = {
+    kind: "inject";
+    sessionId: string;
+    text: string;
+    updateId: number;
+    threadId: string;
+    messageId: number;
+    attachment?: InboundAttachment;
+} | {
+    kind: "duplicate";
+    updateId: number;
+} | {
+    kind: "ignore";
+    reason: string;
+};
+/**
+ * Decide whether an inbound update should inject a user turn. Fail-closed:
+ * returns `ignore` (with a reason) or `duplicate` for anything that is not an
+ * unambiguous, first-seen, paired-chat, known-topic text message.
+ */
+export declare function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboundCtx): ThreadedInboundDecision;

package/dist/types/sdk/bus/threaded-render.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure rendering of threaded-session frames into Telegram send specs.
+ *
+ * The daemon receives the additive `ServerMessage` frames (identity_header,
+ * context_update, turn_stream, image_attachment, config_update) over the session
+ * WS and must turn each into a Bot API call scoped to the session's forum topic
+ * (`message_thread_id`), throttled through the shared rate-limit pool. This
+ * module is the pure frame→send mapping (including the priority lane and live-
+ * edit coalesce key), so rendering is unit-testable without a live Bot API.
+ */
+import type { RateLimitLane } from "./rate-limit-pool";
+/** A Telegram send derived from a threaded frame (topic id is applied by the daemon). */
+export interface ThreadedSend {
+    method: "sendMessage" | "sendPhoto" | "sendDocument";
+    /** Rate-limit lane for prioritisation/fairness. */
+    lane: RateLimitLane;
+    /** Message text (sendMessage) or photo caption (sendPhoto). */
+    text?: string;
+    /** Base64 image bytes for sendPhoto. */
+    photoBase64?: string;
+    /** Base64 file bytes for sendDocument. */
+    documentBase64?: string;
+    /** Image MIME type for sendPhoto. */
+    mime?: string;
+    /** Suggested document filename. */
+    fileName?: string;
+    /** Coalesce key for live edits (same key collapses to the latest). */
+    coalesceKey?: string;
+    /** True for the one-time identity header (the daemon pins it once). */
+    identity?: boolean;
+    /**
+     * When true the daemon may deliver this as an in-place edit of the message
+     * previously sent under the same `(sessionId, coalesceKey)` instead of a new
+     * message. Set for streamed turn frames so live + finalized share one message.
+     */
+    editable?: boolean;
+    /** Rich message class metadata. Only finalized final-answer sends are ever
+     * rich-promoted; the daemon gate (`shouldPromoteRich`) requires exactly this. */
+    richClass?: "final";
+    /** Rich final-answer markdown (raw). Delivery marker derived ONLY from a frame's `finalAnswer` bit; never inferred from `phase`. */
+    richMarkdown?: string;
+    /** Live-turn raw markdown for opt-in draft streaming (set ONLY on non-finalized turn frames; never triggers rich-final promotion, which requires `lane === "finalized"`). */
+    richDraftMarkdown?: string;
+    /**
+     * True for a terminal tool_activity frame (phase completed/failed/cancelled/
+     * unknown). The daemon evicts the tool's `tool:<toolCallId>` live-message entry
+     * after delivering it, so completed tools do not accumulate unbounded across a
+     * long session (concurrent in-flight `started` entries are retained).
+     */
+    terminal?: boolean;
+}
+interface ThreadedFrame {
+    type?: unknown;
+    sessionId?: unknown;
+    repo?: unknown;
+    branch?: unknown;
+    machine?: unknown;
+    title?: unknown;
+    lastMessage?: unknown;
+    task?: unknown;
+    goal?: unknown;
+    tokenUsage?: unknown;
+    model?: unknown;
+    diff?: unknown;
+    cwd?: unknown;
+    phase?: unknown;
+    finalAnswer?: boolean;
+    text?: unknown;
+    messageRef?: unknown;
+    turnRef?: unknown;
+    toolCallId?: unknown;
+    toolName?: unknown;
+    argsSummary?: unknown;
+    resultSummary?: unknown;
+    isError?: unknown;
+    source?: unknown;
+    data?: unknown;
+    mime?: unknown;
+    caption?: unknown;
+    name?: unknown;
+    verbosity?: unknown;
+    redact?: unknown;
+    status?: unknown;
+    message?: unknown;
+}
+/** Format the one-time identity header as pinned bullets. */
+export declare function formatIdentityHeader(frame: {
+    repo?: unknown;
+    branch?: unknown;
+    machine?: unknown;
+    sessionId?: unknown;
+    title?: unknown;
+}): string;
+/** Format a streamed context update into a compact block (omitting empty fields). */
+export declare function formatContextUpdate(frame: ThreadedFrame): string | undefined;
+/**
+ * Map a threaded frame to a Telegram send spec, or `undefined` when there is
+ * nothing to send (e.g. an empty context update or an unknown frame type).
+ */
+export declare function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefined;
+export {};

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each SKC session owns one active Telegram forum topic in the paired private
+ * DM. The topic is created via `createForumTopic`, reused while the session
+ * remains active, and removed from the registry when the daemon deletes it on
+ * shutdown. The registry also tracks whether the one-time identity header has
+ * already been pinned, so it is sent exactly once per active topic, even across
+ * reconnects.
+ *
+ * State is a plain serialisable map persisted beside the daemon state files;
+ * topic creation is injected so this module is pure and unit-testable without a
+ * live Bot API.
+ */
+/** Persisted record for one session's topic. */
+export interface TopicRecord {
+    /** Telegram forum topic id (message_thread_id). */
+    topicId: string;
+    /** Whether the one-time identity header has been sent/pinned. */
+    identitySent: boolean;
+    /** Creation timestamp (ms epoch). */
+    createdAt: number;
+    /** First positive observation that the owning endpoint is stale, dead, or missing. */
+    orphanedAt?: number;
+    /** Last applied or observed Telegram topic title. */
+    name?: string;
+    /** Naming authority. Missing values are legacy daemon-owned records. */
+    nameOwner?: "user";
+    /** Whether a user-owned name still needs a best-effort Telegram re-assert. */
+    nameReconcilePending?: boolean;
+    /** Last accepted Telegram update id for a user-owned name. */
+    userNameUpdateId?: number;
+    /** Stable repo/branch identity used when topic names are user-owned or customized. */
+    identityKey?: string;
+    /** Last SDK event generation durably consumed by the notification daemon. */
+    replayGeneration?: number;
+    /** Last SDK event sequence durably consumed within replayGeneration. */
+    replaySeq?: number;
+    /** Serialized authority epoch; a late create may commit only in its starting epoch. */
+    authorityEpoch?: number;
+    /** An uncertain delete fences future creation and inbound routing. */
+    authorityState?: "active" | "delete_pending";
+}
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+    /** sessionId -> record. */
+    topics: Record<string, TopicRecord>;
+    /** Durable deletion epochs retained after a definite delete. */
+    fences?: Record<string, number>;
+}
+export declare function emptyTopicRegistryState(): TopicRegistryState;
+/**
+ * In-memory registry over a serialisable state. Topic creation is injected via
+ * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
+ * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
+ */
+export declare class TopicRegistry {
+    #private;
+    private readonly topics;
+    /** Maps topicId -> sessionId for fast inbound routing. */
+    private readonly byTopic;
+    /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
+    private readonly inflight;
+    /** Monotonic authority epochs, including deletion fences for absent records. */
+    private readonly epochs;
+    constructor(state?: TopicRegistryState);
+    /** Merge serialized state and normalize authority fields from older releases. */
+    load(state: TopicRegistryState): void;
+    private rebuildInboundRoutes;
+    /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+    sessionForTopic(topicId: string): string | undefined;
+    /** All session ids with a persisted topic record. */
+    sessionIds(): string[];
+    /** The existing topic record for a session, if any. */
+    get(sessionId: string): TopicRecord | undefined;
+    /**
+     * Return the existing active topic for `sessionId`, or create one via
+     * `create` (called only on first use).
+     */
+    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string): Promise<TopicRecord>;
+    /** Mark the identity header as sent for a session. Idempotent. */
+    markIdentitySent(sessionId: string): void;
+    /** Whether the identity header still needs sending for this session. */
+    needsIdentity(sessionId: string): boolean;
+    /** Remember stable repo/branch identity independently of the displayed name. */
+    markIdentityKey(sessionId: string, identityKey: string): boolean;
+    /** Start the orphan grace clock on the first positive liveness-loss observation. */
+    markOrphaned(sessionId: string, now: number): boolean;
+    /** Clear a prior orphan observation after the endpoint is positively live again. */
+    clearOrphaned(sessionId: string): boolean;
+    /** Last durably consumed SDK event cursor for reconnect replay. */
+    replayCursor(sessionId: string): {
+        generation: number;
+        seq: number;
+    } | undefined;
+    /** Advance the durable reconnect cursor without allowing stale responses to move it backwards. */
+    markReplayCursor(sessionId: string, generation: number, seq: number): boolean;
+    /** Whether daemon identity reconciliation should apply `name`. */
+    needsRename(sessionId: string, name: string): boolean;
+    /** The user-owned name that must be preserved, when one exists. */
+    userOwnedName(sessionId: string): string | undefined;
+    /** A user-owned name whose Telegram reconciliation is still pending. */
+    userNameToReconcile(sessionId: string): string | undefined;
+    /** Record an explicit Telegram-side user rename, rejecting stale update ids. */
+    markUserName(sessionId: string, name: string, updateId: number): "updated" | "duplicate" | "stale";
+    /** Mark the matching preserved user name as reconciled with Telegram. */
+    markUserNameReconciled(sessionId: string, name: string): boolean;
+    /** Restore retryable reconciliation after a failed pending-clear persistence. */
+    markUserNamePending(sessionId: string, name: string): boolean;
+    /** Commit a successfully-applied daemon topic title. */
+    markNameApplied(sessionId: string, name: string): void;
+    /** Fence new work before the remote delete starts, including an absent in-flight create. */
+    beginDelete(sessionId: string): TopicRecord | undefined;
+    /** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
+    awaitInflight(sessionId: string): Promise<void>;
+    /** Remove only after a definite remote deletion; ambiguity deliberately retains its fence. */
+    settleDelete(sessionId: string, topicId: string): boolean;
+    /** Remove a topic record immediately for local/test cleanup compatibility. */
+    delete(sessionId: string): boolean;
+    /** Serialise for atomic persistence beside the daemon state. */
+    serialize(): TopicRegistryState;
+}

package/dist/types/sdk/cli/index.d.ts

@@ -0,0 +1 @@
+export * from "./session-cli";

package/dist/types/sdk/cli/session-cli.d.ts

@@ -0,0 +1,19 @@
+export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+export interface SdkSessionCliArgs {
+    action?: string;
+    sessionId?: string;
+    operation?: string;
+    query?: string;
+    jsonInput?: string;
+    jsonInputFile?: string;
+    idempotencyKey?: string;
+    jsonInputStdin?: boolean;
+    confirm?: boolean;
+    cursor?: string;
+    showEndpointCredential?: boolean;
+    yes?: boolean;
+    repo?: string;
+    agentDir?: string;
+}
+/** Runs the pure-SDK `skc daemon session` command family. */
+export declare function runSdkSessionCli(args: SdkSessionCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/client/client.d.ts

@@ -0,0 +1 @@
+export * from "@sayknow-cli/bridge-client";

package/dist/types/sdk/client/discovery.d.ts

@@ -0,0 +1,27 @@
+import { type BrokerDiscovery } from "../broker/discovery";
+export interface SdkSessionEndpoint {
+    sessionId: string;
+    url: string;
+    token: string;
+    path: string;
+}
+export interface SdkDiscoveryWarning {
+    code: "discovery_error";
+    path: string;
+    message: string;
+}
+export interface SdkSessionEndpointList {
+    endpoints: SdkSessionEndpoint[];
+    warnings: SdkDiscoveryWarning[];
+}
+export declare class SdkDiscoveryError extends Error {
+    readonly path: string;
+    readonly code = "discovery_error";
+    constructor(path: string, message: string);
+}
+/** Lists endpoint files and returns individual malformed or unreadable records as warnings. */
+export declare function listSdkSessionEndpoints(repo: string): Promise<SdkSessionEndpointList>;
+/** Resolves one per-session SDK endpoint discovery file. */
+export declare function readSdkSessionEndpoint(repo: string, sessionId: string): Promise<SdkSessionEndpoint | null>;
+/** Reads the agent-global broker discovery record. */
+export declare function readSdkBrokerDiscovery(agentDir: string): Promise<BrokerDiscovery | null>;

package/dist/types/sdk/client/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./discovery";

package/dist/types/sdk/host/control/dispatch.d.ts

@@ -0,0 +1,34 @@
+import { type Operation } from "../../protocol/operation-registry";
+import type { ControlSurface, ControlValue } from "./operations";
+export interface ControlRequest {
+    id: string;
+    operation: string;
+    input: unknown;
+    expectedRevision?: string;
+    idempotencyKey?: string;
+    confirm?: boolean;
+}
+export type ControlErrorCode = string;
+export interface ControlError {
+    code: ControlErrorCode;
+    message: string;
+    currentRevision?: string;
+    details?: ControlValue;
+}
+export interface ControlResponse {
+    id: string;
+    ok: boolean;
+    result?: ControlValue;
+    error?: ControlError;
+}
+/** An error whose code is intentionally safe to expose on the control protocol. */
+export declare class TypedControlError extends Error {
+    readonly code: ControlErrorCode;
+    constructor(code: ControlErrorCode, message: string);
+}
+/** Busy is reserved for explicitly typed transient unavailability. */
+export declare class BusyError extends TypedControlError {
+    constructor(message?: string);
+}
+/** Dispatches a registry-defined per-session control operation. */
+export declare function dispatchControl(surface: ControlSurface, registryRow: Operation | undefined, request: ControlRequest): Promise<ControlResponse>;

package/dist/types/sdk/host/control/index.d.ts

@@ -0,0 +1,2 @@
+export { BusyError, type ControlError, type ControlErrorCode, type ControlRequest, type ControlResponse, dispatchControl, TypedControlError, } from "./dispatch";
+export type { ControlInput, ControlSurface, ControlValue } from "./operations";