Add Agent Orchestrations Authoring Surface

nodejs/src/client.ts

@@ -85,6 +85,7 @@ import type {
     TypedSessionLifecycleHandler,
 } from "./types.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
+import type { OrchestrationHandle } from "./orchestration.js";
 
 /**
  * Minimum protocol version this SDK can communicate with.
@@ -1663,6 +1664,23 @@ export class CopilotClient {
      * ```
      */
     async resumeSession(sessionId: string, config: ResumeSessionConfig): Promise<CopilotSession> {
+        return this.resumeSessionInternal(sessionId, config);
+    }
+
+    /** @internal */
+    async resumeSessionForExtension(
+        sessionId: string,
+        config: ResumeSessionConfig,
+        orchestrations?: OrchestrationHandle[]
+    ): Promise<CopilotSession> {
+        return this.resumeSessionInternal(sessionId, config, orchestrations);
+    }
+
+    private async resumeSessionInternal(
+        sessionId: string,
+        config: ResumeSessionConfig,
+        orchestrations?: OrchestrationHandle[]
+    ): Promise<CopilotSession> {
         if (!this.connection) {
             await this.start();
         }
@@ -1679,6 +1697,7 @@ export class CopilotClient {
         session.registerTools(config.tools);
         session.registerCanvases(config.canvases);
         session.registerCommands(config.commands);
+        session.registerOrchestrations(orchestrations);
         const {
             wireProvider: bearerWireProvider,
             wireProviders: bearerWireProviders,
@@ -1750,6 +1769,7 @@ export class CopilotClient {
                 })),
                 toolSearch: config.toolSearch,
                 canvases: config.canvases?.map((canvas) => canvas.declaration),
+                orchestrations: orchestrations?.map((orchestration) => orchestration.meta),
                 requestCanvasRenderer: config.requestCanvasRenderer,
                 requestExtensions: config.requestExtensions,
                 extensionSdkPath: config.extensionSdkPath,

nodejs/src/extension.ts

@@ -6,10 +6,10 @@ import { CopilotClient } from "./client.js";
 import type { CopilotSession } from "./session.js";
 import {
     defaultJoinSessionPermissionHandler,
-    type ExtensionInfo,
     type PermissionHandler,
     type ResumeSessionConfig,
 } from "./types.js";
+import type { OrchestrationHandle } from "./orchestration.js";
 
 export {
     Canvas,
@@ -27,9 +27,29 @@ export type JoinSessionConfig = Omit<
     "onPermissionRequest" | "extensionSdkPath"
 > & {
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Orchestration handles to register when the extension joins the session.
+     *
+     * @experimental Part of the experimental Agent Orchestrations surface and may
+     * change or be removed in future SDK or CLI releases.
+     */
+    orchestrations?: OrchestrationHandle[];
 };
 
-export type { ExtensionInfo };
+export type { ExtensionInfo, OrchestrationLimits, OrchestrationMeta } from "./types.js";
+export {
+    defineOrchestration,
+    OrchestrationRunError,
+    type RunOptions,
+    type SessionOrchestrationApi,
+    type OrchestrationAgentOptions,
+    type OrchestrationContext,
+    type OrchestrationDefinition,
+    type OrchestrationHandle,
+    type OrchestrationJsonSchema,
+    type OrchestrationPipelineStage,
+    type OrchestrationStepOptions,
+} from "./orchestration.js";
 
 /**
  * Joins the current foreground session.
@@ -58,14 +78,22 @@ export async function joinSession(config: JoinSessionConfig = {}): Promise<Copil
     // at the type level — untyped (JS) callers can still slip it through, and
     // honoring it here would be misleading since the extension subprocess has
     // already been forked by the host with the SDK the host chose.
-    const { extensionSdkPath: _stripped, ...rest } = config as JoinSessionConfig & {
+    const {
+        extensionSdkPath: _stripped,
+        orchestrations,
+        ...rest
+    } = config as JoinSessionConfig & {
         extensionSdkPath?: string;
     };
     void _stripped;
 
-    return client.resumeSession(sessionId, {
-        ...rest,
-        onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
-        suppressResumeEvent: config.suppressResumeEvent ?? true,
-    });
+    return client.resumeSessionForExtension(
+        sessionId,
+        {
+            ...rest,
+            onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
+            suppressResumeEvent: config.suppressResumeEvent ?? true,
+        },
+        orchestrations
+    );
 }