@github/copilot-sdk-darwin-arm64 1.0.15-unstable.35663726336.gcb2a8cc → 1.0.15

package/copilot-sdk/installationConfirmation.d.ts

@@ -0,0 +1,19 @@
+import { type CancellationToken, type MessageConnection } from "vscode-jsonrpc/node.js";
+import type { InstallationConfirmationRequest, InstallationDecision, InstallationsConfirmResult } from "./generated/rpc.js";
+/** The `installations.confirm` receiver, invoked with the transport's request cancellation. */
+export interface InstallationConfirmationReceiver {
+    confirm(request: InstallationConfirmationRequest, token: CancellationToken): Promise<InstallationsConfirmResult>;
+}
+/**
+ * Collects an explicit human decision for the complete runtime review.
+ * Match operationId and policySessionId to the exact action registered by the host
+ * before displaying it. Refuse unknown actions or incomplete reviews; never infer
+ * authority from the current session or a global pending slot.
+ *
+ * The SDK echoes the original challenge and fingerprint. Separately spawned UI
+ * work must observe the token to retire itself when the request or connection ends.
+ * Registering this callback does not enable installation capabilities.
+ * @experimental
+ */
+export type InstallationConfirmationHandler = (request: InstallationConfirmationRequest, token: CancellationToken) => InstallationDecision | Promise<InstallationDecision>;
+export declare function createInstallationConfirmationAdapter(connection: MessageConnection, handler: InstallationConfirmationHandler): InstallationConfirmationReceiver;

package/copilot-sdk/schema.d.ts

@@ -0,0 +1,4 @@
+import type { ResponseSchema, ZodSchema } from "./types.js";
+export declare function isZodSchema(value: unknown): value is ZodSchema;
+export declare function toJsonSchema(schema: ZodSchema | Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export declare function isResponseSchema(value: unknown): value is ResponseSchema;

package/copilot-sdk/session.d.ts

@@ -1,8 +1,8 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { ModelSwitchAutoTierResult } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
-import type { MessageOptions, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
-import { type SessionFactoryApi } from "./factory.js";
+import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
+import { type SessionWorkflowApi } from "./workflow.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -48,8 +48,8 @@ export declare class CopilotSession {
     private canvases;
     private bearerTokenProviders;
     private commandHandlers;
-    private factories;
-    private factoryAbortControllers;
+    private workflows;
+    private workflowAbortControllers;
     private permissionHandler?;
     private mcpAuthHandler?;
     private userInputHandler?;
@@ -65,25 +65,19 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    private readonly pendingStructuredWaits;
     private disconnecting;
     private onDisconnected?;
     /**
-     * Friendly factory API for running registered factories by name or handle.
+     * Friendly workflow API for running registered workflows by name or handle.
      *
-     * @experimental Part of the experimental Agent Factories surface and may
+     * @experimental Part of the experimental Dynamic Workflows surface and may
      * change or be removed in future SDK or CLI releases.
      */
-    readonly factory: SessionFactoryApi;
+    readonly workflow: SessionWorkflowApi;
+    private settleWorkflowRun;
     /**
-     * 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.
+     * Resolve when a workflow 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
@@ -92,7 +86,7 @@ export declare class CopilotSession {
      * collapse into a single in-flight read. A bounded periodic re-read keeps a
      * dropped invalidation from leaving the wait pending forever.
      */
-    private waitForFactoryRun;
+    private waitForWorkflowRun;
     /**
      * Typed session-scoped RPC methods.
      */
@@ -122,13 +116,14 @@ export declare class CopilotSession {
      */
     get ui(): SessionUiApi;
     /**
-     * Sends a message to this session and waits for the response.
+     * Sends a message to this session and returns once it is admitted.
      *
      * 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
+     * @returns The submitted user message's ID, not an assistant response ID.
+     *          When this send starts a run, root assistant messages carry it as originatingMessageId.
      * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
@@ -149,6 +144,10 @@ export declare class CopilotSession {
      * assistant has finished processing the message.
      *
      * Events are still delivered to handlers registered via {@link on} while waiting.
+     * Sub-agent events with a non-empty `agentId` do not complete the wait or supply its reply.
+     * With a schema as the second argument, returns its parsed, validated result.
+     * Structured waits select only root-agent output originating from this send;
+     * other queued work may delay session.idle but cannot replace the result.
      *
      * @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.
@@ -165,7 +164,9 @@ export declare class CopilotSession {
      * ```
      */
     sendAndWait(prompt: string, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    sendAndWait<TResult>(options: MessageOptions | string, responseSchema: ResponseSchema<TResult>, timeout?: number): Promise<TResult>;
     sendAndWait(options: MessageOptions, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    private sendAndWaitForStructuredMessage;
     /**
      * Subscribes to events from this session.
      *

package/copilot-sdk/types.d.ts

@@ -4,14 +4,16 @@
 import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
-import type { AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { InstallationConfirmationHandler } from "./installationConfirmation.js";
+export type { InstallationConfirmationHandler } from "./installationConfirmation.js";
+import type { AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
-import type { FactoryJsonSchema, JsonValue } from "./factory.js";
-import type { GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
+import type { JsonValue } from "./workflow.js";
+import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
-export type { GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
+export type { ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorStatus, ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, } from "./generated/rpc.js";
 /**
  * Arguments passed to a session's {@link GitHubTokenProvider}.
  *
@@ -282,6 +284,20 @@ export interface CopilotClientOptions {
      * startup before any sessions can be created.
      */
     builtinPluginDirectories?: readonly string[];
+    /**
+     * Connection-level extension launch profile provider.
+     * When set, the client registers the provider during startup before any
+     * session can be created.
+     *
+     * @experimental
+     */
+    extensionLaunchProvider?: ExtensionLaunchProvider;
+    /**
+     * Connection-global human review for experimental installation operations.
+     * Does not register or enable installation capabilities on the runtime.
+     * @experimental
+     */
+    installationConfirmationHandler?: InstallationConfirmationHandler;
     /**
      * Log level for the Copilot runtime. When omitted, the runtime uses its
      * own default (currently `"info"`).
@@ -409,6 +425,8 @@ export interface CopilotClientOptions {
      */
     clientInfo?: CopilotClientInfo;
 }
+/** Resolves launch profiles for extension entrypoints discovered by the runtime. */
+export type ExtensionLaunchProvider = GeneratedExtensionLaunchProvider;
 /**
  * Configuration for creating a session
  */
@@ -510,6 +528,13 @@ export interface ZodSchema<T = unknown> {
     _output: T;
     toJSONSchema(): Record<string, unknown>;
 }
+/**
+ * A Zod-compatible output schema that both describes and parses a typed result.
+ * TypeScript types are erased at runtime, so typed output requires a schema value.
+ */
+export interface ResponseSchema<T = unknown> extends ZodSchema<T> {
+    parse(value: unknown): T;
+}
 /**
  * Tool definition. Parameters can be either:
  * - A Zod schema (provides type inference for handler)
@@ -1605,6 +1630,8 @@ export interface McpAuthStaticClientConfig {
     grantType?: "client_credentials";
     /** Whether this is a public OAuth client. */
     publicClient?: boolean;
+    /** Configured OAuth scope string used when the server challenge omits scope. */
+    scope?: string;
 }
 /** MCP OAuth request that the SDK host can satisfy with a host-acquired token. */
 export interface McpAuthRequest {
@@ -1673,69 +1700,6 @@ export interface CanvasProviderIdentity {
     /** Optional display name surfaced as the canvas extension name. */
     name?: string;
 }
-/**
- * Static resource ceilings declared by a factory before it runs.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryLimits {
-    /** Maximum number of factory subagents that may run concurrently. Must be positive when present. */
-    maxConcurrentSubagents?: number;
-    /** Maximum total number of factory subagents that may be spawned. Must be positive when present. */
-    maxTotalSubagents?: number;
-    /** Maximum AI credits consumed by factory subagents and descendants. This post-paid ceiling is soft. */
-    maxAiCredits?: number;
-    /**
-     * Maximum accumulated active-execution time, in seconds. Active execution includes the entire extension body,
-     * subprocess waits, queued-agent waits, and sleeps. The limit is armed from the remaining headroom when a run
-     * resumes; time between attempts is not counted. Must be finite and positive when present.
-     */
-    timeoutSeconds?: number;
-}
-/**
- * Registration metadata for an extension-authored factory.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryMeta {
-    /** Stable factory name used for invocation. */
-    name: string;
-    /** Human-readable factory description. */
-    description: string;
-    /** Display metadata for the progress phases the factory may report. */
-    phases: Array<{
-        title: string;
-        detail?: string;
-    }>;
-    /**
-     * Optional declared shape of the arguments this factory expects as `ctx.args`.
-     *
-     * Declaring one is strongly recommended for any factory that reads `ctx.args`.
-     * When the model invokes the factory through the `run_factory` tool, the CLI
-     * validates `args` against this declaration **before** the run starts, so a
-     * malformed call is rejected with a correction hint and retried without ever
-     * creating a run row, prompting the user for permission, or spending credits. A
-     * factory that declares nothing is never validated: a malformed call starts,
-     * takes an approval, spends credits, and then fails inside the factory body.
-     * `factories_manage` with `operation: "inspect"` reports the declared shape so an
-     * agent can read it before invoking.
-     *
-     * This covers the model's `run_factory` path only. `session.factory.run(...)` is
-     * not validated against the declaration, so a factory should still check
-     * `ctx.args` rather than assume the declared shape held.
-     *
-     * Enforcement covers structure — types, required properties, and enum/const
-     * values. Finer constraints such as `minLength`, `pattern`, and
-     * `additionalProperties` are recorded in the declaration but not enforced. See
-     * {@link FactoryJsonSchema} for the accepted subset. A declaration outside that
-     * subset is rejected at registration.
-     */
-    argsSchema?: FactoryJsonSchema;
-    /** Optional resource ceilings presented to the user before execution. */
-    limits?: FactoryLimits;
-}
 /**
  * Provider-scoped options for the Copilot API (CAPI).
  *
@@ -1905,6 +1869,16 @@ export interface SessionConfigBase {
      * the session to the long-context tier; omit or use "default" otherwise.
      */
     contextTier?: ContextTier;
+    /**
+     * Enables session-scoped MCP diagnostic capture at the requested level.
+     *
+     * Diagnostics are off by default. At `"debug"` and `"trace"` levels, entries
+     * can contain MCP payloads, tool arguments, paths, and server stderr. Do not
+     * upload entries as telemetry or export them without deliberate host action.
+     * Omit this option when resuming a resident session to preserve its current
+     * diagnostic level.
+     */
+    diagnostics?: DiagnosticsConfiguration;
     /** Per-property overrides for model capabilities, deep-merged over runtime defaults. */
     modelCapabilities?: ModelCapabilitiesOverride;
     /**
@@ -2448,6 +2422,14 @@ export interface SessionConfig extends SessionConfigBase {
      * Optional custom session ID. If not provided, the server generates one.
      */
     sessionId?: string;
+    /**
+     * Invalidates the process-wide custom-instruction discovery cache before
+     * creating this session. Use when instruction files changed in the same runtime.
+     * Other sessions in this runtime may observe updated instructions on later turns
+     * or discovery. This does not watch files or enable disabled instruction loading.
+     * @default false
+     */
+    refreshCustomInstructions?: boolean;
     /**
      * Creates a remote session in the cloud instead of a local session.
      * The optional repository is associated with the cloud session.
@@ -2740,6 +2722,8 @@ export interface ProviderModelConfig {
  * Message provenance, independent of delivery mode.
  */
 export type MessageSource = "user" | "system" | `agent-${string}`;
+/** Structured context contributed by an extension. */
+export type ExtensionContextAttachment = GeneratedExtensionContextAttachment;
 export interface MessageOptions {
     /**
      * The prompt/message to send
@@ -2752,7 +2736,7 @@ export interface MessageOptions {
      */
     source?: MessageSource;
     /**
-     * File, directory, selection, or blob attachments
+     * File, directory, selection, blob, or extension context attachments
      */
     attachments?: Array<{
         type: "file";
@@ -2782,7 +2766,7 @@ export interface MessageOptions {
         data: string;
         mimeType: string;
         displayName?: string;
-    }>;
+    } | ExtensionContextAttachment>;
     /**
      * Message delivery mode
      * - "enqueue": Add to queue (default)
@@ -2802,6 +2786,19 @@ export interface MessageOptions {
      * If provided, this is shown in the timeline instead of `prompt`.
      */
     displayPrompt?: string;
+    /**
+     * JSON Schema or a Zod schema for this run's output, including requests after tool calls.
+     * Independent sends do not inherit it. Ordinary immediate steering retains the active
+     * schema and origin, even when promoted to a follow-up after the model request finishes.
+     * Specifying a schema with mode "immediate" is rejected, even while idle.
+     * This is not a persisted session default and does not survive a context reset.
+     *
+     * sendAndWait still returns an assistant message event. For a typed result, pass a
+     * Zod-compatible schema as sendAndWait's second argument instead.
+     * Streaming events remain text and may include intermediate messages.
+     * Use rpc.send's responseFormat for provider-specific name, description and strict options.
+     */
+    responseSchema?: ZodSchema | Record<string, unknown>;
 }
 /**
  * All possible event type strings from SessionEvent