@witqq/agent-sdk 0.6.0 → 0.7.0

package/dist/transport-D1OaUgRk.d.ts

@@ -0,0 +1,67 @@
+import { ChatEvent } from './chat/core.js';
+
+/**
+ * @witqq/agent-sdk/chat/backends/transport
+ *
+ * IChatTransport abstracts how ChatEvents are delivered to clients.
+ * SSEChatTransport implements Server-Sent Events over HTTP.
+ */
+
+/**
+ * Abstraction for delivering chat events to a client.
+ * Implementations handle protocol details (SSE, WebSocket, etc.).
+ */
+interface IChatTransport {
+    /** Send a single chat event to the client */
+    send(event: ChatEvent): void;
+    /** Signal stream completion and close the connection */
+    close(): void;
+    /** Signal an error to the client */
+    error(err: Error): void;
+    /** Whether the transport is still open */
+    readonly isOpen: boolean;
+}
+/** Writable HTTP response interface (Node.js http.ServerResponse subset) */
+interface WritableResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    write(chunk: string): boolean;
+    end(): void;
+    readonly writableEnded: boolean;
+}
+/** Minimal interface for detecting client disconnection */
+interface CloseDetectable {
+    on(event: "close", listener: () => void): void;
+}
+/** Configuration options for SSEChatTransport */
+interface SSETransportOptions {
+    /** Heartbeat interval in milliseconds. 0 or undefined disables heartbeat. */
+    heartbeatMs?: number;
+    /** Request object for detecting client disconnection (listens for 'close' event) */
+    request?: CloseDetectable;
+}
+/**
+ * Server-Sent Events transport for ChatEvent streaming.
+ * Sends events as `data: JSON\n\n` lines with SSE headers.
+ */
+declare class SSEChatTransport implements IChatTransport {
+    private readonly res;
+    private _open;
+    private _heartbeatTimer;
+    constructor(res: WritableResponse, options?: SSETransportOptions);
+    get isOpen(): boolean;
+    send(event: ChatEvent): void;
+    close(): void;
+    error(err: Error): void;
+    private _cleanup;
+    private _clearHeartbeat;
+}
+/**
+ * Pipes an async iterable of ChatEvents into a transport.
+ * Handles errors and ensures transport is closed on completion.
+ *
+ * @param events - Async iterable of ChatEvent (from adapter.streamMessage)
+ * @param transport - Transport to send events through
+ */
+declare function streamToTransport(events: AsyncIterable<ChatEvent>, transport: IChatTransport): Promise<void>;
+
+export { type CloseDetectable as C, type IChatTransport as I, SSEChatTransport as S, type WritableResponse as W, type SSETransportOptions as a, streamToTransport as s };

package/dist/transport-DX1Nhm4N.d.cts

@@ -0,0 +1,67 @@
+import { ChatEvent } from './chat/core.cjs';
+
+/**
+ * @witqq/agent-sdk/chat/backends/transport
+ *
+ * IChatTransport abstracts how ChatEvents are delivered to clients.
+ * SSEChatTransport implements Server-Sent Events over HTTP.
+ */
+
+/**
+ * Abstraction for delivering chat events to a client.
+ * Implementations handle protocol details (SSE, WebSocket, etc.).
+ */
+interface IChatTransport {
+    /** Send a single chat event to the client */
+    send(event: ChatEvent): void;
+    /** Signal stream completion and close the connection */
+    close(): void;
+    /** Signal an error to the client */
+    error(err: Error): void;
+    /** Whether the transport is still open */
+    readonly isOpen: boolean;
+}
+/** Writable HTTP response interface (Node.js http.ServerResponse subset) */
+interface WritableResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    write(chunk: string): boolean;
+    end(): void;
+    readonly writableEnded: boolean;
+}
+/** Minimal interface for detecting client disconnection */
+interface CloseDetectable {
+    on(event: "close", listener: () => void): void;
+}
+/** Configuration options for SSEChatTransport */
+interface SSETransportOptions {
+    /** Heartbeat interval in milliseconds. 0 or undefined disables heartbeat. */
+    heartbeatMs?: number;
+    /** Request object for detecting client disconnection (listens for 'close' event) */
+    request?: CloseDetectable;
+}
+/**
+ * Server-Sent Events transport for ChatEvent streaming.
+ * Sends events as `data: JSON\n\n` lines with SSE headers.
+ */
+declare class SSEChatTransport implements IChatTransport {
+    private readonly res;
+    private _open;
+    private _heartbeatTimer;
+    constructor(res: WritableResponse, options?: SSETransportOptions);
+    get isOpen(): boolean;
+    send(event: ChatEvent): void;
+    close(): void;
+    error(err: Error): void;
+    private _cleanup;
+    private _clearHeartbeat;
+}
+/**
+ * Pipes an async iterable of ChatEvents into a transport.
+ * Handles errors and ensures transport is closed on completion.
+ *
+ * @param events - Async iterable of ChatEvent (from adapter.streamMessage)
+ * @param transport - Transport to send events through
+ */
+declare function streamToTransport(events: AsyncIterable<ChatEvent>, transport: IChatTransport): Promise<void>;
+
+export { type CloseDetectable as C, type IChatTransport as I, SSEChatTransport as S, type WritableResponse as W, type SSETransportOptions as a, streamToTransport as s };

package/dist/types-Bh5AhqD-.d.ts

@@ -0,0 +1,141 @@
+import { A as AgentSDKError } from './errors-BDLbNu9w.js';
+
+/**
+ * Base auth token returned by all auth providers.
+ *
+ * @example
+ * ```ts
+ * import type { AuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: AuthToken = {
+ *   accessToken: "gho_abc123...",
+ *   tokenType: "bearer",
+ *   obtainedAt: Date.now(),
+ * };
+ * ```
+ */
+interface AuthToken {
+    /** The access token string */
+    accessToken: string;
+    /** Token type (e.g. "bearer") */
+    tokenType: string;
+    /** Seconds until token expires (undefined = long-lived) */
+    expiresIn?: number;
+    /** Timestamp when the token was obtained */
+    obtainedAt: number;
+}
+/**
+ * Copilot-specific token (GitHub OAuth, long-lived).
+ *
+ * @example
+ * ```ts
+ * import type { CopilotAuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: CopilotAuthToken = {
+ *   accessToken: "gho_abc123...",
+ *   tokenType: "bearer",
+ *   obtainedAt: Date.now(),
+ *   login: "octocat",
+ * };
+ * ```
+ */
+interface CopilotAuthToken extends AuthToken {
+    /** GitHub user login associated with the token */
+    login?: string;
+}
+/**
+ * Claude-specific token (OAuth+PKCE, expires in 8h).
+ *
+ * @example
+ * ```ts
+ * import type { ClaudeAuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: ClaudeAuthToken = {
+ *   accessToken: "sk-ant-oat01-...",
+ *   tokenType: "bearer",
+ *   expiresIn: 28800,
+ *   obtainedAt: Date.now(),
+ *   refreshToken: "sk-ant-rt01-...",
+ *   scopes: ["user:inference", "user:profile"],
+ * };
+ * ```
+ */
+interface ClaudeAuthToken extends AuthToken {
+    /** Refresh token for obtaining new access tokens */
+    refreshToken: string;
+    /** OAuth scopes granted */
+    scopes: string[];
+}
+/**
+ * Result of initiating a GitHub Device Flow.
+ *
+ * @example
+ * ```ts
+ * import { CopilotAuth } from "@witqq/agent-sdk/auth";
+ *
+ * const auth = new CopilotAuth();
+ * const { userCode, verificationUrl, waitForToken } = await auth.startDeviceFlow();
+ * console.log(`Open ${verificationUrl} and enter code: ${userCode}`);
+ * const token = await waitForToken();
+ * ```
+ */
+interface DeviceFlowResult {
+    /** The code the user must enter at the verification URL */
+    userCode: string;
+    /** URL where the user enters the code */
+    verificationUrl: string;
+    /** Polls GitHub until user authorizes; resolves with token */
+    waitForToken: (signal?: AbortSignal) => Promise<CopilotAuthToken>;
+}
+/** Options for starting a Claude OAuth flow */
+interface OAuthFlowOptions {
+    /** The redirect URI registered with the OAuth app */
+    redirectUri?: string;
+    /** OAuth scopes to request (defaults to user:profile user:inference) */
+    scopes?: string;
+}
+/**
+ * Result of initiating a Claude OAuth flow.
+ *
+ * @example
+ * ```ts
+ * import type { OAuthFlowResult } from "@witqq/agent-sdk/auth";
+ *
+ * const result: OAuthFlowResult = {
+ *   authorizeUrl: "https://claude.ai/oauth/authorize?...",
+ *   completeAuth: async (code) => ({ ... }),
+ * };
+ * // Open result.authorizeUrl in browser, get code from redirect
+ * const token = await result.completeAuth(code);
+ * ```
+ */
+interface OAuthFlowResult {
+    /** URL to open in browser for user authorization */
+    authorizeUrl: string;
+    /** Exchange the authorization code (or full redirect URL) for tokens */
+    completeAuth: (codeOrUrl: string) => Promise<ClaudeAuthToken>;
+}
+/** Base error for auth operations.
+ * @param message - Error description
+ * @param options - Standard ErrorOptions (e.g. cause)
+ */
+declare class AuthError extends AgentSDKError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Device code expired before user authorized */
+declare class DeviceCodeExpiredError extends AuthError {
+    constructor();
+}
+/** User denied access during OAuth flow */
+declare class AccessDeniedError extends AuthError {
+    constructor();
+}
+/** Token exchange or refresh failed.
+ * @param message - Error description
+ * @param options - Standard ErrorOptions (e.g. cause)
+ */
+declare class TokenExchangeError extends AuthError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+export { type AuthToken as A, type ClaudeAuthToken as C, type DeviceFlowResult as D, type OAuthFlowOptions as O, TokenExchangeError as T, type OAuthFlowResult as a, AccessDeniedError as b, AuthError as c, type CopilotAuthToken as d, DeviceCodeExpiredError as e };

package/dist/types-CGF7AEX1.d.cts

@@ -0,0 +1,141 @@
+import { A as AgentSDKError } from './errors-BDLbNu9w.cjs';
+
+/**
+ * Base auth token returned by all auth providers.
+ *
+ * @example
+ * ```ts
+ * import type { AuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: AuthToken = {
+ *   accessToken: "gho_abc123...",
+ *   tokenType: "bearer",
+ *   obtainedAt: Date.now(),
+ * };
+ * ```
+ */
+interface AuthToken {
+    /** The access token string */
+    accessToken: string;
+    /** Token type (e.g. "bearer") */
+    tokenType: string;
+    /** Seconds until token expires (undefined = long-lived) */
+    expiresIn?: number;
+    /** Timestamp when the token was obtained */
+    obtainedAt: number;
+}
+/**
+ * Copilot-specific token (GitHub OAuth, long-lived).
+ *
+ * @example
+ * ```ts
+ * import type { CopilotAuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: CopilotAuthToken = {
+ *   accessToken: "gho_abc123...",
+ *   tokenType: "bearer",
+ *   obtainedAt: Date.now(),
+ *   login: "octocat",
+ * };
+ * ```
+ */
+interface CopilotAuthToken extends AuthToken {
+    /** GitHub user login associated with the token */
+    login?: string;
+}
+/**
+ * Claude-specific token (OAuth+PKCE, expires in 8h).
+ *
+ * @example
+ * ```ts
+ * import type { ClaudeAuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * const token: ClaudeAuthToken = {
+ *   accessToken: "sk-ant-oat01-...",
+ *   tokenType: "bearer",
+ *   expiresIn: 28800,
+ *   obtainedAt: Date.now(),
+ *   refreshToken: "sk-ant-rt01-...",
+ *   scopes: ["user:inference", "user:profile"],
+ * };
+ * ```
+ */
+interface ClaudeAuthToken extends AuthToken {
+    /** Refresh token for obtaining new access tokens */
+    refreshToken: string;
+    /** OAuth scopes granted */
+    scopes: string[];
+}
+/**
+ * Result of initiating a GitHub Device Flow.
+ *
+ * @example
+ * ```ts
+ * import { CopilotAuth } from "@witqq/agent-sdk/auth";
+ *
+ * const auth = new CopilotAuth();
+ * const { userCode, verificationUrl, waitForToken } = await auth.startDeviceFlow();
+ * console.log(`Open ${verificationUrl} and enter code: ${userCode}`);
+ * const token = await waitForToken();
+ * ```
+ */
+interface DeviceFlowResult {
+    /** The code the user must enter at the verification URL */
+    userCode: string;
+    /** URL where the user enters the code */
+    verificationUrl: string;
+    /** Polls GitHub until user authorizes; resolves with token */
+    waitForToken: (signal?: AbortSignal) => Promise<CopilotAuthToken>;
+}
+/** Options for starting a Claude OAuth flow */
+interface OAuthFlowOptions {
+    /** The redirect URI registered with the OAuth app */
+    redirectUri?: string;
+    /** OAuth scopes to request (defaults to user:profile user:inference) */
+    scopes?: string;
+}
+/**
+ * Result of initiating a Claude OAuth flow.
+ *
+ * @example
+ * ```ts
+ * import type { OAuthFlowResult } from "@witqq/agent-sdk/auth";
+ *
+ * const result: OAuthFlowResult = {
+ *   authorizeUrl: "https://claude.ai/oauth/authorize?...",
+ *   completeAuth: async (code) => ({ ... }),
+ * };
+ * // Open result.authorizeUrl in browser, get code from redirect
+ * const token = await result.completeAuth(code);
+ * ```
+ */
+interface OAuthFlowResult {
+    /** URL to open in browser for user authorization */
+    authorizeUrl: string;
+    /** Exchange the authorization code (or full redirect URL) for tokens */
+    completeAuth: (codeOrUrl: string) => Promise<ClaudeAuthToken>;
+}
+/** Base error for auth operations.
+ * @param message - Error description
+ * @param options - Standard ErrorOptions (e.g. cause)
+ */
+declare class AuthError extends AgentSDKError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Device code expired before user authorized */
+declare class DeviceCodeExpiredError extends AuthError {
+    constructor();
+}
+/** User denied access during OAuth flow */
+declare class AccessDeniedError extends AuthError {
+    constructor();
+}
+/** Token exchange or refresh failed.
+ * @param message - Error description
+ * @param options - Standard ErrorOptions (e.g. cause)
+ */
+declare class TokenExchangeError extends AuthError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+export { type AuthToken as A, type ClaudeAuthToken as C, type DeviceFlowResult as D, type OAuthFlowOptions as O, TokenExchangeError as T, type OAuthFlowResult as a, AccessDeniedError as b, AuthError as c, type CopilotAuthToken as d, DeviceCodeExpiredError as e };

package/dist/{types-BvwNzZCj.d.cts → types-CqvUAYxt.d.cts}

@@ -42,9 +42,19 @@ interface ToolDeclaration<TParams = unknown> {
     };
 }
 /** Full tool with execute function. Required for API-based backends.
- *  CLI backends extract declaration; execute map held internally. */
+ *  CLI backends extract declaration; execute map held internally.
+ *  The optional second parameter receives request-scoped context
+ *  when invoked through ChatRuntime (session ID, user data, custom metadata). */
 interface ToolDefinition<TParams = unknown> extends ToolDeclaration<TParams> {
-    execute: (params: TParams) => Promise<JSONValue> | JSONValue;
+    execute: (params: TParams, context?: ToolContext) => Promise<JSONValue> | JSONValue;
+}
+/** Request-scoped context passed to tool execute functions via ChatRuntime.
+ *  Contains session identity and user-defined metadata from the current session. */
+interface ToolContext {
+    /** Active chat session ID */
+    sessionId: string;
+    /** Custom metadata from the session (e.g. user ID, tenant, permissions) */
+    custom?: Record<string, unknown>;
 }
 /** A tool call made by the LLM during execution */
 interface ToolCall {
@@ -329,8 +339,13 @@ interface CopilotBackendOptions {
     cliArgs?: string[];
     /** Timeout in milliseconds for sendAndWait() calls. When undefined, uses copilot-sdk default (60s). */
     timeout?: number;
+    /** Timeout in milliseconds for CLI startup and auth check (default: 30000). */
+    startupTimeoutMs?: number;
     /** Custom environment variables merged into the subprocess env */
     env?: Record<string, string | undefined>;
+    /** Session ID to resume after server restart. On startup, the backend attempts
+     *  to resume this session before creating a new one. */
+    resumeSessionId?: string;
 }
 /** Options for Claude CLI backend */
 interface ClaudeBackendOptions {
@@ -341,6 +356,9 @@ interface ClaudeBackendOptions {
     oauthToken?: string;
     /** Custom environment variables merged into the subprocess env */
     env?: Record<string, string | undefined>;
+    /** Session ID to resume after server restart. On startup, the backend attempts
+     *  to resume this session before creating a new one. */
+    resumeSessionId?: string;
 }
 /** Options for Vercel AI SDK backend */
 interface VercelAIBackendOptions {
@@ -349,4 +367,4 @@ interface VercelAIBackendOptions {
     baseUrl?: string;
 }
 
-export type { CopilotBackendOptions as C, IAgentService as I, VercelAIBackendOptions as V, ClaudeBackendOptions as a };
+export type { AgentEvent as A, CopilotBackendOptions as C, IAgentService as I, Message as M, ToolDefinition as T, UsageData as U, VercelAIBackendOptions as V, ClaudeBackendOptions as a, IAgent as b, AgentConfig as c, ModelInfo as d, ToolResult as e };

package/dist/{types-BvwNzZCj.d.ts → types-CqvUAYxt.d.ts}

@@ -42,9 +42,19 @@ interface ToolDeclaration<TParams = unknown> {
     };
 }
 /** Full tool with execute function. Required for API-based backends.
- *  CLI backends extract declaration; execute map held internally. */
+ *  CLI backends extract declaration; execute map held internally.
+ *  The optional second parameter receives request-scoped context
+ *  when invoked through ChatRuntime (session ID, user data, custom metadata). */
 interface ToolDefinition<TParams = unknown> extends ToolDeclaration<TParams> {
-    execute: (params: TParams) => Promise<JSONValue> | JSONValue;
+    execute: (params: TParams, context?: ToolContext) => Promise<JSONValue> | JSONValue;
+}
+/** Request-scoped context passed to tool execute functions via ChatRuntime.
+ *  Contains session identity and user-defined metadata from the current session. */
+interface ToolContext {
+    /** Active chat session ID */
+    sessionId: string;
+    /** Custom metadata from the session (e.g. user ID, tenant, permissions) */
+    custom?: Record<string, unknown>;
 }
 /** A tool call made by the LLM during execution */
 interface ToolCall {
@@ -329,8 +339,13 @@ interface CopilotBackendOptions {
     cliArgs?: string[];
     /** Timeout in milliseconds for sendAndWait() calls. When undefined, uses copilot-sdk default (60s). */
     timeout?: number;
+    /** Timeout in milliseconds for CLI startup and auth check (default: 30000). */
+    startupTimeoutMs?: number;
     /** Custom environment variables merged into the subprocess env */
     env?: Record<string, string | undefined>;
+    /** Session ID to resume after server restart. On startup, the backend attempts
+     *  to resume this session before creating a new one. */
+    resumeSessionId?: string;
 }
 /** Options for Claude CLI backend */
 interface ClaudeBackendOptions {
@@ -341,6 +356,9 @@ interface ClaudeBackendOptions {
     oauthToken?: string;
     /** Custom environment variables merged into the subprocess env */
     env?: Record<string, string | undefined>;
+    /** Session ID to resume after server restart. On startup, the backend attempts
+     *  to resume this session before creating a new one. */
+    resumeSessionId?: string;
 }
 /** Options for Vercel AI SDK backend */
 interface VercelAIBackendOptions {
@@ -349,4 +367,4 @@ interface VercelAIBackendOptions {
     baseUrl?: string;
 }
 
-export type { CopilotBackendOptions as C, IAgentService as I, VercelAIBackendOptions as V, ClaudeBackendOptions as a };
+export type { AgentEvent as A, CopilotBackendOptions as C, IAgentService as I, Message as M, ToolDefinition as T, UsageData as U, VercelAIBackendOptions as V, ClaudeBackendOptions as a, IAgent as b, AgentConfig as c, ModelInfo as d, ToolResult as e };

package/dist/types-DLZzlJxt.d.ts

@@ -0,0 +1,39 @@
+import { IChatProvider, ChatSession, SendMessageOptions, ChatEvent } from './chat/core.js';
+import { I as IAgentService, c as AgentConfig } from './types-CqvUAYxt.js';
+
+/**
+ * @witqq/agent-sdk/chat/backends/types
+ *
+ * IBackendAdapter extends IChatProvider with session resume capabilities.
+ * Backend adapters own the IAgentService lifecycle and normalize events.
+ */
+
+/** Options for creating a backend adapter */
+interface BackendAdapterOptions {
+    /** Agent configuration (model, systemPrompt, tools, etc.) */
+    agentConfig: AgentConfig;
+    /** Pre-created agent service (if adapter should not own lifecycle) */
+    agentService?: IAgentService;
+}
+/**
+ * Extended chat provider with session resume support.
+ * Adapters wrap an IAgentService, manage its lifecycle,
+ * and bridge AgentEvent → ChatEvent via the existing bridge.
+ */
+interface IBackendAdapter extends IChatProvider {
+    /** Whether this adapter supports session resume */
+    canResume(): boolean;
+    /**
+     * Resume a previous session by its backend session ID.
+     * Streams events from the resumed session.
+     * @throws ChatError with SESSION_EXPIRED if session is no longer valid
+     * @throws ChatError with SESSION_NOT_FOUND if session ID is unknown
+     */
+    resume(session: ChatSession, backendSessionId: string, options?: SendMessageOptions): AsyncIterable<ChatEvent>;
+    /** The backend session ID from the last stream, or null if not yet streamed */
+    readonly backendSessionId: string | null;
+    /** The underlying agent service (for advanced consumers) */
+    readonly agentService: IAgentService;
+}
+
+export type { BackendAdapterOptions as B, IBackendAdapter as I };

package/dist/types-tE0CXwBl.d.cts

@@ -0,0 +1,39 @@
+import { IChatProvider, ChatSession, SendMessageOptions, ChatEvent } from './chat/core.cjs';
+import { I as IAgentService, c as AgentConfig } from './types-CqvUAYxt.cjs';
+
+/**
+ * @witqq/agent-sdk/chat/backends/types
+ *
+ * IBackendAdapter extends IChatProvider with session resume capabilities.
+ * Backend adapters own the IAgentService lifecycle and normalize events.
+ */
+
+/** Options for creating a backend adapter */
+interface BackendAdapterOptions {
+    /** Agent configuration (model, systemPrompt, tools, etc.) */
+    agentConfig: AgentConfig;
+    /** Pre-created agent service (if adapter should not own lifecycle) */
+    agentService?: IAgentService;
+}
+/**
+ * Extended chat provider with session resume support.
+ * Adapters wrap an IAgentService, manage its lifecycle,
+ * and bridge AgentEvent → ChatEvent via the existing bridge.
+ */
+interface IBackendAdapter extends IChatProvider {
+    /** Whether this adapter supports session resume */
+    canResume(): boolean;
+    /**
+     * Resume a previous session by its backend session ID.
+     * Streams events from the resumed session.
+     * @throws ChatError with SESSION_EXPIRED if session is no longer valid
+     * @throws ChatError with SESSION_NOT_FOUND if session ID is unknown
+     */
+    resume(session: ChatSession, backendSessionId: string, options?: SendMessageOptions): AsyncIterable<ChatEvent>;
+    /** The backend session ID from the last stream, or null if not yet streamed */
+    readonly backendSessionId: string | null;
+    /** The underlying agent service (for advanced consumers) */
+    readonly agentService: IAgentService;
+}
+
+export type { BackendAdapterOptions as B, IBackendAdapter as I };