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

package/dist/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 { 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 { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, 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 { ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, 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}.
  *
@@ -290,6 +292,12 @@ export interface CopilotClientOptions {
      * @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"`).
@@ -1622,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 {
@@ -1690,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).
  *
@@ -1922,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;
     /**
@@ -2465,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.

package/dist/workflow.d.ts

@@ -0,0 +1,367 @@
+import type { WorkflowGetRunProgressRequest, WorkflowListRunsRequest, WorkflowListRunsResult, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunResult, WorkflowRunStatus, WorkflowRunSummary } from "./generated/rpc.js";
+import type { ContextTier } from "./generated/session-events.js";
+import type { CopilotSession } from "./session.js";
+export type { WorkflowRunResult };
+/** A value that can be represented losslessly on the SDK JSON wire. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type { WorkflowAgentSummary, WorkflowPhaseStatus, WorkflowPhaseObservation, WorkflowProgressLine, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunStatus, WorkflowRunSummary, } from "./generated/rpc.js";
+/**
+ * Options for paging durable workflow runs.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type WorkflowListRunsOptions = WorkflowListRunsRequest;
+/**
+ * A page of durable workflow runs and its paging metadata.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type WorkflowRunsPage = WorkflowListRunsResult;
+/**
+ * Whether a workflow run status is terminal.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare function isWorkflowRunTerminal(status: WorkflowRunStatus): boolean;
+declare const workflowHandleBrand: unique symbol;
+/**
+ * Conservative JSON shape language accepted by the Dynamic Workflows surface, for
+ * both structured workflow agent output and a workflow's declared `argsSchema`.
+ *
+ * This is a best-effort structural guard — used to decide whether a subagent's
+ * structured output should be accepted or retried, and whether a caller's
+ * workflow `args` match the declared shape — **not** a full JSON Schema
+ * validator. Only these keywords are honored: `type`, `required`, `enum`,
+ * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type`
+ * is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or
+ * `object`, or a non-empty array of those (for example `["object", "null"]`).
+ *
+ * Everything else is **ignored, not enforced**. In particular, string
+ * constraints (`pattern`, `minLength`, `maxLength`, `format`), numeric ranges
+ * (`minimum`, `maximum`), and `additionalProperties` do not reject
+ * non-conforming output. Boolean schemas are outside this accepted shape.
+ * `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 Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type WorkflowJsonSchema = {
+    [key: string]: JsonValue;
+};
+/**
+ * Static resource ceilings declared by a workflow before it runs.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowLimits {
+    /** Maximum number of workflow subagents that may run concurrently. Must be positive when present. */
+    maxConcurrentSubagents?: number;
+    /** Maximum total number of workflow subagents that may be spawned. Must be positive when present. */
+    maxTotalSubagents?: number;
+    /** Maximum AI credits consumed by workflow 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 workflow.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowMeta {
+    /** Stable workflow name used for invocation. */
+    name: string;
+    /** Human-readable workflow description. */
+    description: string;
+    /** Display metadata for the progress phases the workflow may report. */
+    phases: Array<{
+        title: string;
+        detail?: string;
+    }>;
+    /**
+     * Optional declared shape of the arguments this workflow expects as `ctx.args`.
+     *
+     * The runtime records and validates this schema when the workflow contribution
+     * is registered. Workflow bodies should still validate any semantic constraints
+     * they depend on because the public `session.workflow.run(...)` API forwards
+     * arguments directly.
+     */
+    argsSchema?: WorkflowJsonSchema;
+    /** Optional resource ceilings presented before execution. */
+    limits?: WorkflowLimits;
+}
+/**
+ * Options for one workflow-scoped subagent call.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowAgentOptions {
+    label?: string;
+    schema?: WorkflowJsonSchema;
+    model?: string;
+    reasoningEffort?: string;
+    contextTier?: ContextTier;
+    agent?: string;
+}
+export declare const WORKFLOW_AGENT_OPTION_KEYS: readonly ["label", "schema", "model", "reasoningEffort", "contextTier", "agent"];
+/**
+ * Options for a durable workflow step.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowStepOptions {
+    /** Skip the journal and always invoke the producer. */
+    volatile?: boolean;
+}
+/**
+ * Per-invocation workflow resource ceiling overrides.
+ *
+ * An omitted field preserves the existing/default ceiling, a number replaces
+ * it, and `null` explicitly makes that dimension unlimited.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowLimitOverrides {
+    maxConcurrentSubagents?: number | null;
+    maxTotalSubagents?: number | null;
+    maxAiCredits?: number | null;
+    timeoutSeconds?: number | null;
+}
+/**
+ * One stage in a per-item workflow pipeline.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type WorkflowPipelineStage<TInput = unknown, TResult = unknown> = (previous: TInput, item: unknown, index: number) => Promise<TResult> | TResult;
+/**
+ * Context passed to an extension-authored workflow body.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowContext<TArgs extends JsonValue = JsonValue> {
+    /** Stable identifier for the current workflow run. */
+    readonly runId: string;
+    /** Spawn and await one workflow-scoped subagent. */
+    agent(prompt: string, options?: WorkflowAgentOptions): Promise<unknown>;
+    /** Memoize an arbitrary producer under a stable author-supplied key. */
+    step(key: string, producer: () => Promise<JsonValue> | JsonValue, options?: WorkflowStepOptions): Promise<JsonValue>;
+    /**
+     * Pause this run at a durable, one-shot checkpoint.
+     *
+     * The first attempt to reach a key pauses and aborts cooperatively. A
+     * resumed attempt returns from the same key and continues.
+     */
+    pause(key: string): Promise<void>;
+    /**
+     * 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 WorkflowContext.parallel}, cancellation and hard
+     * runtime failures propagate instead of being recorded per item.
+     */
+    pipeline(items: unknown[], ...stages: WorkflowPipelineStage[]): Promise<unknown[]>;
+    /** Start a named workflow progress phase. */
+    phase(title: string): void;
+    /** Emit a workflow progress line. */
+    log(message: string): void;
+    /** Reject because nested workflows are not supported. */
+    workflow(name: string, args?: JsonValue): Promise<JsonValue | void>;
+    /** Caller-supplied input, forwarded verbatim. */
+    args: TArgs;
+    /**
+     * The session instance returned by `joinSession`. It refuses calls that
+     * start, resume, or pause a workflow run.
+     */
+    session: CopilotSession;
+    /** Cooperative cancellation signal for the current workflow run. */
+    signal: AbortSignal;
+}
+/**
+ * Definition accepted by {@link defineWorkflow}.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowDefinition<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
+    meta: WorkflowMeta;
+    run(context: WorkflowContext<TArgs>): Promise<TResult>;
+}
+/**
+ * A deeply immutable view of a value.
+ *
+ * `defineWorkflow` 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 workflow.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowHandle<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
+    readonly meta: DeepReadonly<WorkflowMeta>;
+    readonly [workflowHandleBrand]: {
+        readonly args: TArgs;
+        readonly result: TResult;
+    };
+}
+/**
+ * Options for invoking a workflow.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowRunOptions<TArgs extends JsonValue = JsonValue> {
+    /** Input surfaced as `context.args`. */
+    args?: TArgs;
+    /** Optional per-invocation resource ceiling overrides. */
+    limits?: WorkflowLimitOverrides;
+    /** Whether to notify the originating session when the workflow completes. */
+    notifyOnComplete?: boolean;
+    /** Whether to emit workflow phase names to the session transcript. */
+    logPhaseNames?: boolean;
+}
+/**
+ * Options for resuming a workflow run by ID.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface WorkflowResumeOptions {
+    /** Optional per-invocation resource ceiling overrides. */
+    limits?: WorkflowLimitOverrides;
+    /** Whether to notify the originating session when the workflow completes. */
+    notifyOnComplete?: boolean;
+    /** Whether to emit workflow phase names to the session transcript. */
+    logPhaseNames?: boolean;
+}
+/**
+ * Machine-readable pre-execution workflow resume failure.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type WorkflowResumeErrorCode = "not_found" | "non_resumable" | "workflow_run_not_resumable" | "already_active" | "workflow_already_running" | "workflow_limits_invalid" | "workflow_session_disposed" | "workflow_storage_unavailable" | "workflow_storage_corrupt";
+/**
+ * Friendly workflow API exposed on a session.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface SessionWorkflowApi {
+    /**
+     * Run a registered workflow and resolve with its run envelope.
+     *
+     * The envelope is returned for every outcome, including `error`, `halted`,
+     * `paused`, and `cancelled` — inspect `status` and read `result` only when
+     * the run completed. `paused` settles the current attempt, but the same
+     * durable run can later resume under its existing run ID. SDK-initiated
+     * runs do not request permission, so they have no declined outcome.
+     * Failures that occur before a run exists (such as an unknown workflow or
+     * attempting to start a run while the session is at its active top-level
+     * run limit) still reject.
+     */
+    run(name: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    run<TArgs extends JsonValue>(workflow: WorkflowHandle<TArgs, JsonValue | void>, options?: WorkflowRunOptions<TArgs>): Promise<WorkflowRunResult>;
+    /**
+     * Resume a run from its persisted workflow name, arguments, journal, and accounting.
+     *
+     * Resolves with the run envelope like {@link SessionWorkflowApi.run}.
+     * SDK-initiated resumes do not request permission. A pre-execution failure
+     * with a documented resume code rejects with {@link WorkflowResumeError}.
+     */
+    resume(runId: string, options?: WorkflowResumeOptions): Promise<WorkflowRunResult>;
+    /** Read the latest durable envelope for a workflow run. */
+    getRun(runId: string): Promise<WorkflowRunResult>;
+    /**
+     * Wait for the current attempt to settle and resolve with its envelope.
+     *
+     * Resolves as soon as the run reaches `completed`, `error`, `halted`,
+     * `paused`, or `cancelled`, and resolves immediately when the current
+     * attempt has already settled. A `paused` envelope is an attempt-level
+     * snapshot: resuming the same durable run can later change the envelope
+     * returned by {@link SessionWorkflowApi.getRun}.
+     *
+     * This watches the runtime's `workflow.run_updated` event 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 SessionWorkflowApi.cancel} to actually stop it.
+     */
+    waitForRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkflowRunResult>;
+    /**
+     * List the newest default page of this session's durable workflow runs.
+     *
+     * This backwards-compatible overload returns only the runs array. Pass
+     * paging options to receive the full page, including its cursors and
+     * truncation metadata.
+     */
+    listRuns(): Promise<WorkflowRunSummary[]>;
+    /**
+     * Page this session's durable workflow runs.
+     *
+     * `afterSeq` and `beforeSeq` are exclusive cursors. The result includes
+     * `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` so callers
+     * can continue paging without using the raw RPC client.
+     */
+    listRuns(options: WorkflowListRunsOptions): Promise<WorkflowRunsPage>;
+    /** Read durable phases, direct agents, and the latest progress tail for a run. */
+    getRunDetail(runId: string): Promise<WorkflowRunDetail>;
+    /** Page durable progress forward, backward, or from the latest tail. */
+    getRunProgress(runId: string, options?: Omit<WorkflowGetRunProgressRequest, "runId">): Promise<WorkflowProgressPage>;
+    /** Pause a running workflow attempt and return its `paused` envelope. */
+    pause(runId: string): Promise<WorkflowRunResult>;
+    /** Cancel a workflow run and return its terminal envelope. */
+    cancel(runId: string): Promise<WorkflowRunResult>;
+}
+/**
+ * Error thrown when a workflow cannot be resumed before execution begins.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare class WorkflowResumeError extends Error {
+    readonly code: WorkflowResumeErrorCode;
+    constructor(code: WorkflowResumeErrorCode, message: string);
+}
+/**
+ * Defines an extension-authored workflow and returns an opaque registration handle.
+ *
+ * @experimental Part of the experimental Dynamic Workflows surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export declare function defineWorkflow<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void>(definition: WorkflowDefinition<TArgs, TResult>): WorkflowHandle<TArgs, TResult>;

package/dist/{factory.js → workflow.js}

@@ -1,14 +1,14 @@
-const FACTORY_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+const WORKFLOW_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "completed",
   "halted",
   "paused",
   "cancelled",
   "error"
 ]);
-function isFactoryRunTerminal(status) {
-  return FACTORY_TERMINAL_STATUSES.has(status);
+function isWorkflowRunTerminal(status) {
+  return WORKFLOW_TERMINAL_STATUSES.has(status);
 }
-const FACTORY_AGENT_OPTION_KEYS = [
+const WORKFLOW_AGENT_OPTION_KEYS = [
   "label",
   "schema",
   "model",
@@ -16,16 +16,16 @@ const FACTORY_AGENT_OPTION_KEYS = [
   "contextTier",
   "agent"
 ];
-class FactoryResumeError extends Error {
+class WorkflowResumeError extends Error {
   constructor(code, message) {
     super(message);
     this.code = code;
-    this.name = "FactoryResumeError";
+    this.name = "WorkflowResumeError";
   }
   code;
 }
-const factoryHandles = /* @__PURE__ */ new WeakMap();
-const MAX_FACTORY_TIMEOUT_SECONDS = 2147483647e-3;
+const workflowHandles = /* @__PURE__ */ new WeakMap();
+const MAX_WORKFLOW_TIMEOUT_SECONDS = 2147483647e-3;
 const NANO_AIU_PER_AIU = 1e9;
 function deepFreeze(value) {
   if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
@@ -44,24 +44,24 @@ function validateLimits(meta) {
   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`);
+      throw new Error(`Workflow 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'
+      'Workflow limit "timeoutSeconds" must be a positive, finite number of seconds'
     );
   }
-  if (limits.timeoutSeconds !== void 0 && limits.timeoutSeconds > MAX_FACTORY_TIMEOUT_SECONDS) {
+  if (limits.timeoutSeconds !== void 0 && limits.timeoutSeconds > MAX_WORKFLOW_TIMEOUT_SECONDS) {
     throw new Error(
-      `Factory limit "timeoutSeconds" must not exceed ${MAX_FACTORY_TIMEOUT_SECONDS} seconds`
+      `Workflow limit "timeoutSeconds" must not exceed ${MAX_WORKFLOW_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'
+        'Workflow limit "maxAiCredits" must be a positive, finite number that rounds to a safe positive integer nano-AIU ceiling'
       );
     }
   }
@@ -70,15 +70,15 @@ 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");
+      throw new Error("Workflow phase titles must not be empty");
     }
     if (titles.has(phase.title)) {
-      throw new Error(`Factory phase title "${phase.title}" is declared more than once`);
+      throw new Error(`Workflow phase title "${phase.title}" is declared more than once`);
     }
     titles.add(phase.title);
   }
 }
-function defineFactory(definition) {
+function defineWorkflow(definition) {
   const meta = deepFreeze(structuredClone(definition.meta));
   validateLimits(meta);
   validatePhases(meta);
@@ -87,20 +87,20 @@ function defineFactory(definition) {
     run: definition.run
   };
   const handle = Object.freeze({ meta });
-  factoryHandles.set(handle, stored);
+  workflowHandles.set(handle, stored);
   return handle;
 }
-function getFactoryDefinition(handle) {
-  const definition = factoryHandles.get(handle);
+function getWorkflowDefinition(handle) {
+  const definition = workflowHandles.get(handle);
   if (!definition) {
-    throw new Error("Invalid factory handle");
+    throw new Error("Invalid workflow handle");
   }
   return definition;
 }
 export {
-  FACTORY_AGENT_OPTION_KEYS,
-  FactoryResumeError,
-  defineFactory,
-  getFactoryDefinition,
-  isFactoryRunTerminal
+  WORKFLOW_AGENT_OPTION_KEYS,
+  WorkflowResumeError,
+  defineWorkflow,
+  getWorkflowDefinition,
+  isWorkflowRunTerminal
 };

package/docs/extensions.md

@@ -77,5 +77,5 @@ An approved extension can pass a granted value to anything it starts, so ask onl
 ## Further Reading
 
 - `examples.md` — Practical code examples for tools, hooks, events, and complete extensions
-- `factories.md`: Authoring, running, resuming, and observing Agent Factories
+- `workflows.md` — Authoring, running, resuming, and observing Dynamic Workflows
 - `agent-author.md` — Step-by-step workflow for agents authoring extensions programmatically