@github/copilot-sdk 1.0.28 → 1.0.29-preview.1

package/README.md

@@ -41,6 +41,24 @@ verify all eight platforms.
 npm install @github/copilot-sdk
 ```
 
+## Model provider metadata
+
+`client.listModels()` and `client.rpc.models.list()` preserve the runtime's optional
+`provider` reference on each model: `{ id, kind, label }`. The existing `Model`,
+`ModelInfo`, and `ModelProviderRef` types are available from the package root.
+Native kinds remain `copilot` and `loki`; `id` is opaque and `label` is display text.
+Configured BYOK and older, unattributed rows omit `provider`; do not infer Copilot
+branding from a model ID or fill it from the active account. This metadata identifies
+the model source, not the agent harness, an account, or a new routing/selection API.
+
+## Kerberos authentication callback
+
+Provide `kerberosAuth: { mode, callback }` in `CopilotClientOptions` when Kerberos tickets must be obtained by the SDK host, for example from Windows when the runtime runs in WSL. The runtime currently uses it for proxy authentication. The callback receives `{ spn }`, a service principal in the platform-independent `service/host[@REALM]` form, and returns a fresh base64 SPNEGO token without the `Negotiate ` prefix, or `undefined` when credentials are unavailable. The callback should validate the principal before issuing credentials. Its second argument is an `AbortSignal` that fires when the runtime stops waiting (it cancels the request, for example after its timeout, or the connection closes); the SDK then stops awaiting the callback and ignores any later result.
+
+With `mode: "fallback"`, native credential acquisition (including the first token) is tried first; only failure invokes the callback. With `mode: "always"`, native credential lookup is never attempted. Without this option, behavior is unchanged. Registration happens during `start()`, before sessions can be created.
+
+By default the callback authenticates only requests made for sessions this client creates or resumes. With `scope: "runtime"` it also authenticates the runtime's shared background traffic, such as catalog refreshes and telemetry; only one connection at a time can hold that scope, so startup fails if another client holds it. The registration ends when the connection closes. In `fallback` mode, if the callback cannot supply a valid token, the native credential error is reported. In `always` mode, a disconnected, throwing, or empty callback fails authentication. The runtime waits at most 30 seconds for the callback (less when the request's own deadline is sooner) and treats a timeout as a callback failure. Tokens are not cached and must not be logged or persisted. The callback supplies the initial SPNEGO token only; exchanges requiring continuation tokens still need native negotiation.
+
 ## Runtime-supervised AHP host (experimental)
 
 `startAhpHost()` requires `authentication`: `github`, or direct-only `none` / `custom`
@@ -275,16 +293,15 @@ new CopilotClient(options?: CopilotClientOptions)
 - `logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all"` - Log level. When omitted, the runtime uses its own default (currently `"info"`).
 - `env?: Record<string, string | undefined>` - Environment variables for the runtime process. When omitted, inherits `process.env`.
 
-    For the native standalone runtime, set `COPILOT_GITHUB_TELEMETRY_DISABLED=true`
-    before startup to disable direct GitHub telemetry uploads for the entire host,
-    including session and sessionless events. Authentication, SDK
-    `onGitHubTelemetry` forwarding, and user-configured OpenTelemetry export remain
-    unchanged. The value must be exactly `"true"` and is read at startup; changing
-    it requires a runtime restart. With `RuntimeConnection.forInProcess()`, set it
-    in the host process environment; per-client `env` is rejected for that
-    transport. This is separate from `enableSessionTelemetry: false`, which
-    disables only a session's telemetry pipeline. The Node CLI host does not use
-    this environment variable.
+    Set `COPILOT_TELEMETRY_DISABLED=true` before startup to disable Copilot-owned
+    GitHub and Entra authentication telemetry process-wide, including sessionless
+    events. Authentication, SDK `onGitHubTelemetry` forwarding, and user-configured
+    OpenTelemetry remain unchanged. The value must be exactly `"true"`; restart
+    the process to change it. With `RuntimeConnection.forInProcess()`, set the host
+    process environment; per-client `env` is rejected. `enableSessionTelemetry: false`
+    affects only the session pipeline. The existing native-runtime-only
+    `COPILOT_GITHUB_TELEMETRY_DISABLED=true` remains GitHub-only; the Node CLI host
+    uses the general variable or `--disable-client-telemetry` instead.
 
 - `gitHubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `RuntimeConnection.forUri`.
@@ -372,7 +389,7 @@ Retirement releases session-owned tool, hook, auth/input, provider, workflow, ca
 and transform registrations without changing caller-owned configuration. Late
 registration and callback dispatch are rejected; callbacks already admitted may finish.
 
-##### `createSession(config?: SessionConfig): Promise<CopilotSession>`
+##### `createSession(config: SessionConfig): Promise<CopilotSession>`
 
 Create a new conversation session.
 
@@ -389,6 +406,7 @@ Create a new conversation session.
 - `trustWorkingDirectory?: "session" | "user"` - Grant trust to the canonical working directory during session creation. `"session"` trusts it only for this session; `"user"` persists trust for later sessions. Omit to leave trust unchanged. Not available on resume.
 - `refreshCustomInstructions?: boolean` - Invalidates the process-wide custom-instruction discovery cache before creating this session, so instruction-file edits made in the same runtime are read again. Defaults to `false` (cache reuse). Other sessions in this runtime may observe updated instructions on later turns or discovery. This does not watch files or enable disabled instruction loading. Available on `SessionConfig`, not `ResumeSessionConfig`.
 - `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
+- `enableSessionTelemetry?: boolean` - Disables internal session telemetry only when set to `false`. Omission or `true` enables it for eligible GitHub-authenticated sessions, including custom-provider (BYOK) sessions. Host and account policies still control uploads; this is separate from OpenTelemetry configuration.
 - `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
@@ -411,7 +429,7 @@ const session = await client.createSession({
 
 Initial acquisition runs during session creation or resume. Cancellation, provider errors, and invalid token responses reject that operation instead of falling back to ambient authentication. Idle sessions refresh only before their next credential-consuming operation; there is no background refresh timer.
 
-##### `resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>`
+##### `resumeSession(sessionId: string, config: ResumeSessionConfig): Promise<CopilotSession>`
 
 Both create and resume accept experimental `autopilot: AutopilotOptions`, and
 `session.rpc.options.update({ autopilot: ... })` patches the same policy.
@@ -816,7 +834,7 @@ await session.send({
 });
 ```
 
-Supported image formats include JPG, PNG, GIF, and other common image types. The agent's `view` tool can also read images directly from the filesystem, so you can also ask questions like:
+Supported image formats are PNG, JPEG, WebP, and GIF. Images in other formats, such as BMP or TIFF, are not sent to the model. The agent's `view` tool can also read images directly from the filesystem, so you can also ask questions like:
 
 ```typescript
 await session.send({ prompt: "What does the most recent jpg in this directory portray?" });
@@ -1475,6 +1493,33 @@ security checks, user permissions, or sandbox policy. `permissions.limitTo` neit
 enables the sandbox nor changes `sandbox.userPolicy.network`; configure sandbox
 network restrictions explicitly.
 
+### Policy Helper failures and scoped recheck
+
+Snapshots may expose `policyHelperFailure` and `policyHelperCapabilities`.
+Recheck requires session opt-in through `enableManagedSettings: true`.
+Treat helper text as untrusted plain text, keep `diagnostic` secondary,
+and sanitize `helpLink` before navigation.
+
+```typescript
+const snapshot = await session.rpc.managedSettings.get();
+
+if (snapshot.policyHelperFailure) {
+    console.warn(snapshot.policyHelperFailure.message);
+}
+
+if (snapshot.policyHelperCapabilities?.recheck === true) {
+    const refreshed = await session.rpc.managedSettings.recheckPolicyHelper();
+    // Only a current capable snapshot without policyHelperFailure establishes recovery.
+    console.log(refreshed.policyHelperFailure ?? "Policy Helper recovered");
+}
+```
+
+Older runtimes omit `policyHelperCapabilities`. Do not infer support or recovery
+only because `policyHelperFailure` is absent. Only applicable `session.create` and
+`session.resume` failures attach it to `error.data.policyHelperFailure`, retaining
+the primary code/message. Activation callers read
+`managedSettings.resolve(...).resolved.policyHelperFailure` instead.
+
 ### Permission Result Kinds
 
 The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-result" }`). Approval scopes are present-tense — they describe the decision to apply, not the outcome reported back on session events:

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.105";
+const COPILOT_CLI_VERSION = "1.0.106-2";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -36,7 +36,7 @@ var import_node_crypto = require("node:crypto");
 var import_node_fs = require("node:fs");
 var import_node_net = require("node:net");
 var import_node_path = require("node:path");
-var import_node = require("vscode-jsonrpc/node.js");
+var import_node = require("vscode-jsonrpc/node");
 var import_rpc = require("./generated/rpc.js");
 var import_sdkProtocolVersion = require("./sdkProtocolVersion.js");
 var import_session = require("./session.js");
@@ -46,6 +46,7 @@ var import_cliVersion = require("./cliVersion.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_copilotRequestHandler = require("./copilotRequestHandler.js");
 var import_installationConfirmation = require("./installationConfirmation.js");
+var import_entra = require("./entra.js");
 var import_telemetry = require("./telemetry.js");
 var import_schema = require("./schema.js");
 var import_toolSet = require("./toolSet.js");
@@ -148,6 +149,30 @@ async function waitForChildExit(child, timeoutMs) {
     }
   });
 }
+async function acquireKerberosToken(connection, callback, request, token) {
+  const ended = () => token.isCancellationRequested ? new import_node.ResponseError(-32800, "Kerberos auth request cancelled") : new Error("Kerberos auth connection closed");
+  if (token.isCancellationRequested) {
+    throw ended();
+  }
+  const controller = new AbortController();
+  const abandoned = new Promise((_resolve, reject) => {
+    controller.signal.addEventListener("abort", () => reject(ended()), { once: true });
+  });
+  const abort = () => controller.abort();
+  const subscriptions = [
+    token.onCancellationRequested(abort),
+    connection.onClose(abort),
+    connection.onDispose(abort)
+  ];
+  try {
+    const lookup = Promise.resolve().then(() => callback(request, controller.signal));
+    return { token: await Promise.race([lookup, abandoned]) };
+  } finally {
+    for (const subscription of subscriptions) {
+      subscription.dispose();
+    }
+  }
+}
 const DEFAULT_PROVIDER_NAME = "default";
 function extractBearerTokenProviders(provider, providers) {
   const callbacks = /* @__PURE__ */ new Map();
@@ -325,6 +350,7 @@ class CopilotClient {
   sessionFsConfig = null;
   requestHandler = null;
   extensionLaunchProvider;
+  kerberosAuth;
   installationConfirmationHandler;
   builtinPluginDirectories = [];
   onGitHubTelemetry;
@@ -484,6 +510,7 @@ class CopilotClient {
     this.sessionFsConfig = options.sessionFs ?? null;
     this.requestHandler = options.requestHandler ?? null;
     this.extensionLaunchProvider = options.extensionLaunchProvider;
+    this.kerberosAuth = options.kerberosAuth;
     this.installationConfirmationHandler = options.installationConfirmationHandler;
     this.onGitHubTelemetry = options.onGitHubTelemetry;
     this.setupClientGlobalHandlers();
@@ -499,7 +526,7 @@ class CopilotClient {
     const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
     this.connectionExtraArgs = [...connArgs];
     this.options = {
-      entra: options.entra ? { ...options.entra } : void 0,
+      entra: options.entra ? { ...options.entra, tokenProvider: options.entra.tokenProvider } : void 0,
       workingDirectory: options.workingDirectory ?? process.cwd(),
       logLevel: options.logLevel,
       gitHubToken: options.gitHubToken,
@@ -588,6 +615,11 @@ class CopilotClient {
         "SessionFsConfig declares capabilities.binary but the provider does not implement readFileBytes and writeFileBytes."
       );
     }
+    if (this.sessionFsConfig.capabilities?.readFileRange && !provider.readFileRange) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.readFileRange but the provider does not implement readFileRange."
+      );
+    }
     session.clientSessionApis.sessionFs = (0, import_sessionFsProvider.createSessionFsAdapter)(provider);
   }
   setupClientGlobalHandlers() {
@@ -722,6 +754,10 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.kerberosAuth) {
+        const { mode, scope } = this.kerberosAuth;
+        await this.rpc.kerberosAuth.setProvider(scope ? { mode, scope } : { mode });
+      }
       if (this.extensionLaunchProvider) {
         await this.rpc.registerExtensionLaunchProvider();
       }
@@ -1236,7 +1272,7 @@ class CopilotClient {
     if (config.cloud != null && config.skillProvider) {
       throw new Error("Skill providers are not supported for cloud sessions.");
     }
-    if (!this.connection) {
+    if (!this.connection || this.startPromise) {
       await this.start();
     }
     const modeDefaults = this.configDefaultsForMode();
@@ -1390,6 +1426,7 @@ class CopilotClient {
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
         mcpServers: toWireMcpServers(config.mcpServers),
         ...config.diagnostics !== void 0 ? { diagnostics: config.diagnostics } : {},
+        ...config.lifecycleDiagnostics !== void 0 ? { lifecycleDiagnostics: config.lifecycleDiagnostics } : {},
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         authClientIdMetadataUrl: config.authClientIdMetadataUrl,
         envValueMode: "direct",
@@ -1527,7 +1564,7 @@ class CopilotClient {
     if (config.gitHubToken !== void 0 && config.gitHubTokenProvider !== void 0) {
       throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
     }
-    if (!this.connection) {
+    if (!this.connection || this.startPromise) {
       await this.start();
     }
     const session = new import_session.CopilotSession(
@@ -1675,6 +1712,7 @@ class CopilotClient {
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
         mcpServers: toWireMcpServers(config.mcpServers),
         ...config.diagnostics !== void 0 ? { diagnostics: config.diagnostics } : {},
+        ...config.lifecycleDiagnostics !== void 0 ? { lifecycleDiagnostics: config.lifecycleDiagnostics } : {},
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         authClientIdMetadataUrl: config.authClientIdMetadataUrl,
         envValueMode: "direct",
@@ -2105,7 +2143,11 @@ class CopilotClient {
     let serverVersion;
     try {
       const connectParams = {
-        entra: this.options.entra,
+        entra: this.options.entra && {
+          clientId: this.options.entra.clientId,
+          matsAppName: this.options.entra.matsAppName
+        },
+        entraTokenProvider: this.options.entra?.tokenProvider ? true : void 0,
         token: this.effectiveConnectionToken,
         supportedTaskKinds: ["agent", "client", "shell"]
       };
@@ -2117,6 +2159,9 @@ class CopilotClient {
         connectParams.clientInfo = clientInfo;
       }
       const result = await raceAgainstExit(this.internalRpc.connect(connectParams));
+      if (this.options.entra?.tokenProvider && result.entraTokenProvider !== true) {
+        throw new Error("This runtime does not support host-owned Entra token providers.");
+      }
       serverVersion = result.protocolVersion;
     } catch (err) {
       if (err instanceof import_node.ResponseError && (err.code === import_node.ErrorCodes.MethodNotFound || err.message === "Unhandled method connect")) {
@@ -2373,8 +2418,10 @@ class CopilotClient {
       if (t.filePath !== void 0) env.COPILOT_OTEL_FILE_EXPORTER_PATH = t.filePath;
       if (t.exporterType !== void 0) env.COPILOT_OTEL_EXPORTER_TYPE = t.exporterType;
       if (t.sourceName !== void 0) env.COPILOT_OTEL_SOURCE_NAME = t.sourceName;
-      if (t.captureContent !== void 0)
+      if (t.captureContent !== void 0) {
+        env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT = t.captureContent ? "SPAN_ONLY" : "NO_CONTENT";
         env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT = String(t.captureContent);
+      }
     }
     return env;
   }
@@ -2755,6 +2802,9 @@ stderr: ${stderrOutput}` : ""}`
       return session.clientSessionApis;
     });
     (0, import_rpc.registerClientGlobalApiHandlers)(this.connection, this.clientGlobalHandlers);
+    if (this.options.entra?.tokenProvider) {
+      (0, import_entra.registerEntraTokenProvider)(this.connection, this.options.entra.tokenProvider);
+    }
     if (this.installationConfirmationHandler) {
       const confirmation = (0, import_installationConfirmation.createInstallationConfirmationAdapter)(
         this.connection,
@@ -2765,6 +2815,14 @@ stderr: ${stderrOutput}` : ""}`
         (params, token) => confirmation.confirm(params, token)
       );
     }
+    if (this.kerberosAuth) {
+      const { callback } = this.kerberosAuth;
+      const connection2 = this.connection;
+      this.connection.onRequest(
+        "kerberosAuth.acquire",
+        (params, token) => acquireKerberosToken(connection2, callback, params, token)
+      );
+    }
     this.connection.onRequest(
       "host.materializeSession",
       (params) => this.createHostSession(params)

package/dist/cjs/entra.js

@@ -0,0 +1,83 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var entra_exports = {};
+__export(entra_exports, {
+  registerEntraTokenProvider: () => registerEntraTokenProvider
+});
+module.exports = __toCommonJS(entra_exports);
+var import_node = require("vscode-jsonrpc/node");
+function registerEntraTokenProvider(connection, provider) {
+  const closed = new import_node.CancellationTokenSource();
+  const connectionClosed = closed.token;
+  const close = connection.onClose(() => closed.cancel());
+  const dispose = connection.onDispose(() => {
+    closed.cancel();
+    closed.dispose();
+    close.dispose();
+    dispose.dispose();
+  });
+  connection.onRequest(
+    "entraToken.getToken",
+    async ({ request }, token) => {
+      const combined = new import_node.CancellationTokenSource();
+      const subscriptions = [];
+      const checkCancellation = () => {
+        if (connectionClosed.isCancellationRequested || token.isCancellationRequested) {
+          combined.cancel();
+          throw new import_node.ResponseError(-32800, "Entra token acquisition cancelled");
+        }
+      };
+      try {
+        const cancelled = new Promise((_resolve, reject) => {
+          const cancel = () => {
+            combined.cancel();
+            reject(new import_node.ResponseError(-32800, "Entra token acquisition cancelled"));
+          };
+          subscriptions.push(
+            token.onCancellationRequested(cancel),
+            connectionClosed.onCancellationRequested(cancel)
+          );
+        });
+        checkCancellation();
+        const result = await Promise.race([
+          Promise.resolve().then(() => {
+            checkCancellation();
+            return provider(request, combined.token);
+          }),
+          cancelled
+        ]);
+        checkCancellation();
+        if (result === void 0 || result === null) {
+          throw new import_node.ResponseError(-32603, "Entra token provider failed");
+        }
+        return result;
+      } catch {
+        checkCancellation();
+        throw new import_node.ResponseError(-32603, "Entra token provider failed");
+      } finally {
+        for (const subscription of subscriptions) subscription.dispose();
+        combined.dispose();
+      }
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  registerEntraTokenProvider
+});

package/dist/cjs/generated/lifecycle-diagnostics.js

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var lifecycle_diagnostics_exports = {};
+module.exports = __toCommonJS(lifecycle_diagnostics_exports);