@github/copilot-sdk-darwin-arm64 0.0.1 → 1.0.13-preview.6

package/copilot-sdk/runtimeArtifacts.d.ts

@@ -0,0 +1,6 @@
+export interface RuntimeArtifactSources {
+    packageRoot: string;
+    platform: string;
+}
+export declare function defaultRuntimeCacheRoot(platform?: NodeJS.Platform, home?: string, environment?: NodeJS.ProcessEnv): string;
+export declare function materializeRuntimeBundle(sources: RuntimeArtifactSources, cacheRoot?: string): string;

package/copilot-sdk/sdkProtocolVersion.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The SDK protocol version.
+ * This must match the version expected by the copilot-agent-runtime server.
+ */
+export declare const SDK_PROTOCOL_VERSION = 3;
+/**
+ * Gets the SDK protocol version.
+ * @returns The protocol version number
+ */
+export declare function getSdkProtocolVersion(): number;

package/copilot-sdk/session.d.ts

@@ -0,0 +1,331 @@
+import { createSessionRpc } from "./generated/rpc.js";
+import type { OpenCanvasInstance } from "./generated/rpc.js";
+import type { MessageOptions, ContextTier, ReasoningEffort, ReasoningSummary, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
+import { type SessionFactoryApi } from "./factory.js";
+/** Assistant message event - the final response from the assistant. */
+export type AssistantMessageEvent = Extract<SessionEvent, {
+    type: "assistant.message";
+}>;
+/**
+ * Represents a single conversation session with the Copilot CLI.
+ *
+ * A session maintains conversation state, handles events, and manages tool execution.
+ * Sessions are created via {@link CopilotClient.createSession} or resumed via
+ * {@link CopilotClient.resumeSession}.
+ *
+ * @example
+ * ```typescript
+ * const session = await client.createSession({ model: "gpt-4" });
+ *
+ * // Subscribe to events
+ * session.on((event) => {
+ *   if (event.type === "assistant.message") {
+ *     console.log(event.data.content);
+ *   }
+ * });
+ *
+ * // Send a message and wait for completion
+ * await session.sendAndWait({ prompt: "Hello, world!" });
+ *
+ * // Clean up
+ * await session.disconnect();
+ * ```
+ */
+/**
+ * Fixed name of the runtime's built-in tool-search tool. A client can replace
+ * its behavior by registering a {@link Tool} with this exact name and
+ * `overridesBuiltInTool: true`.
+ */
+export declare class CopilotSession {
+    readonly sessionId: string;
+    private connection;
+    private _workspacePath?;
+    private eventHandlers;
+    private typedEventHandlers;
+    private toolHandlers;
+    private canvases;
+    private bearerTokenProviders;
+    private commandHandlers;
+    private factories;
+    private factoryAbortControllers;
+    private permissionHandler?;
+    private mcpAuthHandler?;
+    private userInputHandler?;
+    private elicitationHandler?;
+    private exitPlanModeHandler?;
+    private autoModeSwitchHandler?;
+    private hooks?;
+    private transformCallbacks?;
+    private _rpc;
+    private traceContextProvider?;
+    private readonly managedSettingsEnabled;
+    private _capabilities;
+    private openCanvasInstances;
+    private disconnected;
+    private onDisconnected?;
+    /**
+     * Friendly factory API for running registered factories by name or handle.
+     *
+     * @experimental Part of the experimental Agent Factories surface and may
+     * change or be removed in future SDK or CLI releases.
+     */
+    readonly factory: SessionFactoryApi;
+    /**
+     * Resolve a start/resume envelope into the terminal envelope callers expect.
+     *
+     * The CLI may answer `session.factory.run` and `session.factory.resume`
+     * before the run settles, so a non-terminal envelope is followed by a wait
+     * on the run's terminal state.
+     */
+    private settleFactoryRun;
+    /**
+     * Resolve when a factory run reaches a terminal status.
+     *
+     * The subscription is installed *before* the first read so a transition
+     * landing between the two cannot be missed, and re-reads are serialized so
+     * overlapping invalidation events cannot interleave — the run's revision
+     * advances once per operation, so a burst of events is common and must
+     * collapse into a single in-flight read. A bounded periodic re-read keeps a
+     * dropped invalidation from leaving the wait pending forever.
+     */
+    private waitForFactoryRun;
+    /**
+     * Typed session-scoped RPC methods.
+     */
+    get rpc(): ReturnType<typeof createSessionRpc>;
+    /**
+     * Path to the session workspace directory when infinite sessions are enabled.
+     * Contains checkpoints/, plan.md, and files/ subdirectories.
+     * Undefined if infinite sessions are disabled.
+     */
+    get workspacePath(): string | undefined;
+    /**
+     * Host capabilities reported when the session was created or resumed.
+     * Use this to check feature support before calling capability-gated APIs.
+     */
+    get capabilities(): SessionCapabilities;
+    /**
+     * Interactive UI methods for showing dialogs to the user.
+     * Only available when the CLI host supports elicitation
+     * (`session.capabilities.ui?.elicitation === true`).
+     *
+     * @example
+     * ```typescript
+     * if (session.capabilities.ui?.elicitation) {
+     *   const ok = await session.ui.confirm("Deploy to production?");
+     * }
+     * ```
+     */
+    get ui(): SessionUiApi;
+    /**
+     * Sends a message to this session and waits for the response.
+     *
+     * The message is processed asynchronously. Subscribe to events via {@link on}
+     * to receive streaming responses and other session events.
+     *
+     * @param options - The message options including the prompt and optional attachments
+     * @returns A promise that resolves with the message ID of the response
+     * @throws Error if the session has been disconnected or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const messageId = await session.send({
+     *   prompt: "Explain this code",
+     *   attachments: [{ type: "file", path: "./src/index.ts" }]
+     * });
+     * ```
+     */
+    send(prompt: string): Promise<string>;
+    send(options: MessageOptions): Promise<string>;
+    /**
+     * Sends a message to this session and waits until the session becomes idle.
+     *
+     * This is a convenience method that combines {@link send} with waiting for
+     * the `session.idle` event. Use this when you want to block until the
+     * assistant has finished processing the message.
+     *
+     * Events are still delivered to handlers registered via {@link on} while waiting.
+     *
+     * @param options - The message options including the prompt and optional attachments
+     * @param timeout - Timeout in milliseconds (default: 60000). Controls how long to wait; does not abort in-flight agent work.
+     * @returns A promise that resolves with the final assistant message when the session becomes idle,
+     *          or undefined if no assistant message was received
+     * @throws Error if the timeout is reached before the session becomes idle
+     * @throws Error if the session has been disconnected or the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Send and wait for completion with default 60s timeout
+     * const response = await session.sendAndWait({ prompt: "What is 2+2?" });
+     * console.log(response?.data.content); // "4"
+     * ```
+     */
+    sendAndWait(prompt: string, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    sendAndWait(options: MessageOptions, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    /**
+     * Subscribes to events from this session.
+     *
+     * Events include assistant messages, tool executions, errors, and session state changes.
+     * Multiple handlers can be registered and will all receive events.
+     *
+     * @param eventType - The specific event type to listen for (e.g., "assistant.message", "session.idle")
+     * @param handler - A callback function that receives events of the specified type
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * // Listen for a specific event type
+     * const unsubscribe = session.on("assistant.message", (event) => {
+     *   console.log("Assistant:", event.data.content);
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on<K extends SessionEventType>(eventType: K, handler: TypedSessionEventHandler<K>): () => void;
+    /**
+     * Subscribes to all events from this session.
+     *
+     * @param handler - A callback function that receives all session events
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = session.on((event) => {
+     *   switch (event.type) {
+     *     case "assistant.message":
+     *       console.log("Assistant:", event.data.content);
+     *       break;
+     *     case "session.error":
+     *       console.error("Error:", event.data.message);
+     *       break;
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on(handler: SessionEventHandler): () => void;
+    private upsertOpenCanvasFromEvent;
+    private removeOpenCanvasFromEvent;
+    private removeOpenCanvas;
+    private upsertOpenCanvas;
+    /**
+     * Snapshot of canvas instances currently known to be open for this session.
+     * Populated from the `session.resume` response and live `session.canvas.opened`
+     * and `session.canvas.closed` events. Returns a defensive copy — mutating the
+     * returned array has no effect on the session.
+     */
+    get openCanvases(): OpenCanvasInstance[];
+    private assertElicitation;
+    private _elicitation;
+    private _confirm;
+    private _select;
+    private _input;
+    /**
+     * Retrieves all events and messages from this session's history.
+     *
+     * This returns the complete conversation history including user messages,
+     * assistant responses, tool executions, and other session events.
+     *
+     * @returns A promise that resolves with an array of all session events
+     * @throws Error if the session has been disconnected or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const events = await session.getEvents();
+     * for (const event of events) {
+     *   if (event.type === "assistant.message") {
+     *     console.log("Assistant:", event.data.content);
+     *   }
+     * }
+     * ```
+     */
+    getEvents(): Promise<SessionEvent[]>;
+    /**
+     * Disconnects this session and releases all in-memory resources (event handlers,
+     * tool handlers, permission handlers).
+     *
+     * Session state on disk (conversation history, planning state, artifacts) is
+     * preserved, so the conversation can be resumed later by calling
+     * {@link CopilotClient.resumeSession} with the session ID. To permanently
+     * remove all session data including files on disk, use
+     * {@link CopilotClient.deleteSession} instead.
+     *
+     * After calling this method, the session object can no longer be used.
+     *
+     * @returns A promise that resolves when the session is disconnected
+     * @throws Error if the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Clean up when done — session can still be resumed later
+     * await session.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /** Enables `await using session = ...` syntax for automatic cleanup. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Aborts the currently processing message in this session.
+     *
+     * Use this to cancel a long-running request. The session remains valid
+     * and can continue to be used for new messages.
+     *
+     * @returns A promise that resolves when the abort request is acknowledged
+     * @throws Error if the session has been disconnected or the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Start a long-running request
+     * const messagePromise = session.send({ prompt: "Write a very long story..." });
+     *
+     * // Abort after 5 seconds
+     * setTimeout(async () => {
+     *   await session.abort();
+     * }, 5000);
+     * ```
+     */
+    abort(): Promise<void>;
+    /**
+     * Change the model for this session.
+     * The new model takes effect for the next message. Conversation history is preserved.
+     *
+     * @param model - Model ID to switch to
+     * @param options - Optional settings for the new model
+     *
+     * @example
+     * ```typescript
+     * await session.setModel("gpt-5.4");
+     * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
+     * ```
+     */
+    setModel(model: string, options?: {
+        reasoningEffort?: ReasoningEffort;
+        reasoningSummary?: ReasoningSummary;
+        contextTier?: ContextTier;
+        modelCapabilities?: ModelCapabilitiesOverride;
+    }): Promise<void>;
+    /**
+     * Log a message to the session timeline.
+     * The message appears in the session event stream and is visible to SDK consumers
+     * and (for non-ephemeral messages) persisted to the session event log on disk.
+     *
+     * @param message - Human-readable message text
+     * @param options - Optional log level and ephemeral flag
+     *
+     * @example
+     * ```typescript
+     * await session.log("Processing started");
+     * await session.log("Disk usage high", { level: "warning" });
+     * await session.log("Connection failed", { level: "error" });
+     * await session.log("Debug info", { ephemeral: true });
+     * ```
+     */
+    log(message: string, options?: {
+        level?: "info" | "warning" | "error";
+        ephemeral?: boolean;
+    }): Promise<void>;
+}

package/copilot-sdk/sessionFsProvider.d.ts

@@ -0,0 +1,107 @@
+import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteTransactionErrorClass, SessionFsSqliteQueryType } from "./generated/rpc.js";
+export type { SessionFsSqliteQueryType, SessionFsSqliteTransactionErrorClass };
+/**
+ * File metadata returned by {@link SessionFsProvider.stat}.
+ * Same shape as the generated {@link SessionFsStatResult} but without the
+ * `error` field, since providers signal errors by throwing.
+ */
+export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
+/**
+ * Result of a SQLite query execution via {@link SessionFsSqliteProvider.query}.
+ * Same shape as the generated {@link GeneratedSqliteQueryResult} but without the
+ * `error` field, since providers signal errors by throwing.
+ */
+export type SessionFsSqliteQueryResult = Omit<GeneratedSqliteQueryResult, "error">;
+/**
+ * One statement in an atomic SQLite transaction passed to
+ * {@link SessionFsSqliteProvider.transaction}.
+ */
+export interface SessionFsSqliteStatement {
+    /** How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE. */
+    queryType: SessionFsSqliteQueryType;
+    /** SQL statement to execute. */
+    query: string;
+    /** Optional named bind parameters. */
+    params?: Record<string, string | number | null>;
+}
+/**
+ * Error thrown by {@link SessionFsSqliteProvider.transaction} to classify a
+ * transaction failure for the runtime.
+ *
+ * Any other thrown value is reported as `"fatal"`. Throw this with
+ * `"busyOrLocked"` when SQLite reported BUSY/LOCKED before commit and the
+ * transaction was rolled back, so the runtime knows the call is safe to retry.
+ */
+export declare class SessionFsSqliteTransactionFailure extends Error {
+    /** Failure classification reported to the runtime. */
+    readonly errorClass: SessionFsSqliteTransactionErrorClass;
+    constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
+}
+/**
+ * SQLite operations for the per-session database.
+ * Implementers provide query execution and existence checking.
+ */
+export interface SessionFsSqliteProvider {
+    /**
+     * Execute a SQLite query against the per-session database.
+     *
+     * @param queryType - How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE.
+     * @param query - SQL query to execute.
+     * @param params - Optional named bind parameters.
+     */
+    query(queryType: SessionFsSqliteQueryType, query: string, params?: Record<string, string | number | null>): Promise<SessionFsSqliteQueryResult | undefined>;
+    /**
+     * Execute `statements` atomically against the per-session database.
+     *
+     * Apply busy handling to every statement and roll back the whole batch if
+     * any statement fails. Throw {@link SessionFsSqliteTransactionFailure} to
+     * classify the failure; any other thrown value is reported as `"fatal"`.
+     *
+     * @param statements - Statements to execute in order inside a single transaction.
+     * @returns One result per statement, in the same order.
+     */
+    transaction?(statements: SessionFsSqliteStatement[]): Promise<SessionFsSqliteQueryResult[]>;
+    /**
+     * Check whether the per-session database already exists, without creating it.
+     */
+    exists(): Promise<boolean>;
+}
+/**
+ * Interface for session filesystem providers. Implementers use idiomatic
+ * TypeScript patterns: throw on error, return values directly. Use
+ * {@link createSessionFsAdapter} to convert a provider into the
+ * {@link SessionFsHandler} expected by the SDK.
+ *
+ * Errors with a `code` property of `"ENOENT"` are mapped to the ENOENT
+ * error code; all others map to UNKNOWN.
+ */
+export interface SessionFsProvider {
+    /** Reads the full content of a file. Throw if the file does not exist. */
+    readFile(path: string): Promise<string>;
+    /** Writes content to a file, creating parent directories if needed. */
+    writeFile(path: string, content: string, mode?: number): Promise<void>;
+    /** Appends content to a file, creating parent directories if needed. */
+    appendFile(path: string, content: string, mode?: number): Promise<void>;
+    /** Checks whether a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Gets metadata about a file or directory. Throw if it does not exist. */
+    stat(path: string): Promise<SessionFsFileInfo>;
+    /** Creates a directory. If recursive is true, creates parents as needed. */
+    mkdir(path: string, recursive: boolean, mode?: number): Promise<void>;
+    /** Lists entry names in a directory. Throw if it does not exist. */
+    readdir(path: string): Promise<string[]>;
+    /** Lists entries with type info. Throw if the directory does not exist. */
+    readdirWithTypes(path: string): Promise<SessionFsReaddirWithTypesEntry[]>;
+    /** Removes a file or directory. If force is true, do not throw on ENOENT. */
+    rm(path: string, recursive: boolean, force: boolean): Promise<void>;
+    /** Renames/moves a file or directory. */
+    rename(src: string, dest: string): Promise<void>;
+    /** Per-session SQLite database operations. Optional — omit if the provider does not support SQLite. */
+    sqlite?: SessionFsSqliteProvider;
+}
+/**
+ * Wraps a {@link SessionFsProvider} into the {@link SessionFsHandler}
+ * interface expected by the SDK, converting thrown errors into
+ * {@link SessionFsError} results.
+ */
+export declare function createSessionFsAdapter(provider: SessionFsProvider): SessionFsHandler;

package/copilot-sdk/telemetry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Trace-context helpers.
+ *
+ * The SDK does not depend on any OpenTelemetry packages.  Instead, users
+ * provide an {@link TraceContextProvider} callback via client options.
+ *
+ * @module telemetry
+ */
+import type { TraceContext, TraceContextProvider } from "./types.js";
+/**
+ * Calls the user-provided {@link TraceContextProvider} to obtain the current
+ * W3C Trace Context.  Returns `{}` when no provider is configured.
+ */
+export declare function getTraceContext(provider?: TraceContextProvider): Promise<TraceContext>;

package/copilot-sdk/toolSet.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Builder that produces a list of source-qualified tool filter strings for
+ * {@link SessionConfigBase.availableTools}.
+ *
+ * Tools are classified by the runtime at registration time (not from name
+ * parsing), so `addBuiltIn("foo")` matches only tools the runtime registered
+ * as built-in, even if an MCP server or custom-agent extension happens to
+ * register a tool with the same wire name.
+ *
+ * @example
+ * ```typescript
+ * const tools = new ToolSet()
+ *     .addBuiltIn(BuiltInTools.Isolated)
+ *     .addMcp("*")
+ *     .addCustom("*");
+ *
+ * const session = await client.createSession({
+ *     availableTools: tools,
+ *     // ...
+ * });
+ * ```
+ */
+export declare class ToolSet {
+    private readonly items;
+    /**
+     * Adds one or more built-in tool patterns.
+     *
+     * @param name A specific built-in tool name (e.g. `"bash"`) or `"*"` to match all
+     *   built-in tools.
+     */
+    addBuiltIn(name: string): ToolSet;
+    /**
+     * Adds a list of built-in tool patterns (e.g. {@link BuiltInTools.Isolated}).
+     */
+    addBuiltIn(names: readonly string[]): ToolSet;
+    /**
+     * Adds a custom tool pattern. Matches tools registered via the SDK's
+     * `tools` option or via custom agents.
+     *
+     * @param name A specific custom tool name or `"*"` to match all custom tools.
+     */
+    addCustom(name: string): ToolSet;
+    /**
+     * Adds an MCP tool pattern. Matches tools advertised by any configured
+     * MCP server.
+     *
+     * @param toolName The runtime's canonical wire name for the MCP tool
+     *   (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
+     *   any server.
+     */
+    addMcp(toolName: string): ToolSet;
+    /**
+     * Returns a defensive copy of the accumulated filter strings, suitable for
+     * passing as {@link SessionConfigBase.availableTools}.
+     */
+    toArray(): string[];
+}
+/**
+ * Curated sets of built-in tool names for common scenarios. Each constant is
+ * meant to be passed to {@link ToolSet.addBuiltIn}.
+ */
+export declare const BuiltInTools: {
+    /**
+     * Built-in tools that operate only within the bounds of a single session —
+     * no host filesystem access outside the session, no cross-session state,
+     * no host environment access, no network. Safe to enable in `Mode = "empty"`
+     * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
+     *
+     * **Contract:** tools in this set MUST NOT be extended (even behind options
+     * or args) to read or write state outside the session boundary. Adding
+     * cross-session or host-state behavior to one of these tools is a
+     * breaking change that requires removing it from this set.
+     */
+    readonly Isolated: readonly string[];
+};