@jawcode-dev/coding-agent 1.1.0

package/dist/types/notifications/lifecycle-audit.d.ts

@@ -0,0 +1,60 @@
+import type { NotificationLifecycleCommandIntent } from "./lifecycle-command-parser";
+/**
+ * Result of dispatching a parsed Telegram lifecycle intent through the JWC
+ * control runtime. Telegram-driven process execution (create/resume/close) is
+ * deferred as a later C4 decision (chase 10.033), so mutating intents resolve
+ * to `execution_deferred` rather than spawning, attaching, or killing a process.
+ *
+ * No variant carries a bot token or raw message text — outcomes are safe to
+ * persist to a JSONL audit ledger.
+ */
+export type LifecycleOutcome = {
+    kind: "listed";
+    sessionCount: number;
+} | {
+    kind: "execution_deferred";
+    reason: "remote_lifecycle_execution_disabled";
+} | {
+    kind: "rejected";
+    reason: LifecycleRejectionReason;
+};
+export type LifecycleRejectionReason = "unauthorized_chat" | "unknown_session";
+/**
+ * JSONL-safe audit record for a single lifecycle dispatch. Deliberately omits
+ * the bot token and any message text; only the command kind, the chat id, the
+ * (safe-regex) session id for resume, the outcome, a bounded reason, the
+ * idempotency key, and whether the dispatch was a replay are recorded.
+ */
+export interface LifecycleAuditRecord {
+    at: number;
+    chatId: number;
+    intent: NotificationLifecycleCommandIntent["kind"];
+    sessionId?: string;
+    outcome: LifecycleOutcome["kind"];
+    reason?: string;
+    idempotencyKey: string;
+    replayed: boolean;
+}
+export interface BuildLifecycleAuditRecordInput {
+    now: number;
+    chatId: number;
+    intent: NotificationLifecycleCommandIntent;
+    idempotencyKey: string;
+    outcome: LifecycleOutcome;
+    replayed: boolean;
+}
+export declare function buildLifecycleAuditRecord(input: BuildLifecycleAuditRecordInput): LifecycleAuditRecord;
+/**
+ * Bounded in-memory idempotency ledger for lifecycle dispatches. A replayed
+ * idempotency key returns the first recorded outcome without re-dispatch, which
+ * prevents duplicate create/close/resume requests from acting twice. Eviction is
+ * insertion-order (oldest first) so the ledger cannot grow without bound.
+ */
+export declare class LifecycleIdempotencyLedger {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    get(key: string): LifecycleOutcome | undefined;
+    record(key: string, outcome: LifecycleOutcome): void;
+    get size(): number;
+}

package/dist/types/notifications/lifecycle-command-parser.d.ts

@@ -0,0 +1,19 @@
+export type NotificationLifecycleCommandIntent = {
+    kind: "list";
+} | {
+    kind: "new";
+} | {
+    kind: "close_current";
+} | {
+    kind: "resume";
+    sessionId: string;
+};
+export type NotificationLifecycleCommandRejectionReason = "empty_command" | "unknown_command" | "unexpected_arguments" | "missing_session_id" | "unsafe_session_id";
+export type ParseNotificationLifecycleCommandResult = {
+    ok: true;
+    intent: NotificationLifecycleCommandIntent;
+} | {
+    ok: false;
+    reason: NotificationLifecycleCommandRejectionReason;
+};
+export declare function parseNotificationLifecycleCommand(input: string): ParseNotificationLifecycleCommandResult;

package/dist/types/notifications/lifecycle-control-runtime.d.ts

@@ -0,0 +1,45 @@
+import { type LifecycleAuditRecord, type LifecycleIdempotencyLedger, type LifecycleOutcome } from "./lifecycle-audit";
+import type { NotificationLifecycleCommandIntent } from "./lifecycle-command-parser";
+/**
+ * Privacy-minimized, read-only summary of a session, returned for the `list`
+ * intent (chase 10.033-B). Carries no secrets, no filesystem paths, no prompt
+ * bodies — only a safe session id, a short human title, and a timestamp.
+ */
+export interface LifecycleSessionSummary {
+    sessionId: string;
+    title: string;
+    updatedAt: number;
+}
+/**
+ * Authorization + data context for a single lifecycle dispatch. The runtime is
+ * fail-closed: only the paired `ownerChatId` may drive lifecycle, and
+ * resume/close additionally require session ownership.
+ */
+export interface LifecycleControlContext {
+    /** The single paired owner chat permitted to drive lifecycle. */
+    ownerChatId: number;
+    /** Chat the command actually arrived from. */
+    chatId: number;
+    /** Caller-supplied idempotency key (e.g. Telegram update/callback id). */
+    idempotencyKey: string;
+    /** Read-only provider of privacy-minimized session summaries (for `list`). */
+    listSessions: () => readonly LifecycleSessionSummary[];
+    /** Ownership predicate for resume/close target sessions. */
+    ownsSession: (sessionId: string) => boolean;
+}
+export interface LifecycleDispatchResult {
+    outcome: LifecycleOutcome;
+    audit: LifecycleAuditRecord;
+    /** Present only for an accepted `list`; the read-only summaries to render. */
+    sessions?: readonly LifecycleSessionSummary[];
+}
+/**
+ * Authorize and dispatch a parsed lifecycle intent. Telegram-driven process
+ * execution stays deferred (chase 10.033): `new`/`resume`/`close_current` are
+ * authorized, idempotency-tracked, and audited, but resolve to
+ * `execution_deferred` and never spawn, attach to, or kill a process. `list`
+ * returns privacy-minimized read-only summaries. Every dispatch yields a
+ * token/text-free audit record; a replayed idempotency key returns the first
+ * recorded outcome without re-dispatch.
+ */
+export declare function executeLifecycleIntent(intent: NotificationLifecycleCommandIntent, ctx: LifecycleControlContext, ledger: LifecycleIdempotencyLedger, now?: () => number): LifecycleDispatchResult;

package/dist/types/notifications/notification-redaction.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Remote notification redaction (chase 10.032, gate 4 + gate 6 lead-in).
+ *
+ * Invariant: when redaction is on, the streamed assistant/tool/context text is
+ * redacted, but the ask *question and options stay verbatim* so the user can
+ * still act on the prompt remotely. The assistant lead-in (pre-ask text) obeys
+ * redaction. Pure / side-effect-free; transport-agnostic.
+ */
+export interface RedactionPolicy {
+    redact: boolean;
+}
+export declare const REDACTED_PLACEHOLDER = "[redacted]";
+/**
+ * Redact free streamed/context text. Returns the text verbatim when redaction
+ * is off; when on, returns the placeholder for non-empty text and "" for
+ * empty/whitespace (never emit a placeholder for nothing).
+ */
+export declare function redactStreamText(text: string, policy: RedactionPolicy): string;
+export interface RemoteAskView {
+    leadIn?: string;
+    question: string;
+    options: string[];
+}
+export interface BuildRemoteAskViewInput {
+    question: string;
+    options: readonly string[];
+    /** Assistant pre-ask text (gate 6); obeys redaction. */
+    leadIn?: string;
+    policy: RedactionPolicy;
+}
+/**
+ * Build the remote-facing view of an ask. The question and options are emitted
+ * verbatim regardless of redaction (gate 4); the lead-in is redacted when the
+ * policy says so and omitted entirely when empty.
+ */
+export declare function buildRemoteAskView(input: BuildRemoteAskViewInput): RemoteAskView;

package/dist/types/notifications/protocol.d.ts

@@ -0,0 +1,43 @@
+export declare const NOTIFICATION_PROTOCOL_VERSION = 1;
+export type NotificationServerFrame = NotificationActionNeededFrame | NotificationActionResolvedFrame | NotificationReplyRejectedFrame | NotificationServerHelloFrame | NotificationPongFrame;
+export type NotificationClientFrame = NotificationReplyFrame | NotificationClientHelloFrame | NotificationPingFrame;
+export interface NotificationActionNeededFrame {
+    type: "action_needed";
+    actionId: string;
+    prompt: string;
+    options?: string[];
+}
+export interface NotificationActionResolvedFrame {
+    type: "action_resolved";
+    actionId: string;
+}
+export interface NotificationReplyRejectedFrame {
+    type: "reply_rejected";
+    actionId?: string;
+    reason: string;
+    source?: "local" | "telegram";
+}
+export interface NotificationServerHelloFrame {
+    type: "hello";
+    version: number;
+    sessionId: string;
+}
+export interface NotificationPongFrame {
+    type: "pong";
+    nonce?: string;
+}
+export interface NotificationReplyFrame {
+    type: "reply";
+    actionId: string;
+    value: string;
+    source?: "local" | "telegram";
+}
+export interface NotificationClientHelloFrame {
+    type: "hello";
+    version: number;
+}
+export interface NotificationPingFrame {
+    type: "ping";
+    nonce?: string;
+}
+export declare function isSupportedNotificationProtocolVersion(version: number): boolean;

package/dist/types/notifications/remote-answer.d.ts

@@ -0,0 +1,78 @@
+export type RemoteAnswerTransport = "telegram";
+export type RemoteAnswerKind = "button" | "free_text";
+export type RemoteAnswerSource = "local" | "telegram";
+export interface RemoteAnswerInput {
+    sessionId: string;
+    actionId: string;
+    idempotencyKey: string;
+    transport: RemoteAnswerTransport;
+    kind: RemoteAnswerKind;
+    value: string;
+    presentedToken?: string;
+}
+export interface RemoteIdempotencyRecord {
+    key: string;
+    valueHash: string;
+    status: "accepted" | "rejected";
+    reason?: RemoteAnswerRejectionReason;
+}
+export interface RemoteActionContext {
+    sessionId: string;
+    actionId: string;
+    expectedToken: string;
+    answeredBy?: RemoteAnswerSource;
+    idempotencyRecords?: readonly RemoteIdempotencyRecord[];
+    allowedValues?: readonly string[];
+    allowFreeText?: boolean;
+}
+export interface NormalizedRemoteAnswer {
+    sessionId: string;
+    actionId: string;
+    idempotencyKey: string;
+    source: "telegram";
+    kind: RemoteAnswerKind;
+    value: string;
+}
+export interface RemoteActionContextPatch {
+    answeredBy: "telegram";
+    idempotencyRecord: {
+        key: string;
+        valueHash: string;
+        status: "accepted";
+    };
+}
+export type RemoteAnswerRejectionReason = "unauthorized" | "session_mismatch" | "stale_action" | "idempotency_conflict" | "already_answered" | "invalid_button_value" | "free_text_not_allowed" | "empty_free_text";
+export type RemoteAnswerDecision = {
+    status: "accepted";
+    answer: NormalizedRemoteAnswer;
+    contextPatch: RemoteActionContextPatch;
+} | {
+    status: "rejected";
+    reason: RemoteAnswerRejectionReason;
+    idempotencyRecord?: {
+        key: string;
+        valueHash: string;
+        status: "rejected";
+        reason: RemoteAnswerRejectionReason;
+    };
+};
+export interface TelegramCallbackPayloadParts {
+    sessionId: string;
+    actionId: string;
+    value: string;
+    nonce: string;
+}
+export type ParseTelegramCallbackPayloadResult = {
+    ok: true;
+    input: Omit<RemoteAnswerInput, "presentedToken">;
+} | {
+    ok: false;
+    code: "invalid_payload";
+};
+export declare function stripTelegramOptionPrefix(label: string): string;
+export declare function normalizeRemoteAnswerValue(input: RemoteAnswerInput): string;
+export declare function buildTelegramCallbackPayload(parts: TelegramCallbackPayloadParts): string;
+export declare function parseTelegramCallbackPayload(payload: string): ParseTelegramCallbackPayloadResult;
+export declare function isRemoteAnswerInput(value: unknown): value is Omit<RemoteAnswerInput, "presentedToken">;
+export declare function parseRemoteAnswerPayload(payload: unknown): ParseTelegramCallbackPayloadResult;
+export declare function decideRemoteAnswer(input: RemoteAnswerInput, context: RemoteActionContext): RemoteAnswerDecision;

package/dist/types/notifications/reply-bridge.d.ts

@@ -0,0 +1,21 @@
+import { readNotificationDiscoveryRecord } from "./discovery";
+export interface ForwardReplyResult {
+    ok: boolean;
+    actionId?: string;
+    reason?: string;
+}
+/**
+ * Forward a remote (e.g. Telegram in-topic) reply to exactly one mapped session by acting as a
+ * notification WS client: connect to that session's loopback endpoint, learn the pending `actionId`
+ * from the replayed `action_needed`, send a `reply`, and confirm the session resolved it. Fail-closed
+ * when the session has no endpoint or no pending ask; the token (from the discovery record) is never
+ * logged. Injectable `webSocketImpl`/`readRecord` for tests.
+ */
+export declare function forwardTelegramReplyToSession(opts: {
+    stateRoot: string;
+    sessionId: string;
+    value: string;
+    webSocketImpl?: typeof WebSocket;
+    timeoutMs?: number;
+    readRecord?: typeof readNotificationDiscoveryRecord;
+}): Promise<ForwardReplyResult>;

package/dist/types/notifications/server.d.ts

@@ -0,0 +1,38 @@
+import { type NotificationActionNeededFrame, type NotificationServerFrame } from "./protocol";
+import { type NotificationActionDraft } from "./session-registry";
+export interface NotificationLoopbackServerOptions {
+    sessionId: string;
+    stateRoot: string;
+    /** Per-session connect token. Generated if omitted. Never logged. */
+    connectToken?: string;
+    now?: () => number;
+}
+/**
+ * Loopback-only (127.0.0.1) WebSocket transport for the notification SDK.
+ *
+ * Business logic (token gate, action replay, remote/local answer race, idempotency) lives in
+ * {@link NotificationSessionRegistry}; this class is the thin Bun-native transport that
+ * authenticates clients at upgrade time, replays buffered asks, accepts remote replies, and
+ * broadcasts resolution frames. The connect token is never logged.
+ */
+export declare class NotificationLoopbackServer {
+    #private;
+    private constructor();
+    static start(options: NotificationLoopbackServerOptions): Promise<NotificationLoopbackServer>;
+    get url(): string;
+    get port(): number;
+    /** The per-session connect token. Exposed for host wiring/tests only; never log it. */
+    get connectToken(): string;
+    /** Register a callback fired when a remote reply is accepted (resolves an ask). Single slot. */
+    setOnRemoteResolved(callback: (actionId: string, value: string) => void): void;
+    /** Enqueue an ask and broadcast the resulting action_needed frame to connected clients. */
+    enqueueAction(draft: NotificationActionDraft): NotificationActionNeededFrame;
+    /** Resolve an ask locally (local answer wins the race) and broadcast action_resolved. */
+    resolveLocal(actionId: string): NotificationServerFrame;
+    /**
+     * Resolves when the most recent pending-action discovery publish settles. The publish is best-effort
+     * and never blocks an ask, so production code does not await it; tests/wiring use this to observe it.
+     */
+    whenPendingActionPublished(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/types/notifications/session-lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { Settings } from "../config/settings";
+import { NotificationLoopbackServer } from "./server";
+export interface MaybeStartNotificationServerOptions {
+    settings: Settings;
+    sessionId: string;
+    /** Workspace/project root; the discovery file is written under `<cwd>/.jwc/state/notifications`. */
+    cwd: string;
+    /** Subagent depth; only top-level sessions (0) start a server. */
+    taskDepth?: number;
+    registerCleanup: (name: string, cleanup: () => Promise<void> | void) => void;
+    /** Injectable for tests. */
+    startServer?: typeof NotificationLoopbackServer.start;
+    now?: () => number;
+}
+/**
+ * Start the loopback notification server for a live session when notifications are enabled.
+ *
+ * Returns the running server, or `null` when skipped (subagent session, notifications disabled,
+ * or a start failure). A start failure is logged and swallowed — it must never break session
+ * creation. On success a `stop()` cleanup is registered so the server is torn down on dispose.
+ */
+export declare function maybeStartNotificationServer(options: MaybeStartNotificationServerOptions): Promise<NotificationLoopbackServer | null>;

package/dist/types/notifications/session-registry.d.ts

@@ -0,0 +1,31 @@
+import { type NotificationEndpointRecord } from "./discovery";
+import { type NotificationActionNeededFrame, type NotificationServerFrame } from "./protocol";
+import { type RemoteAnswerInput } from "./remote-answer";
+export interface NotificationSessionRegistryOptions {
+    sessionId: string;
+    connectToken: string;
+    now?: () => number;
+}
+export interface NotificationActionDraft {
+    actionId: string;
+    prompt: string;
+    options?: readonly string[];
+    allowFreeText?: boolean;
+}
+export interface NotificationConnectSnapshot {
+    sessionId: string;
+    frames: NotificationServerFrame[];
+}
+export type NotificationConnectDecision = NotificationConnectSnapshot | {
+    rejected: true;
+    reason: "unauthorized";
+};
+export declare class NotificationSessionRegistry {
+    #private;
+    constructor(options: NotificationSessionRegistryOptions);
+    connect(presentedToken: string | undefined): NotificationConnectDecision;
+    enqueueAction(action: NotificationActionDraft): NotificationActionNeededFrame;
+    resolveRemote(input: RemoteAnswerInput): NotificationServerFrame;
+    resolveLocal(actionId: string): NotificationServerFrame;
+}
+export declare function markStaleNotificationDiscoveryRecord(stateRoot: string, sessionId: string, now?: number): Promise<NotificationEndpointRecord | null>;

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

@@ -0,0 +1,93 @@
+/**
+ * Token-safe Telegram Bot API client for the managed daemon's poll loop.
+ *
+ * `fetchImpl` is injectable for unit tests (no live token). The bot token goes in the request URL and
+ * is sanitized out of every returned `reason`. Errors are classified retryable/fatal so the daemon
+ * can back off transient failures and stop on a 409 single-owner conflict.
+ */
+export interface TelegramUpdate {
+    update_id: number;
+    [key: string]: unknown;
+}
+export type TelegramCallOutcome<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    retryable: boolean;
+    status?: number;
+    retryAfterMs?: number;
+    reason: string;
+};
+interface TelegramErrorBody {
+    description?: string;
+    parameters?: {
+        retry_after?: number;
+    };
+}
+export declare function classifyTelegramError(status: number | undefined, body: TelegramErrorBody | undefined): {
+    retryable: boolean;
+    retryAfterMs?: number;
+    reason: string;
+};
+/** Exponential backoff with a cap: min(cap, base * 2^attempt). */
+export declare function nextBackoffMs(attempt: number, base?: number, cap?: number): number;
+export declare function getTelegramUpdates(opts: {
+    token: string;
+    offset?: number;
+    timeoutSec?: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<TelegramCallOutcome<TelegramUpdate[]>>;
+export declare function sendTelegramMessage(opts: {
+    token: string;
+    chatId: string;
+    text: string;
+    fetchImpl?: typeof fetch;
+}): Promise<TelegramCallOutcome<{
+    message_id: number;
+}>>;
+export declare function createForumTopic(opts: {
+    token: string;
+    chatId: string;
+    name: string;
+    fetchImpl?: typeof fetch;
+}): Promise<TelegramCallOutcome<{
+    message_thread_id: number;
+}>>;
+export declare function deleteForumTopic(opts: {
+    token: string;
+    chatId: string;
+    messageThreadId: number;
+    fetchImpl?: typeof fetch;
+}): Promise<TelegramCallOutcome<true>>;
+/**
+ * Acknowledge a tapped inline-keyboard button so Telegram clears the button
+ * spinner. Optional `text` shows a transient toast to the user. Token-safe.
+ */
+export declare function answerTelegramCallbackQuery(opts: {
+    token: string;
+    callbackQueryId: string;
+    text?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<TelegramCallOutcome<true>>;
+export interface SendTelegramFileOptions {
+    token: string;
+    chatId: string;
+    /** Raw file bytes (already workspace-confined and size/MIME-checked by the caller). */
+    data: Uint8Array;
+    fileName: string;
+    caption?: string;
+    messageThreadId?: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}
+/** Upload a workspace-confined image as a Telegram photo. Token-safe. */
+export declare function sendTelegramPhoto(opts: SendTelegramFileOptions): Promise<TelegramCallOutcome<{
+    message_id: number;
+}>>;
+/** Upload a workspace-confined file as a Telegram document. Token-safe. */
+export declare function sendTelegramDocument(opts: SendTelegramFileOptions): Promise<TelegramCallOutcome<{
+    message_id: number;
+}>>;
+export {};

package/dist/types/notifications/telegram-ask-keyboard.d.ts

@@ -0,0 +1,57 @@
+/** Telegram Bot API limit for inline keyboard callback_data. */
+export declare const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+export interface InlineKeyboardButton {
+    text: string;
+    callback_data: string;
+}
+export type InlineKeyboard = InlineKeyboardButton[][];
+export interface BuildAskInlineKeyboardInput {
+    /** Option labels as presented to the user (may carry leading "1." numbering). */
+    options: readonly string[];
+    /** Per-ask nonce used as the idempotency seed; must be non-empty. */
+    nonce: string;
+    /** Buttons per row (default 1). Values < 1 are treated as 1. */
+    columns?: number;
+}
+export interface DecodedAskCallback {
+    index: number;
+    nonce: string;
+}
+export type DecodeAskCallbackResult = {
+    ok: true;
+    decoded: DecodedAskCallback;
+} | {
+    ok: false;
+    code: "invalid_callback";
+};
+export interface ResolveAskButtonInput {
+    callbackData: string;
+    allowedValues: readonly string[];
+}
+export type ResolveAskButtonResult = {
+    ok: true;
+    value: string;
+    index: number;
+    nonce: string;
+} | {
+    ok: false;
+    reason: "invalid_button_value";
+};
+/**
+ * Build a Telegram inline keyboard for an ask. Button text is the option label
+ * with any embedded "1." / "2)" numbering stripped (avoids double-numbering),
+ * and callback_data is a compact, 64-byte-safe `jwc1:<index>:<nonce>` token.
+ *
+ * @throws Error("callback_data_too_large") if the nonce is so long that a
+ *   callback_data would exceed Telegram's 64-byte limit.
+ */
+export declare function buildAskInlineKeyboard(input: BuildAskInlineKeyboardInput): InlineKeyboard;
+/** Decode a `jwc1:<index>:<nonce>` callback_data token. Nonce may contain ":". */
+export declare function decodeAskCallbackData(data: string): DecodeAskCallbackResult;
+/**
+ * Resolve a button callback to its canonical option value by decoding the
+ * index and looking it up in the active action's allowedValues. Out-of-range
+ * indices and malformed callbacks reject with `invalid_button_value`, matching
+ * RemoteAnswerRejectionReason so the caller can feed decideRemoteAnswer directly.
+ */
+export declare function resolveAskButtonAnswer(input: ResolveAskButtonInput): ResolveAskButtonResult;

package/dist/types/notifications/telegram-callback-ingest.d.ts

@@ -0,0 +1,49 @@
+import { type NormalizedRemoteAnswer, type RemoteActionContext, type RemoteActionContextPatch, type RemoteAnswerRejectionReason } from "./remote-answer";
+import type { TelegramUpdate } from "./telegram-api";
+/**
+ * Inbound Telegram callback_query (inline-button tap) ingestion (chase 10.032).
+ *
+ * Bridges a tapped ask button through:
+ *   decode compact callback_data -> resolveAskButtonAnswer (against allowedValues)
+ *   -> decideRemoteAnswer (token auth + race + idempotency, owned by remote-answer.ts).
+ *
+ * Pure / side-effect-free. The decision always surfaces `callbackQueryId` so the
+ * caller can `answerTelegramCallbackQuery` to clear the spinner. No token, chat id,
+ * or session secret is embedded in callback_data or echoed in the decision.
+ */
+export interface TelegramCallbackQuery {
+    id: string;
+    data?: string;
+    fromId?: number;
+    chatId?: number;
+    messageThreadId?: number;
+}
+export type TelegramCallbackIgnoreReason = "not_a_callback" | "empty_callback_data";
+export type TelegramCallbackDecision = {
+    mode: "ignore";
+    reason: TelegramCallbackIgnoreReason;
+} | {
+    mode: "accepted";
+    callbackQueryId: string;
+    answer: NormalizedRemoteAnswer;
+    contextPatch: RemoteActionContextPatch;
+} | {
+    mode: "rejected";
+    callbackQueryId: string;
+    reason: RemoteAnswerRejectionReason;
+};
+export interface DecideTelegramCallbackInput {
+    update: TelegramUpdate;
+    presentedToken?: string;
+    context?: RemoteActionContext;
+}
+/**
+ * Safely extract a Telegram callback_query from a (loosely typed) update.
+ * Returns null for non-callback updates or structurally invalid payloads.
+ */
+export declare function extractTelegramCallbackQuery(update: TelegramUpdate): TelegramCallbackQuery | null;
+/**
+ * Decide what to do with an inbound callback_query. Token authorization, action
+ * staleness, session match, and idempotency are all enforced by decideRemoteAnswer.
+ */
+export declare function decideTelegramCallbackInbound(input: DecideTelegramCallbackInput): TelegramCallbackDecision;

package/dist/types/notifications/telegram-inbound-router.d.ts

@@ -0,0 +1,57 @@
+import type { RemoteActionContext, RemoteAnswerKind } from "./remote-answer";
+import type { TelegramUpdate } from "./telegram-api";
+import { type ThreadTopicRegistry } from "./threaded-surface";
+/**
+ * Telegram inbound dispatch router (chase 10.032 live routing, gates 1/2).
+ *
+ * Composes the individually-tested deciders into a single side-effect-free dispatch plan:
+ *   callback_query -> chat/topic resolution + `decideTelegramCallbackInbound`
+ *   text message   -> `classifyThreadInboundUpdate` (thread->session, fail-closed) + `decideTelegramMessageInbound`
+ *
+ * The router owns NO live state: the caller injects `resolveActionContext(sessionId)` (the pending ask's
+ * RemoteActionContext) and the dedupe hooks, then executes the returned plan
+ * (`answerTelegramCallbackQuery` + `forwardTelegramReplyToSession`). Token/chat/session secrets are never
+ * embedded in or echoed by the plan.
+ *
+ * Fail-closed policy:
+ *   - foreign chat / missing chat / missing topic  -> silent `drop` (no ack, reveals nothing).
+ *   - legit chat but unmapped/stale topic or no active ask -> ack the callback as `rejected` (clear the
+ *     user's spinner) / for text, `drop`.
+ *   - a rejected free-text answer (not allowed, already answered, ...) -> `drop`, never injected.
+ *   - in-topic free text with NO active ask -> `forward_reply` (an ordinary reply for the caller).
+ */
+export type InboundDispatchAction = {
+    kind: "answer_callback";
+    callbackQueryId: string;
+    outcome: "accepted" | "rejected";
+    reason?: string;
+} | {
+    kind: "deliver_answer";
+    sessionId: string;
+    value: string;
+    source: RemoteAnswerKind;
+    ackMessageId?: number;
+} | {
+    kind: "forward_reply";
+    sessionId: string;
+    text: string;
+    updateId: number;
+} | {
+    kind: "drop";
+    reason: string;
+};
+export type InboundDispatchPlan = InboundDispatchAction[];
+export interface InboundRouterContext {
+    expectedChatIdFingerprint: string;
+    presentedToken?: string;
+    registry: ThreadTopicRegistry;
+    isDuplicateUpdate: (updateId: number) => boolean;
+    recordUpdateId?: (updateId: number) => void;
+    resolveActionContext: (sessionId: string) => RemoteActionContext | undefined;
+}
+/**
+ * Route one inbound Telegram update into a dispatch plan. callback_query updates take the button path;
+ * everything else is treated as a (possibly text) message. Returns an empty plan only when an update is
+ * structurally neither (never reached in practice — message path returns an explicit drop).
+ */
+export declare function routeTelegramInboundUpdate(update: TelegramUpdate, ctx: InboundRouterContext): InboundDispatchPlan;