@gajae-code/coding-agent 0.13.2 → 0.14.0

package/dist/types/sdk/bus/telegram-reference.d.ts

@@ -1,18 +1,4 @@
-/**
- * Telegram **reference** client for the Gajae-Code SDK.
- *
- * This is an example/template, NOT an upstream-owned integration: it implements
- * the documented WS protocol (see `docs/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+).
- */
+/** Telegram transport and presentation helpers shared by the managed provider adapter. */
 /** One inline-keyboard button. */
 export interface InlineButton {
     text: string;
@@ -132,36 +118,4 @@ 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, pid?, stale?}` from an endpoint discovery file. */
-export declare function readEndpoint(path: string): {
-    url: string;
-    token: string;
-    pid?: number;
-    stale?: boolean;
-};
-/** A bounded, diagnostic-only notification mirrored to reference-client embedders. */
-export type TelegramReferenceDiagnostic = Readonly<{
-    code: "action_unavailable";
-    requiredCapabilities: readonly string[];
-}>;
-/** Options for {@link runTelegramReferenceClient}. */
-export interface TelegramReferenceOptions {
-    botToken: string;
-    chatId: string;
-    endpointFile: string;
-    apiBase?: string;
-    fetchImpl?: typeof fetch;
-    sound?: TelegramNotificationSound;
-    /**
-     * Additive mirror of bounded logger diagnostics. It never receives tokens,
-     * identifiers, raw frames, Telegram content, or WebSocket replies.
-     */
-    onDiagnostic?: (diagnostic: TelegramReferenceDiagnostic) => void;
-}
-/**
- * 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/sdk/bus/threaded-render.d.ts

@@ -56,6 +56,7 @@ interface ThreadedFrame {
     branch?: unknown;
     machine?: unknown;
     title?: unknown;
+    telegramTopicsEnabled?: unknown;
     lastMessage?: unknown;
     task?: unknown;
     goal?: unknown;

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -1,11 +1,12 @@
 /**
- * Per-session forum-topic registry for the threaded session surface.
+ * Forum-topic registry for eligible orchestration sessions on the threaded
+ * Telegram surface.
  *
- * Each GJC session owns one active Telegram forum topic. Remote archive closes
- * daemon-created topics without deleting their durable records; rotated
- * successors move inactive records into retained history before creating a new
- * active authority. The registry also tracks whether the one-time identity
- * header has already been pinned.
+ * Each eligible orchestration session owns one active Telegram forum topic.
+ * Remote archive closes daemon-created topics without deleting their durable
+ * records; rotated successors move inactive records into retained history before
+ * creating a new active authority. The registry also tracks whether the one-time
+ * identity header has already been pinned.
  *
  * 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
@@ -51,6 +52,10 @@ export interface TopicRecord {
     authorityState?: TopicLifecycleState;
     /** Telegram chat and endpoint authority last proven to use this topic. */
     chatId?: string;
+    /** Stable provider binding; never contains SDK endpoint or attachment identity. */
+    telegramBinding?: TelegramTopicBinding;
+    /** Why this record is archive-fenced; absence means no remote archive is authorized. */
+    archiveReason?: "session_closed" | "notification_subscription_removed" | "create_compensation";
     /** Canonical endpoint tuple (URL + token) that currently holds the lease. */
     endpointKey?: string;
     /** Authenticated endpoint authority digest, excluding transport presentation. */
@@ -78,6 +83,8 @@ export interface TopicCreateClaim {
     leaseOwner?: string;
     authorityEpoch: number;
     createdAt: number;
+    telegramBinding?: TelegramTopicBinding;
+    /** Legacy v2 input only; never emitted by serialize(). */
     binding?: TopicEndpointBinding;
 }
 export interface ArchiveJob {
@@ -103,8 +110,8 @@ export interface TopicRegistryState {
     topics: Record<string, TopicRecord>;
     /** Durable lifecycle epochs retained after an archive starts. */
     fences?: Record<string, number>;
-    /** Closed transport endpoint leases; unchanged endpoint discovery remains fenced across restart. */
-    closedEndpoints?: Record<string, TopicEndpointBinding>;
+    /** Closed durable Telegram bindings; values intentionally contain no SDK endpoint identity. */
+    closedEndpoints?: Record<string, TelegramTopicBinding>;
     /** Persistent host identity used to distinguish concurrent installations. */
     installationHostId?: string;
     /** Bounded durable archive work; no topic record is physically deleted. */
@@ -122,11 +129,20 @@ export interface TopicRegistryCasAuthority {
     read(): Promise<TopicRegistryState | undefined>;
     compareAndSet(expectedGeneration: number, next: TopicRegistryState): Promise<boolean>;
 }
+/** Durable Telegram authority. This is the only binding shape writers persist. */
+export interface TelegramTopicBinding {
+    chatId: string;
+    transport: "telegram";
+}
+export type TopicArchiveReason = NonNullable<TopicRecord["archiveReason"]>;
 /** Authenticated runtime binding for a durable topic lease. */
 export interface TopicEndpointBinding {
     chatId: string;
-    endpointKey: string;
-    endpointDigest: string;
+    transport?: "telegram";
+    logicalSessionId?: string;
+    /** Legacy input-only fields. They are never authority or persistence fields. */
+    endpointKey?: string;
+    endpointDigest?: string;
     endpointGeneration?: number;
 }
 /** Discriminated durable endpoint authority for identity-less replay admission. */
@@ -239,9 +255,9 @@ export declare class TopicRegistry {
      * incumbents, cross-chat records, malformed evidence, collisions, and delete
      * fences remain fail-closed.
      */
-    bindEndpoint(sessionId: string, binding: TopicEndpointBinding, activeEndpointKeys?: ReadonlySet<string>, allowEndpointRotation?: boolean): "bound" | "unchanged" | "rejected";
+    bindEndpoint(sessionId: string, binding: TopicEndpointBinding, _activeEndpointKeys?: ReadonlySet<string>, _allowEndpointRotation?: boolean): "bound" | "unchanged" | "rejected";
     /** Undo a failed durable endpoint migration without disturbing concurrent metadata writers. */
-    restoreEndpointBinding(sessionId: string, expected: TopicEndpointBinding, previous: Pick<TopicRecord, "chatId" | "endpointKey" | "endpointDigest" | "endpointGeneration" | "endpointIncarnation">): boolean;
+    restoreEndpointBinding(sessionId: string, expected: TopicEndpointBinding, previous: Pick<TopicRecord, "chatId">): boolean;
     /**
      * Return the existing active topic for `sessionId`, or create one via
      * `create` (called only on first use).
@@ -296,28 +312,28 @@ export declare class TopicRegistry {
     /** Restore the exact archive fence after a failed compensation publication. */
     restoreArchiveFence(snapshot: TopicArchiveAuthoritySnapshot): boolean;
     /** Fence new work before the remote archive starts, including an absent in-flight create. */
-    beginArchive(sessionId: string, hostId?: string, now?: number): TopicRecord | undefined;
+    beginArchive(sessionId: string, hostId: string | undefined, now: number, reason: TopicArchiveReason): TopicRecord | undefined;
     /** Verify the durable archive initiator immediately before remote dispatch. */
     archiveAuthorityAllows(sessionId: string, hostId: string, pairedChatId: string, now: number): boolean;
     /** @deprecated Production dispatch must provide the current paired chat id. */
     archiveAuthorityAllows(sessionId: string, hostId: string, now: number): boolean;
     /** Retain an accepted create as deletion-fenced before remote compensation can begin. */
-    fenceAcceptedCreate(sessionId: string, topicId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string): TopicRecord;
+    fenceAcceptedCreate(sessionId: string, topicId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string, reason?: TopicArchiveReason): TopicRecord;
     /** Fence an accepted create only when its exact creator lease still owns the record. */
-    fenceAcceptedCreateForLease(sessionId: string, topicId: string, creationLeaseEpoch: number, hostId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string): TopicRecord | undefined;
+    fenceAcceptedCreateForLease(sessionId: string, topicId: string, creationLeaseEpoch: number, hostId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string, reason?: TopicArchiveReason): TopicRecord | undefined;
     /** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
     awaitInflight(sessionId: string): Promise<void>;
     /**
      * Retain a topic record after a definite remote archive only while the exact
      * dispatched authority epoch is still current.
      */
-    settleArchive(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number): boolean;
+    settleArchive(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number, reason: TopicArchiveReason): boolean;
     /** Durable archive jobs that are eligible for a retry at `now`. */
     archivePendingSessionIds(now?: number): string[];
     /** Durable/manual recovery candidates that exceeded the automatic archive retry budget. */
     archiveExhaustedSessionIds(): string[];
     /** Persist an indefinitely discoverable retry after an ambiguous archive result. */
-    scheduleArchiveRetry(sessionId: string, now: number, diagnostic?: string): ArchiveJob | undefined;
+    scheduleArchiveRetry(sessionId: string, now: number, reason: TopicArchiveReason, diagnostic?: string): ArchiveJob | undefined;
     /** Serialise active records plus unpublished staged creates for atomic commit. */
     serialize(): TopicRegistryState;
 }

package/dist/types/sdk/cli/rows.d.ts

@@ -4,9 +4,8 @@
  * Every semantic verb renders its output through these rows so machine
  * consumers get one deterministic, versioned envelope per verb. Credentials
  * are never part of the row schema: broker `session.list` rows carry no
- * credentials, offline inspect rows are projected from endpoint discovery
- * records with secret-shaped fields stripped before they can reach a row, and
- * pass-through host payloads are redacted recursively before rendering.
+ * credentials, and pass-through host payloads are redacted recursively before
+ * rendering.
  */
 export declare const SESSION_ROWS_VERSION = 1;
 export type SdkSessionActivityState = "active" | "idle";
@@ -80,14 +79,6 @@ export declare function stripSecretFields(value: unknown): unknown;
  * index shapes.
  */
 export declare function toSessionRowV1(value: unknown): SdkSessionRowV1;
-/**
- * Offline inspect row projected from a local SDK endpoint discovery record.
- * The discovery record carries the endpoint credential (`url`/`token`); neither
- * is ever projected into the row. `path` is the endpoint file
- * `<stateRoot>/sdk/<sessionId>.json`, so the state root is recovered from the
- * path when the layout matches.
- */
-export declare function toOfflineSessionRowV1(value: unknown): SdkSessionRowV1;
 export declare function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | undefined;
 export declare function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined;
 /** Projects a transcript entry or ring event into a tail item with dedupe keys. */

package/dist/types/sdk/cli/session-cli.d.ts

@@ -1,51 +1,41 @@
-import { type OperationKind } from "../protocol/operation-registry";
-export type SdkSessionCliAction = "list" | "inspect" | "send" | "status" | "tail" | "elevate" | "raw";
+import { SessionRouter } from "../router";
+export type SdkSessionCliAction = "list" | "inspect" | "send" | "status" | "tail" | "raw" | "control" | "query" | "global";
 export type SdkSessionCliRawKind = "control" | "query" | "global";
 export interface SdkSessionCliArgs {
     action?: string;
-    /** Raw dispatch kind when action is "raw" (control | query | global). */
     rawAction?: string;
     sessionId?: string;
-    /** Caller-chosen operation reference (ULID) for `send`; required target for `status`. */
     opRef?: string;
     operation?: string;
     query?: string;
-    /** Convenience `send` body: forwarded as the `text` field of turn.prompt. */
     text?: string;
     jsonInput?: string;
     jsonInputFile?: string;
     jsonInputStdin?: boolean;
     idempotencyKey?: string;
-    elevationRequestId?: string;
-    operationKind?: OperationKind;
     confirm?: boolean;
-    /** Raw query continuation cursor, or a saved checkpoint token to resume `tail` from (re-minted per connection). */
     cursor?: string;
-    showEndpointCredential?: boolean;
-    yes?: boolean;
-    /** `send --wait`: poll turn.prompt_status until terminal or the wait window elapses. */
     wait?: boolean;
-    /** Bounded wait for `send --wait`, `status`, and live `tail` follow. */
     timeoutMs?: number;
-    /** `tail --strict`: fail closed on retention gaps (exit 1 retention_gap). */
     strict?: boolean;
-    /** `tail --until-idle`: exit once the observed event stream reaches a terminal turn state. */
     untilIdle?: boolean;
-    /** `tail --all-events`: include every event-ring kind instead of the tail subset. */
     allEvents?: boolean;
     repo?: string;
     agentDir?: string;
 }
-/**
- * Time-ordered operation reference (ULID): 48-bit millisecond timestamp plus
- * 80 bits of randomness, Crockford base32, lowercase. The ref is used as the
- * `turn.prompt` clientRef so `send`/`status` correlate without a broker round
- * trip, and matches the plan's durable op-ref ledger shape (C7).
- */
+export interface RetainedTranscriptTailReader {
+    readonly size: number;
+    readRange(start: number, end: number): Promise<Uint8Array>;
+}
+/** Creates a lowercase ULID operation reference for prompt reconciliation. */
 export declare function createOperationRef(now?: number): string;
+/** Exported for tests: each status poll must stay inside the caller's wait window. */
+export declare function waitForTerminalStatus(router: SessionRouter, sessionId: string, clientRef: string, timeoutMs: number | undefined): Promise<{
+    terminal: boolean;
+    status: string;
+    detail: unknown;
+}>;
+export declare function scanRetainedTranscriptTail(reader: RetainedTranscriptTailReader): Promise<unknown[]>;
 export declare function runTail(repo: string, agentDir: string, sessionId: string, args: SdkSessionCliArgs): Promise<unknown>;
-/**
- * Runs the `gjc sdk session` command family: semantic verbs (list, inspect,
- * send, status, tail) plus the explicit raw control/query/global hatch.
- */
+/** Runs the broker-bound `gjc sdk session` command family without exposing endpoint credentials. */
 export declare function runSdkSessionCli(args: SdkSessionCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/client/client.d.ts

@@ -1 +1,97 @@
-export * from "@gajae-code/bridge-client";
+export type SdkErrorCode = "invalid_input" | "unknown_operation" | "not_found" | "unavailable" | "timeout" | "connection_closed" | "uncertain_after_send" | "endpoint_credential_forbidden" | (string & {});
+export declare class SdkClientError extends Error {
+    readonly code: SdkErrorCode;
+    readonly details: unknown;
+    /**
+     * Reconnect-cycle diagnostics, separate from `details` because `details` is an
+     * established contract: callers read the terminating transport error straight off
+     * it (`session-cli.ts` matches `details.code` against `ENOENT`/`ECONNREFUSED`, and
+     * lifecycle callers cast it to a sent record). Wrapping that value would silently
+     * break every such reader, so the new attribution rides alongside it instead.
+     */
+    readonly reconnect?: SdkReconnectExhaustedDetails;
+    constructor(code: SdkErrorCode, message: string, details?: unknown, reconnect?: SdkReconnectExhaustedDetails);
+}
+export type SdkReconnectTerminationReason = "attempts_exhausted" | "deadline" | "cancelled";
+/**
+ * Reconnect-cycle termination diagnostics. `attemptsConsumed` counts retry slots,
+ * not socket opens: the initial open is free, so the loop can open one more socket
+ * than `attemptBudget`. Both values are therefore directly comparable.
+ *
+ * `reason` is authoritative. `attemptsConsumed < attemptBudget` is corroborating
+ * evidence of truncation, not a classifier: a zero-attempt client that trips its
+ * deadline immediately reports `0 === 0` and is still deadline-terminated.
+ */
+export interface SdkReconnectExhaustedDetails {
+    readonly attemptsConsumed: number;
+    readonly attemptBudget: number;
+    readonly elapsedMs: number;
+    readonly reason: SdkReconnectTerminationReason;
+}
+/**
+ * Deadline a one-shot request client waits for a reply. Long-lived session
+ * clients override it per request; see `SESSION_REQUEST_TIMEOUT_MS`.
+ */
+export declare const DEFAULT_SDK_REQUEST_TIMEOUT_MS = 10000;
+export interface SdkClientOptions {
+    timeoutMs?: number;
+    /** Absolute wall-clock deadline shared by connect, hello, retry, and request work. */
+    deadline?: number;
+    reconnectAttempts?: number;
+    reconnectBackoffMs?: number;
+    /**
+     * Per-attempt ceiling for the exponential reconnect backoff. A long reconnect
+     * budget must keep probing frequently instead of sleeping for tens of seconds
+     * on its last attempts. Defaults to 2s.
+     */
+    reconnectMaxBackoffMs?: number;
+}
+export interface SdkRequestOptions {
+    timeoutMs?: number;
+    idempotencyKey?: string;
+    confirm?: boolean;
+}
+export type SdkFrame = Record<string, unknown>;
+/** Request identity retained after an uncertain send for lifecycle reconciliation. */
+export interface SdkSentRecord {
+    readonly id: string;
+    readonly operation?: string;
+    readonly idempotencyKey?: string;
+    readonly fingerprint: string;
+}
+export type SdkFrameHandler = (frame: SdkFrame) => void;
+export type SdkReconnectHandler = () => void;
+export type SdkReconnectFailedHandler = (error: SdkClientError) => void;
+/**
+ * Transport facts attached to a request timeout before an outcome is known.
+ * A timeout after send is surfaced as `uncertain_after_send` with an
+ * {@link SdkSentRecord} in its details.
+ */
+export interface SdkRequestTimeoutDetails {
+    requestId: string;
+    requestSent: boolean;
+}
+/** A transport-only v3 SDK WebSocket client with no host or session authority. */
+export declare class SdkClient {
+    #private;
+    connectionId?: string;
+    constructor(url: string, token: string, options?: SdkClientOptions);
+    static connect(url: string, token: string, options?: SdkClientOptions): Promise<SdkClient>;
+    connect(): Promise<void>;
+    /** Resolves once the current WebSocket has received its server hello frame. */
+    awaitHello(): Promise<void>;
+    onFrame(handler: SdkFrameHandler): () => void;
+    onReconnect(handler: SdkReconnectHandler): () => void;
+    onReconnectFailed(handler: SdkReconnectFailedHandler): () => void;
+    send(frame: SdkFrame): void;
+    request(frame: SdkFrame, timeout?: number | {
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<SdkFrame>;
+    close(): Promise<void>;
+    control(operation: string, input?: Record<string, unknown>, options?: SdkRequestOptions): Promise<unknown>;
+    query(query: string, input?: Record<string, unknown>, cursor?: string, options?: SdkRequestOptions): Promise<unknown>;
+    global(operation: string, input?: Record<string, unknown>, options?: SdkRequestOptions): Promise<unknown>;
+    getSentRecord(id: string): SdkSentRecord | undefined;
+    lookupLifecycle(record: SdkSentRecord, timeoutMs?: number): Promise<unknown>;
+}

package/dist/types/sdk/host/control/dispatch.d.ts

@@ -7,8 +7,6 @@ export interface ControlRequest {
     expectedRevision?: string;
     idempotencyKey?: string;
     confirm?: boolean;
-    /** Top-level elevation claim selector, preserved from the control frame. */
-    elevationRequestId?: string;
 }
 export type ControlErrorCode = string;
 export interface ControlError {
@@ -32,11 +30,6 @@ export declare class TypedControlError extends Error {
 export declare class BusyError extends TypedControlError {
     constructor(message?: string);
 }
-/**
- * Build the typed control request from a wire frame. Every runtime transport
- * mapper uses this helper so the top-level elevation claim selector cannot
- * drift between callsites.
- */
 export declare function controlRequestFromFrame(frame: Record<string, unknown>): ControlRequest;
 /** Dispatches a registry-defined per-session control operation. */
 export declare function dispatchControl(surface: ControlSurface, registryRow: Operation | undefined, request: ControlRequest): Promise<ControlResponse>;

package/dist/types/sdk/host/control/index.d.ts

@@ -1,2 +1,2 @@
 export { BusyError, type ControlError, type ControlErrorCode, type ControlRequest, type ControlResponse, controlRequestFromFrame, dispatchControl, TypedControlError, } from "./dispatch";
-export type { ControlInput, ControlSurface, ControlValue } from "./operations";
+export type { AbortScope, ControlInput, ControlSurface, ControlValue } from "./operations";

package/dist/types/sdk/host/control/operations.d.ts

@@ -1,19 +1,32 @@
 export type ControlValue = unknown;
+export type AbortMode = "turn" | "terminal";
+export type AbortScope = "turn" | "owned";
+/**
+ * Terminal-mode C04 `turn.abort` input. `scope` selects whether exact causal
+ * owned work (background Bash/task jobs, detached subagents) is also stopped
+ * (`"owned"`) or left running so its completion can resume the root worker
+ * (`"turn"`, the default).
+ */
+export interface TerminalAbortInput {
+    mode: "terminal";
+    scope?: AbortScope;
+}
 export type ControlInput = Record<string, unknown>;
 /**
  * Narrow host contract used by control dispatch. Implementations adapt an
  * AgentSession and its controllers without exposing those concrete types here.
  */
 export interface ControlSurface {
-    authorizeElevationClaim?(sdkId: string, input: ControlInput, capability: string): boolean;
     prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-    steer(text: string): Promise<ControlValue> | ControlValue;
+    steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
     followUp(text: string): Promise<ControlValue> | ControlValue;
     abort(): Promise<ControlValue> | ControlValue;
+    /** Terminal abort: stop the current root turn (and optionally exact owned work). */
+    abortTerminal?(input: TerminalAbortInput, idempotencyKey?: string): Promise<ControlValue> | ControlValue;
     abortAndPrompt(text: string): Promise<ControlValue> | ControlValue;
     answerAsk(id: string, answer: ControlValue): Promise<ControlValue> | ControlValue;
-    answerGate(id: string, response: ControlValue, expectedSessionId?: string, idempotencyKey?: string, elevationRequestId?: string): Promise<ControlValue> | ControlValue;
-    approvePlan(id: string, choice: ControlValue, expectedSessionId?: string, elevationRequestId?: string): Promise<ControlValue> | ControlValue;
+    answerGate(id: string, response: ControlValue, expectedSessionId?: string, idempotencyKey?: string): Promise<ControlValue> | ControlValue;
+    approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
     invokeSkill(name: string, args: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
     setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;
     operateGoal(op: string, objective?: string): Promise<ControlValue> | ControlValue;
@@ -34,7 +47,7 @@ export interface ControlSurface {
     newSession(): Promise<ControlValue> | ControlValue;
     forkSession(): Promise<ControlValue> | ControlValue;
     resumeSession(id: string): Promise<ControlValue> | ControlValue;
-    closeSession(): Promise<ControlValue> | ControlValue;
+    closeSession(capability?: string): Promise<ControlValue> | ControlValue;
     switchSession(id: string): Promise<ControlValue> | ControlValue;
     branchSession(entryId: string): Promise<ControlValue> | ControlValue;
     renameSession(name: string): Promise<ControlValue> | ControlValue;

package/dist/types/sdk/host/control/runtime-gate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Private field carried only on the Broker's endpoint close request.
+ *
+ * The value is the lifecycle effect marker bound to the serving process. It is
+ * never published in endpoint discovery or lifecycle service results; callers
+ * that do not hold the Broker's indexed lifecycle record cannot satisfy this
+ * gate.
+ */
+export declare const BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD = "__gjcBrokerCloseCapability";
+export declare function brokerRuntimeCloseCapability(input: unknown): string | undefined;
+/** Remove the private close capability before a request is exposed to diagnostics. */
+export declare function redactBrokerRuntimeCloseCapability(frame: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Runtime-local authority check for the Broker-only graceful close executor.
+ *
+ * A lifecycle child receives GJC_LIFECYCLE_REQUEST_ID from the Broker launch
+ * environment. Generic SDK requests never receive that private marker.
+ */
+export declare function hasBrokerRuntimeCloseCapability(input: unknown): boolean;

package/dist/types/sdk/host/host.d.ts

@@ -34,12 +34,21 @@ export type SessionActivationGate = (input: {
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
     control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
     query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+    /** Test/lifecycle seam invoked synchronously before fire-and-forget dispatch. */
+    onFrameAdmitted?: (connectionId: string, frame: SdkFrame) => void;
     /** Best-effort diagnostic observation of accepted control/query frames. */
     onRequest?: SdkRequestObserver;
     /** Runs before a control response is sent; identity transitions use sendTerminal. */
-    beforeControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame, sendTerminal: () => Promise<void>) => void | Promise<void>;
+    beforeControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame, sendTerminal: () => Promise<unknown>) => void | Promise<void>;
     /** Runs only after a successful control response has been sent to the client. */
     afterControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame) => void | Promise<void>;
+    /**
+     * Classifies the awaited control-response write exactly once: `written`
+     * (sent), `rejected` (the write threw), or `dropped` (the send adapter
+     * deliberately skipped delivery). `afterControlResponse` runs only
+     * on `written`. Used to persist monotonic response-state transitions.
+     */
+    onControlResponseDelivery?: (connectionId: string, request: SdkFrame, response: SdkFrame, outcome: "written" | "rejected" | "dropped") => void | Promise<void>;
     installProviderDefinitions?: (capability: string, definitions: unknown) => void;
     onProviderDefinitionsRemoved?: (capability: string) => void;
     onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
@@ -54,6 +63,11 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
      */
     activationGate?: SessionActivationGate;
 }
+/** Shared by the replay filter and transport live broadcasts: a connection
+ *  must see the same capability-gated event kinds on both legs, or live and
+ *  replay delivery diverge for the same subscriber. */
+export declare const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
+export declare const CAP_GATED_FRAME_KINDS: ReadonlySet<string>;
 /** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
 export declare function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env?: NodeJS.ProcessEnv): boolean;
 /** Adapter-based session host; bus wiring owns NotificationServer creation and transport framing. */

package/dist/types/sdk/host/query/handlers.d.ts

@@ -50,6 +50,11 @@ export interface SessionSurface {
         commandId?: string;
         turnId?: string;
     }): unknown | Promise<unknown>;
+    getSteerStatus?(selector: {
+        commandId?: string;
+        turnId?: string;
+        clientRef?: string;
+    }): unknown | Promise<unknown>;
     /** Q27 effective model-profile catalog from the live session registry. */
     getModelProfiles?(): unknown[] | Promise<unknown[]>;
     /**

package/dist/types/sdk/host/reverse-leases.d.ts

@@ -25,7 +25,7 @@ export interface ProviderLease {
 export interface ReverseLeaseOptions {
     now?: () => number;
     leaseTtlMs?: number;
-    sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+    sendFrame: (connectionId: string, frame: SdkFrame) => unknown;
     installDefinitions?: (capability: string, definitions: unknown) => void;
     onCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
     onDefinitionsRemoved?: (capability: string) => void;