@bradygaster/squad-sdk 0.7.0 → 0.8.2

package/dist/adapter/client.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Squad SDK Client Adapter
+ *
+ * Wraps CopilotClient to provide connection lifecycle management, error recovery,
+ * automatic reconnection, and protocol version validation.
+ *
+ * @module adapter/client
+ */
+import type { SquadSessionConfig, SquadSession, SquadSessionEventHandler, SquadSessionEventType, SquadSessionMetadata, SquadGetAuthStatusResponse, SquadGetStatusResponse, SquadModelInfo, SquadMessageOptions } from "./types.js";
+/**
+ * Connection state for SquadClient.
+ */
+export type SquadConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "error";
+/**
+ * Options for creating a SquadClient.
+ */
+export interface SquadClientOptions {
+    /**
+     * Path to the Copilot CLI executable.
+     * Defaults to bundled CLI from @github/copilot package.
+     */
+    cliPath?: string;
+    /**
+     * Additional arguments to pass to the CLI process.
+     */
+    cliArgs?: string[];
+    /**
+     * Working directory for the CLI process.
+     * @default process.cwd()
+     */
+    cwd?: string;
+    /**
+     * Port to bind the CLI server (TCP mode).
+     * Set to 0 for random port, or undefined to use stdio mode.
+     */
+    port?: number;
+    /**
+     * Use stdio transport instead of TCP.
+     * @default true
+     */
+    useStdio?: boolean;
+    /**
+     * URL of an external CLI server to connect to.
+     * Mutually exclusive with useStdio and cliPath.
+     */
+    cliUrl?: string;
+    /**
+     * Log level for the CLI process.
+     * @default "debug"
+     */
+    logLevel?: "error" | "warning" | "info" | "debug" | "all" | "none";
+    /**
+     * Automatically start the connection when creating a session.
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Automatically reconnect on transient failures.
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Environment variables to pass to the CLI process.
+     * @default process.env
+     */
+    env?: Record<string, string>;
+    /**
+     * GitHub token for authentication.
+     * If not provided, uses logged-in user credentials.
+     */
+    githubToken?: string;
+    /**
+     * Use logged-in user credentials for authentication.
+     * @default true (false if githubToken is provided)
+     */
+    useLoggedInUser?: boolean;
+    /**
+     * Maximum number of reconnection attempts before giving up.
+     * @default 3
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Initial delay in milliseconds before first reconnection attempt.
+     * Subsequent attempts use exponential backoff.
+     * @default 1000
+     */
+    reconnectDelayMs?: number;
+}
+/**
+ * SquadClient wraps CopilotClient with enhanced lifecycle management.
+ *
+ * Features:
+ * - Connection state tracking
+ * - Automatic reconnection with exponential backoff
+ * - Protocol version validation
+ * - Error recovery
+ * - Session lifecycle event handling
+ *
+ * @example
+ * ```typescript
+ * const client = new SquadClient();
+ * await client.connect();
+ *
+ * const session = await client.createSession({
+ *   model: "claude-sonnet-4.5"
+ * });
+ *
+ * await client.disconnect();
+ * ```
+ */
+export declare class SquadClient {
+    private client;
+    private state;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private options;
+    private manualDisconnect;
+    /**
+     * Creates a new SquadClient instance.
+     *
+     * @param options - Configuration options
+     * @throws Error if mutually exclusive options are provided
+     */
+    constructor(options?: SquadClientOptions);
+    /**
+     * Get the current connection state.
+     */
+    getState(): SquadConnectionState;
+    /**
+     * Check if the client is connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Establish connection to the Copilot CLI server.
+     *
+     * This method:
+     * 1. Spawns or connects to the CLI server
+     * 2. Validates protocol version compatibility
+     * 3. Sets up automatic reconnection handlers
+     *
+     * @returns Promise that resolves when connection is established
+     * @throws Error if connection fails or protocol version is incompatible
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the Copilot CLI server.
+     *
+     * Performs graceful cleanup:
+     * 1. Destroys all active sessions
+     * 2. Closes the connection
+     * 3. Terminates the CLI process (if spawned)
+     *
+     * @returns Promise that resolves with any errors encountered during cleanup
+     */
+    disconnect(): Promise<Error[]>;
+    /**
+     * Force disconnect without graceful cleanup.
+     * Use only when disconnect() fails or hangs.
+     */
+    forceDisconnect(): Promise<void>;
+    /**
+     * Create a new Squad session.
+     *
+     * If autoStart is enabled and the client is not connected, this will
+     * automatically establish the connection.
+     *
+     * @param config - Session configuration
+     * @returns Promise that resolves with the created session
+     */
+    createSession(config?: SquadSessionConfig): Promise<SquadSession>;
+    /**
+     * Resume an existing Squad session by ID.
+     *
+     * @param sessionId - ID of the session to resume
+     * @param config - Optional configuration overrides
+     * @returns Promise that resolves with the resumed session
+     */
+    resumeSession(sessionId: string, config?: SquadSessionConfig): Promise<SquadSession>;
+    /**
+     * List all available sessions.
+     */
+    listSessions(): Promise<SquadSessionMetadata[]>;
+    /**
+     * Delete a session by ID.
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Get the ID of the last updated session.
+     */
+    getLastSessionId(): Promise<string | undefined>;
+    /**
+     * Send a ping to verify connectivity.
+     */
+    ping(message?: string): Promise<{
+        message: string;
+        timestamp: number;
+        protocolVersion?: number;
+    }>;
+    /**
+     * Get CLI status information.
+     */
+    getStatus(): Promise<SquadGetStatusResponse>;
+    /**
+     * Get authentication status.
+     */
+    getAuthStatus(): Promise<SquadGetAuthStatusResponse>;
+    /**
+     * List available models.
+     */
+    listModels(): Promise<SquadModelInfo[]>;
+    /**
+     * Send a message to a session, wrapped with OTel tracing.
+     *
+     * Creates a `squad.session.message` span for the full call and a
+     * child `squad.session.stream` span that tracks streaming duration
+     * with `first_token`, `last_token`, and `stream_error` events.
+     *
+     * @param session - The session to send the message to
+     * @param options - Message content and delivery options
+     * @returns Promise that resolves when the message is processed
+     */
+    sendMessage(session: SquadSession, options: SquadMessageOptions): Promise<void>;
+    /**
+     * Close a session (alias for deleteSession with `squad.session.close` span).
+     *
+     * @param sessionId - ID of the session to close
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to session lifecycle events.
+     */
+    on(eventType: SquadSessionEventType, handler: SquadSessionEventHandler): () => void;
+    on(handler: SquadSessionEventHandler): () => void;
+    /**
+     * Determine if an error is recoverable via reconnection.
+     */
+    private shouldAttemptReconnect;
+    /**
+     * Attempt to reconnect with exponential backoff.
+     */
+    private attemptReconnection;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/adapter/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/adapter/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EAEZ,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AAE1G;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IAEnE;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,OAAO,CAMb;IACF,OAAO,CAAC,gBAAgB,CAAkB;IAE1C;;;;;OAKG;gBACS,OAAO,GAAE,kBAAuB;IAkC5C;;OAEG;IACH,QAAQ,IAAI,oBAAoB;IAIhC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;OAUG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C9B;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAwBpC;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAatC;;;;;;;;OAQG;IACG,aAAa,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC;IAqC3E;;;;;;OAMG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC;IA+B9F;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA4BrD;;OAEG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BrD;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgBrD;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAgBvG;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAgBlD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAgB1D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAgB7C;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4DrF;;;;OAIG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,wBAAwB,GAAG,MAAM,IAAI;IACnF,EAAE,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAYjD;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6B9B;;OAEG;YACW,mBAAmB;CA0BlC"}