@github/copilot-sdk 1.0.9-preview.0 → 1.0.9-preview.1

package/dist/extension.js

@@ -7,6 +7,11 @@ import {
   CanvasError,
   createCanvas
 } from "./canvas.js";
+import {
+  defineFactory,
+  FactoryResumeError,
+  isFactoryRunTerminal
+} from "./factory.js";
 async function joinSession(config = {}) {
   const sessionId = process.env.SESSION_ID;
   if (!sessionId) {
@@ -15,17 +20,28 @@ async function joinSession(config = {}) {
     );
   }
   const client = new CopilotClient({ _internalConnection: { kind: "parent-process" } });
-  const { extensionSdkPath: _stripped, ...rest } = config;
+  const {
+    extensionSdkPath: _stripped,
+    factories,
+    ...rest
+  } = config;
   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
+    },
+    factories
+  );
 }
 export {
   Canvas,
   CanvasError,
+  FactoryResumeError,
   createCanvas,
+  defineFactory,
+  isFactoryRunTerminal,
   joinSession
 };

package/dist/factory.d.ts

@@ -0,0 +1,273 @@
+import type { FactoryGetRunProgressRequest, FactoryProgressPage, FactoryRunDetail, FactoryRunResult as WireFactoryRunResult, FactoryRunStatus, FactoryRunSummary } from "./generated/rpc.js";
+import type { CopilotSession } from "./session.js";
+import type { FactoryLimits, FactoryMeta } from "./types.js";
+/**
+ * The envelope describing a factory run: its identity, status, and — once it
+ * has completed — its result. `getRun` returns this for an in-flight run too,
+ * so `status` may be `pending` or `running` and the outcome fields absent.
+ *
+ * `result` is re-typed here rather than taken from the generated wire type. The
+ * runtime returns any JSON value — including `null`, a string, a number, or an
+ * array — but the schema models the field as an opaque node, which the
+ * generator renders as an object. Narrowing the correction to this surface
+ * keeps the `x-opaque-json` handling unchanged for every other consumer.
+ *
+ * This override is temporary. Once the schema distinguishes an opaque JSON
+ * value from an opaque in-process value and that ships in a CLI release,
+ * regenerating produces the right type directly, and this declaration, the
+ * `toPublicFactoryRunResult` boundary helper, and the casts around it should
+ * all be deleted. Tracked by github/copilot-agent-runtime#14122.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryRunResult = Omit<WireFactoryRunResult, "result"> & {
+    /** Completed factory result. */
+    result?: JsonValue;
+};
+export type { FactoryAgentSummary, FactoryPhaseStatus, FactoryPhaseObservation, FactoryProgressLine, FactoryProgressPage, FactoryRunDetail, FactoryRunStatus, FactoryRunSummary, } from "./generated/rpc.js";
+/**
+ * Whether a factory run status is terminal.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare function isFactoryRunTerminal(status: FactoryRunStatus): boolean;
+declare const factoryHandleBrand: unique symbol;
+/** A value that can be represented losslessly on the SDK JSON wire. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Conservative JSON shape language accepted for structured factory agent output.
+ *
+ * This is a best-effort structural guard used to decide whether a subagent's
+ * structured output should be accepted or retried — **not** a full JSON Schema
+ * validator. Only these keywords are honored: `type`, `required`, `enum`,
+ * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`.
+ *
+ * Everything else is **ignored, not enforced**. In particular, string
+ * constraints (`pattern`, `minLength`, `maxLength`, `format`), numeric ranges
+ * (`minimum`, `maximum`), `additionalProperties`, and boolean (`true`/`false`)
+ * schemas do not reject non-conforming output. `oneOf` is treated like `anyOf`
+ * (at least one branch must match) rather than strict exactly-one. Author
+ * schemas within this subset; do not rely on unsupported constraints for
+ * correctness.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryJsonSchema = {
+    [key: string]: JsonValue;
+};
+/**
+ * Options for one factory-scoped subagent call.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryAgentOptions {
+    label?: string;
+    schema?: FactoryJsonSchema;
+    model?: string;
+}
+/**
+ * Options for a durable factory step.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryStepOptions {
+    /** Skip the journal and always invoke the producer. */
+    volatile?: boolean;
+}
+/**
+ * One stage in a per-item factory pipeline.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryPipelineStage<TInput = unknown, TResult = unknown> = (previous: TInput, item: unknown, index: number) => Promise<TResult> | TResult;
+/**
+ * Context passed to an extension-authored factory body.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryContext<TArgs extends JsonValue = JsonValue> {
+    /** Stable identifier for the current factory run. */
+    readonly runId: string;
+    /** Spawn and await one factory-scoped subagent. */
+    agent(prompt: string, options?: FactoryAgentOptions): Promise<unknown>;
+    /** Memoize an arbitrary producer under a stable author-supplied key. */
+    step(key: string, producer: () => Promise<JsonValue> | JsonValue, options?: FactoryStepOptions): Promise<JsonValue>;
+    /**
+     * Run thunks concurrently and await all of them.
+     *
+     * A thunk that throws becomes `null` in the result array, so one failed
+     * item does not lose the rest. Cancellation and hard runtime failures
+     * (`ResponseError`, `ConnectionError`) are the exception: those propagate
+     * and reject the whole call, because they mean the run itself is in
+     * trouble rather than one item having failed.
+     */
+    parallel<TResult>(thunks: Array<() => Promise<TResult> | TResult>): Promise<Array<TResult | null>>;
+    /**
+     * Run each item through every stage without barriers between stages.
+     *
+     * A stage that throws drops that item to `null` and skips its remaining
+     * stages. As with {@link FactoryContext.parallel}, cancellation and hard
+     * runtime failures propagate instead of being recorded per item.
+     */
+    pipeline(items: unknown[], ...stages: FactoryPipelineStage[]): Promise<unknown[]>;
+    /** Start a named factory progress phase. */
+    phase(title: string): void;
+    /** Emit a factory progress line. */
+    log(message: string): void;
+    /** Reject because nested factories are not supported. */
+    factory(name: string, args?: JsonValue): Promise<JsonValue | void>;
+    /** Caller-supplied input, forwarded verbatim. */
+    args: TArgs;
+    /** The same full session instance returned by `joinSession`. */
+    session: CopilotSession;
+    /** Cooperative cancellation signal for the current factory run. */
+    signal: AbortSignal;
+}
+/**
+ * Definition accepted by {@link defineFactory}.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryDefinition<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
+    meta: FactoryMeta;
+    run(context: FactoryContext<TArgs>): Promise<TResult>;
+}
+/**
+ * A deeply immutable view of a value.
+ *
+ * `defineFactory` deep-freezes the metadata it stores, so the handle's view of
+ * it has to be readonly all the way down or `handle.meta.name = "..."` and
+ * `handle.meta.phases.push(...)` would compile and then throw at runtime.
+ */
+type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * Opaque reusable reference to a defined factory.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryHandle<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
+    readonly meta: DeepReadonly<FactoryMeta>;
+    readonly [factoryHandleBrand]: {
+        readonly args: TArgs;
+        readonly result: TResult;
+    };
+}
+/**
+ * Options for invoking a factory.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface RunOptions<TArgs extends JsonValue = JsonValue> {
+    /** Input surfaced as `context.args`. */
+    args?: TArgs;
+    /** Optional per-invocation resource ceiling overrides. */
+    limits?: FactoryLimits;
+    /**
+     * Prior run whose persisted identity, arguments, journal, and accounting should be resumed.
+     *
+     * @deprecated Use {@link SessionFactoryApi.resume} instead.
+     */
+    resumeFromRunId?: string;
+}
+/**
+ * Options for resuming a factory run by ID.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface ResumeOptions {
+    /** Optional per-invocation resource ceiling overrides. */
+    limits?: FactoryLimits;
+}
+/**
+ * Machine-readable pre-execution factory resume failure.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryResumeErrorCode = "not_found" | "non_resumable" | "already_active" | "reapproval_declined" | "no_approval_provider";
+/**
+ * Friendly factory API exposed on a session.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface SessionFactoryApi {
+    /**
+     * Run a registered factory and resolve with its run envelope.
+     *
+     * The envelope is returned for every outcome, including `error`, `halted`,
+     * and `cancelled` — inspect `status` and read `result` only when the run
+     * completed. A declined fresh run resolves with a terminal `cancelled`
+     * envelope. Failures that occur before a run exists (such as an unknown
+     * factory or an already-active session) still reject.
+     */
+    run(name: string, options?: RunOptions): Promise<FactoryRunResult>;
+    run<TArgs extends JsonValue>(factory: FactoryHandle<TArgs, JsonValue | void>, options?: RunOptions<TArgs>): Promise<FactoryRunResult>;
+    /**
+     * Resume a run from its persisted factory name, arguments, journal, and accounting.
+     *
+     * Resolves with the run envelope like {@link SessionFactoryApi.run}. A
+     * pre-execution failure, including declined reapproval, rejects with
+     * {@link FactoryResumeError}.
+     */
+    resume(runId: string, options?: ResumeOptions): Promise<FactoryRunResult>;
+    /** Read the latest durable envelope for a factory run. */
+    getRun(runId: string): Promise<FactoryRunResult>;
+    /**
+     * Wait for a run to settle and resolve with its terminal envelope.
+     *
+     * Resolves as soon as the run reaches `completed`, `error`, `halted`, or
+     * `cancelled`, and resolves immediately when it has already settled. A
+     * terminal envelope is final, so the resolved value never changes
+     * afterwards.
+     *
+     * This watches the run's `factory.run_updated` invalidation events and
+     * periodically re-reads the durable envelope so a missed event cannot
+     * leave the wait hanging. Pass a `signal` to stop waiting; aborting rejects
+     * and has no effect on the run itself, which keeps executing. Use
+     * {@link SessionFactoryApi.cancel} to actually stop it.
+     */
+    waitForRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<FactoryRunResult>;
+    /** List this session's durable factory runs in creation order. */
+    listRuns(): Promise<FactoryRunSummary[]>;
+    /** Read durable phases, direct agents, and the latest progress tail for a run. */
+    getRunDetail(runId: string): Promise<FactoryRunDetail>;
+    /** Page durable progress forward, backward, or from the latest tail. */
+    getRunProgress(runId: string, options?: Omit<FactoryGetRunProgressRequest, "runId">): Promise<FactoryProgressPage>;
+    /** Cancel a factory run and return its terminal envelope. */
+    cancel(runId: string): Promise<FactoryRunResult>;
+}
+/**
+ * Error thrown when a factory cannot be resumed before execution begins.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare class FactoryResumeError extends Error {
+    readonly code: FactoryResumeErrorCode;
+    constructor(code: FactoryResumeErrorCode, message: string);
+}
+/**
+ * Defines an extension-authored factory and returns an opaque registration handle.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare function defineFactory<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void>(definition: FactoryDefinition<TArgs, TResult>): FactoryHandle<TArgs, TResult>;

package/dist/factory.js

@@ -0,0 +1,96 @@
+const FACTORY_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "halted",
+  "cancelled",
+  "error"
+]);
+function isFactoryRunTerminal(status) {
+  return FACTORY_TERMINAL_STATUSES.has(status);
+}
+class FactoryResumeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FactoryResumeError";
+  }
+  code;
+}
+const factoryHandles = /* @__PURE__ */ new WeakMap();
+const MAX_FACTORY_TIMEOUT_SECONDS = 2147483647e-3;
+const NANO_AIU_PER_AIU = 1e9;
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) {
+      deepFreeze(nested);
+    }
+  }
+  return value;
+}
+function validateLimits(meta) {
+  const limits = meta.limits;
+  if (!limits) {
+    return;
+  }
+  for (const field of ["maxConcurrentSubagents", "maxTotalSubagents"]) {
+    const value = limits[field];
+    if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) {
+      throw new Error(`Factory limit "${field}" must be a positive integer`);
+    }
+  }
+  if (limits.timeoutSeconds !== void 0 && (!Number.isFinite(limits.timeoutSeconds) || limits.timeoutSeconds <= 0)) {
+    throw new Error(
+      'Factory limit "timeoutSeconds" must be a positive, finite number of seconds'
+    );
+  }
+  if (limits.timeoutSeconds !== void 0 && limits.timeoutSeconds > MAX_FACTORY_TIMEOUT_SECONDS) {
+    throw new Error(
+      `Factory limit "timeoutSeconds" must not exceed ${MAX_FACTORY_TIMEOUT_SECONDS} seconds`
+    );
+  }
+  if (limits.maxAiCredits !== void 0) {
+    const maxNanoAiu = Math.round(limits.maxAiCredits * NANO_AIU_PER_AIU);
+    if (!Number.isFinite(limits.maxAiCredits) || limits.maxAiCredits <= 0 || !Number.isSafeInteger(maxNanoAiu) || maxNanoAiu < 1) {
+      throw new Error(
+        'Factory limit "maxAiCredits" must be a positive, finite number that rounds to a safe positive integer nano-AIU ceiling'
+      );
+    }
+  }
+}
+function validatePhases(meta) {
+  const titles = /* @__PURE__ */ new Set();
+  for (const phase of meta.phases) {
+    if (phase.title.trim().length === 0) {
+      throw new Error("Factory phase titles must not be empty");
+    }
+    if (titles.has(phase.title)) {
+      throw new Error(`Factory phase title "${phase.title}" is declared more than once`);
+    }
+    titles.add(phase.title);
+  }
+}
+function defineFactory(definition) {
+  const meta = deepFreeze(structuredClone(definition.meta));
+  validateLimits(meta);
+  validatePhases(meta);
+  const stored = {
+    meta,
+    run: definition.run
+  };
+  const handle = Object.freeze({ meta });
+  factoryHandles.set(handle, stored);
+  return handle;
+}
+function getFactoryDefinition(handle) {
+  const definition = factoryHandles.get(handle);
+  if (!definition) {
+    throw new Error("Invalid factory handle");
+  }
+  return definition;
+}
+export {
+  FactoryResumeError,
+  defineFactory,
+  getFactoryDefinition,
+  isFactoryRunTerminal
+};

package/dist/index.d.ts

@@ -7,7 +7,9 @@ export { CopilotClient } from "./client.js";
 export { RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { RunOptions, ResumeOptions, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/index.js

@@ -2,6 +2,7 @@ import { CopilotClient } from "./client.js";
 import { RuntimeConnection } from "./types.js";
 import { BuiltInTools, ToolSet } from "./toolSet.js";
 import { CopilotSession } from "./session.js";
+import { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 import {
   Canvas,
   CanvasError,
@@ -29,6 +30,7 @@ export {
   CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder,
   CopilotWebSocketHandler,
+  FactoryResumeError,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
@@ -37,5 +39,7 @@ export {
   convertMcpCallToolResult,
   createCanvas,
   createSessionFsAdapter,
-  defineTool
+  defineFactory,
+  defineTool,
+  isFactoryRunTerminal
 };

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 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";
@@ -45,6 +46,8 @@ export declare class CopilotSession {
     private canvases;
     private bearerTokenProviders;
     private commandHandlers;
+    private factories;
+    private factoryAbortControllers;
     private permissionHandler?;
     private mcpAuthHandler?;
     private userInputHandler?;
@@ -58,6 +61,24 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    /**
+     * 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 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.
      */