@gajae-code/coding-agent 0.6.5 → 0.7.1

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

@@ -0,0 +1,276 @@
+import * as fs from "node:fs";
+import type { Settings } from "../config/settings";
+import type { DaemonRuntimeInfo } from "../daemon/control-types";
+import { type AliasTable, type CallbackRoute, type PendingAsk } from "./telegram-reference";
+export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled";
+export interface DaemonState {
+    pid: number;
+    ownerId: string;
+    tokenFingerprint: string;
+    chatId: string;
+    startedAt: number;
+    heartbeatAt: number;
+    roots: string[];
+    version: 1;
+    stoppedAt?: number;
+}
+export interface DaemonPaths {
+    dir: string;
+    lock: string;
+    state: string;
+    roots: string;
+    steal: string;
+    aliases: string;
+}
+export interface TelegramDaemonFs {
+    mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<void>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, opts?: fs.WriteFileOptions): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    open(path: string, flags: string, mode?: number): Promise<{
+        close(): Promise<void>;
+    }>;
+    readdir(path: string): Promise<string[]>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+export interface SpawnResult {
+    unref?: () => void;
+}
+export interface TelegramDaemonDeps {
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    pidAlive?: (pid: number) => boolean;
+    spawn?: (command: string, args: string[], opts: {
+        detached: boolean;
+        stdio: "ignore";
+        logPath?: string;
+    }) => SpawnResult;
+    execPath?: string;
+    randomId?: () => string;
+}
+export declare const HEARTBEAT_INTERVAL_MS = 5000;
+export declare const HEARTBEAT_TTL_MS = 20000;
+export declare const DAEMON_VERSION = 1;
+/** Capability token advertised when the server supports app-level ping/pong. */
+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;
+export declare function registerNotificationRoot(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+    fs?: TelegramDaemonFs;
+}): Promise<string>;
+export declare function isFreshLiveOwner(input: {
+    state: DaemonState | undefined;
+    now: number;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+}): boolean;
+export declare function acquireDaemonOwnership(input: {
+    settings: Settings;
+    roots?: string[];
+    tokenFingerprint: string;
+    chatId: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    pidAlive?: (pid: number) => boolean;
+    randomId?: () => string;
+}): Promise<{
+    acquired: boolean;
+    ownerId?: string;
+    attached?: boolean;
+}>;
+export declare function renewDaemonHeartbeat(input: {
+    settings: Settings;
+    ownerId: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+}): Promise<boolean>;
+export declare function releaseDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+}): Promise<void>;
+/** Read the persisted daemon ownership state (or undefined when absent). */
+export declare function readDaemonState(settings: Settings, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
+/** Read the persisted notification roots list. */
+export declare function readDaemonRoots(settings: Settings, fs?: TelegramDaemonFs): Promise<string[]>;
+export interface TelegramSpawnOwnerInput {
+    settings: Settings;
+    roots?: string[];
+    tokenFingerprint: string;
+    chatId: string;
+}
+export interface TelegramSpawnOwnerResult {
+    result: EnsureDaemonResult;
+    ownerId?: string;
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+}
+/**
+ * Build the detached spawn command/args for the daemon-internal entrypoint.
+ * Source mode prepends the entry script so the respawn loads edited source;
+ * a compiled binary self-spawns its own subcommand directly.
+ */
+export declare function buildTelegramDaemonSpawnArgs(input: {
+    execPath?: string;
+    ownerId: string;
+    agentDir: string;
+}): {
+    command: string;
+    args: string[];
+    runtime: DaemonRuntimeInfo;
+};
+/**
+ * Acquire ownership for the given Telegram identity and, if acquired, spawn a
+ * fresh detached daemon process. Does NOT register notification roots; callers
+ * that own a session (autostart) register roots separately, while reload reuses
+ * already-persisted roots.
+ */
+export declare function spawnTelegramDaemonOwner(input: TelegramSpawnOwnerInput, deps?: TelegramDaemonDeps): Promise<TelegramSpawnOwnerResult>;
+export declare function ensureTelegramDaemonRunning(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+}, deps?: TelegramDaemonDeps): Promise<EnsureDaemonResult>;
+export interface BotApi {
+    call(method: string, body: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/**
+ * Cooperative control seam for the daemon run loop. Implemented by the
+ * daemon-internal CLI / controller against the owner-scoped control-request
+ * file so the daemon does not import the control module directly.
+ */
+export interface DaemonControlHooks {
+    /** Returns true when a stop/reload has been requested for this owner. */
+    shouldStop(ownerId: string): Promise<boolean>;
+    /** Clear a consumed control request (best-effort). */
+    clear?(ownerId: string): Promise<void>;
+}
+export interface TelegramDaemonOptions {
+    settings: Settings;
+    ownerId: string;
+    botToken: string;
+    chatId: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    fs?: TelegramDaemonFs;
+    WebSocketImpl?: typeof WebSocket;
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+    idleTimeoutMs?: number;
+    scanIntervalMs?: number;
+    pid?: number;
+    botApi?: BotApi;
+    control?: DaemonControlHooks;
+}
+interface SessionSocket {
+    sessionId: string;
+    token: string;
+    ws: WebSocket;
+    pending: Map<string, {
+        sessionId: string;
+        actionId: string;
+    }>;
+    /** True once the server advertised the `client_ping_pong` capability. */
+    capable: boolean;
+    /** Timestamp (via opts.now) of the last received pong; seeds the TTL window. */
+    lastPongAt: number;
+    /** Nonce of the most recent in-flight ping, if any. */
+    awaitingNonce: string | undefined;
+    /** Per-session liveness interval handle (only set for capable sessions). */
+    pingTimer: ReturnType<typeof setInterval> | undefined;
+}
+export declare class TelegramNotificationDaemon {
+    private readonly opts;
+    readonly aliasTable: AliasTable;
+    readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+    readonly sessions: Map<string, SessionSocket>;
+    private running;
+    private offset;
+    private readonly fsImpl;
+    private readonly botApi;
+    private readonly topics;
+    private readonly pool;
+    private readonly seenUpdateIds;
+    private flushTimer;
+    private scanTimer;
+    private scanning;
+    private typingTimer;
+    /** Sessions whose agent loop is currently busy (drives the typing indicator). */
+    private readonly 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;
+    /**
+     * 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;
+    constructor(opts: TelegramDaemonOptions);
+    loadAliases(): Promise<void>;
+    persistAliases(): Promise<void>;
+    scanRoots(): Promise<void>;
+    connectSession(sessionId: string, url: string, token: string): void;
+    /**
+     * Start ack-based liveness for a session whose server advertised the
+     * `client_ping_pong` capability. Each interval drops the session when no pong
+     * has arrived within the TTL (the half-open case the socket never signals via
+     * `close`), otherwise sends a fresh application-level ping. The timer is bound
+     * to this exact session object.
+     */
+    private startLiveness;
+    /**
+     * Idempotent, identity-guarded session teardown. Clears the liveness timer,
+     * removes the map entry only when it still points at this exact session object
+     * (so a delayed old close cannot delete a replacement), and best-effort closes
+     * the socket. `scanRoots()` then reconnects the session.
+     */
+    private dropSession;
+    private static readonly THREADED_FRAMES;
+    private topicNameFor;
+    private ensureTopic;
+    private persistTopics;
+    loadTopics(): Promise<void>;
+    private flushPool;
+    private startFlushTimer;
+    private stopFlushTimer;
+    private runScan;
+    private startScanTimer;
+    private stopScanTimer;
+    private sendTyping;
+    private setReaction;
+    private startTypingTimer;
+    private stopTypingTimer;
+    handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
+    pendingBySession: (sessionId?: string) => PendingAsk[];
+    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>;
+    private controlStopRequested;
+}
+export {};

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

@@ -0,0 +1,111 @@
+/**
+ * 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;
+}
+/** A rendered Telegram message for an `action_needed`. */
+export interface RenderedMessage {
+    text: string;
+    inline_keyboard?: InlineButton[][];
+}
+/** 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;
+export interface CallbackRoute {
+    sessionId: string;
+    actionId: string;
+    answer: number | string;
+}
+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[];
+    summary?: string;
+}): RenderedMessage;
+/** A protocol `reply` frame the client should send to the server. */
+export interface ReplyFrame {
+    type: "reply";
+    id: string;
+    answer: number | string;
+    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 PendingAsk {
+    sessionId: string;
+    actionId: string;
+}
+export interface RouteInboundContext {
+    aliasTable: Pick<AliasTable, "get">;
+    messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+    pendingBySession: (sessionId?: string) => PendingAsk[];
+    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}` from an endpoint discovery file. */
+export declare function readEndpoint(path: string): {
+    url: string;
+    token: string;
+};
+/** 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>;

package/dist/types/notifications/threaded-inbound.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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;
+        chat?: {
+            id?: unknown;
+        };
+        message_thread_id?: unknown;
+    };
+}
+/** 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;
+} | {
+    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,66 @@
+/**
+ * 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";
+    /** Rate-limit lane for prioritisation/fairness. */
+    lane: RateLimitLane;
+    /** Message text (sendMessage) or photo caption (sendPhoto). */
+    text?: string;
+    /** Base64 image bytes for sendPhoto. */
+    photoBase64?: string;
+    /** Image MIME type for sendPhoto. */
+    mime?: 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;
+}
+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;
+    phase?: unknown;
+    text?: unknown;
+    messageRef?: unknown;
+    source?: unknown;
+    data?: unknown;
+    mime?: unknown;
+    caption?: unknown;
+    verbosity?: unknown;
+    redact?: 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,67 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each GJC 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
+ * 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 topic title (for rename detection). */
+    name?: 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 a serialized state into this registry, preserving all persisted fields. */
+    load(state: TopicRegistryState): void;
+    /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+    sessionForTopic(topicId: string): string | undefined;
+    /** 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`.
+     */
+    getOrCreateTopic(sessionId: string, create: () => Promise<string>, now?: () => number): 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;
+    /**
+     * Record the topic's applied title. Returns `true` when it changed (so the
+     * caller should `editForumTopic`), `false` when already current or unknown.
+     */
+    applyName(sessionId: string, name: string): boolean;
+    /** Serialise for atomic persistence beside the daemon state. */
+    serialize(): TopicRegistryState;
+}

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

@@ -31,5 +31,17 @@ export declare function buildRlmGoalObjective(input: {
 }): string;
 export declare function isRlmAutonomousRun(parsed: Pick<Args, "print" | "mode" | "messages">, pipedStdin: boolean): boolean;
 export declare function prepareRlmLaunchMode(parsed: Args, pipedStdin: boolean): boolean;
+/**
+ * RLM artifacts are scoped under a GJC session directory and resolving their
+ * paths is a *write* (it must pick a concrete session). When `gjc rlm` runs
+ * standalone — no parent agent, no `GJC_SESSION_ID` in the environment — there is
+ * no session to resolve and `resolveGjcSessionForWrite` throws
+ * `missing_for_write`. Establish a dedicated GJC session id in that case and pin
+ * it into the environment so artifact-path resolution, the per-session activity
+ * marker, and the child agent's workflow state all share one writable session.
+ *
+ * Returns the resolved (existing or freshly generated) GJC session id.
+ */
+export declare function ensureRlmGjcSessionId(): string;
 export declare function runRlmCommand(argv: string[]): Promise<void>;
 export {};

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

@@ -71,7 +71,7 @@ import { type AgentRegistry } from "../registry/agent-registry";
 import { type DiscoverableMCPSearchIndex, type DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
 import { type SecretObfuscator } from "../secrets/obfuscator";
 import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
-import type { ToolSession } from "../tools";
+import type { AskAnswerSource, ToolSession } from "../tools";
 import type { CheckpointState } from "../tools/checkpoint";
 import { type TodoItem, type TodoPhase } from "../tools/todo-write";
 import type { ClientBridge } from "./client-bridge";
@@ -128,6 +128,9 @@ export type AgentSessionEvent = AgentEvent | {
 } | {
     type: "irc_message";
     message: CustomMessage;
+} | {
+    type: "subagent_steer_message";
+    message: CustomMessage;
 } | {
     type: "notice";
     level: "info" | "warning" | "error";
@@ -558,6 +561,7 @@ export declare class AgentSession {
     getGoalModeState(): GoalModeState | undefined;
     setGoalModeState(state: GoalModeState | undefined): void;
     getWorkflowGateEmitter(): WorkflowGateEmitter | undefined;
+    getAskAnswerSource(): AskAnswerSource | undefined;
     setWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void;
     get goalRuntime(): GoalRuntime;
     markPlanReferenceSent(): void;
@@ -713,12 +717,38 @@ export declare class AgentSession {
     }): Promise<void>;
     setActiveModelProfile(name: string | undefined): void;
     getActiveModelProfile(): string | undefined;
+    /**
+     * The model selector ("provider/id") that resume restores as the session
+     * default — the latest session-log `model_change` with role="default".
+     * Model-profile activation snapshots this before mutating the session so a
+     * failed-activation rollback can restore the pre-activation resume default
+     * instead of promoting a transient runtime model to the resume default.
+     */
+    getSessionDefaultModelSelector(): string | undefined;
+    /**
+     * Re-assert the session resume default ("provider/id") in the session log
+     * WITHOUT touching the live runtime model. Appends a `model_change` with
+     * role="default"; never writes to global settings (apply-for-this-session
+     * semantics). Used by model-profile activation rollback to neutralize the
+     * profile main model the failed activation already recorded as the default.
+     */
+    recordResumeDefaultModel(selector: string): void;
     /**
      * Set model temporarily (for this session only).
      * Validates API key, saves to session log but NOT to settings.
+     *
+     * The change is recorded in the session log as `role: "temporary"` by
+     * default, which means it is NOT restored as the session default on resume —
+     * transient retry/fallback/context-promotion/plan switches must not clobber
+     * the user's explicit pick (issue #849). Model-profile activation passes
+     * `persistAsSessionDefault: true` so the profile's main model becomes the
+     * session default and survives resume, while still not being written to
+     * global settings (new sessions keep the global default).
      * @throws Error if no API key available for the model
      */
-    setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel): Promise<void>;
+    setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {
+        persistAsSessionDefault?: boolean;
+    }): Promise<void>;
     /**
      * Cycle to next/previous model.
      * Uses scoped models (from --models flag) if available, otherwise all available models.
@@ -946,6 +976,13 @@ export declare class AgentSession {
      * Does not persist the record to history. Public so other sessions can forward.
      */
     emitIrcRelayObservation(record: CustomMessage): void;
+    emitSubagentSteerObservation(args: {
+        from: string;
+        to: string;
+        body: string;
+        timestamp?: number;
+    }): void;
+    emitSubagentSteerRelayObservation(record: CustomMessage): void;
     /**
      * Run a single ephemeral side-channel turn against this session's current
      * model + system prompt + history.  No tools are used; the side request

package/dist/types/session/auth-storage.d.ts

@@ -2,5 +2,5 @@
  * Re-exports from @gajae-code/ai.
  * All credential storage types and the AuthStorage class now live in the ai package.
  */
-export type { ApiKeyCredential, AuthCredential, AuthCredentialEntry, AuthCredentialStore, AuthStorageData, AuthStorageOptions, OAuthCredential, SerializedAuthStorage, StoredAuthCredential, } from "@gajae-code/ai";
+export type { ApiKeyCredential, AuthCredential, AuthCredentialEntry, AuthCredentialIfAbsentReason, AuthCredentialIfAbsentResult, AuthCredentialIfAbsentSnapshotResult, AuthCredentialStore, AuthStorageData, AuthStorageOptions, OAuthCredential, SerializedAuthStorage, StoredAuthCredential, } from "@gajae-code/ai";
 export { AuthBrokerClient, AuthStorage, REMOTE_REFRESH_SENTINEL, RemoteAuthCredentialStore, SqliteAuthCredentialStore, } from "@gajae-code/ai";