@spotpatch/bridge 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,10 +1,13 @@
-import { ExternalHandoffActiveAdapterKind, ExternalHandoffReportableDispatchPhase, ExternalHandoffSummary } from '@spotpatch/shared';
+import { ExternalHandoffActiveAdapterKind, externalHandoffSnapshotSchema, ExternalHandoffReportableDispatchPhase, ExternalHandoffSummary, ResolvedAgentCheckDefinition, AgentLimits, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult } from '@spotpatch/shared';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/server';
 import { StdioServerHandle } from '@modelcontextprotocol/server/stdio';
+import { ManagedExecutionPort, ManagedExecutionResult } from '@spotpatch/agent';
 
 type ActiveAdapterKind = ExternalHandoffActiveAdapterKind;
 type ActiveReportPhase = ExternalHandoffReportableDispatchPhase;
+type AgentDeliveryPhase = Exclude<ActiveReportPhase, "dispatching">;
+type AgentHandoffSnapshot = z.infer<typeof externalHandoffSnapshotSchema>;
 /**
  * Lease data is connector-private. It must never be included in MCP output,
  * Channel metadata, diagnostics, or browser-facing state.
@@ -26,6 +29,16 @@ interface ActiveBridgeClient {
     readonly activeRelease: (lease: ActiveBridgeLease, signal?: AbortSignal) => Promise<void>;
     readonly activeReport: (lease: ActiveBridgeLease, cursor: string, phase: ActiveReportPhase, signal?: AbortSignal) => Promise<void>;
 }
+interface AgentDeliveryLifecycle {
+    /** The sole state-writing path available to a vendor adapter. */
+    readonly report: (phase: AgentDeliveryPhase) => Promise<void>;
+}
+interface AgentAdapter {
+    readonly kind: ActiveAdapterKind;
+    readonly close: () => Promise<void>;
+    /** Resolves only after a proved completed/failed terminal report. */
+    readonly deliver: (handoff: AgentHandoffSnapshot, lifecycle: AgentDeliveryLifecycle, signal: AbortSignal) => Promise<void>;
+}
 
 declare const sessionListItemSchema: z.ZodObject<{
     sessionId: z.ZodString;
@@ -499,4 +512,99 @@ interface SpotPatchMcpScope {
 declare function createSpotPatchMcpServer(cwd?: string, scope?: SpotPatchMcpScope): McpServer;
 declare function serveSpotPatchMcp(cwd?: string, scope?: SpotPatchMcpScope): StdioServerHandle;
 
-export { type BridgeCliAdapter, type BridgeSetupClient, type BridgeSetupMode, type BridgeSetupPlan, type ExternalAgentSessionListItem, type HandoffDelivery, type HandoffWaitDelivery, type RunSpotPatchBridgeCliOptions, type SpotPatchBridgeClient, applyBridgeSetupPlan, createBridgeSetupPlan, createSpotPatchBridgeClient, createSpotPatchMcpServer, runSpotPatchBridgeCli, serveSpotPatchMcp };
+interface ManagedThreadCleanupEntry {
+    readonly threadId: string;
+    readonly createdAt: string;
+}
+interface ManagedThreadCleanupJournal {
+    list(): Promise<readonly ManagedThreadCleanupEntry[]>;
+    add(threadId: string): Promise<void>;
+    remove(threadId: string): Promise<void>;
+}
+
+type ManagedAdapterEvent = Readonly<{
+    type: "phase";
+    revision: number;
+    phase: "preparing" | "running" | "auditing" | "validating" | "applying";
+}> | Readonly<{
+    type: "result";
+    result: ManagedExecutionResult;
+}> | Readonly<{
+    type: "cleanup-warning";
+    revision: number;
+}> | Readonly<{
+    type: "failure";
+    revision: number;
+    reason: "apply" | "change-limit" | "config-isolation" | "protocol" | "scope" | "snapshot" | "validation" | "workspace-conflict";
+}>;
+interface ManagedAdapterConnection {
+    readonly adapter: AgentAdapter;
+    readonly authReadiness: "authenticated" | "auth-not-required" | "signed-out" | "unknown";
+    readonly requestedModel?: string;
+    readonly effectiveModel?: string;
+}
+interface ConnectManagedAdapterOptions {
+    readonly bridgeAdapter: BridgeCliAdapter;
+    readonly execution: ManagedExecutionPort;
+    readonly cleanupJournal: ManagedThreadCleanupJournal;
+    readonly onEvent: (event: ManagedAdapterEvent) => void;
+    readonly privateRuntimeBase?: string;
+    readonly projectRoot: string;
+    readonly runtimeKey: string;
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+}
+type ConnectManagedAdapter = (options: ConnectManagedAdapterOptions) => Promise<ManagedAdapterConnection>;
+interface ExternalAgentSupervisor {
+    getStatus(): ExternalAgentControlStatus;
+    connect(request: ExternalAgentControlConnectRequest, signal: AbortSignal): Promise<ExternalAgentControlStatus>;
+    disconnect(request: ExternalAgentControlDisconnectRequest): Promise<ExternalAgentControlStatus>;
+    cancel(request: ExternalAgentControlCancelRequest): Promise<ExternalAgentControlStatus>;
+    getResult(revision: number): ExternalAgentManagedResult | undefined;
+    subscribe(listener: (status: ExternalAgentControlStatus) => void): () => void;
+    dispose(): Promise<void>;
+}
+interface CreateExternalAgentSupervisorOptions {
+    readonly bridgeAdapter: BridgeCliAdapter;
+    readonly checks?: Readonly<Record<string, ResolvedAgentCheckDefinition>>;
+    readonly configBase?: string;
+    readonly confirmManagedAccess?: (projectLabel: string) => Promise<boolean>;
+    readonly connectManagedAdapter?: ConnectManagedAdapter;
+    readonly limits?: Readonly<AgentLimits>;
+    readonly now?: () => Date;
+    readonly projectLabel?: string;
+    readonly root: string;
+    readonly sessionId: string;
+}
+declare function createExternalAgentSupervisor(options: CreateExternalAgentSupervisorOptions): Promise<ExternalAgentSupervisor>;
+
+interface CodexProtocolDiagnostics {
+    readonly stderrBytesObserved: number;
+    readonly stderrTruncated: boolean;
+}
+
+interface ConnectManagedCodexAppServerOptions extends ConnectManagedAdapterOptions {
+    readonly maximumLineBytes?: number;
+    readonly maximumStderrBytes?: number;
+    readonly pathValue?: string;
+    readonly processShutdownTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly terminalTimeoutMs?: number;
+}
+declare class ManagedCodexAppServerAdapter implements AgentAdapter {
+    #private;
+    readonly kind: "codex-app-server";
+    private constructor();
+    static connect(options: ConnectManagedCodexAppServerOptions): Promise<Readonly<{
+        adapter: ManagedCodexAppServerAdapter;
+        authReadiness: ManagedAdapterConnection["authReadiness"];
+        requestedModel: string;
+        effectiveModel: string;
+    }>>;
+    diagnostics(): CodexProtocolDiagnostics;
+    deliver(handoff: AgentHandoffSnapshot, lifecycle: AgentDeliveryLifecycle, signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}
+declare function connectManagedCodexAppServer(options: ConnectManagedCodexAppServerOptions): Promise<ManagedAdapterConnection>;
+
+export { type BridgeCliAdapter, type BridgeSetupClient, type BridgeSetupMode, type BridgeSetupPlan, type ConnectManagedAdapter, type ConnectManagedAdapterOptions, type ConnectManagedCodexAppServerOptions, type CreateExternalAgentSupervisorOptions, type ExternalAgentSessionListItem, type ExternalAgentSupervisor, type HandoffDelivery, type HandoffWaitDelivery, type ManagedAdapterConnection, type ManagedAdapterEvent, ManagedCodexAppServerAdapter, type RunSpotPatchBridgeCliOptions, type SpotPatchBridgeClient, applyBridgeSetupPlan, connectManagedCodexAppServer, createBridgeSetupPlan, createExternalAgentSupervisor, createSpotPatchBridgeClient, createSpotPatchMcpServer, runSpotPatchBridgeCli, serveSpotPatchMcp };

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-import { ExternalHandoffActiveAdapterKind, ExternalHandoffReportableDispatchPhase, ExternalHandoffSummary } from '@spotpatch/shared';
+import { ExternalHandoffActiveAdapterKind, externalHandoffSnapshotSchema, ExternalHandoffReportableDispatchPhase, ExternalHandoffSummary, ResolvedAgentCheckDefinition, AgentLimits, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult } from '@spotpatch/shared';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/server';
 import { StdioServerHandle } from '@modelcontextprotocol/server/stdio';
+import { ManagedExecutionPort, ManagedExecutionResult } from '@spotpatch/agent';
 
 type ActiveAdapterKind = ExternalHandoffActiveAdapterKind;
 type ActiveReportPhase = ExternalHandoffReportableDispatchPhase;
+type AgentDeliveryPhase = Exclude<ActiveReportPhase, "dispatching">;
+type AgentHandoffSnapshot = z.infer<typeof externalHandoffSnapshotSchema>;
 /**
  * Lease data is connector-private. It must never be included in MCP output,
  * Channel metadata, diagnostics, or browser-facing state.
@@ -26,6 +29,16 @@ interface ActiveBridgeClient {
     readonly activeRelease: (lease: ActiveBridgeLease, signal?: AbortSignal) => Promise<void>;
     readonly activeReport: (lease: ActiveBridgeLease, cursor: string, phase: ActiveReportPhase, signal?: AbortSignal) => Promise<void>;
 }
+interface AgentDeliveryLifecycle {
+    /** The sole state-writing path available to a vendor adapter. */
+    readonly report: (phase: AgentDeliveryPhase) => Promise<void>;
+}
+interface AgentAdapter {
+    readonly kind: ActiveAdapterKind;
+    readonly close: () => Promise<void>;
+    /** Resolves only after a proved completed/failed terminal report. */
+    readonly deliver: (handoff: AgentHandoffSnapshot, lifecycle: AgentDeliveryLifecycle, signal: AbortSignal) => Promise<void>;
+}
 
 declare const sessionListItemSchema: z.ZodObject<{
     sessionId: z.ZodString;
@@ -499,4 +512,99 @@ interface SpotPatchMcpScope {
 declare function createSpotPatchMcpServer(cwd?: string, scope?: SpotPatchMcpScope): McpServer;
 declare function serveSpotPatchMcp(cwd?: string, scope?: SpotPatchMcpScope): StdioServerHandle;
 
-export { type BridgeCliAdapter, type BridgeSetupClient, type BridgeSetupMode, type BridgeSetupPlan, type ExternalAgentSessionListItem, type HandoffDelivery, type HandoffWaitDelivery, type RunSpotPatchBridgeCliOptions, type SpotPatchBridgeClient, applyBridgeSetupPlan, createBridgeSetupPlan, createSpotPatchBridgeClient, createSpotPatchMcpServer, runSpotPatchBridgeCli, serveSpotPatchMcp };
+interface ManagedThreadCleanupEntry {
+    readonly threadId: string;
+    readonly createdAt: string;
+}
+interface ManagedThreadCleanupJournal {
+    list(): Promise<readonly ManagedThreadCleanupEntry[]>;
+    add(threadId: string): Promise<void>;
+    remove(threadId: string): Promise<void>;
+}
+
+type ManagedAdapterEvent = Readonly<{
+    type: "phase";
+    revision: number;
+    phase: "preparing" | "running" | "auditing" | "validating" | "applying";
+}> | Readonly<{
+    type: "result";
+    result: ManagedExecutionResult;
+}> | Readonly<{
+    type: "cleanup-warning";
+    revision: number;
+}> | Readonly<{
+    type: "failure";
+    revision: number;
+    reason: "apply" | "change-limit" | "config-isolation" | "protocol" | "scope" | "snapshot" | "validation" | "workspace-conflict";
+}>;
+interface ManagedAdapterConnection {
+    readonly adapter: AgentAdapter;
+    readonly authReadiness: "authenticated" | "auth-not-required" | "signed-out" | "unknown";
+    readonly requestedModel?: string;
+    readonly effectiveModel?: string;
+}
+interface ConnectManagedAdapterOptions {
+    readonly bridgeAdapter: BridgeCliAdapter;
+    readonly execution: ManagedExecutionPort;
+    readonly cleanupJournal: ManagedThreadCleanupJournal;
+    readonly onEvent: (event: ManagedAdapterEvent) => void;
+    readonly privateRuntimeBase?: string;
+    readonly projectRoot: string;
+    readonly runtimeKey: string;
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+}
+type ConnectManagedAdapter = (options: ConnectManagedAdapterOptions) => Promise<ManagedAdapterConnection>;
+interface ExternalAgentSupervisor {
+    getStatus(): ExternalAgentControlStatus;
+    connect(request: ExternalAgentControlConnectRequest, signal: AbortSignal): Promise<ExternalAgentControlStatus>;
+    disconnect(request: ExternalAgentControlDisconnectRequest): Promise<ExternalAgentControlStatus>;
+    cancel(request: ExternalAgentControlCancelRequest): Promise<ExternalAgentControlStatus>;
+    getResult(revision: number): ExternalAgentManagedResult | undefined;
+    subscribe(listener: (status: ExternalAgentControlStatus) => void): () => void;
+    dispose(): Promise<void>;
+}
+interface CreateExternalAgentSupervisorOptions {
+    readonly bridgeAdapter: BridgeCliAdapter;
+    readonly checks?: Readonly<Record<string, ResolvedAgentCheckDefinition>>;
+    readonly configBase?: string;
+    readonly confirmManagedAccess?: (projectLabel: string) => Promise<boolean>;
+    readonly connectManagedAdapter?: ConnectManagedAdapter;
+    readonly limits?: Readonly<AgentLimits>;
+    readonly now?: () => Date;
+    readonly projectLabel?: string;
+    readonly root: string;
+    readonly sessionId: string;
+}
+declare function createExternalAgentSupervisor(options: CreateExternalAgentSupervisorOptions): Promise<ExternalAgentSupervisor>;
+
+interface CodexProtocolDiagnostics {
+    readonly stderrBytesObserved: number;
+    readonly stderrTruncated: boolean;
+}
+
+interface ConnectManagedCodexAppServerOptions extends ConnectManagedAdapterOptions {
+    readonly maximumLineBytes?: number;
+    readonly maximumStderrBytes?: number;
+    readonly pathValue?: string;
+    readonly processShutdownTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly terminalTimeoutMs?: number;
+}
+declare class ManagedCodexAppServerAdapter implements AgentAdapter {
+    #private;
+    readonly kind: "codex-app-server";
+    private constructor();
+    static connect(options: ConnectManagedCodexAppServerOptions): Promise<Readonly<{
+        adapter: ManagedCodexAppServerAdapter;
+        authReadiness: ManagedAdapterConnection["authReadiness"];
+        requestedModel: string;
+        effectiveModel: string;
+    }>>;
+    diagnostics(): CodexProtocolDiagnostics;
+    deliver(handoff: AgentHandoffSnapshot, lifecycle: AgentDeliveryLifecycle, signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}
+declare function connectManagedCodexAppServer(options: ConnectManagedCodexAppServerOptions): Promise<ManagedAdapterConnection>;
+
+export { type BridgeCliAdapter, type BridgeSetupClient, type BridgeSetupMode, type BridgeSetupPlan, type ConnectManagedAdapter, type ConnectManagedAdapterOptions, type ConnectManagedCodexAppServerOptions, type CreateExternalAgentSupervisorOptions, type ExternalAgentSessionListItem, type ExternalAgentSupervisor, type HandoffDelivery, type HandoffWaitDelivery, type ManagedAdapterConnection, type ManagedAdapterEvent, ManagedCodexAppServerAdapter, type RunSpotPatchBridgeCliOptions, type SpotPatchBridgeClient, applyBridgeSetupPlan, connectManagedCodexAppServer, createBridgeSetupPlan, createExternalAgentSupervisor, createSpotPatchBridgeClient, createSpotPatchMcpServer, runSpotPatchBridgeCli, serveSpotPatchMcp };