@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/notifications/config-commands.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 verbose (full tool output + reasoning)
+ * - `/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";
+export type TelegramControlCommand = {
+    name: "reasoning";
+    action: "cycle" | "status" | "set";
+    level?: string;
+} | {
+    name: "usage";
+} | {
+    name: "context";
+} | {
+    name: "compact";
+    instructions?: 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;

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

@@ -0,0 +1,132 @@
+import type { Settings } from "../config/settings";
+/**
+ * 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 interface NotificationConfig {
+    enabled: boolean;
+    botToken?: string;
+    chatId?: string;
+    discord: {
+        botToken?: string;
+        channelId?: string;
+    };
+    slack: {
+        botToken?: string;
+        channelId?: 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;
+    rich: {
+        enabled: boolean;
+    };
+    richDraft: {
+        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 config from Settings. */
+export declare function getNotificationConfig(settings: Settings): NotificationConfig;
+export declare function hasNonBlankValue(value: string | undefined): boolean;
+/** Is Telegram configured with usable non-blank boundary credentials? */
+export declare function isTelegramConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+    botToken: string;
+    chatId: 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;
+/** Resolve whether the notifications extension should be registered at SDK startup. */
+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) isGloballyConfigured(cfg)      -> true (global auto-on)
+ *  5) otherwise false
+ */
+export declare function isSessionNotificationsEnabled(input: {
+    cfg: NotificationConfig;
+    env: NodeJS.ProcessEnv;
+    sessionDisabled: 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;
+/** 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;
+    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;

package/dist/types/notifications/daemon-paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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;
+    roots: string;
+    steal: string;
+    aliases: string;
+    seenUpdates: string;
+}
+export declare function daemonPaths(agentDir: string): DaemonPaths;

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

@@ -0,0 +1,59 @@
+import { type RedactableAction } from "./config";
+export type NotificationEvent = ({
+    type: "action_needed";
+} & RedactableAction) | {
+    type: "action_resolved";
+    id: string;
+    sessionId: string;
+    resolvedBy?: string;
+} | {
+    type: "frame";
+    sessionId: string;
+    frame: Record<string, unknown>;
+};
+export interface NotificationReplyRoute {
+    sessionId: string;
+    actionId: string;
+    answer: number | string | {
+        selected?: Array<number | string>;
+        custom?: string;
+    };
+}
+export interface NotificationAdapterPayload {
+    adapter: string;
+    channelKey?: string;
+    body: unknown;
+    route?: Omit<NotificationReplyRoute, "answer">;
+}
+export interface NotificationPresentationAdapter {
+    readonly kind: "telegram" | "discord" | "slack";
+    render(event: NotificationEvent): NotificationAdapterPayload[];
+    mapInbound(input: unknown): NotificationReplyRoute | undefined;
+}
+export interface EngineSessionSink {
+    sendReply(route: NotificationReplyRoute): void;
+}
+export interface NotificationEngineOptions {
+    redact: boolean;
+    sessionTag: (sessionId: string) => string;
+}
+/**
+ * Shared presentation engine for managed notification clients.
+ *
+ * It owns fanout, redaction boundaries, pending-action routing, and reply
+ * delivery into session sinks. Transport adapters stay pure: render an internal
+ * event into a public-safe payload and map an inbound transport interaction
+ * back into a session/action answer.
+ */
+export declare class NotificationPresentationEngine {
+    private readonly opts;
+    readonly adapters: readonly NotificationPresentationAdapter[];
+    private readonly sessions;
+    private readonly pending;
+    constructor(adapters: readonly NotificationPresentationAdapter[], opts: NotificationEngineOptions);
+    connectSession(sessionId: string, sink: EngineSessionSink): void;
+    dropSession(sessionId: string): void;
+    fanout(event: NotificationEvent): NotificationAdapterPayload[];
+    routeInbound(adapterKind: NotificationPresentationAdapter["kind"], input: unknown): boolean;
+    private redactEvent;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Pure helpers for the notifications extension.
+ *
+ * Kept side-effect-free so the mapping logic (ask extraction, idle summary,
+ * dedupe keys) is unit-testable without a live session or the native server.
+ */
+import { type RedactableAction } from "./config";
+/** A pending ask derived from an `ask` tool call. */
+export interface PendingAsk {
+    /** Action id: `${toolCallId}:${questionId}`. */
+    id: string;
+    /** Question text. */
+    question: string;
+    /** Option labels (may be empty for free-text questions). */
+    options: string[];
+}
+/** Truncate text to `max` chars, appending an ellipsis when cut. */
+export declare function truncate(text: string, max?: number): string;
+/** Stable per-turn idle dedupe key so exactly one idle action fires per turn. */
+export declare function idleDedupeKey(sessionId: string, turnIndex: number): string;
+/**
+ * Extract pending asks from an `ask` tool call input.
+ *
+ * Defensive: tolerates partial/unknown shapes and always returns an array.
+ */
+export declare function asksFromAskInput(toolCallId: string, input: unknown): PendingAsk[];
+/** Prepare an action JSON payload for remote notification delivery. */
+export declare function notificationActionPayload<T extends RedactableAction>(action: T, opts: {
+    redact: boolean;
+    sessionTag: string;
+}): RedactableAction;
+/** Extract a plain-text summary from an agent message's content, if any. */
+export declare function summaryFromMessage(message: unknown, max?: number): string | undefined;
+/**
+ * Extract an idle summary from an `agent_end` event's settled message list: the
+ * last message that yields text (i.e. the final assistant message; tool-result
+ * messages have no text and are skipped).
+ *
+ * `agent_end` fires exactly once when the agent loop settles to await the user,
+ * so emitting idle from this — instead of per-`turn_end` — produces exactly one
+ * idle notification per genuine idle, eliminating the multi-turn flood.
+ */
+export declare function summaryFromMessages(messages: unknown, max?: number): string | undefined;
+/** An agent-produced image extracted from a message's content. */
+export interface ExtractedImage {
+    source: string;
+    mime: string;
+    data: string;
+}
+/**
+ * Extract agent-produced images (`{ type: "image", data, mimeType }` blocks)
+ * from a message's content — e.g. computer-use/browser screenshots or tool
+ * image outputs — for `image_attachment` delivery.
+ */
+export declare function imageAttachmentsFromMessage(message: unknown, source?: string): ExtractedImage[];

package/dist/types/notifications/html-format.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Telegram HTML formatting helpers for the notifications SDK.
+ *
+ * All notifications-SDK Telegram output is sent with `parse_mode: "HTML"`. This
+ * module is the single source of truth for: escaping dynamic text, converting a
+ * bounded markdown subset into Telegram HTML, safely truncating a finished
+ * message to Telegram's 4096-char limit without breaking tags/entities, and
+ * laying out inline-keyboard buttons as a numbered grid.
+ *
+ * Discipline: escape first, tag second. Telegram only parses a small tag set
+ * (b, i, u, s, code, pre, a, blockquote, tg-spoiler); a stray `<` or unbalanced
+ * tag can make Telegram reject the whole message, so dynamic text is always
+ * escaped before any tag is emitted.
+ */
+export declare const TELEGRAM_PARSE_MODE: "HTML";
+export declare const TELEGRAM_MESSAGE_LIMIT = 4096;
+/** Escape text for Telegram HTML body content (`& < >`). */
+export declare function escapeHtml(value: string): string;
+/** Bold the given raw text (escaped internally). */
+export declare function bold(raw: string): string;
+/** Italicize the given raw text (escaped internally). */
+export declare function italic(raw: string): string;
+/** Render the given raw text as inline code (escaped internally). */
+export declare function code(raw: string): string;
+/** Render the given raw text as a preformatted block (escaped internally). */
+export declare function pre(raw: string): string;
+/**
+ * Convert a bounded markdown subset into Telegram HTML. Supported: fenced code,
+ * inline code, `**bold**`, `*italic*`, `[text](url)` (safe schemes only),
+ * `#` headers, `>` blockquotes, and GFM tables (rendered as a monospace block).
+ * Unsupported or malformed markdown is left as escaped literal text — never
+ * emitted as unbalanced tags.
+ */
+export declare function markdownToTelegramHtml(markdown: string): string;
+/**
+ * Truncate a finished Telegram HTML message to at most `max` chars without
+ * splitting a tag or entity, closing any still-open allowed tags and appending
+ * `marker`. The final string is guaranteed to be <= `max`.
+ */
+export declare function truncateTelegramHtml(message: string, max?: number, marker?: string): string;
+/** Split a finished Telegram HTML message into ordered chunks without splitting tags or entities. */
+export declare function splitTelegramHtml(message: string, max?: number): string[];
+/** Finalize an optional message: undefined passthrough, else safe-truncate. */
+export declare function finalizeTelegramHtml(message?: string): string | undefined;
+/**
+ * One-based, plain-text button label (Telegram does not parse HTML in labels).
+ *
+ * Strips any leading `N.`/`N)` index already embedded in the label (e.g.
+ * deep-interview options pre-numbered by the ask tool) and applies the canonical
+ * one-based button index instead. This avoids duplicated numbering like
+ * `1. 1. …` and keeps the displayed number aligned with the button's real index.
+ */
+export declare function buttonLabel(label: string, index: number): string;
+/** Numbered, escaped option list for the Telegram message body. */
+export declare function numberedOptionList(labels: string[]): string;
+/** Compact numeric button label; full option text belongs in the message body. */
+export declare function choiceButtonLabel(index: number): string;
+export interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+/**
+ * Lay out option callbacks as compact numeric buttons. Telegram mobile clients
+ * ellipsize long inline-keyboard labels and tall keyboards can be obscured by
+ * the composer, so the full choice text is rendered in the message body while
+ * the keyboard keeps only stable one-based tap targets.
+ */
+export declare function buildCompactChoiceGrid(labels: string[], callbackForIndex: (index: number) => string): InlineButton[][];
+/**
+ * Lay out option labels as a numbered button grid. Long buttons take a
+ * full-width row; runs of short buttons are packed into rows of up to 3. The
+ * callback value comes from `callbackForIndex(i)` using the original zero-based
+ * option index — layout never changes callback semantics.
+ */
+export declare function buildButtonGrid(labels: string[], callbackForIndex: (index: number) => string): InlineButton[][];

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

@@ -0,0 +1,219 @@
+/**
+ * Notifications extension.
+ *
+ * Hosts a per-session loopback WebSocket notification server (the Rust core via
+ * N-API) and bridges SKC session events + the `ask` tool to it so a remote client
+ * (e.g. a Telegram bot) can both see action-needed signals and ANSWER them —
+ * without requiring RPC/unattended mode:
+ *
+ * - `ask` (interactive): registers an {@link AskAnswerSource}; the ask tool races
+ *   the local UI against a remote reply. First valid answer wins; a local answer
+ *   aborts the remote wait (and broadcasts `action_resolved` resolvedBy=local).
+ * - `ask` (unattended/RPC): observes emitted workflow gates and resolves the real
+ *   gate on a remote reply via `ctx.workflowGate`.
+ * - `turn_end` -> `action_needed` (kind `idle`, deduped per turn).
+ * - `session_shutdown` -> `session_closed` frame, stop server, deregister answer source.
+ *
+ * Enable with Settings notifications config, `SKC_NOTIFICATIONS=1` (a token is
+ * generated), or `SKC_NOTIFICATIONS_TOKEN`.
+ */
+import { Settings } from "../config/settings";
+import type { ExtensionAPI, ExtensionContext } from "../extensibility/extensions";
+/** Where a `session_create` should run. Discriminated by `kind`. */
+export type SessionCreateTarget = {
+    kind: "existing_path";
+    path: string;
+} | {
+    kind: "worktree";
+    repo: string;
+    branch: string;
+} | {
+    kind: "plain_dir";
+    path: string;
+};
+/** Identifies the session a `session_close` targets. */
+export interface SessionCloseTarget {
+    sessionId: string;
+    /** Expected SKC-managed tmux session name (defense-in-depth match). */
+    tmuxSession?: string;
+    /** Expected `@skc-session-state-file` tag (defense-in-depth match). */
+    sessionStateFile?: string;
+}
+/** Identifies the session a `session_resume` targets. */
+export interface SessionResumeTarget {
+    sessionIdOrPrefix: string;
+    /** Optional repo/working-dir hint to disambiguate matches. */
+    path?: string;
+}
+/** Create a new session. */
+export interface SessionCreateFrame {
+    type: "session_create";
+    requestId: string;
+    /** Deterministic lifecycle marker preallocated by the daemon before spawn. */
+    lifecycleRequestId: string;
+    /** Session id the daemon preallocated and propagates to the child. */
+    intendedSessionId: string;
+    /** Telegram update id (idempotency key on the daemon side). */
+    updateId: number;
+    chatId: string;
+    /** Control-endpoint token authorizing this frame. */
+    token: string;
+    target: SessionCreateTarget;
+    /** Reference to the daemon-written, once-consumed startup-prompt file. */
+    startupPromptRef?: string;
+    /** Model profile preset to activate for the spawned session (--mpreset). */
+    modelPreset?: string;
+}
+/** Close (hard-kill, history preserved) a session. */
+export interface SessionCloseFrame {
+    type: "session_close";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionCloseTarget;
+    /** Required force-only close flag; false/omitted is rejected by daemon policy. */
+    force?: boolean;
+}
+/** Resume a session (reattach if alive, else cold-restart from history). */
+export interface SessionResumeFrame {
+    type: "session_resume";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionResumeTarget;
+    startupPromptRef?: string;
+}
+/** Any client -> ingress lifecycle request frame. */
+export type SessionLifecycleRequest = SessionCreateFrame | SessionCloseFrame | SessionResumeFrame;
+/** Terminal status of a lifecycle request. */
+export type LifecycleStatus = "ok" | "error";
+/** A connected session's per-session endpoint, returned to the control client. */
+export interface LifecycleEndpoint {
+    url: string;
+    token: string;
+}
+/** The Telegram topic/thread a session is surfaced in. */
+export interface LifecycleTopic {
+    chatId: string;
+    threadId: string;
+}
+/** How a create request was correlated to its spawned session. */
+export type MatchedBy = "spawn_marker" | "session_ready";
+/** Response to a successful `session_create`. */
+export interface SessionCreateResponseFrame {
+    type: "session_create_response";
+    requestId: string;
+    status: LifecycleStatus;
+    lifecycleRequestId: string;
+    sessionId: string;
+    matchedBy: MatchedBy;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+    target: SessionCreateTarget;
+}
+/** Response to a successful `session_close`. */
+export interface SessionCloseResponseFrame {
+    type: "session_close_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    processGone: boolean;
+    historyPreserved: boolean;
+    endpointStale: boolean;
+}
+/** Whether a resume reattached to a live session or cold-restarted a dead one. */
+export type ResumeMode = "reattached" | "cold_restarted";
+/** Response to a successful `session_resume`. */
+export interface SessionResumeResponseFrame {
+    type: "session_resume_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    mode: ResumeMode;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+}
+/** Machine-readable reason a lifecycle request failed. */
+export type LifecycleErrorReason = "unauthorized" | "rate_limited" | "duplicate_conflict" | "invalid_target" | "ambiguous_target" | "spawn_failed" | "discovery_timeout" | "readiness_timeout" | "close_refused" | "not_found" | "terminal_uncertain";
+/** A candidate returned with an `ambiguous_target` resume error. */
+export interface ResumeCandidate {
+    sessionId: string;
+    path?: string;
+    /** Last-activity epoch-millis (session history file mtime), if known. */
+    mtimeMs?: number;
+}
+/** A structured lifecycle error frame. */
+export interface SessionLifecycleErrorFrame {
+    type: "session_lifecycle_error";
+    requestId: string;
+    status: LifecycleStatus;
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+}
+/** Any ingress -> client lifecycle response frame. */
+export type SessionLifecycleResponse = SessionCreateResponseFrame | SessionCloseResponseFrame | SessionResumeResponseFrame | SessionLifecycleErrorFrame;
+/**
+ * Replayable per-session readiness signal (mirror of the Rust `session_ready`
+ * frame). Buffered and replayed to late clients so WS-open alone never implies
+ * the session is live and surfaced.
+ */
+export interface SessionReadyFrame {
+    type: "session_ready";
+    sessionId: string;
+    lifecycleRequestId?: string;
+    startupPromptRef?: string;
+    repo?: string;
+    branch?: string;
+    title?: string;
+}
+/**
+ * Best-effort real repository name (no git spawn): resolves the main worktree
+ * root directory so linked worktrees report the repo (e.g. `sayknow-cli`)
+ * instead of the worktree directory (e.g. `feat-foo-01047f11`).
+ */
+export declare function readGitRepoName(cwd: string): string | undefined;
+export declare function notificationsEnabled(): boolean;
+/** Workflow-gate answer shape (unattended mode). */
+interface GateAnswer {
+    selected: string[];
+    other?: boolean;
+    custom?: string;
+}
+/**
+ * Discriminated result of mapping a client answer to a workflow-gate answer.
+ * `ok: false` means the reply is invalid and the caller must close the exact
+ * claim/receipt and reissue the interaction rather than durably accepting it.
+ */
+type GateAnswerResult = {
+    ok: true;
+    answer: GateAnswer;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Map a client answer to the workflow-gate answer shape (unattended mode).
+ *
+ * The protocol defines a numeric reply as an option index, so a number outside
+ * `options` is invalid (issue #2030): it must NOT be converted into a free-text
+ * `Other` that passes the ask schema and triggers a misleading success ack.
+ * Only JSON strings enter the free-text/Other path.
+ */
+export declare function mapAnswerToGate(answerJson: string, options: string[]): GateAnswerResult;
+interface NotificationControlCommandPayload {
+    name?: unknown;
+    action?: unknown;
+    level?: unknown;
+    instructions?: unknown;
+}
+export declare function executeNotificationControlCommand(command: NotificationControlCommandPayload | undefined, ctx: ExtensionContext, api: ExtensionAPI): Promise<{
+    status: "ok" | "error" | "unavailable";
+    message: string;
+}>;
+export declare function createNotificationsExtension(api: ExtensionAPI, options?: {
+    settings?: Settings;
+}): void;
+export {};