@sayknow-cli/coding-agent 0.3.1 → 0.3.2

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

@@ -0,0 +1,98 @@
+import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
+import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
+/** Minimal view of the native control server this runtime depends on. */
+export interface ControlServerLike {
+    onLifecycleRequest(cb: (err: Error | null, req: {
+        kind: string;
+        requestId: string;
+        payloadJson: string;
+    }) => void): void;
+    respond(responseJson: string): void;
+}
+/**
+ * A startable control server (the native NotificationControlServer, or a fake in
+ * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
+ * daemon owns.
+ */
+export interface LifecycleControlServer extends ControlServerLike {
+    start(): Promise<unknown>;
+    stop(): void;
+}
+/** Factory the daemon uses to construct a control server bound to its ownership. */
+export type LifecycleControlServerFactory = (input: {
+    token: string;
+    ownerId: string;
+    agentDir: string;
+}) => LifecycleControlServer;
+/** Atomic + fsynced file-backed idempotency ledger store. */
+export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
+/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
+export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
+/** Simple per-chat sliding-window create rate limiter. */
+export declare function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean;
+/** Build the `skc` argv for a create target (existing path / worktree / dir).
+ *
+ *  The launched session id is carried via `SKC_SESSION_ID` in the child env (see
+ *  {@link daemonSpawnCreate}); the root `skc` launcher has no `--session-id`
+ *  flag, so it must never appear in argv. Only flags the launch parser actually
+ *  supports are emitted (`--worktree <branch>` for worktree targets). */
+export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}): {
+    cwd: string;
+    args: string[];
+};
+/** Real daemon-safe tmux launcher: detached `tmux new-session -d` + SKC tags. */
+export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv): (frame: SessionCreateFrame, ids: {
+    lifecycleRequestId: string;
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}) => Promise<CreateEffectResult>;
+/** Real force-close effect (SKC-managed only, id-matched). */
+export declare function daemonCloseSession(env?: NodeJS.ProcessEnv): (target: {
+    sessionId: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+}) => Promise<{
+    processGone: boolean;
+}>;
+/** Real resume effect: reattach if a live SKC session matches; else resolve the
+ *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
+ *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
+export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
+    sessionsRoot?: string;
+}): (target: {
+    sessionIdOrPrefix: string;
+    path?: string;
+}) => Promise<ResumeEffectResult | {
+    ambiguous: ResumeCandidate[];
+} | {
+    notFound: true;
+}>;
+/** Translate an orchestrator outcome into a wire response frame. */
+export declare function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse;
+/**
+ * Wire a control server's lifecycle requests through the orchestrator.
+ *
+ * Handlers run on a single serial queue (a promise chain): the daemon owns the
+ * one control endpoint, so serializing here makes each request's ledger
+ * read -> classify -> write atomic with respect to every other request. Two
+ * identical updates that arrive nearly simultaneously can no longer both
+ * classify as `new` and both spawn — the second sees the first's persisted
+ * `in_progress`/`success` entry and re-acks instead.
+ */
+export declare function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void;
+/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
+export declare function buildOrchestratorDeps(input: {
+    pairedChatId: string;
+    agentNotificationsDir: string;
+    /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
+    sessionsRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps;
+/**
+ * Default production factory: a real native NotificationControlServer bound to
+ * the daemon's control token, owner id, and agent dir.
+ */
+export declare const createNativeControlServer: LifecycleControlServerFactory;

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

@@ -0,0 +1,144 @@
+import type { LifecycleErrorReason, ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest } from "./index";
+/** Durable idempotency state for a single lifecycle request. */
+export type LedgerState = "in_progress" | "success" | "failure" | "terminal_uncertain";
+/** One persisted idempotency entry, keyed by `chatId:updateId`. */
+export interface LedgerEntry {
+    requestHash: string;
+    state: LedgerState;
+    requestId: string;
+    verb: SessionLifecycleRequest["type"];
+    intendedSessionId?: string;
+    startupPromptRef?: string;
+    createdAt: number;
+    updatedAt: number;
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+    endpointUrl?: string;
+    /** Close effect outcome: whether the tmux process is confirmed gone. */
+    processGone?: boolean;
+    reason?: LifecycleErrorReason;
+}
+/** The full on-disk ledger document. */
+export interface LedgerDoc {
+    version: 1;
+    entries: Record<string, LedgerEntry>;
+}
+/** Persistence boundary: atomic + fsynced read/write of the ledger document. */
+export interface LedgerStore {
+    read(): Promise<LedgerDoc>;
+    /** Write atomically (temp + fsync + rename) under a per-ledger lock. */
+    write(doc: LedgerDoc): Promise<void>;
+}
+/** One audit line. Tokens and raw prompts are NEVER included. */
+export interface AuditEvent {
+    ts: string;
+    event: "accepted" | "rejected" | "duplicate_reack" | "rate_limited" | "spawn_started" | "recovered_in_progress" | "success" | "failure" | "terminal_uncertain";
+    chatId: string;
+    updateId: number;
+    requestId: string;
+    requestHash: string;
+    verb: SessionLifecycleRequest["type"];
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    reason?: LifecycleErrorReason;
+    /** Prompt byte length only (never the prompt text). */
+    promptBytes?: number;
+    /** Prompt content hash only (never the prompt text). */
+    promptHash?: string;
+}
+export interface CreateEffectResult {
+    sessionId: string;
+    tmuxSession: string;
+    sessionStateFile?: string;
+    endpointUrl: string;
+    topicThreadId: string;
+}
+export interface ResumeEffectResult extends CreateEffectResult {
+    mode: "reattached" | "cold_restarted";
+}
+/** Injected effects + policy. Pure orchestration calls into these. */
+export interface OrchestratorDeps {
+    /** The single paired chat id. Anything else is rejected before parsing. */
+    pairedChatId: string;
+    now: () => number;
+    store: LedgerStore;
+    audit: (event: AuditEvent) => Promise<void> | void;
+    /** Per-chat create rate limiter: returns true when allowed. */
+    allowCreate: (chatId: string, nowMs: number) => boolean;
+    /** Persist the once-consumed 0600 startup-prompt file; returns its ref. */
+    writeStartupPrompt: (requestId: string, prompt: string | undefined) => Promise<string | undefined>;
+    /** Spawn a session for a create/cold-restart. */
+    spawnCreate: (frame: SessionCreateFrame, ids: {
+        lifecycleRequestId: string;
+        intendedSessionId: string;
+        startupPromptRef?: string;
+    }) => Promise<CreateEffectResult>;
+    closeSession: (target: {
+        sessionId: string;
+        tmuxSession?: string;
+        sessionStateFile?: string;
+    }) => Promise<{
+        processGone: boolean;
+    }>;
+    resumeSession: (target: {
+        sessionIdOrPrefix: string;
+        path?: string;
+    }) => Promise<ResumeEffectResult | {
+        ambiguous: ResumeCandidate[];
+    } | {
+        notFound: true;
+    }>;
+    newLifecycleRequestId: () => string;
+    newSessionId: () => string;
+}
+/** A redaction-safe summary of a request target (never includes the token). */
+export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
+/**
+ * Stable request hash over the meaningful (non-token) request content. Used to
+ * detect a duplicate update id reused with a DIFFERENT body (conflict).
+ */
+export declare function requestHash(frame: SessionLifecycleRequest): string;
+export declare function ledgerKey(chatId: string, updateId: number): string;
+/** How a freshly-arrived request relates to the durable ledger. */
+export type DuplicateClass = {
+    kind: "new";
+} | {
+    kind: "reack_success";
+    entry: LedgerEntry;
+} | {
+    kind: "reack_failure";
+    entry: LedgerEntry;
+} | {
+    kind: "in_progress";
+    entry: LedgerEntry;
+} | {
+    kind: "terminal_uncertain";
+    entry: LedgerEntry;
+} | {
+    kind: "conflict";
+    entry: LedgerEntry;
+};
+/** Classify a request against an existing ledger entry (pure). */
+export declare function classifyDuplicate(existing: LedgerEntry | undefined, hash: string): DuplicateClass;
+/** The structured outcome the daemon translates into a wire response frame. */
+export type LifecycleOutcome = {
+    status: "ok";
+    entry: LedgerEntry;
+    mode?: "reattached" | "cold_restarted";
+} | {
+    status: "error";
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+} | {
+    status: "pending";
+    entry: LedgerEntry;
+};
+/**
+ * Handle one authenticated lifecycle request. Enforces paired-chat gating,
+ * idempotency, and rate limiting BEFORE any side effect, then dispatches.
+ */
+export declare function handleLifecycleRequest(frame: SessionLifecycleRequest, deps: OrchestratorDeps): Promise<LifecycleOutcome>;

package/dist/types/notifications/operator-runtime.d.ts

@@ -0,0 +1,52 @@
+export interface NotificationOperatorTimerDeps {
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+}
+export interface NotificationOperatorRuntimeState {
+    running: boolean;
+    stopRequested: boolean;
+    activeAbort: boolean;
+}
+export interface OperatorBackoffOptions {
+    initialMs: number;
+    maxMs: number;
+    factor?: number;
+}
+export declare class OperatorBackoffPolicy {
+    #private;
+    constructor(opts: OperatorBackoffOptions);
+    next(): number;
+    reset(): void;
+    get currentMs(): number;
+}
+export interface OperatorRoute<TContext> {
+    name: string;
+    matches(event: Record<string, unknown>): boolean;
+    handle(context: TContext, event: Record<string, unknown>): Promise<void> | void;
+}
+export declare class OperatorEventRouter<TContext> {
+    readonly routes: OperatorRoute<TContext>[];
+    add(input: OperatorRoute<TContext>): this;
+    dispatch(context: TContext, event: Record<string, unknown>): Promise<boolean>;
+}
+export declare class NotificationOperatorRuntime {
+    #private;
+    constructor(deps?: NotificationOperatorTimerDeps);
+    get state(): NotificationOperatorRuntimeState;
+    start(): void;
+    stop(): void;
+    requestStop(): void;
+    get running(): boolean;
+    get stopRequested(): boolean;
+    createAbortController(): AbortController;
+    clearAbortController(controller: AbortController): void;
+    startInterval(name: string, intervalMs: number, tick: () => void): void;
+    stopInterval(name: string): void;
+    stopAllIntervals(): void;
+    runExclusive(name: string, fn: () => Promise<void>): Promise<void>;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    now(): number;
+}

package/dist/types/notifications/rate-limit-pool.d.ts

@@ -81,6 +81,8 @@ export declare class RateLimitPool<T = unknown> {
      * single session monopolises a lane), consuming one token each.
      */
     drain(nowMs?: number): RateLimitItem<T>[];
+    /** Remove queued items matching `predicate` without consuming tokens. Returns removed items in lane/FIFO order. */
+    removeWhere(predicate: (item: RateLimitItem<T>) => boolean): RateLimitItem<T>[];
     private refill;
     /** Pop the next item by lane priority + per-session round-robin fairness. */
     private takeNext;

package/dist/types/notifications/recent-activity.d.ts

@@ -0,0 +1,35 @@
+/** One ranked recent-session entry surfaced to the picker. */
+export interface RecentSessionEntry {
+    /** Session id (the `.jsonl` file stem). */
+    sessionId: string;
+    /** Working directory / repo path, when recoverable from the header. */
+    path?: string;
+    /** Branch, when recoverable from the header. */
+    branch?: string;
+    /** A short title (first user message), when recoverable. */
+    title?: string;
+    /** Absolute path of the session history (state) file. */
+    sessionStateFile: string;
+    /** Last-activity epoch-millis (history file mtime). */
+    mtimeMs: number;
+    /** True when a terminal breadcrumb points at this session file. */
+    currentTerminal?: boolean;
+}
+export interface RecentActivityDeps {
+    /** Root holding `<encoded-cwd>/<sessionId>.jsonl` history files. */
+    sessionsRoot: string;
+    /** Optional breadcrumb session-file paths (current terminals). */
+    breadcrumbPaths?: string[];
+    /** Max entries to return (default 20). */
+    limit?: number;
+    /** Injection seam for tests. */
+    readFirstLine?: (file: string) => string | undefined;
+}
+/**
+ * List recent sessions ranked by history-file mtime (newest first).
+ *
+ * Scans `<sessionsRoot>/<encoded-cwd>/<sessionId>.jsonl`, stats each file, and
+ * returns up to `limit` entries enriched with header metadata and a
+ * `currentTerminal` flag for any breadcrumb-referenced session file.
+ */
+export declare function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry[];

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

@@ -1,6 +1,8 @@
 import * as fs from "node:fs";
 import type { Settings } from "../config/settings";
 import type { DaemonRuntimeInfo } from "../daemon/control-types";
+import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
+import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute, type PendingAsk } from "./telegram-reference";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled";
 export interface DaemonState {
@@ -58,6 +60,22 @@ export declare const CLIENT_PING_PONG_CAPABILITY = "client_ping_pong";
 /** Protocol version the daemon advertises in its ClientHello. */
 export declare const NOTIFICATION_PROTOCOL_VERSION = 2;
 export declare function daemonPaths(agentDir: string): DaemonPaths;
+/**
+ * Attach session-lifecycle control (create/close/resume) to the running daemon.
+ *
+ * Wires an already-started, authenticated control server to the lifecycle
+ * orchestrator with real daemon-side effects (tmux launcher / force-close /
+ * resume), a durable fsynced idempotency ledger + audit JSONL under the agent
+ * notifications dir, and strict paired-chat gating. The control server itself
+ * (NotificationControlServer) is owned/started by the daemon process; this
+ * function only connects it to policy. Returns the orchestrator deps for tests.
+ */
+export declare function startDaemonLifecycleControl(input: {
+    controlServer: ControlServerLike;
+    pairedChatId: string;
+    agentDir: string;
+    env?: NodeJS.ProcessEnv;
+}): void;
 export declare function registerNotificationRoot(input: {
     settings: Settings;
     cwd: string;
@@ -146,6 +164,40 @@ export interface BotApi {
         signal?: AbortSignal;
     }): Promise<unknown>;
 }
+export interface TelegramTransportOptions {
+    botToken: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    setTimeoutImpl?: typeof setTimeout;
+}
+/** Telegram Bot API transport: HTTP JSON/multipart details stay out of daemon orchestration. */
+export declare class TelegramBotTransport implements BotApi {
+    #private;
+    constructor(opts: TelegramTransportOptions);
+    call(method: string, body: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface TelegramUpdatePollerOptions {
+    botApi: BotApi;
+    runtime: NotificationOperatorRuntime;
+    backoff: OperatorBackoffPolicy;
+    processUpdate: (update: unknown) => Promise<void>;
+}
+/** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
+export declare class TelegramUpdatePoller {
+    #private;
+    constructor(opts: TelegramUpdatePollerOptions);
+    pollOnce(signal?: AbortSignal): Promise<number>;
+}
+/** Mutable dispatch state shared by session frames and inbound Telegram updates. */
+export declare class TelegramEventDispatchState {
+    readonly busy: Set<string>;
+    readonly inboundReactions: Map<number, {
+        messageId: number;
+    }>;
+    readonly seenUpdateIds: Set<number>;
+}
 /**
  * Cooperative control seam for the daemon run loop. Implemented by the
  * daemon-internal CLI / controller against the owner-scoped control-request
@@ -174,8 +226,17 @@ export interface TelegramDaemonOptions {
     idleTimeoutMs?: number;
     scanIntervalMs?: number;
     pid?: number;
+    /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
+    pidAlive?: (pid: number) => boolean;
     botApi?: BotApi;
     control?: DaemonControlHooks;
+    /**
+     * Factory for the session-lifecycle control server. Defaults to the real
+     * native NotificationControlServer; tests inject a fake to verify the
+     * owner-bound start/stop lifecycle without a socket. When `undefined` AND no
+     * default applies (e.g. lifecycle control disabled), no control server starts.
+     */
+    createLifecycleControlServer?: LifecycleControlServerFactory | null;
 }
 interface SessionSocket {
     sessionId: string;
@@ -199,40 +260,72 @@ export declare class TelegramNotificationDaemon {
     readonly aliasTable: AliasTable;
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
     readonly sessions: Map<string, SessionSocket>;
+    private readonly runtime;
+    private readonly sessionRouter;
+    private readonly pollConflictBackoff;
+    private readonly loopBackoff;
     private running;
-    private offset;
     private readonly fsImpl;
     private readonly botApi;
     private readonly topics;
     private readonly pool;
-    private readonly seenUpdateIds;
+    private readonly poller;
+    private readonly dispatchState;
+    /** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
+    private readonly topicOwnerByIdentity;
+    /** Non-identity frames held until identity creates the correct thread. */
+    private readonly pendingThreadedFrames;
     /** True once the daemon has nudged the user to enable Threaded Mode. */
     private threadedFallbackNoticeSent;
     /** Sessions whose identity header was already sent flat (Threaded Mode off). */
     private readonly flatIdentitySent;
     /** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
     private pairedChatPrivate;
-    private flushTimer;
-    private scanTimer;
-    private scanning;
-    private typingTimer;
     /** Sessions whose agent loop is currently busy (drives the typing indicator). */
-    private readonly busy;
+    private get busy();
     /** Inbound update id → originating Telegram message, for delivery reactions. */
-    private readonly inboundReactions;
-    /** AbortController for the in-flight long poll; aborted by requestStop() to wake the loop. */
-    private activePoll;
-    /** Set when a cooperative stop has been requested (signal or control request). */
-    private stopRequested;
-    /** Current bounded backoff after a Telegram getUpdates 409 conflict (0 when healthy). */
-    private pollConflictBackoffMs;
+    private get inboundReactions();
+    /**
+     * The owner-bound session-lifecycle control server (create/close/resume).
+     * Started in {@link run} after ownership is confirmed (so exactly one owner
+     * ever runs one), stopped in run()'s finally on any exit path.
+     */
+    private controlServer;
+    /** True while lifecycle control is active, so the loop keeps polling at idle. */
+    private lifecycleControlActive;
+    /** Control token (in-memory) the loopback client presents; never persisted/logged. */
+    private controlToken;
+    /** Loopback WS client to the daemon's own control endpoint (Option A real wire path). */
+    private controlClient;
+    /** Pending lifecycle responses awaiting a control-endpoint reply, by requestId. */
+    private readonly pendingLifecycle;
+    /** Monotonic counter for unique lifecycle request ids. */
+    private lifecycleSeq;
     /**
      * Cooperatively stop the daemon: set the stop flag and abort the in-flight
      * long poll so the run loop wakes immediately instead of waiting out the
      * ~25s getUpdates timeout. Safe to call from a signal handler.
      */
     requestStop(_reason?: "reload" | "stop" | "signal"): void;
+    private startLifecycleControl;
+    /** Stop the lifecycle control server (idempotent); called from run()'s finally. */
+    private stopLifecycleControl;
+    /**
+     * Connect the loopback control client and resolve responses by requestId.
+     * Resolves true once the socket is OPEN (bounded), false on error/timeout, so
+     * the caller only marks lifecycle control active when commands can be sent.
+     */
+    private connectControlClient;
+    /** Send a lifecycle frame over the loopback client and await the response. */
+    private submitLifecycleFrame;
+    private nextLifecycleRequestId;
+    /** Build an authenticated lifecycle frame from a parsed command + identity. */
+    private buildLifecycleFrame;
+    private handleLifecycleCommand;
+    /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
+    private formatLifecycleResponse;
     constructor(opts: TelegramDaemonOptions);
+    private createSessionRouter;
     loadAliases(): Promise<void>;
     persistAliases(): Promise<void>;
     scanRoots(): Promise<void>;
@@ -254,7 +347,14 @@ export declare class TelegramNotificationDaemon {
     private dropSession;
     private static readonly THREADED_FRAMES;
     private topicNameFor;
+    private topicIdentityKey;
+    private topicIdentityBase;
+    private topicOwnerForIdentity;
+    private submitThreadedFrame;
+    private rememberPendingThreadedFrame;
+    private flushPendingThreadedFrames;
     private ensureTopic;
+    private deleteTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
     private downloadTelegramFile;
@@ -285,8 +385,6 @@ export declare class TelegramNotificationDaemon {
     private sendStaleGuidance;
     handleTelegramUpdate(update: unknown): Promise<void>;
     pollOnce(signal?: AbortSignal): Promise<number>;
-    /** Abortable sleep honoring the injected timer; resolves early on abort. */
-    private sleep;
     /** Sync the bot's Telegram command menu to what the daemon actually handles. */
     registerBotCommands(): Promise<void>;
     run(): Promise<void>;

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

@@ -90,10 +90,12 @@ export interface RouteInboundContext {
 }
 /** 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}` from an endpoint discovery file. */
+/** 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 {

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

@@ -1,11 +1,11 @@
 /**
  * Per-session forum-topic registry for the threaded session surface.
  *
- * Each SKC session owns exactly one Telegram forum topic in the paired private
- * DM. The topic is created once (via `createForumTopic`) and REUSED on resume,
- * keyed by session id, so a resumed session streams back into its existing
- * thread/history. The registry also tracks whether the one-time identity header
- * has already been pinned, so it is sent exactly once per topic even across
+ * 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;
@@ -45,14 +45,15 @@ export declare class TopicRegistry {
     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 topic for `sessionId`, or create one via `create`
-     * (called only on first use). Reuse-on-resume: an existing record is
-     * returned without invoking `create`.
+     * 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): Promise<TopicRecord>;
+    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. */
@@ -62,6 +63,8 @@ export declare class TopicRegistry {
      * caller should `editForumTopic`), `false` when already current or unknown.
      */
     applyName(sessionId: string, name: string): boolean;
+    /** 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/runtime-mcp/types.d.ts

@@ -64,6 +64,13 @@ export interface MCPStdioServerConfig extends MCPServerConfigBase {
     command: string;
     args?: string[];
     env?: Record<string, string>;
+    /**
+     * When true, the child process is NOT given the host environment. Only a
+     * minimal OS allowlist (PATH/HOME/temp/locale) plus any explicit `env` keys
+     * are passed. Used for third-party plugin-bundle MCP servers so they cannot
+     * read host secrets from the inherited environment.
+     */
+    noInheritEnv?: boolean;
     cwd?: string;
 }
 /** HTTP server configuration (Streamable HTTP transport) */

package/dist/types/sdk.d.ts

@@ -10,6 +10,7 @@ import "./discovery";
 import type { CustomCommandsLoadResult } from "./extensibility/custom-commands";
 import type { CustomTool } from "./extensibility/custom-tools/types";
 import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "./extensibility/extensions";
+import { type ConstrainedPluginHook } from "./extensibility/skc-plugins/constrained-hooks";
 import { type Skill, type SkillWarning } from "./extensibility/skills";
 import type { FileSlashCommand } from "./extensibility/slash-commands";
 import type { HindsightSessionState } from "./hindsight/state";
@@ -240,4 +241,5 @@ export interface BuildSystemPromptOptions {
  * as separate entries so providers can cache prompt prefixes without concatenating blocks.
  */
 export declare function buildSystemPrompt(options?: BuildSystemPromptOptions): Promise<BuildSystemPromptResult>;
+export declare function createPluginHooksExtension(hooks: ConstrainedPluginHook[]): ExtensionFactory;
 export declare function createAgentSession(options?: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;