@gajae-code/coding-agent 0.10.2 → 0.11.0

package/dist/types/modes/shared/agent-wire/workflow-gate-broker.d.ts

@@ -1,14 +1,12 @@
 import type { AskSelectedAckOutcome } from "../../../tools";
-import type { RpcWorkflowGate, RpcWorkflowGateContext, RpcWorkflowGateKind, RpcWorkflowGateOption, RpcWorkflowGateResolution, RpcWorkflowGateResponse, RpcWorkflowGateValidationError, RpcWorkflowStage } from "../../rpc/rpc-types";
+import type { WorkflowGate, WorkflowGateContext, WorkflowGateDiagnostic, WorkflowGateKind, WorkflowGateOption, WorkflowGateQueryRecord, WorkflowGateResolution, WorkflowGateResponse, WorkflowGateValidationError, WorkflowStage } from "./workflow-gate-types";
 export type PersistedSemanticDisposition = "commit" | "resolve_without_commit";
 export type PersistedResolutionOrigin = {
     kind: "generic";
-    channel: "rpc" | "bridge" | "other";
+    channel: "sdk" | "other";
 } | {
     kind: "telegram_notification";
     interactionActionId: string;
-} | {
-    kind: "legacy_unknown";
 };
 export type PersistedAckPolicy = {
     kind: "none";
@@ -27,51 +25,153 @@ export interface GateResolutionOptions {
     ackPolicy?: PersistedAckPolicy;
     beforeAdvance?: () => Promise<void>;
 }
+export type WorkflowGateTerminalProof = "retired" | "already_terminal" | "not_published";
+export interface WorkflowGateTerminalController {
+    completeGateInteractions(gateId: string): WorkflowGateTerminalProof | Promise<WorkflowGateTerminalProof>;
+    cancelGateInteractions(gateId: string, reason: string): void | Promise<void>;
+}
+export interface NotificationGateResolutionOptions {
+    interactionActionId: string;
+    replyReceiptId: string;
+    answerJson: string;
+    idempotencyKey?: string;
+    requestSelectedAck(input: {
+        replyReceiptId: string;
+        actionId: string;
+        commitKey: string;
+        daemonDeadlineAt: number;
+        hostTimeoutMs: number;
+    }): Promise<AskSelectedAckOutcome>;
+    resolveClaim(): void;
+    closeClaimInvalid(reason: string): void;
+}
+export interface AskSelectedAckRecoveryParticipant {
+    requestRecoveredAskSelectedAck(input: {
+        sessionId: string;
+        actionId: string;
+        commitKey: string;
+        deadlineAt: number;
+        hostTimeoutMs: number;
+    }): Promise<AskSelectedAckOutcome>;
+}
+/** SDK-native surface for emitting a workflow gate and awaiting its answer. */
+export interface WorkflowGateEmitter {
+    isUnattended(): boolean;
+    emitGate(input: OpenGateInput): Promise<unknown>;
+    onGateEmitted?(listener: (gate: WorkflowGate) => void): () => void;
+    resolveGate?(response: WorkflowGateResponse): Promise<WorkflowGateResolution>;
+    resolveGateFromNotification?(response: WorkflowGateResponse, options: NotificationGateResolutionOptions): Promise<WorkflowGateResolution>;
+    registerGateTerminalController?(controller: WorkflowGateTerminalController): () => void;
+    /** Records the exact terminalization proof established by direct control preparation. */
+    prepareTerminalization?(gateId: string, proof: WorkflowGateTerminalProof): boolean;
+    /** Discards a prepared proof when the gate remains pending after a rejected direct response. */
+    clearPreparedTerminalization?(gateId: string): void;
+    listPendingGates?(): WorkflowGate[];
+    listGateDiagnostics?(): WorkflowGateDiagnostic[];
+    listWorkflowGateQueryRecords?(): WorkflowGateQueryRecord[];
+    quarantineGate?(gateId: string): void;
+    setAckRecoveryParticipant?(participant: AskSelectedAckRecoveryParticipant | null): void;
+    /** Explicit host hook for same-process accepted-but-unadvanced recovery. */
+    recoverAcceptedGates?(): Promise<string[]>;
+    /** Permanently revoke all in-process continuation authority and reject their waiters. */
+    fence?(): void;
+    /** Temporarily make this emitter unavailable while a session transition is reversible. */
+    suspend?(): void;
+    resume?(): void;
+}
+/**
+ * SDK-native workflow-gate emitter backed by a durable broker/store pair.
+ *
+ * Answers are resolved by the broker, so validation and idempotency have one
+ * authority. Listeners replay durable pending gates when attached, allowing an
+ * SDK host that starts after a gate was opened to discover it.
+ */
+export declare class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
+    #private;
+    constructor(runId: string, store: GateStore, emitterHooks?: Pick<BrokerHooks, "advance">);
+    isUnattended(): boolean;
+    emitGate(input: OpenGateInput): Promise<unknown>;
+    onGateEmitted(listener: (gate: WorkflowGate) => void): () => void;
+    resolveGate(response: WorkflowGateResponse): Promise<WorkflowGateResolution>;
+    prepareTerminalization(gateId: string, proof: WorkflowGateTerminalProof): boolean;
+    clearPreparedTerminalization(gateId: string): void;
+    listPendingGates(): WorkflowGate[];
+    listGateDiagnostics(): WorkflowGateDiagnostic[];
+    listWorkflowGateQueryRecords(): WorkflowGateQueryRecord[];
+    suspend(): void;
+    resume(): void;
+    fence(): void;
+    quarantineGate(gateId: string): void;
+    registerGateTerminalController(controller: WorkflowGateTerminalController): () => void;
+    setAckRecoveryParticipant(participant: AskSelectedAckRecoveryParticipant | null): void;
+    recoverAcceptedGates(): Promise<string[]>;
+    resolveGateFromNotification(response: WorkflowGateResponse, options: NotificationGateResolutionOptions): Promise<WorkflowGateResolution>;
+}
 export interface PersistedGate {
-    gate: RpcWorkflowGate;
-    status: "pending" | "accepted";
+    gate: WorkflowGate;
+    status: "pending" | "accepted" | "quarantined";
+    ownerInstanceId?: string;
     idempotencyKey?: string;
     responseHash?: string;
-    /** Raw accepted answer, retained so a crashed advance can be replayed. */
+    /** Raw accepted answer, retained so a same-process advance can be replayed. */
     answer?: unknown;
-    resolution?: RpcWorkflowGateResolution;
+    resolution?: WorkflowGateResolution;
     advanced: boolean;
+    /** Exact presentation terminalization completed before workflow advancement. */
+    terminalized?: boolean;
+    /** Exact presentation terminalization proof recorded before workflow advancement. */
+    terminalProof?: WorkflowGateTerminalProof;
     semanticDisposition?: PersistedSemanticDisposition;
     resolutionOrigin?: PersistedResolutionOrigin;
     ackPolicy?: PersistedAckPolicy;
+    lifecycle?: WorkflowGateDiagnostic["lifecycle"];
 }
 export interface GateStore {
-    nextSeq(stage: RpcWorkflowStage): number;
+    nextSeq(stage: WorkflowStage): number;
     put(record: PersistedGate): void;
     get(gateId: string): PersistedGate | undefined;
-    /** All persisted gate records (used for crash recovery). */
+    /** Atomically quarantines records owned by a prior runtime before exposure. */
+    beginRuntimeInstance(instanceId: string): void;
+    /** All persisted gate records (used for same-process recovery and Q12). */
     list(): PersistedGate[];
 }
 export declare class MemoryGateStore implements GateStore {
     private counters;
     private gates;
-    nextSeq(stage: RpcWorkflowStage): number;
+    private runtimeInstanceId;
+    nextSeq(stage: WorkflowStage): number;
     put(record: PersistedGate): void;
     get(gateId: string): PersistedGate | undefined;
+    beginRuntimeInstance(instanceId: string): void;
     list(): PersistedGate[];
 }
+/** A write may have reached `rename` but not the directory fsync durability barrier. */
+export declare class GateStoreWriteError extends Error {
+    readonly certainty: "not_committed" | "uncertain";
+    constructor(certainty: "not_committed" | "uncertain", cause: unknown);
+}
 /** Crash-durable JSON-file backed store. Writes the full state on every mutation. */
 export declare class FileGateStore implements GateStore {
     private readonly filePath;
+    private readonly sync;
     private state;
-    constructor(filePath: string);
+    private certaintyUnknown;
+    constructor(filePath: string, sync?: (fd: number) => void);
     private load;
-    private flush;
-    nextSeq(stage: RpcWorkflowStage): number;
+    private flushState;
+    private commit;
+    private reconcileCertainty;
+    nextSeq(stage: WorkflowStage): number;
     put(record: PersistedGate): void;
     get(gateId: string): PersistedGate | undefined;
+    beginRuntimeInstance(instanceId: string): void;
     list(): PersistedGate[];
 }
 export type GateAuditEvent = {
     event: "gate_emitted";
     gate_id: string;
-    stage: RpcWorkflowStage;
-    kind: RpcWorkflowGateKind;
+    stage: WorkflowStage;
+    kind: WorkflowGateKind;
 } | {
     event: "gate_response_accepted";
     gate_id: string;
@@ -98,49 +198,88 @@ export type GateAuditEvent = {
 };
 export interface BrokerHooks {
     /** Called once when a pending gate has been persisted and should be emitted. */
-    emit?(gate: RpcWorkflowGate): void;
+    emit?(gate: WorkflowGate): void;
     /**
      * Invoked to advance the workflow after an accepted resolution is durably
      * committed. MUST be idempotent keyed by `gate.gate_id`: `recover()` replays
      * it for any gate left `accepted` but not `advanced` by a crash.
      */
-    advance?(gate: RpcWorkflowGate, answer: unknown): void | Promise<void>;
-    /** Runs after durable acceptance and before advance, including crash recovery. */
+    advance?(gate: WorkflowGate, answer: unknown): void | Promise<void>;
+    /** Runs after durable acceptance and before presentation terminalization, including crash recovery. */
     finalizeAccepted?(record: PersistedGate): Promise<void>;
+    /**
+     * Terminalizes the exact presentation before `advance` can run and returns
+     * proof for the durable record. `not_published` explicitly proves that no
+     * presentation existed. On failure it MUST revoke authority or throw.
+     */
+    terminalizeAccepted?(record: PersistedGate): WorkflowGateTerminalProof | Promise<WorkflowGateTerminalProof>;
+    /** Runs only after a successful advance has been durably marked advanced. */
+    completeAccepted?(record: PersistedGate): void | Promise<void>;
     /** Append-only audit sink. */
     audit?(event: GateAuditEvent): void;
 }
+/** Live in-process continuation authority for one emitted gate. */
+export interface GateContinuation {
+    activate(gate: WorkflowGate): void;
+    isLive(gateId: string): boolean;
+    release?(gateId: string): void;
+    /** Explicitly declares that this direct continuation owns no presentation. */
+    terminalProof?: "not_published";
+}
 export interface OpenGateInput {
-    stage: RpcWorkflowStage;
-    kind: RpcWorkflowGateKind;
-    schema: RpcWorkflowGate["schema"];
-    options?: RpcWorkflowGateOption[];
-    context?: RpcWorkflowGateContext;
+    stage: WorkflowStage;
+    kind: WorkflowGateKind;
+    schema: WorkflowGate["schema"];
+    options?: WorkflowGateOption[];
+    context?: WorkflowGateContext;
+    /** Optional diagnostic gate replaced by this newly persisted gate. */
+    supersedesGateId?: string;
 }
 export declare class WorkflowGateBrokerError extends Error {
     readonly code: "unknown_gate" | "already_resolved" | "idempotency_conflict" | "invalid_workflow_stage";
     constructor(code: "unknown_gate" | "already_resolved" | "idempotency_conflict" | "invalid_workflow_stage", message: string);
 }
 export declare class WorkflowGateBroker {
+    #private;
     private readonly runId;
     private readonly store;
     private readonly hooks;
+    private readonly instanceId;
     private readonly recovering;
     private readonly gateLocks;
+    private readonly continuations;
     private withGateLock;
-    constructor(runId: string, store: GateStore, hooks?: BrokerHooks);
+    constructor(runId: string, store: GateStore, hooks?: BrokerHooks, instanceId?: `${string}-${string}-${string}-${string}-${string}`);
     classifyDisposition(gateId: string, answer: unknown): PersistedSemanticDisposition;
-    validationError(gateId: string, keyword: string, message: string): RpcWorkflowGateValidationError;
+    validationError(gateId: string, keyword: string, message: string): WorkflowGateValidationError;
     updateAckPolicy(gateId: string, ackPolicy: PersistedAckPolicy): void;
     private runShort;
+    private hasLiveContinuation;
+    hasRecoverableAcceptedGate(): boolean;
+    prepareTerminalization(gateId: string, proof: WorkflowGateTerminalProof): boolean;
+    clearPreparedTerminalization(gateId: string): void;
+    /**
+     * Fences a gate after an uncertain control outcome by deliberately releasing
+     * this runtime's continuation authority. The durable diagnostic is retained
+     * for recovery; it is never republished as a pending gate.
+     */
+    quarantineGate(gateId: string): void;
+    /** Revoke every live continuation, including accepted-but-unadvanced recovery authority. */
+    fenceContinuations(): void;
+    /** Fence a cancelled/lost continuation before it can be exposed or advanced. */
+    loseContinuation(gateId: string): void;
+    listPendingGates(): WorkflowGate[];
+    listGateDiagnostics(): WorkflowGateDiagnostic[];
+    listWorkflowGateQueryRecords(): WorkflowGateQueryRecord[];
     /** Open and emit a gate. The pending record is persisted BEFORE emission. */
-    openGate(input: OpenGateInput): RpcWorkflowGate;
+    openGate(input: OpenGateInput, continuation?: GateContinuation): WorkflowGate;
     /**
      * Resolve a gate with an answer. Validates against the advertised schema.
-     * On success the resolution is persisted BEFORE `advance` is invoked exactly
-     * once. Invalid answers leave the gate pending (per #315 acceptance).
+     * Accepted answers are persisted first, then their presentation is terminalized,
+     * then the workflow advances and commits `advanced:true` exactly once. Invalid
+     * answers leave the gate pending (per #315 acceptance).
      */
-    resolve(response: RpcWorkflowGateResponse, options?: GateResolutionOptions): Promise<RpcWorkflowGateResolution>;
+    resolve(response: WorkflowGateResponse, options?: GateResolutionOptions): Promise<WorkflowGateResolution>;
     private resolveUnlocked;
     /**
      * Recover any gate left `accepted` but not `advanced` by a crash between the

package/dist/types/modes/shared/agent-wire/workflow-gate-schema.d.ts

@@ -1,4 +1,4 @@
-import type { RpcJsonSchema, RpcWorkflowGateValidationError } from "../../rpc/rpc-types";
+import type { JsonSchema, WorkflowGateValidationError } from "./workflow-gate-types";
 export declare const GATE_SCHEMA_LIMITS: {
     readonly maxSchemaBytes: number;
     readonly maxDepth: 16;
@@ -13,10 +13,10 @@ export declare class WorkflowGateSchemaError extends Error {
 }
 /** Canonical (stable-key-ordered) JSON serialization used for hashing. */
 export declare function canonicalJson(value: unknown): string;
-export declare function schemaHash(schema: RpcJsonSchema): string;
+export declare function schemaHash(schema: JsonSchema): string;
 declare function answerHashOf(answer: unknown): string;
 /** Validate the schema *shape*. Throws WorkflowGateSchemaError on any problem. */
-export declare function assertSupportedGateSchema(schema: RpcJsonSchema): void;
+export declare function assertSupportedGateSchema(schema: JsonSchema): void;
 type SchemaError = {
     path: string;
     keyword: string;
@@ -25,15 +25,15 @@ type SchemaError = {
 };
 /** A compiled, cached validator for one schema. */
 export interface CompiledGateSchema {
-    readonly schema: RpcJsonSchema;
+    readonly schema: JsonSchema;
     readonly hash: string;
     validate(answer: unknown): SchemaError[];
 }
 /** Compile (and cache) a validator for a schema. Asserts shape on first compile. */
-export declare function compileGateSchema(schema: RpcJsonSchema): CompiledGateSchema;
+export declare function compileGateSchema(schema: JsonSchema): CompiledGateSchema;
 /**
  * Validate an answer against a compiled gate schema. Returns `null` on success
- * or a typed {@link RpcWorkflowGateValidationError} on mismatch.
+ * or a typed {@link WorkflowGateValidationError} on mismatch.
  */
-export declare function validateGateAnswer(compiled: CompiledGateSchema, gateId: string, answer: unknown): RpcWorkflowGateValidationError | null;
+export declare function validateGateAnswer(compiled: CompiledGateSchema, gateId: string, answer: unknown): WorkflowGateValidationError | null;
 export { answerHashOf };

package/dist/types/modes/shared/agent-wire/workflow-gate-types.d.ts

@@ -0,0 +1,105 @@
+/** Transport-neutral workflow gate contract used by SDK workflow coordination. */
+/** Lifecycle stages that emit machine-addressable SDK workflow gates. */
+export type WorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export declare const RESERVED_WORKFLOW_STAGES: readonly string[];
+export type WorkflowGateKind = "question" | "approval" | "execution";
+/** The documented JSON Schema 2020-12 subset supported by the gate validator. */
+export interface JsonSchema {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+}
+export interface WorkflowGateOption {
+    value: unknown;
+    label: string;
+    description?: string;
+}
+export interface WorkflowGateContext {
+    title?: string;
+    plan?: string;
+    source?: string;
+    prompt?: string;
+    summary?: string;
+    stage_state?: Record<string, unknown>;
+    artifact_refs?: Array<{
+        kind: string;
+        path?: string;
+        sha256?: string;
+    }>;
+    language?: string;
+}
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface WorkflowGate {
+    type: "workflow_gate";
+    gate_id: string;
+    stage: WorkflowStage;
+    kind: WorkflowGateKind;
+    schema: JsonSchema;
+    schema_hash: string;
+    options?: WorkflowGateOption[];
+    context: WorkflowGateContext;
+    created_at: string;
+    required: true;
+}
+/** Non-actionable durable-gate state retained for restart diagnostics. */
+export interface WorkflowGateLifecycle {
+    state: "quarantined";
+    reason: "orphaned_after_process_restart" | "accepted_unadvanced_after_process_restart" | "continuation_owner_lost" | "opened_without_continuation" | "finalization_failed" | "advance_failed";
+    quarantinedAt: string;
+    supersededByGateId?: string;
+}
+/** A quarantined gate is diagnostic-only and must never be presented or answered. */
+export interface WorkflowGateDiagnostic extends WorkflowGate {
+    id: string;
+    tag: "quarantined";
+    lifecycle: WorkflowGateLifecycle;
+}
+/** Stable Q12 row preserving the root WorkflowGate shape. */
+export type WorkflowGateQueryRecord = (WorkflowGate & {
+    id: string;
+    tag: "pending";
+    lifecycle?: undefined;
+}) | WorkflowGateDiagnostic;
+/** Inbound: the agent's answer to a workflow gate. */
+export interface WorkflowGateResponse {
+    gate_id: string;
+    answer: unknown;
+    idempotency_key?: string;
+}
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface WorkflowGateResolution {
+    gate_id: string;
+    status: "accepted" | "rejected";
+    answer_hash: string;
+    resolved_at: string;
+    error?: WorkflowGateValidationError;
+}
+/** Typed error shape for schema validation failures. */
+export interface WorkflowGateValidationError {
+    code: "invalid_workflow_gate_answer";
+    gate_id: string;
+    schema_hash: string;
+    errors: Array<{
+        path: string;
+        keyword: string;
+        message: string;
+        expected?: unknown;
+    }>;
+}

package/dist/types/modes/types.d.ts

@@ -9,6 +9,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { Skill } from "../extensibility/skills";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { MCPManager } from "../runtime-mcp";
+import type { NotificationSessionReconcileResult, NotificationSessionStatus } from "../sdk/bus/session-control";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
@@ -80,6 +81,10 @@ export interface InteractiveModeContext {
     historyStorage?: HistoryStorage;
     mcpManager?: MCPManager;
     lspServers?: LspStartupServerInfo[];
+    /** Shared controller query; absent in ACP/lightweight test contexts. */
+    getCurrentSessionNotificationStatus?(): NotificationSessionStatus | undefined;
+    /** Toggle only the current session; absent in ACP/lightweight test contexts. */
+    setCurrentSessionNotificationsEnabled?(enabled: boolean): Promise<NotificationSessionReconcileResult | undefined>;
     readonly ircLedger: IrcObservationLedger;
     isInitialized: boolean;
     isBackgrounded: boolean;

package/dist/types/runtime-mcp/client.d.ts

@@ -5,6 +5,8 @@ import type { MCPGetPromptResult, MCPPrompt, MCPRequestOptions, MCPResource, MCP
  */
 export declare function connectToServer(name: string, config: MCPServerConfig, options?: {
     signal?: AbortSignal;
+    /** Whether to advertise the roots/list capability (default: true). */
+    advertiseRoots?: boolean;
     onNotification?: (method: string, params: unknown) => void;
     onRequest?: (method: string, params: unknown) => Promise<unknown>;
 }): Promise<MCPServerConnection>;

package/dist/types/runtime-mcp/config.d.ts

@@ -13,8 +13,10 @@ export interface LoadMCPConfigsOptions {
     filterExa?: boolean;
     /** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
     filterBrowser?: boolean;
-    /** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+    /** Only include startup-eligible servers; exact-config sessions always enforce autoload !== false. */
     autoloadOnly?: boolean;
+    /** Load only this explicit MCP config file. */
+    configPath?: string;
 }
 /** Result of loading MCP configs */
 export interface LoadMCPConfigsResult {
@@ -24,6 +26,8 @@ export interface LoadMCPConfigsResult {
     exaApiKeys: string[];
     /** Source metadata for each server */
     sources: Record<string, SourceMeta>;
+    /** Whether the explicit configuration was unavailable or contained invalid entries. */
+    configurationWarning: boolean;
 }
 /**
  * Load all MCP server configs from standard locations.

package/dist/types/runtime-mcp/manager.d.ts

@@ -42,6 +42,12 @@ export interface MCPDiscoverOptions {
     autoloadOnly?: boolean;
     /** Called when starting to connect to servers */
     onConnecting?: (serverNames: string[]) => void;
+    /** Load only this explicit MCP config file. */
+    configPath?: string;
+}
+export interface MCPManagerOptions {
+    /** Restrict this instance to tools from an explicit MCP config. */
+    toolsOnly?: boolean;
 }
 /**
  * MCP Server Manager.
@@ -58,7 +64,8 @@ export declare class MCPManager {
     static setInstance(value: MCPManager | undefined): void;
     /** Reset the process-global instance. Test-only. */
     static resetForTests(): void;
-    constructor(cwd: string, toolCache?: MCPToolCache | null);
+    constructor(cwd: string, toolCache?: MCPToolCache | null, options?: MCPManagerOptions);
+    isToolsOnly(): boolean;
     /**
      * Set a callback to receive all server notifications.
      */

package/dist/types/runtime-mcp/types.d.ts

@@ -187,6 +187,10 @@ export interface MCPToolCallResult {
     content: MCPContent[];
     isError?: boolean;
 }
+/** Expected configured-server transport or protocol failure. */
+export declare class MCPExpectedFailure extends Error {
+    constructor(cause?: unknown);
+}
 export interface MCPRequestOptions {
     /** Abort signal (e.g. Escape-to-interrupt) */
     signal?: AbortSignal;

package/dist/types/sdk/acp/adapter.d.ts

@@ -0,0 +1,67 @@
+import { SdkClient, SdkClientError, type SdkFrame } from "../client";
+type JsonObject = Record<string, unknown>;
+/** The small agent-side ACP surface used for reverse requests. */
+export interface AcpReverseConnection {
+    request?(method: string, params: JsonObject): Promise<unknown>;
+    [key: string]: unknown;
+}
+export interface AcpProviderRegistration {
+    capability: string;
+    definitions: unknown;
+}
+export interface AcpSdkAdapterOptions {
+    url: string;
+    token: string;
+    client?: SdkClient;
+    connection?: AcpReverseConnection;
+    providers?: AcpProviderRegistration[];
+    /** Lease IDs persisted by the ACP host across a WebSocket reconnect. */
+    expectedLeaseIds?: Record<string, string>;
+    heartbeatMs?: number;
+    reverseCancelTtlMs?: number;
+}
+export declare class AcpSdkAdapterError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
+export type AcpFrameHandler = (frame: SdkFrame) => void;
+/**
+ * Pure ACP-to-SDK adapter. It deliberately owns neither an AgentSession nor an
+ * ACP bridge: all session work is performed through authenticated v3 frames.
+ */
+export declare class AcpSdkAdapter {
+    #private;
+    constructor(options: AcpSdkAdapterOptions);
+    static connect(options: AcpSdkAdapterOptions): Promise<AcpSdkAdapter>;
+    get leaseIds(): ReadonlyMap<string, string>;
+    get connectionId(): string | undefined;
+    onReconnectFailed(handler: AcpReconnectFailedHandler): () => void;
+    onFrame(handler: AcpFrameHandler): () => void;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    prompt(params: JsonObject | string): Promise<unknown>;
+    cancel(): Promise<unknown>;
+    setModel(params: JsonObject | string): Promise<unknown>;
+    control(operation: string, input?: JsonObject): Promise<unknown>;
+    query(query: string, input?: JsonObject, cursor?: string): Promise<unknown>;
+    global(operation: string, input?: JsonObject, idempotencyKey?: string): Promise<unknown>;
+    sdkControl(params: {
+        operation: string;
+        input?: JsonObject;
+    }): Promise<unknown>;
+    sdkQuery(params: {
+        query: string;
+        input?: JsonObject;
+        cursor?: string;
+    }): Promise<unknown>;
+    sdkGlobal(params: {
+        operation: string;
+        input?: JsonObject;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    /** Dispatches the ACP extension method names without exposing endpoint credentials. */
+    handle(method: string, params?: JsonObject): Promise<unknown>;
+    registerProvider(provider: AcpProviderRegistration): Promise<void>;
+}
+export {};

package/dist/types/sdk/acp/index.d.ts

@@ -0,0 +1,2 @@
+export type { AcpProviderRegistration, AcpReverseConnection, AcpSdkAdapterOptions } from "./adapter";
+export { AcpSdkAdapter, AcpSdkAdapterError } from "./adapter";

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

@@ -0,0 +1,53 @@
+import { type BrokerDiscovery, redactBrokerDiscovery } from "./discovery";
+import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
+import { SessionIndex } from "./session-index";
+export interface BrokerSettings {
+    agentDir: string;
+    packageGeneration?: string;
+    port?: number;
+    heartbeatTtlMs?: number;
+}
+export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export type BrokerCleanupEvidence = {
+    phase: "artifacts" | "transcript" | "metadata";
+    artifactsIdentity?: {
+        dev: string;
+        ino: string;
+    };
+    transcriptIdentity?: {
+        dev: string;
+        ino: string;
+    };
+};
+export type BrokerResponse = {
+    ok: true;
+    result?: unknown;
+    indexSeq?: number;
+} | {
+    ok: false;
+    error: {
+        code: BrokerErrorCode;
+        message: string;
+        endpoint?: "unavailable";
+        cleanup?: BrokerCleanupEvidence;
+    };
+    indexSeq?: number;
+    durableEffects?: LifecycleDurableEffectsReceipt;
+    startupFailure?: LifecycleStartupFailureReceipt;
+};
+export declare class Broker {
+    #private;
+    readonly settings: Required<BrokerSettings>;
+    readonly index: SessionIndex;
+    readonly ledger: LifecycleLedger;
+    discovery: BrokerDiscovery | null;
+    constructor(settings: BrokerSettings);
+    start(): Promise<BrokerDiscovery>;
+    get ownsDiscovery(): boolean;
+    status(): ReturnType<typeof redactBrokerDiscovery> | null;
+    heartbeat(): Promise<void>;
+    stop(): Promise<void>;
+    handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse>;
+}
+/** Test-only hook for simulating a process crash after terminal persistence verification. */
+export declare function setTerminalPersistenceHookForTest(broker: Broker, hook: (() => void) | undefined): void;