@witqq/agent-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,444 @@
+import { z } from 'zod';
+
+/** Pluggable store for persisting permission (scope) decisions across runs. */
+interface IPermissionStore {
+    /** Check if tool is already approved */
+    isApproved(toolName: string): Promise<boolean>;
+    /** Store an approval decision */
+    approve(toolName: string, scope: PermissionScope): Promise<void>;
+    /** Revoke approval for a tool */
+    revoke(toolName: string): Promise<void>;
+    /** Clear all approvals */
+    clear(): Promise<void>;
+    /** Dispose resources */
+    dispose(): Promise<void>;
+}
+/** In-memory store — approvals live until process exits (or dispose). */
+declare class InMemoryPermissionStore implements IPermissionStore {
+    private approvals;
+    isApproved(toolName: string): Promise<boolean>;
+    approve(toolName: string, scope: PermissionScope): Promise<void>;
+    revoke(toolName: string): Promise<void>;
+    clear(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** File-backed store — reads/writes a JSON file for persistent approvals. */
+declare class FilePermissionStore implements IPermissionStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    isApproved(toolName: string): Promise<boolean>;
+    approve(toolName: string, scope: PermissionScope): Promise<void>;
+    revoke(toolName: string): Promise<void>;
+    clear(): Promise<void>;
+    dispose(): Promise<void>;
+    private readFile;
+    private writeFileAtomic;
+}
+/**
+ * Composes multiple stores — checks in order, routes writes by scope.
+ *
+ * - "session" → sessionStore (in-memory)
+ * - "project" → projectStore (file-based in project directory)
+ * - "always"  → userStore (file-based in user home)
+ */
+declare class CompositePermissionStore implements IPermissionStore {
+    private readonly sessionStore;
+    private readonly projectStore;
+    private readonly userStore;
+    constructor(sessionStore: IPermissionStore, projectStore: IPermissionStore, userStore?: IPermissionStore);
+    isApproved(toolName: string): Promise<boolean>;
+    approve(toolName: string, scope: PermissionScope): Promise<void>;
+    revoke(toolName: string): Promise<void>;
+    clear(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Create a default composite store with separate project and user-level persistence. */
+declare function createDefaultPermissionStore(projectDir?: string): CompositePermissionStore;
+
+/** JSON-serializable value used for tool arguments and results */
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/** Message content — plain string or array of text/image parts */
+type MessageContent = string | Array<ContentPart>;
+/** Individual content part within a multi-part message */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/** What the LLM sees — name, description, schema. Passed to all backends. */
+interface ToolDeclaration<TParams = unknown> {
+    name: string;
+    description: string;
+    parameters: z.ZodType<TParams>;
+    needsApproval?: boolean;
+    metadata?: {
+        category?: string;
+        icon?: string;
+        tags?: string[];
+    };
+}
+/** Full tool with execute function. Required for API-based backends.
+ *  CLI backends extract declaration; execute map held internally. */
+interface ToolDefinition<TParams = unknown> extends ToolDeclaration<TParams> {
+    execute: (params: TParams) => Promise<JSONValue> | JSONValue;
+}
+/** A tool call made by the LLM during execution */
+interface ToolCall {
+    id: string;
+    name: string;
+    args: JSONValue;
+}
+/** Result of executing a tool call */
+interface ToolResult {
+    toolCallId: string;
+    name: string;
+    result: JSONValue;
+    isError?: boolean;
+}
+/** Conversation message — discriminated union on `role` */
+type Message = {
+    role: "user";
+    content: MessageContent;
+} | {
+    role: "assistant";
+    content: MessageContent;
+    toolCalls?: ToolCall[];
+} | {
+    role: "tool";
+    content?: string;
+    toolResults: ToolResult[];
+} | {
+    role: "system";
+    content: string;
+};
+/** Scope for "remember this decision" */
+type PermissionScope = "once" | "session" | "project" | "always";
+/** What the permission callback receives */
+interface PermissionRequest {
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+    /** SDK-suggested scope (from Claude CLI's suggestions) */
+    suggestedScope?: PermissionScope;
+    /** Original SDK permission request (for pass-through) */
+    rawSDKRequest?: unknown;
+}
+/** What the permission callback returns */
+interface PermissionDecision {
+    allowed: boolean;
+    /** How long to remember this decision */
+    scope?: PermissionScope;
+    /** Modified tool arguments (tool args may be altered by user) */
+    modifiedInput?: Record<string, unknown>;
+    /** Denial reason (if denied) */
+    reason?: string;
+}
+/** Permission callback signature */
+type PermissionCallback = (request: PermissionRequest, signal: AbortSignal) => Promise<PermissionDecision>;
+/** Request for user input — separate from permissions */
+interface UserInputRequest {
+    question: string;
+    choices?: string[];
+    /** Whether to allow freeform text input (default: true) */
+    allowFreeform?: boolean;
+}
+/** Response from user to an input request */
+interface UserInputResponse {
+    answer: string;
+    /** true if user typed a custom answer instead of selecting a choice */
+    wasFreeform: boolean;
+    /** Index of selected choice (if choice was selected) */
+    selectedChoiceIndex?: number;
+}
+/** Hooks for supervisor/UI to intercept agent actions */
+interface SupervisorHooks {
+    onPermission?: PermissionCallback;
+    onAskUser?: (request: UserInputRequest, signal: AbortSignal) => Promise<UserInputResponse>;
+}
+/** Configuration for typed structured output from LLM */
+interface StructuredOutputConfig<T = unknown> {
+    schema: z.ZodType<T>;
+    name?: string;
+    description?: string;
+}
+/** Events emitted during streaming agent execution */
+type AgentEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call_start";
+    toolName: string;
+    args: JSONValue;
+} | {
+    type: "tool_call_end";
+    toolName: string;
+    result: JSONValue;
+} | {
+    type: "permission_request";
+    request: PermissionRequest;
+} | {
+    type: "permission_response";
+    toolName: string;
+    decision: PermissionDecision;
+} | {
+    type: "ask_user";
+    request: UserInputRequest;
+} | {
+    type: "ask_user_response";
+    answer: string;
+} | {
+    type: "thinking_start";
+} | {
+    type: "thinking_end";
+} | {
+    type: "usage_update";
+    promptTokens: number;
+    completionTokens: number;
+} | {
+    type: "error";
+    error: string;
+    recoverable: boolean;
+} | {
+    type: "done";
+    finalOutput: string | null;
+    structuredOutput?: unknown;
+};
+/** Options passed to agent.run() / agent.stream() */
+interface RunOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Arbitrary context passed to the agent run */
+    context?: Record<string, unknown>;
+}
+/** LLM model parameters */
+interface ModelParams {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+}
+/** Timeout configuration for agent operations */
+interface TimeoutConfig {
+    /** Max time for entire agent run (ms) */
+    total?: number;
+    /** Max time for a single tool execution (ms) */
+    perTool?: number;
+    /** Max time for a single LLM request (ms) */
+    perLLMRequest?: number;
+}
+/** Error handling strategy configuration */
+interface ErrorHandlingConfig {
+    /** What to do when a tool throws */
+    onToolError?: "fail" | "continue" | "ask-llm";
+    /** Retry config for transient LLM failures */
+    retryLLM?: {
+        maxAttempts: number;
+        backoffMs: number;
+    };
+    /** Global error callback for monitoring */
+    onError?: (error: Error, context: {
+        phase: "tool" | "llm" | "permission" | "ask-user";
+    }) => void;
+}
+/** Configuration for creating an agent */
+interface AgentConfig {
+    model?: string;
+    modelParams?: ModelParams;
+    systemPrompt: string;
+    tools: ToolDefinition[];
+    supervisor?: SupervisorHooks;
+    maxTurns?: number;
+    timeout?: TimeoutConfig;
+    errorHandling?: ErrorHandlingConfig;
+    /** Pluggable store for persisting permission scope decisions across runs */
+    permissionStore?: IPermissionStore;
+}
+/** Result of an agent run, generic over structured output type T */
+interface AgentResult<T = void> {
+    output: string | null;
+    structuredOutput: T extends void ? undefined : T;
+    toolCalls: Array<{
+        toolName: string;
+        args: JSONValue;
+        result: JSONValue;
+        approved: boolean;
+    }>;
+    messages: Message[];
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+/** Agent lifecycle state */
+type AgentState = "idle" | "running" | "streaming" | "disposed";
+/** Core agent interface — run prompts, stream events, manage lifecycle */
+interface IAgent {
+    run(prompt: MessageContent, options?: RunOptions): Promise<AgentResult>;
+    runWithContext(messages: Message[], options?: RunOptions): Promise<AgentResult>;
+    runStructured<T>(prompt: MessageContent, schema: StructuredOutputConfig<T>, options?: RunOptions): Promise<AgentResult<T>>;
+    stream(prompt: MessageContent, options?: RunOptions): AsyncIterable<AgentEvent>;
+    abort(): void;
+    getState(): AgentState;
+    getConfig(): Readonly<AgentConfig>;
+    /** Release resources. After dispose(), agent must not be used. */
+    dispose(): void;
+}
+/** Model metadata returned by listModels() */
+interface ModelInfo {
+    id: string;
+    name?: string;
+    provider?: string;
+}
+/** Result of backend validation check */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Backend service interface — creates agents, lists models, validates config */
+interface IAgentService {
+    readonly name: string;
+    createAgent(config: AgentConfig): IAgent;
+    listModels(): Promise<ModelInfo[]>;
+    validate(): Promise<ValidationResult>;
+    dispose(): Promise<void>;
+}
+/** Options for Copilot CLI backend */
+interface CopilotBackendOptions {
+    cliPath?: string;
+    workingDirectory?: string;
+    githubToken?: string;
+    useLoggedInUser?: boolean;
+}
+/** Options for Claude CLI backend */
+interface ClaudeBackendOptions {
+    cliPath?: string;
+    workingDirectory?: string;
+    maxTurns?: number;
+}
+/** Options for Vercel AI SDK backend */
+interface VercelAIBackendOptions {
+    apiKey: string;
+    provider?: string;
+    baseUrl?: string;
+}
+/** Type guard: checks if a ToolDeclaration has an execute function (i.e., is a ToolDefinition) */
+declare function isToolDefinition(tool: ToolDeclaration): tool is ToolDefinition;
+/** Type guard: checks if MessageContent is plain string */
+declare function isTextContent(content: MessageContent): content is string;
+/** Type guard: checks if MessageContent is multi-part array */
+declare function isMultiPartContent(content: MessageContent): content is ContentPart[];
+/** Extract text from MessageContent regardless of format */
+declare function getTextContent(content: MessageContent): string;
+
+/** Base error class for agent-sdk */
+declare class AgentSDKError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when agent.run() is called while already running (M8 re-entrancy guard) */
+declare class ReentrancyError extends AgentSDKError {
+    constructor();
+}
+/** Thrown when an operation is attempted on a disposed agent/service */
+declare class DisposedError extends AgentSDKError {
+    constructor(entity: string);
+}
+/** Thrown when a backend is not found in the registry */
+declare class BackendNotFoundError extends AgentSDKError {
+    constructor(backend: string);
+}
+/** Thrown when a backend is already registered */
+declare class BackendAlreadyRegisteredError extends AgentSDKError {
+    constructor(backend: string);
+}
+/** Thrown when subprocess management fails */
+declare class SubprocessError extends AgentSDKError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when a required peer dependency is not installed */
+declare class DependencyError extends AgentSDKError {
+    readonly packageName: string;
+    constructor(packageName: string);
+}
+/** Thrown when an agent run is aborted */
+declare class AbortError extends AgentSDKError {
+    constructor();
+}
+/** Thrown when a tool execution fails */
+declare class ToolExecutionError extends AgentSDKError {
+    readonly toolName: string;
+    constructor(toolName: string, message: string, options?: ErrorOptions);
+}
+/** Thrown when structured output parsing fails */
+declare class StructuredOutputError extends AgentSDKError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/** Factory function that creates a backend service from options */
+type BackendFactory<TOptions = unknown> = (options: TOptions) => IAgentService | Promise<IAgentService>;
+/** Map of built-in backend names to their options types */
+interface BackendOptionsMap {
+    copilot: CopilotBackendOptions;
+    claude: ClaudeBackendOptions;
+    "vercel-ai": VercelAIBackendOptions;
+}
+/** All known backend names (built-in + custom) */
+type BuiltinBackendName = keyof BackendOptionsMap;
+/** Register a custom backend factory */
+declare function registerBackend<TOptions = unknown>(name: string, factory: BackendFactory<TOptions>): void;
+/** Unregister a backend (primarily for testing) */
+declare function unregisterBackend(name: string): boolean;
+/** Check if a backend is registered */
+declare function hasBackend(name: string): boolean;
+/** List all registered backend names */
+declare function listBackends(): string[];
+/** Reset registry to initial state (for testing) */
+declare function resetRegistry(): void;
+/** Create a backend service with type-safe options */
+declare function createAgentService<K extends BuiltinBackendName>(name: K, options: BackendOptionsMap[K]): Promise<IAgentService>;
+declare function createAgentService(name: string, options: unknown): Promise<IAgentService>;
+
+/** Abstract base agent with shared lifecycle logic.
+ *  Concrete backends extend this and implement the protected _run/_stream methods. */
+declare abstract class BaseAgent implements IAgent {
+    protected state: AgentState;
+    protected abortController: AbortController | null;
+    protected readonly config: AgentConfig;
+    constructor(config: AgentConfig);
+    run(prompt: MessageContent, options?: RunOptions): Promise<AgentResult>;
+    runWithContext(messages: Message[], options?: RunOptions): Promise<AgentResult>;
+    runStructured<T>(prompt: MessageContent, schema: StructuredOutputConfig<T>, options?: RunOptions): Promise<AgentResult<T>>;
+    stream(prompt: MessageContent, options?: RunOptions): AsyncIterable<AgentEvent>;
+    abort(): void;
+    getState(): AgentState;
+    getConfig(): Readonly<AgentConfig>;
+    /** Mark agent as disposed. Override to add cleanup. */
+    dispose(): void;
+    /** Execute a blocking run. Backend implements the actual LLM call. */
+    protected abstract executeRun(messages: Message[], options: RunOptions | undefined, signal: AbortSignal): Promise<AgentResult>;
+    /** Execute a structured output run. Backend implements parsing. */
+    protected abstract executeRunStructured<T>(messages: Message[], schema: StructuredOutputConfig<T>, options: RunOptions | undefined, signal: AbortSignal): Promise<AgentResult<T>>;
+    /** Execute a streaming run. Backend yields events. */
+    protected abstract executeStream(messages: Message[], options: RunOptions | undefined, signal: AbortSignal): AsyncIterable<AgentEvent>;
+    protected guardReentrancy(): void;
+    protected guardDisposed(): void;
+    /** Throw AbortError if signal is already aborted */
+    protected checkAbort(signal: AbortSignal): void;
+    private createAbortController;
+}
+
+/** Convert a Zod schema to JSON Schema.
+ *  Uses zod's built-in jsonSchema() if available, falls back to _def extraction. */
+declare function zodToJsonSchema(schema: z.ZodType): Record<string, unknown>;
+
+/** Convert our Message[] to a flat prompt string (for CLIs that accept text) */
+declare function messagesToPrompt(messages: Message[]): string;
+/** Convert MessageContent to plain text */
+declare function contentToText(content: MessageContent): string;
+/** Build a system prompt with optional structured output instruction */
+declare function buildSystemPrompt(base: string, schemaInstruction?: string): string;
+
+export { AbortError, type AgentConfig, type AgentEvent, type AgentResult, AgentSDKError, type AgentState, BackendAlreadyRegisteredError, type BackendFactory, BackendNotFoundError, type BackendOptionsMap, BaseAgent, type BuiltinBackendName, type ClaudeBackendOptions, CompositePermissionStore, type ContentPart, type CopilotBackendOptions, DependencyError, DisposedError, type ErrorHandlingConfig, FilePermissionStore, type IAgent, type IAgentService, type IPermissionStore, InMemoryPermissionStore, type JSONValue, type Message, type MessageContent, type ModelInfo, type ModelParams, type PermissionCallback, type PermissionDecision, type PermissionRequest, type PermissionScope, ReentrancyError, type RunOptions, type StructuredOutputConfig, StructuredOutputError, SubprocessError, type SupervisorHooks, type TimeoutConfig, type ToolCall, type ToolDeclaration, type ToolDefinition, ToolExecutionError, type ToolResult, type UserInputRequest, type UserInputResponse, type ValidationResult, type VercelAIBackendOptions, buildSystemPrompt, contentToText, createAgentService, createDefaultPermissionStore, getTextContent, hasBackend, isMultiPartContent, isTextContent, isToolDefinition, listBackends, messagesToPrompt, registerBackend, resetRegistry, unregisterBackend, zodToJsonSchema };