@witqq/agent-sdk 0.1.0

package/dist/types-JVBEqeDw.d.cts

@@ -0,0 +1,288 @@
+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>;
+}
+
+/** 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;
+}
+
+export type { CopilotBackendOptions as C, IAgentService as I, VercelAIBackendOptions as V, ClaudeBackendOptions as a };

package/dist/types-JVBEqeDw.d.ts

@@ -0,0 +1,288 @@
+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>;
+}
+
+/** 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;
+}
+
+export type { CopilotBackendOptions as C, IAgentService as I, VercelAIBackendOptions as V, ClaudeBackendOptions as a };

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@witqq/agent-sdk",
+  "version": "0.1.0",
+  "description": "Universal AI agent abstraction layer supporting Copilot CLI, Claude CLI, and Vercel AI SDK backends",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./copilot": {
+      "import": {
+        "types": "./dist/backends/copilot.d.ts",
+        "default": "./dist/backends/copilot.js"
+      },
+      "require": {
+        "types": "./dist/backends/copilot.d.cts",
+        "default": "./dist/backends/copilot.cjs"
+      }
+    },
+    "./claude": {
+      "import": {
+        "types": "./dist/backends/claude.d.ts",
+        "default": "./dist/backends/claude.js"
+      },
+      "require": {
+        "types": "./dist/backends/claude.d.cts",
+        "default": "./dist/backends/claude.cjs"
+      }
+    },
+    "./vercel-ai": {
+      "import": {
+        "types": "./dist/backends/vercel-ai.d.ts",
+        "default": "./dist/backends/vercel-ai.js"
+      },
+      "require": {
+        "types": "./dist/backends/vercel-ai.d.cts",
+        "default": "./dist/backends/vercel-ai.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "copilot",
+    "claude",
+    "vercel-ai",
+    "llm",
+    "tools",
+    "sdk"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@ai-sdk/openai-compatible": ">=2.0.0",
+    "@anthropic-ai/claude-agent-sdk": ">=0.2.0",
+    "@github/copilot-sdk": "^0.1.22",
+    "ai": ">=4.0.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependenciesMeta": {
+    "@github/copilot-sdk": {
+      "optional": true
+    },
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.27",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.34",
+    "@github/copilot-sdk": "^0.1.22",
+    "@types/node": "^25.2.1",
+    "ai": "^6.0.73",
+    "testfold": "^0.2.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "zod": "^3.24.0"
+  }
+}