@sayknow-cli/coding-agent 0.4.2 → 0.4.4

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

@@ -0,0 +1,353 @@
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Based on MCP specification 2025-03-26:
+ * https://modelcontextprotocol.io/specification/2025-03-26/
+ */
+import type { SourceMeta } from "../capability/types";
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/** Authentication configuration for MCP servers */
+export interface MCPAuthConfig {
+    /** Authentication type */
+    type: "oauth" | "apikey";
+    /** Credential ID for OAuth (references agent.db) */
+    credentialId?: string;
+    /** Token endpoint URL — persisted for proactive token refresh */
+    tokenUrl?: string;
+    /** Client ID — persisted for token refresh */
+    clientId?: string;
+    /** Client secret — persisted for token refresh */
+    clientSecret?: string;
+}
+/** Base server config with shared options */
+interface MCPServerConfigBase {
+    /** Whether this server is enabled (default: true) */
+    enabled?: boolean;
+    /**
+     * Whether an explicit runtime MCP consumer should connect this server
+     * automatically when that consumer starts (default: true). Normal standalone
+     * `skc`, `skc --tmux`, and print-mode sessions do not consume `skc mcp`
+     * registrations today.
+     */
+    autoload?: boolean;
+    /** Connection timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Authentication configuration (optional) */
+    auth?: MCPAuthConfig;
+    /** OAuth configuration for servers requiring explicit client credentials */
+    oauth?: {
+        clientId?: string;
+        clientSecret?: string;
+        redirectUri?: string;
+        callbackPort?: number;
+        callbackPath?: string;
+    };
+}
+/** Stdio server configuration */
+export interface MCPStdioServerConfig extends MCPServerConfigBase {
+    type?: "stdio";
+    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) */
+export interface MCPHttpServerConfig extends MCPServerConfigBase {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** SSE server configuration (deprecated, use HTTP) */
+export interface MCPSseServerConfig extends MCPServerConfigBase {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+export type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig | MCPSseServerConfig;
+export declare const MCP_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/jaybeyond/Sayknow_CLI/main/packages/coding-agent/src/config/mcp-schema.json";
+/** Root mcp.json/.mcp.json file structure */
+export interface MCPConfigFile {
+    $schema?: string;
+    mcpServers?: Record<string, MCPServerConfig>;
+    disabledServers?: string[];
+}
+/** MCP implementation info */
+export interface MCPImplementation {
+    name: string;
+    version: string;
+}
+/** MCP client capabilities */
+export interface MCPClientCapabilities {
+    roots?: {
+        listChanged?: boolean;
+    };
+    sampling?: Record<string, never>;
+    experimental?: Record<string, unknown>;
+}
+/** MCP server capabilities */
+export interface MCPServerCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, never>;
+    experimental?: Record<string, unknown>;
+}
+/** Initialize request params */
+export interface MCPInitializeParams {
+    protocolVersion: string;
+    capabilities: MCPClientCapabilities;
+    clientInfo: MCPImplementation;
+}
+/** Initialize response result */
+export interface MCPInitializeResult {
+    protocolVersion: string;
+    capabilities: MCPServerCapabilities;
+    serverInfo: MCPImplementation;
+    instructions?: string;
+}
+/** MCP tool definition */
+export interface MCPToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+}
+/** tools/list response */
+export interface MCPToolsListResult {
+    tools: MCPToolDefinition[];
+    nextCursor?: string;
+}
+/** tools/call params */
+export interface MCPToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** Content types in tool results */
+export interface MCPTextContent {
+    type: "text";
+    text: string;
+}
+export interface MCPImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface MCPResourceContent {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+/** tools/call response */
+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;
+}
+/** Transport interface - abstracts stdio/http */
+export interface MCPTransport {
+    /** Send a request and wait for response */
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
+    /** Send a notification (no response expected) */
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    /** Close the transport */
+    close(): Promise<void>;
+    /** Whether close must finish before reconnect can safely spawn a replacement. */
+    readonly closeBeforeReconnect?: boolean;
+    /** Whether the transport is connected */
+    readonly connected: boolean;
+    /** Event handlers */
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onNotification?: (method: string, params: unknown) => void;
+    /** Handler for server-to-client requests (e.g. roots/list). Returns result or throws a JsonRpcError. */
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+}
+/** Transport factory function */
+export type TransportFactory = (config: MCPServerConfig) => Promise<MCPTransport>;
+/** Connected MCP server state */
+export interface MCPServerConnection {
+    /** Server name from config */
+    name: string;
+    /** Original config */
+    config: MCPServerConfig;
+    /** Transport instance */
+    transport: MCPTransport;
+    /** Server info from initialize */
+    serverInfo: MCPImplementation;
+    /** Server capabilities */
+    capabilities: MCPServerCapabilities;
+    /** Cached tools (populated on demand) */
+    tools?: MCPToolDefinition[];
+    /** Source metadata (for display) */
+    _source?: SourceMeta;
+    /** Cached resources (populated on demand) */
+    resources?: MCPResource[];
+    /** Cached resource templates (populated on demand) */
+    resourceTemplates?: MCPResourceTemplate[];
+    /** Server instructions from initialize */
+    instructions?: string;
+    /** Cached prompts (populated on demand) */
+    prompts?: MCPPrompt[];
+}
+/** MCP tool with server context */
+export interface MCPToolWithServer {
+    server: MCPServerConnection;
+    tool: MCPToolDefinition;
+}
+/** Annotations for resources, templates, and content blocks */
+export interface MCPAnnotations {
+    audience?: ("user" | "assistant")[];
+    priority?: number;
+    lastModified?: string;
+}
+/** A concrete resource exposed by an MCP server */
+export interface MCPResource {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    annotations?: MCPAnnotations;
+}
+/** A parameterized resource template (RFC 6570 URI template) */
+export interface MCPResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    annotations?: MCPAnnotations;
+}
+/** Result of resources/list */
+export interface MCPResourcesListResult {
+    resources: MCPResource[];
+    nextCursor?: string;
+}
+/** Result of resources/templates/list */
+export interface MCPResourceTemplatesListResult {
+    resourceTemplates: MCPResourceTemplate[];
+    nextCursor?: string;
+}
+/** A single content item from resources/read */
+export interface MCPResourceContentItem {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+/** Result of resources/read */
+export interface MCPResourceReadResult {
+    contents: MCPResourceContentItem[];
+}
+/** Params for resources/read */
+export interface MCPResourceReadParams {
+    uri: string;
+}
+/** Params for resources/subscribe and resources/unsubscribe */
+export interface MCPResourceSubscribeParams {
+    uri: string;
+}
+/** An argument definition for an MCP prompt */
+export interface MCPPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/** A prompt definition exposed by an MCP server */
+export interface MCPPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: MCPPromptArgument[];
+}
+/** Result of prompts/list */
+export interface MCPPromptsListResult {
+    prompts: MCPPrompt[];
+    nextCursor?: string;
+}
+/** Audio content in prompt messages */
+export interface MCPAudioContent {
+    type: "audio";
+    data: string;
+    mimeType: string;
+}
+/** Content type union for prompt messages */
+export type MCPPromptContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceContent;
+/** A single message in a prompt result */
+export interface MCPPromptMessage {
+    role: "user" | "assistant";
+    content: MCPPromptContent | MCPPromptContent[];
+}
+/** Params for prompts/get */
+export interface MCPGetPromptParams {
+    name: string;
+    arguments?: Record<string, string>;
+}
+/** Result of prompts/get */
+export interface MCPGetPromptResult {
+    description?: string;
+    messages: MCPPromptMessage[];
+}
+/** MCP server notification method names */
+export declare const MCPNotificationMethods: {
+    readonly TOOLS_LIST_CHANGED: "notifications/tools/list_changed";
+    readonly RESOURCES_LIST_CHANGED: "notifications/resources/list_changed";
+    readonly RESOURCES_UPDATED: "notifications/resources/updated";
+    readonly PROMPTS_LIST_CHANGED: "notifications/prompts/list_changed";
+};
+/** Extract a JsonRpcError from a thrown value. Preserves `.code` and `.message` from Error instances or plain objects. */
+export declare function toJsonRpcError(error: unknown): JsonRpcError;
+export {};

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,120 @@
+import type { NativeDirectoryTreeSnapshot } from "@sayknow-cli/natives";
+import { type DirectoryMigrationPolicy } from "../session-directory";
+import { type BrokerDiscovery, type RedactedBrokerDiscovery } 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;
+    /** Broker-owned migration policy. Client lifecycle frames cannot select it. */
+    resolveDirectoryMigration?: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+}
+type ResolvedBrokerSettings = {
+    agentDir: string;
+    packageGeneration: string;
+    port: number;
+    heartbeatTtlMs: number;
+    resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+};
+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 BrokerCleanupIdentity = {
+    dev: string;
+    ino: string;
+    size: number;
+    mtimeNs: string;
+    sha256: string;
+};
+/** Exact retry evidence; detached paths are managed-receipt references, never caller authority. */
+export type BrokerLifecycleCleanupFile = {
+    /** Original lifecycle-owned path, retained only for exact identity validation. */
+    path: string;
+    identity: BrokerCleanupIdentity;
+    /** Monotonic append-only cleanup attempt. */
+    attempt?: number;
+    /** Immutable no-replace quarantine destination persisted before native detach. */
+    plannedPath: string;
+    /** Native-returned detached path, persisted after a failed post-detach cleanup. */
+    detachedPath?: string;
+    /** Append-only terminal proof for this exact artifact; completed entries are never retried. */
+    completed?: true;
+};
+/** Durable root-tree authority for broker artifact cleanup. */
+export type BrokerArtifactTree = {
+    identity: BrokerCleanupIdentity;
+    snapshot: NativeDirectoryTreeSnapshot;
+    plannedPath: string;
+    detachedPath?: string;
+    completed?: true;
+};
+export type BrokerCleanupEvidence = {
+    phase: "artifacts" | "transcript" | "metadata" | "lifecycle";
+    /** Ledger-bound deletion target; never reconstructed from a retry request. */
+    sessionsRoot?: string;
+    transcriptPath?: string;
+    cwd?: string;
+    metadataRoot?: string;
+    sessionId?: string;
+    artifactsIdentity?: BrokerCleanupIdentity;
+    transcriptIdentity?: BrokerCleanupIdentity;
+    /** Identity-bound lifecycle metadata marker retained when exact cleanup is deferred. */
+    metadataIdentity?: BrokerCleanupIdentity;
+    metadataPath?: string;
+    /** Monotonic append-only cleanup attempt. */
+    metadataAttempt?: number;
+    /** No-replace quarantine destination persisted before lifecycle metadata detach. */
+    plannedMetadataPath?: string;
+    /** Native-returned metadata quarantine path retained until identity-bound reconciliation succeeds. */
+    detachedMetadataPath?: string;
+    /** Append-only terminal proof for lifecycle metadata cleanup. */
+    metadataCompleted?: true;
+    detachedArtifactsPath?: string;
+    detachedTranscriptPath?: string;
+    /** Durable proof that artifact cleanup completed before transcript mutation. */
+    artifactsRemoved?: boolean;
+    /** Preauthorized no-replace artifact quarantine path persisted before detach. */
+    plannedArtifactsPath?: string;
+    /** Identity-bound artifact tree authority persisted before broker detach and replayed exactly. */
+    artifactTree?: BrokerArtifactTree;
+    /** Preauthorized no-replace transcript quarantine path persisted before detach. */
+    plannedTranscriptPath?: string;
+    /** Fully identity-bound startup-failure cleanup plan, persisted before any detach. */
+    lifecycleFiles?: BrokerLifecycleCleanupFile[];
+    /** Delete metadata receipts authorize only the canonical marker/ready sibling pair. */
+    lifecycleDeleteMetadata?: true;
+};
+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: ResolvedBrokerSettings;
+    readonly index: SessionIndex;
+    readonly ledger: LifecycleLedger;
+    discovery: BrokerDiscovery | null;
+    constructor(settings: BrokerSettings);
+    start(): Promise<BrokerDiscovery>;
+    get ownsDiscovery(): boolean;
+    get completion(): Promise<void>;
+    status(): RedactedBrokerDiscovery | 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;
+export {};

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

@@ -0,0 +1,40 @@
+import { processIncarnation } from "./process-incarnation";
+import { SDK_STATE_VERSION } from "./state-version";
+export type BrokerPublicationObservation = "owned" | "absent" | "replaced" | "ambiguous";
+export interface RetainedBrokerDiscovery {
+    observe(): BrokerPublicationObservation;
+    heartbeat(heartbeatAt: number): Promise<boolean>;
+    close(): void;
+}
+export declare const BROKER_HEARTBEAT_TTL_MS = 15000;
+export interface BrokerDiscovery {
+    version: typeof SDK_STATE_VERSION;
+    protocolVersion: 3;
+    packageGeneration: string;
+    ownerId: string;
+    pid: number;
+    incarnation: string;
+    host: "127.0.0.1";
+    port: number;
+    url: string;
+    token: string;
+    startedAt: number;
+    heartbeatAt: number;
+}
+export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & {
+    token: "[redacted]";
+};
+export type BrokerDiscoveryWrite = Omit<BrokerDiscovery, "incarnation"> & {
+    incarnation?: string;
+};
+export declare const brokerDiscoveryPath: (agentDir: string) => string;
+export declare const newBrokerToken: () => string;
+export declare const brokerProcessIncarnation: typeof processIncarnation;
+export declare function isPidAlive(pid: number): boolean;
+export declare function writeBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite): Promise<void>;
+/** Publish once by name, then retain no-follow native authority for recurring heartbeats. */
+export declare function publishBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite, platform?: NodeJS.Platform): Promise<RetainedBrokerDiscovery>;
+/** Heartbeat through retained authority, or the explicit Windows compatibility path. */
+export declare function heartbeatBrokerDiscoveryRetained(publication: RetainedBrokerDiscovery, heartbeatAt: number): Promise<boolean>;
+export declare function readBrokerDiscovery(agentDir: string, ttlMs?: number): Promise<BrokerDiscovery | null>;
+export declare function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery;

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

@@ -0,0 +1,65 @@
+import { type ChildProcess } from "node:child_process";
+import { type BrokerDiscovery } from "./discovery";
+import { type SdkInternalSpawnCommand } from "./runtime";
+export interface EnsureBrokerSettings {
+    agentDir: string;
+    heartbeatTtlMs?: number;
+    /**
+     * Environment for the spawned detached broker. Defaults to `process.env`; tests
+     * that pre-start an isolated broker pass the same sanitized child env so the
+     * broker and the child that attaches to it share one owned root.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+export interface FixtureBrokerLease {
+    /** Backward-compatible fixture cleanup alias for exact child termination. */
+    close(): Promise<void>;
+}
+export interface ExactFixtureBrokerLease extends FixtureBrokerLease {
+    /** Observes the retained child only; it never signals a process. */
+    waitForExit(timeoutMs: number): Promise<boolean>;
+    /** Signals only the retained ChildProcess, never a discovery-derived PID. */
+    terminateExactChild(): Promise<void>;
+}
+export interface FixtureBrokerCommand {
+    file: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface StartedFixtureBrokerCommand {
+    lease: ExactFixtureBrokerLease;
+    control: NodeJS.WritableStream;
+}
+export interface StartedFixtureBroker {
+    discovery: BrokerDiscovery;
+    lease: ExactFixtureBrokerLease;
+}
+interface BrokerOwner {
+    stop(): Promise<void>;
+    canReuse(discovery: BrokerDiscovery | null): boolean;
+    markReady(discovery: BrokerDiscovery): boolean;
+}
+interface ReapTiming {
+    gracefulMs: number;
+    killVerifyMs: number;
+}
+/** Starts the detached broker entrypoint when discovery has no live owner. */
+export declare function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery>;
+/** Starts one fresh fixture broker and returns its sole exact-child close lease. */
+export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSettings): Promise<StartedFixtureBroker>;
+/**
+ * Test-only launch surface for topology fixtures. It accepts an already-resolved
+ * command and retains the exact spawned child; no production selection path
+ * reaches this function.
+ */
+export declare function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBrokerCommand): StartedFixtureBrokerCommand;
+/** Test hook: returns a stop handle for the detached broker this process spawned. */
+export declare function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined;
+/** Test hook: drives the detached-broker reap on a controllable child surface. */
+export declare function reapSpawnedBrokerForTest(child: ChildProcess, timing?: ReapTiming): Promise<void>;
+/** Test hook: resolves the complete broker environment without spawning. */
+export declare function brokerSpawnEnvironmentForTest(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Test hook: installs an exact controllable owner to exercise replacement fencing. */
+export declare function registerBrokerOwnerForTest(agentDir: string, child: ChildProcess, timing?: ReapTiming): BrokerOwner;
+export {};

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

@@ -0,0 +1,3 @@
+export declare function brokerIdentityPath(agentDir: string): string;
+export declare function getBrokerIdentityKey(agentDir: string): Promise<string>;
+export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, canonicalTargetHash: string): Promise<string>;

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

@@ -0,0 +1,8 @@
+export * from "./broker";
+export * from "./discovery";
+export * from "./ensure";
+export * from "./identity";
+export * from "./lifecycle";
+export * from "./lifecycle-ledger";
+export * from "./session-index";
+export * from "./transport";

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

@@ -0,0 +1,3 @@
+import type { Broker } from "./broker";
+/** Wait for broker-local completion, then terminate only the current broker process. */
+export declare function completeBrokerProcess(broker: Broker, exit?: (code: number) => never): Promise<never>;

package/dist/types/sdk/broker/lifecycle-codec.d.ts

@@ -0,0 +1,4 @@
+/** Decodes persisted lifecycle bytes without replacement characters before JSON parsing. */
+export declare function decodeLifecycleUtf8(bytes: Uint8Array): string;
+/** Parses persisted lifecycle JSON only after fatal UTF-8 decoding. */
+export declare function parseLifecycleJson(bytes: Uint8Array): unknown;