@github/copilot-sdk 0.0.1 → 0.1.10-preview.0

package/dist/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Type definitions for the Copilot SDK
+ */
+import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+export type SessionEvent = GeneratedSessionEvent;
+/**
+ * Options for creating a CopilotClient
+ */
+export interface CopilotClientOptions {
+    /**
+     * Path to the Copilot CLI executable
+     * @default "copilot" (searches PATH)
+     */
+    cliPath?: string;
+    /**
+     * Extra arguments to pass to the CLI executable (inserted before SDK-managed args)
+     */
+    cliArgs?: string[];
+    /**
+     * Working directory for the CLI process
+     * If not set, inherits the current process's working directory
+     */
+    cwd?: string;
+    /**
+     * Port for the CLI server (TCP mode only)
+     * @default 0 (random available port)
+     */
+    port?: number;
+    /**
+     * Use stdio transport instead of TCP
+     * When true, communicates with CLI via stdin/stdout pipes
+     * @default true
+     */
+    useStdio?: boolean;
+    /**
+     * URL of an existing Copilot CLI server to connect to over TCP
+     * When provided, the client will not spawn a CLI process
+     * Format: "host:port" or "http://host:port" or just "port" (defaults to localhost)
+     * Examples: "localhost:8080", "http://127.0.0.1:9000", "8080"
+     * Mutually exclusive with cliPath, useStdio
+     */
+    cliUrl?: string;
+    /**
+     * Log level for the CLI server
+     */
+    logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
+    /**
+     * Auto-start the CLI server on first use
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Auto-restart the CLI server if it crashes
+     * @default true
+     */
+    autoRestart?: boolean;
+    /**
+     * Environment variables to pass to the CLI process. If not set, inherits process.env.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Configuration for creating a session
+ */
+export type ToolResultType = "success" | "failure" | "rejected" | "denied";
+export type ToolBinaryResult = {
+    data: string;
+    mimeType: string;
+    type: string;
+    description?: string;
+};
+export type ToolResultObject = {
+    textResultForLlm: string;
+    binaryResultsForLlm?: ToolBinaryResult[];
+    resultType: ToolResultType;
+    error?: string;
+    sessionLog?: string;
+    toolTelemetry?: Record<string, unknown>;
+};
+export type ToolResult = string | ToolResultObject;
+export interface ToolInvocation {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+}
+export type ToolHandler<TArgs = unknown> = (args: TArgs, invocation: ToolInvocation) => Promise<unknown> | unknown;
+/**
+ * Zod-like schema interface for type inference.
+ * Any object with `toJSONSchema()` method is treated as a Zod schema.
+ */
+export interface ZodSchema<T = unknown> {
+    _output: T;
+    toJSONSchema(): Record<string, unknown>;
+}
+/**
+ * Tool definition. Parameters can be either:
+ * - A Zod schema (provides type inference for handler)
+ * - A raw JSON schema object
+ * - Omitted (no parameters)
+ */
+export interface Tool<TArgs = unknown> {
+    name: string;
+    description?: string;
+    parameters?: ZodSchema<TArgs> | Record<string, unknown>;
+    handler: ToolHandler<TArgs>;
+}
+/**
+ * Helper to define a tool with Zod schema and get type inference for the handler.
+ * Without this helper, TypeScript cannot infer handler argument types from Zod schemas.
+ */
+export declare function defineTool<T = unknown>(name: string, config: {
+    description?: string;
+    parameters?: ZodSchema<T> | Record<string, unknown>;
+    handler: ToolHandler<T>;
+}): Tool<T>;
+export interface ToolCallRequestPayload {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+}
+export interface ToolCallResponsePayload {
+    result: ToolResult;
+}
+/**
+ * Append mode: Use CLI foundation with optional appended content (default).
+ */
+export interface SystemMessageAppendConfig {
+    mode?: "append";
+    /**
+     * Additional instructions appended after SDK-managed sections.
+     */
+    content?: string;
+}
+/**
+ * Replace mode: Use caller-provided system message entirely.
+ * Removes all SDK guardrails including security restrictions.
+ */
+export interface SystemMessageReplaceConfig {
+    mode: "replace";
+    /**
+     * Complete system message content.
+     * Replaces the entire SDK-managed system message.
+     */
+    content: string;
+}
+/**
+ * System message configuration for session creation.
+ * - Append mode (default): SDK foundation + optional custom content
+ * - Replace mode: Full control, caller provides entire system message
+ */
+export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig;
+export interface SessionConfig {
+    /**
+     * Optional custom session ID
+     * If not provided, server will generate one
+     */
+    sessionId?: string;
+    /**
+     * Model to use for this session
+     */
+    model?: string;
+    /**
+     * Tools exposed to the CLI server
+     */
+    tools?: Tool<any>[];
+    /**
+     * System message configuration
+     * Controls how the system prompt is constructed
+     */
+    systemMessage?: SystemMessageConfig;
+    /**
+     * List of tool names to allow. When specified, only these tools will be available.
+     * Takes precedence over excludedTools.
+     */
+    availableTools?: string[];
+    /**
+     * List of tool names to disable. All other tools remain available.
+     * Ignored if availableTools is specified.
+     */
+    excludedTools?: string[];
+    /**
+     * Custom provider configuration (BYOK - Bring Your Own Key).
+     * When specified, uses the provided API endpoint instead of the Copilot API.
+     */
+    provider?: ProviderConfig;
+    /**
+     * Enable streaming of assistant message and reasoning chunks.
+     * When true, ephemeral assistant.message_delta and assistant.reasoning_delta
+     * events are sent as the response is generated. Clients should accumulate
+     * deltaContent values to build the full response.
+     * @default false
+     */
+    streaming?: boolean;
+}
+/**
+ * Configuration for resuming a session
+ */
+export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming">;
+/**
+ * Configuration for a custom API provider.
+ */
+export interface ProviderConfig {
+    /**
+     * Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
+     */
+    type?: "openai" | "azure" | "anthropic";
+    /**
+     * API format (openai/azure only). Defaults to "completions".
+     */
+    wireApi?: "completions" | "responses";
+    /**
+     * API endpoint URL
+     */
+    baseUrl: string;
+    /**
+     * API key. Optional for local providers like Ollama.
+     */
+    apiKey?: string;
+    /**
+     * Bearer token for authentication. Sets the Authorization header directly.
+     * Use this for services requiring bearer token auth instead of API key.
+     * Takes precedence over apiKey when both are set.
+     */
+    bearerToken?: string;
+    /**
+     * Azure-specific options
+     */
+    azure?: {
+        /**
+         * API version. Defaults to "2024-10-21".
+         */
+        apiVersion?: string;
+    };
+}
+/**
+ * Options for sending a message to a session
+ */
+export interface MessageOptions {
+    /**
+     * The prompt/message to send
+     */
+    prompt: string;
+    /**
+     * File or directory attachments
+     */
+    attachments?: Array<{
+        type: "file" | "directory";
+        path: string;
+        displayName?: string;
+    }>;
+    /**
+     * Message delivery mode
+     * - "enqueue": Add to queue (default)
+     * - "immediate": Send immediately
+     */
+    mode?: "enqueue" | "immediate";
+}
+/**
+ * Event handler callback type
+ */
+export type SessionEventHandler = (event: SessionEvent) => void;
+/**
+ * Connection state
+ */
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * Metadata about a session
+ */
+export interface SessionMetadata {
+    sessionId: string;
+    startTime: Date;
+    modifiedTime: Date;
+    summary?: string;
+    isRemote: boolean;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+function defineTool(name, config) {
+  return { name, ...config };
+}
+export {
+  defineTool
+};

package/package.json

@@ -1,5 +1,70 @@
-
 {
   "name": "@github/copilot-sdk",
-  "version": "0.0.1"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/github/copilot-sdk.git"
+  },
+  "version": "0.1.10-preview.0",
+  "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf --glob dist *.tgz",
+    "build": "tsx esbuild-copilotsdk-nodejs.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" --ignore-path .prettierignore",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" --ignore-path .prettierignore",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "generate:session-types": "tsx scripts/generate-session-types.ts",
+    "prepublishOnly": "npm run build",
+    "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.1.0 --no-git-tag-version --allow-same-version"
+  },
+  "keywords": [
+    "github",
+    "copilot",
+    "sdk",
+    "jsonrpc",
+    "agent"
+  ],
+  "author": "GitHub",
+  "license": "MIT",
+  "dependencies": {
+    "@github/copilot": "^0.0.377",
+    "vscode-jsonrpc": "^8.2.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "esbuild": "^0.27.0",
+    "eslint": "^9.0.0",
+    "glob": "^11.0.0",
+    "json-schema": "^0.4.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "prettier": "^3.4.0",
+    "quicktype-core": "^23.2.6",
+    "rimraf": "^6.1.2",
+    "semver": "^7.7.3",
+    "tsx": "^4.20.6",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ]
 }