@sayknow-cli/coding-agent 0.3.13 → 0.3.16

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

@@ -0,0 +1,136 @@
+/**
+ * Telegram **reference** client for the notifications SDK.
+ *
+ * This is an example/template, NOT an upstream-owned integration: it implements
+ * the documented WS protocol (see `docs/notifications-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/notifications/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/notifications/threaded-render.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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;
+}
+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;
+    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/notifications/topic-registry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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;
+    /** 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;
+}
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+    /** sessionId -> record. */
+    topics: Record<string, TopicRecord>;
+}
+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 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;
+    constructor(state?: TopicRegistryState);
+    /** Merge serialized state and normalize authority fields from older releases. */
+    load(state: TopicRegistryState): void;
+    /** 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<string>, 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;
+    /** 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;
+    /** Remove a session topic record after Telegram deletes the topic. */
+    delete(sessionId: string): boolean;
+    /** Serialise for atomic persistence beside the daemon state. */
+    serialize(): TopicRegistryState;
+}

package/dist/types/plan-mode/approved-plan.d.ts

@@ -0,0 +1,49 @@
+/** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
+ *  approval popup. Populated by the standing handler that the resolve tool
+ *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+export interface PlanApprovalDetails {
+    planFilePath: string;
+    finalPlanFilePath: string;
+    title: string;
+    planExists: boolean;
+}
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
+export declare function normalizePlanTitle(title: string): {
+    title: string;
+    fileName: string;
+};
+/** Best-effort derivation of a plan title from inputs the agent already produced.
+ *  Returns the first non-empty candidate that survives `normalizePlanTitle`:
+ *    1. an explicit `suppliedTitle` (e.g. `extra.title` from the resolve call),
+ *    2. the first level-1 markdown heading inside `planContent`,
+ *    3. the filename stem of `planFilePath` (e.g. `PLAN` from `local://PLAN.md`),
+ *    4. the literal `"plan"` so callers never have to handle `null`.
+ *  The fallback exists because some grammar-constrained models cannot emit a
+ *  string into the open `extra` schema and instead drop in `{}` (issue #1179);
+ *  plan-mode would otherwise loop forever on an unreachable validation. */
+export declare function resolvePlanTitle(input: {
+    suppliedTitle?: unknown;
+    planContent: string;
+    planFilePath: string;
+}): {
+    title: string;
+    fileName: string;
+    source: "supplied" | "heading" | "filename" | "default";
+};
+/** Humanize a normalized plan title for use as a session display name.
+ *  Replaces `-`/`_` separators with spaces and capitalizes the first letter.
+ *  Returns an empty string when the input collapses to whitespace. */
+export declare function humanizePlanTitle(title: string): string;
+interface RenameApprovedPlanFileOptions {
+    planFilePath: string;
+    finalPlanFilePath: string;
+    getArtifactsDir: () => string | null;
+    getSessionId: () => string | null;
+}
+export declare function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void>;
+export {};

package/dist/types/plan-mode/state.d.ts

@@ -0,0 +1,6 @@
+export interface PlanModeState {
+    enabled: boolean;
+    planFilePath: string;
+    workflow?: "parallel" | "iterative";
+    reentry?: boolean;
+}

package/dist/types/registry/agent-registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentRegistry - Process-global registry of live AgentSession instances.
+ *
+ * Tracks every alive agent (the main session plus every subagent) so the
+ * `irc` tool can address peers by id. Sessions are registered explicitly at
+ * creation and removed when the owner releases them.
+ */
+import type { AgentSession } from "../session/agent-session";
+export declare const MAIN_AGENT_ID = "0-Main";
+export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+export type AgentKind = "main" | "sub";
+export interface AgentRef {
+    id: string;
+    displayName: string;
+    rosterLabel?: string;
+    kind: AgentKind;
+    parentId?: string;
+    status: AgentStatus;
+    session: AgentSession | null;
+    sessionFile: string | null;
+    createdAt: number;
+    lastActivity: number;
+}
+export type RegistryEvent = {
+    type: "registered";
+    ref: AgentRef;
+} | {
+    type: "status_changed";
+    ref: AgentRef;
+} | {
+    type: "removed";
+    ref: AgentRef;
+};
+type RegistryListener = (event: RegistryEvent) => void;
+export interface RegisterInput {
+    id: string;
+    displayName: string;
+    rosterLabel?: string;
+    kind: AgentKind;
+    parentId?: string;
+    session: AgentSession | null;
+    sessionFile?: string | null;
+    status?: AgentStatus;
+}
+export declare class AgentRegistry {
+    #private;
+    static global(): AgentRegistry;
+    /** Reset the global registry. Test-only. */
+    static resetGlobalForTests(): void;
+    register(input: RegisterInput): AgentRef;
+    setStatus(id: string, status: AgentStatus): void;
+    attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
+    detachSession(id: string): void;
+    unregister(id: string): void;
+    get(id: string): AgentRef | undefined;
+    list(): AgentRef[];
+    /**
+     * Returns every alive agent (running | idle) except the caller.
+     * Flat namespace: every agent can see every other agent.
+     */
+    listVisibleTo(id: string): AgentRef[];
+    onChange(listener: RegistryListener): () => void;
+}
+export {};

package/dist/types/reminders/star-reminder.d.ts

@@ -0,0 +1,115 @@
+import type { ImageContent } from "@sayknow-cli/ai";
+import type { CustomMessage } from "../session/messages";
+export declare const STAR_REMINDER_REPO = "jaybeyond/Sayknow_CLI";
+export declare const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
+export declare const STARRED_CACHE_TTL_MS: number;
+export interface StarReminderState {
+    declined: boolean;
+    starred: boolean;
+    /** ISO-8601 timestamp of the last authoritative star check, or "" if never. */
+    starredCheckedAt: string;
+}
+export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
+export interface GhResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type RunGh = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<GhResult>;
+export interface StarReminderDeps {
+    statePath?: string;
+    now?: () => Date;
+    runGh?: RunGh;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function getStarReminderStatePath(): string;
+export declare function defaultStarReminderState(): StarReminderState;
+/** Read state without locking. Missing or malformed files return the default. */
+export declare function readStarReminderStateUnlocked(statePath?: string): Promise<StarReminderState>;
+/** Whether a stored `starred:true` is still within the 24h cache window. */
+export declare function isStarredCacheFresh(state: StarReminderState, now?: Date): boolean;
+/**
+ * Lock-protected read-modify-write. The mutator receives the freshly re-read
+ * state under the lock; callers MUST base monotonic decisions on that value,
+ * not on any snapshot captured before the lock was held.
+ */
+export declare function updateStarReminderStateLocked(mutator: (current: StarReminderState) => StarReminderState | Promise<StarReminderState>, deps?: StarReminderDeps): Promise<StarReminderState>;
+/** A successful PUT is authoritative: always record starred and clear declined. */
+export declare function recordStarredFromPut(deps?: StarReminderDeps): Promise<StarReminderState>;
+/**
+ * Record the result of a fresh `gh` star check performed by this operation.
+ * - "starred": authoritative, clears declined so all reminders stop.
+ * - "unstarred": may downgrade, but only when the current state is not a
+ *   still-fresh confirmed star (which a concurrent process may have just
+ *   written); in that case the fresher confirmation wins.
+ */
+export declare function recordFreshStarCheck(status: "starred" | "unstarred", deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Record a launch-nudge decline. Never downgrades a confirmed star. */
+export declare function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
+export declare function runGhDefault(args: string[], options?: {
+    timeoutMs?: number;
+}): Promise<GhResult>;
+/** Classify the star state of the repo via `gh api`. */
+export declare function checkGhStarred(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+/** Star the repo via `gh api -X PUT`. Returns whether the PUT succeeded. */
+export declare function autoStarRepo(deps?: StarReminderDeps): Promise<boolean>;
+/**
+ * Determine the star state for this session, hitting `gh` only when needed.
+ * A fresh cached star skips `gh`; unstarred and declined states are rechecked.
+ * Authoritative results are persisted via the monotonic helpers.
+ */
+export declare function refreshStarStateForSession(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+export interface StarReminderPromptUI {
+    /** Show a yes/no confirmation. Resolves true when the user accepts. */
+    confirm(title: string, message: string): Promise<boolean>;
+    /** Optional guard; when it returns false the nudge is skipped silently. */
+    isIdle?: () => boolean;
+}
+/**
+ * Run the launch nudge once. Caller is responsible for the `startup.quiet`,
+ * `starReminder.enabled`, and true-interactive gates. All errors are swallowed
+ * so the launch path can never be broken by the reminder.
+ */
+export declare function maybeShowLaunchStarReminder(ui: StarReminderPromptUI, deps?: StarReminderDeps): Promise<void>;
+/**
+ * Schedule the launch nudge to run after the first render so the networked
+ * `gh` check never blocks startup. Returns immediately.
+ */
+export declare function scheduleLaunchStarReminderAfterFirstRender(ui: StarReminderPromptUI, deps?: StarReminderDeps): void;
+export interface StarReminderLaunchGateInput {
+    /** The `starReminder.enabled` setting. */
+    enabled: boolean;
+    /** The `startup.quiet` setting. */
+    quiet: boolean;
+}
+export interface StarReminderLaunchGate {
+    /** Whether to register the decline-driven injection contributor. */
+    register: boolean;
+    /** Whether to schedule the launch nudge after first render. */
+    schedule: boolean;
+}
+/**
+ * Pure decision for interactive wiring. The injection contributor is registered
+ * whenever the feature is enabled; the launch nudge is additionally suppressed
+ * by quiet startup. Centralizing this keeps the interactive gate testable.
+ */
+export declare function starReminderLaunchGate(input: StarReminderLaunchGateInput): StarReminderLaunchGate;
+export interface StarReminderSessionRef {
+    getSessionId(): string | undefined;
+}
+export type StarReminderCustomMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+export type InternalBeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<StarReminderCustomMessage | undefined>;
+export declare function createStarReminderMessage(): StarReminderCustomMessage;
+/**
+ * Build a before-agent-start contributor that injects the persuasion message
+ * once per logical session id, for declined-and-still-unstarred users only.
+ */
+export declare function createStarReminderBeforeAgentStartContributor(session: StarReminderSessionRef, deps?: StarReminderDeps): InternalBeforeAgentStartContributor;

package/dist/types/research-plan/index.d.ts

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

package/dist/types/research-plan/ledger.d.ts

@@ -0,0 +1,33 @@
+export type ResearchPlanConfidence = "low" | "medium" | "high";
+export type ResearchEvidenceVerdict = "support" | "contradict" | "uncertain";
+export interface ResearchPlanItem {
+    claim: string;
+    confidence: ResearchPlanConfidence;
+    unknowns: string[];
+    evidenceNeeded: string[];
+    counterexampleQueries: string[];
+    sourceConflictPolicy: string;
+    dropCondition: string;
+    verifierChecks: string[];
+}
+export interface ResearchEvidenceEntry {
+    claim: string;
+    source: string;
+    confidence: ResearchPlanConfidence;
+    verdict: ResearchEvidenceVerdict;
+    notes?: string;
+}
+export interface ResearchLedgerVerdict {
+    claim: string;
+    finalVerdict: "accepted" | "rejected" | "uncertain";
+    survivingSources: ResearchEvidenceEntry[];
+    rejectReason?: string;
+    unresolvedUnknowns: string[];
+}
+export interface ResearchPlanValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateResearchPlanItem(item: Partial<ResearchPlanItem>): ResearchPlanValidationResult;
+export declare function validateResearchEvidenceEntry(entry: Partial<ResearchEvidenceEntry>): ResearchPlanValidationResult;
+export declare function evaluateResearchLedger(item: ResearchPlanItem, evidence: readonly ResearchEvidenceEntry[]): ResearchLedgerVerdict;

package/dist/types/rlm/artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { RlmArtifactPaths } from "./types";
+export declare const RLM_DIR_SEGMENT = "rlm";
+export declare function isValidRlmSessionId(sessionId: string): boolean;
+/** Generate a filesystem-safe, sortable session id (timestamp + random suffix). */
+export declare function generateRlmSessionId(now?: Date): string;
+export declare function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArtifactPaths;
+export declare function ensureRlmSessionDir(paths: RlmArtifactPaths): Promise<void>;
+export declare function rlmSessionExists(cwd: string, sessionId: string): Promise<boolean>;
+export declare function readRlmNotebookIfPresent(cwd: string, sessionId: string): Promise<import("../edit/notebook").NotebookDocument | undefined>;