@github/copilot-sdk 0.1.33-preview.2 → 0.1.33-preview.4

package/dist/session.js

@@ -1,5 +1,6 @@
 import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+import { getTraceContext } from "./telemetry.js";
 const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 class CopilotSession {
   /**
@@ -8,12 +9,14 @@ class CopilotSession {
    * @param sessionId - The unique identifier for this session
    * @param connection - The JSON-RPC message connection to the Copilot CLI
    * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+   * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
    * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
    */
-  constructor(sessionId, connection, _workspacePath) {
+  constructor(sessionId, connection, _workspacePath, traceContextProvider) {
     this.sessionId = sessionId;
     this.connection = connection;
     this._workspacePath = _workspacePath;
+    this.traceContextProvider = traceContextProvider;
   }
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
@@ -21,7 +24,9 @@ class CopilotSession {
   permissionHandler;
   userInputHandler;
   hooks;
+  transformCallbacks;
   _rpc = null;
+  traceContextProvider;
   /**
    * Typed session-scoped RPC methods.
    */
@@ -59,6 +64,7 @@ class CopilotSession {
    */
   async send(options) {
     const response = await this.connection.sendRequest("session.send", {
+      ...await getTraceContext(this.traceContextProvider),
       sessionId: this.sessionId,
       prompt: options.prompt,
       attachments: options.attachments,
@@ -188,9 +194,19 @@ class CopilotSession {
       const { requestId, toolName } = event.data;
       const args = event.data.arguments;
       const toolCallId = event.data.toolCallId;
+      const traceparent = event.data.traceparent;
+      const tracestate = event.data.tracestate;
       const handler = this.toolHandlers.get(toolName);
       if (handler) {
-        void this._executeToolAndRespond(requestId, toolName, toolCallId, args, handler);
+        void this._executeToolAndRespond(
+          requestId,
+          toolName,
+          toolCallId,
+          args,
+          handler,
+          traceparent,
+          tracestate
+        );
       }
     } else if (event.type === "permission.requested") {
       const { requestId, permissionRequest } = event.data;
@@ -203,13 +219,15 @@ class CopilotSession {
    * Executes a tool handler and sends the result back via RPC.
    * @internal
    */
-  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler) {
+  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
     try {
       const rawResult = await handler(args, {
         sessionId: this.sessionId,
         toolCallId,
         toolName,
-        arguments: args
+        arguments: args,
+        traceparent,
+        tracestate
       });
       let result;
       if (rawResult == null) {
@@ -323,6 +341,40 @@ class CopilotSession {
   registerHooks(hooks) {
     this.hooks = hooks;
   }
+  /**
+   * Registers transform callbacks for system message sections.
+   *
+   * @param callbacks - Map of section ID to transform callback, or undefined to clear
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerTransformCallbacks(callbacks) {
+    this.transformCallbacks = callbacks;
+  }
+  /**
+   * Handles a systemMessage.transform request from the runtime.
+   * Dispatches each section to its registered transform callback.
+   *
+   * @param sections - Map of section IDs to their current rendered content
+   * @returns A promise that resolves with the transformed sections
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSystemMessageTransform(sections) {
+    const result = {};
+    for (const [sectionId, { content }] of Object.entries(sections)) {
+      const callback = this.transformCallbacks?.get(sectionId);
+      if (callback) {
+        try {
+          const transformed = await callback(content);
+          result[sectionId] = { content: transformed };
+        } catch (_error) {
+          result[sectionId] = { content };
+        }
+      } else {
+        result[sectionId] = { content };
+      }
+    }
+    return { sections: result };
+  }
   /**
    * Handles a permission request in the v2 protocol format (synchronous RPC).
    * Used as a back-compat adapter when connected to a v2 server.
@@ -502,14 +554,16 @@ class CopilotSession {
    * 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-4.1");
+   * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
    * ```
    */
-  async setModel(model) {
-    await this.rpc.model.switchTo({ modelId: model });
+  async setModel(model, options) {
+    await this.rpc.model.switchTo({ modelId: model, ...options });
   }
   /**
    * Log a message to the session timeline.

package/dist/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/dist/telemetry.js

@@ -0,0 +1,11 @@
+async function getTraceContext(provider) {
+  if (!provider) return {};
+  try {
+    return await provider() ?? {};
+  } catch {
+    return {};
+  }
+}
+export {
+  getTraceContext
+};

package/dist/types.d.ts

@@ -6,6 +6,38 @@ export type SessionEvent = GeneratedSessionEvent;
 /**
  * Options for creating a CopilotClient
  */
+/**
+ * W3C Trace Context headers used for distributed trace propagation.
+ */
+export interface TraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+/**
+ * Callback that returns the current W3C Trace Context.
+ * Wire this up to your OpenTelemetry (or other tracing) SDK to enable
+ * distributed trace propagation between your app and the Copilot CLI.
+ */
+export type TraceContextProvider = () => TraceContext | Promise<TraceContext>;
+/**
+ * Configuration for OpenTelemetry instrumentation.
+ *
+ * When provided via {@link CopilotClientOptions.telemetry}, the SDK sets
+ * the corresponding environment variables on the spawned CLI process so
+ * that the CLI's built-in OTel exporter is configured automatically.
+ */
+export interface TelemetryConfig {
+    /** OTLP HTTP endpoint URL for trace/metric export. Sets OTEL_EXPORTER_OTLP_ENDPOINT. */
+    otlpEndpoint?: string;
+    /** File path for JSON-lines trace output. Sets COPILOT_OTEL_FILE_EXPORTER_PATH. */
+    filePath?: string;
+    /** Exporter backend type: "otlp-http" or "file". Sets COPILOT_OTEL_EXPORTER_TYPE. */
+    exporterType?: string;
+    /** Instrumentation scope name. Sets COPILOT_OTEL_SOURCE_NAME. */
+    sourceName?: string;
+    /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
+    captureContent?: boolean;
+}
 export interface CopilotClientOptions {
     /**
      * Path to the CLI executable or JavaScript entry point.
@@ -83,6 +115,37 @@ export interface CopilotClientOptions {
      * available from your custom provider.
      */
     onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
+    /**
+     * OpenTelemetry configuration for the CLI process.
+     * When provided, the corresponding OTel environment variables are set
+     * on the spawned CLI server.
+     */
+    telemetry?: TelemetryConfig;
+    /**
+     * Advanced: callback that returns the current W3C Trace Context for distributed
+     * trace propagation.  Most users do not need this — the {@link telemetry} config
+     * alone is sufficient to collect traces from the CLI.
+     *
+     * This callback is only useful when your application creates its own
+     * OpenTelemetry spans and you want them to appear in the **same** distributed
+     * trace as the CLI's spans.  The SDK calls this before `session.create`,
+     * `session.resume`, and `session.send` RPCs to inject `traceparent`/`tracestate`
+     * into the request.
+     *
+     * @example
+     * ```typescript
+     * import { propagation, context } from "@opentelemetry/api";
+     *
+     * const client = new CopilotClient({
+     *   onGetTraceContext: () => {
+     *     const carrier: Record<string, string> = {};
+     *     propagation.inject(context.active(), carrier);
+     *     return carrier;
+     *   },
+     * });
+     * ```
+     */
+    onGetTraceContext?: TraceContextProvider;
 }
 /**
  * Configuration for creating a session
@@ -108,6 +171,10 @@ export interface ToolInvocation {
     toolCallId: string;
     toolName: string;
     arguments: unknown;
+    /** W3C Trace Context traceparent from the CLI's execute_tool span. */
+    traceparent?: string;
+    /** W3C Trace Context tracestate from the CLI's execute_tool span. */
+    tracestate?: string;
 }
 export type ToolHandler<TArgs = unknown> = (args: TArgs, invocation: ToolInvocation) => Promise<unknown> | unknown;
 /**
@@ -160,6 +227,46 @@ export interface ToolCallRequestPayload {
 export interface ToolCallResponsePayload {
     result: ToolResult;
 }
+/**
+ * Known system prompt section identifiers for the "customize" mode.
+ * Each section corresponds to a distinct part of the system prompt.
+ */
+export type SystemPromptSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "last_instructions";
+/** Section metadata for documentation and tooling. */
+export declare const SYSTEM_PROMPT_SECTIONS: Record<SystemPromptSection, {
+    description: string;
+}>;
+/**
+ * Transform callback for a single section: receives current content, returns new content.
+ */
+export type SectionTransformFn = (currentContent: string) => string | Promise<string>;
+/**
+ * Override action: a string literal for static overrides, or a callback for transforms.
+ *
+ * - `"replace"`: Replace section content entirely
+ * - `"remove"`: Remove the section
+ * - `"append"`: Append to existing section content
+ * - `"prepend"`: Prepend to existing section content
+ * - `function`: Transform callback — receives current section content, returns new content
+ */
+export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | SectionTransformFn;
+/**
+ * Override operation for a single system prompt section.
+ */
+export interface SectionOverride {
+    /**
+     * The operation to perform on this section.
+     * Can be a string action or a transform callback function.
+     */
+    action: SectionOverrideAction;
+    /**
+     * Content for the override. Optional for all actions.
+     * - For replace, omitting content replaces with an empty string.
+     * - For append/prepend, content is added before/after the existing section.
+     * - Ignored for the remove action.
+     */
+    content?: string;
+}
 /**
  * Append mode: Use CLI foundation with optional appended content (default).
  */
@@ -182,12 +289,31 @@ export interface SystemMessageReplaceConfig {
      */
     content: string;
 }
+/**
+ * Customize mode: Override individual sections of the system prompt.
+ * Keeps the SDK-managed prompt structure while allowing targeted modifications.
+ */
+export interface SystemMessageCustomizeConfig {
+    mode: "customize";
+    /**
+     * Override specific sections of the system prompt by section ID.
+     * Unknown section IDs gracefully fall back: content-bearing overrides are appended
+     * to additional instructions, and "remove" on unknown sections is a silent no-op.
+     */
+    sections?: Partial<Record<SystemPromptSection, SectionOverride>>;
+    /**
+     * Additional content appended after all sections.
+     * Equivalent to append mode's content field — provided for convenience.
+     */
+    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
+ * - Customize mode: Section-level overrides with graceful fallback
  */
-export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig;
+export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
 /**
  * Permission request types from the server
  */
@@ -686,7 +812,7 @@ export interface MessageOptions {
      */
     prompt: string;
     /**
-     * File, directory, or selection attachments
+     * File, directory, selection, or blob attachments
      */
     attachments?: Array<{
         type: "file";
@@ -711,6 +837,11 @@ export interface MessageOptions {
             };
         };
         text?: string;
+    } | {
+        type: "blob";
+        data: string;
+        mimeType: string;
+        displayName?: string;
     }>;
     /**
      * Message delivery mode

package/dist/types.js

@@ -1,8 +1,23 @@
 function defineTool(name, config) {
   return { name, ...config };
 }
+const SYSTEM_PROMPT_SECTIONS = {
+  identity: { description: "Agent identity preamble and mode statement" },
+  tone: { description: "Response style, conciseness rules, output formatting preferences" },
+  tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
+  environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
+  code_change_rules: { description: "Coding rules, linting/testing, ecosystem tools, style" },
+  guidelines: { description: "Tips, behavioral best practices, behavioral guidelines" },
+  safety: { description: "Environment limitations, prohibited actions, security policies" },
+  tool_instructions: { description: "Per-tool usage instructions" },
+  custom_instructions: { description: "Repository and organization custom instructions" },
+  last_instructions: {
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+  }
+};
 const approveAll = () => ({ kind: "approved" });
 export {
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 };

package/package.json

@@ -4,18 +4,30 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.1.33-preview.2",
+  "version": "0.1.33-preview.4",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./extension": {
-      "import": "./dist/extension.js",
-      "types": "./dist/extension.d.ts"
+      "import": {
+        "types": "./dist/extension.d.ts",
+        "default": "./dist/extension.js"
+      },
+      "require": {
+        "types": "./dist/extension.d.ts",
+        "default": "./dist/cjs/extension.js"
+      }
     }
   },
   "type": "module",
@@ -44,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.4",
+    "@github/copilot": "^1.0.10-0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },