@microsoft/copilot-sdk 0.0.0-stage → 2.0.0-preview.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +2531 -2
  2. package/dist/canvas.d.ts +135 -0
  3. package/dist/canvas.js +51 -0
  4. package/dist/cjs/canvas.js +77 -0
  5. package/dist/cjs/cliVersion.js +31 -0
  6. package/dist/cjs/client.js +3941 -0
  7. package/dist/cjs/copilotRequestHandler.js +815 -0
  8. package/dist/cjs/decisions.js +139 -0
  9. package/dist/cjs/entra.js +83 -0
  10. package/dist/cjs/extension.js +79 -0
  11. package/dist/cjs/ffiRuntimeHost.js +400 -0
  12. package/dist/cjs/generated/lifecycle-diagnostics.js +16 -0
  13. package/dist/cjs/generated/rpc.js +5883 -0
  14. package/dist/cjs/generated/session-events.js +16 -0
  15. package/dist/cjs/host.js +83 -0
  16. package/dist/cjs/index.js +100 -0
  17. package/dist/cjs/installationConfirmation.js +98 -0
  18. package/dist/cjs/jsonrpcTypes.js +41 -0
  19. package/dist/cjs/localModelJson.js +103 -0
  20. package/dist/cjs/package.json +1 -0
  21. package/dist/cjs/providerConfiguration.js +39 -0
  22. package/dist/cjs/rpcCancellation.js +49 -0
  23. package/dist/cjs/runtimeArtifacts.js +255 -0
  24. package/dist/cjs/schema.js +40 -0
  25. package/dist/cjs/sdkProtocolVersion.js +33 -0
  26. package/dist/cjs/session.js +2764 -0
  27. package/dist/cjs/sessionFsProvider.js +283 -0
  28. package/dist/cjs/taskAnalyticsJson.js +47 -0
  29. package/dist/cjs/telemetry.js +35 -0
  30. package/dist/cjs/toolSet.js +107 -0
  31. package/dist/cjs/types.js +204 -0
  32. package/dist/cjs/workflow.js +278 -0
  33. package/dist/cliVersion.d.ts +2 -0
  34. package/dist/cliVersion.js +6 -0
  35. package/dist/client.d.ts +576 -0
  36. package/dist/client.js +3924 -0
  37. package/dist/copilotRequestHandler.d.ts +91 -0
  38. package/dist/copilotRequestHandler.js +787 -0
  39. package/dist/decisions.d.ts +65 -0
  40. package/dist/decisions.js +113 -0
  41. package/dist/entra.d.ts +3 -0
  42. package/dist/entra.js +59 -0
  43. package/dist/extension.d.ts +69 -0
  44. package/dist/extension.js +59 -0
  45. package/dist/ffiRuntimeHost.d.ts +44 -0
  46. package/dist/ffiRuntimeHost.js +366 -0
  47. package/dist/generated/lifecycle-diagnostics.d.ts +232 -0
  48. package/dist/generated/lifecycle-diagnostics.js +0 -0
  49. package/dist/generated/rpc.d.ts +47706 -0
  50. package/dist/generated/rpc.js +5854 -0
  51. package/dist/generated/session-events.d.ts +17349 -0
  52. package/dist/generated/session-events.js +0 -0
  53. package/dist/host.d.ts +143 -0
  54. package/dist/host.js +59 -0
  55. package/dist/index.d.ts +23 -0
  56. package/dist/index.js +74 -0
  57. package/dist/installationConfirmation.d.ts +19 -0
  58. package/dist/installationConfirmation.js +74 -0
  59. package/dist/jsonrpcTypes.d.ts +16 -0
  60. package/dist/jsonrpcTypes.js +17 -0
  61. package/dist/localModelJson.d.ts +1 -0
  62. package/dist/localModelJson.js +69 -0
  63. package/dist/providerConfiguration.d.ts +3 -0
  64. package/dist/providerConfiguration.js +15 -0
  65. package/dist/rpcCancellation.d.ts +3 -0
  66. package/dist/rpcCancellation.js +25 -0
  67. package/dist/runtimeArtifacts.d.ts +18 -0
  68. package/dist/runtimeArtifacts.js +233 -0
  69. package/dist/schema.d.ts +4 -0
  70. package/dist/schema.js +14 -0
  71. package/dist/sdkProtocolVersion.d.ts +10 -0
  72. package/dist/sdkProtocolVersion.js +8 -0
  73. package/dist/session.d.ts +524 -0
  74. package/dist/session.js +2751 -0
  75. package/dist/sessionFsProvider.d.ts +130 -0
  76. package/dist/sessionFsProvider.js +257 -0
  77. package/dist/taskAnalyticsJson.d.ts +8 -0
  78. package/dist/taskAnalyticsJson.js +12 -0
  79. package/dist/telemetry.d.ts +14 -0
  80. package/dist/telemetry.js +11 -0
  81. package/dist/toolSet.d.ts +75 -0
  82. package/dist/toolSet.js +82 -0
  83. package/dist/types.d.ts +3864 -0
  84. package/dist/types.js +169 -0
  85. package/dist/workflow.d.ts +413 -0
  86. package/dist/workflow.js +248 -0
  87. package/docs/agent-author.md +372 -0
  88. package/docs/examples.md +747 -0
  89. package/docs/extensions.md +121 -0
  90. package/docs/workflows.md +303 -0
  91. package/package.json +135 -5
package/dist/types.js ADDED
@@ -0,0 +1,169 @@
1
+ import { createSessionFsAdapter } from "./sessionFsProvider.js";
2
+ import { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
3
+ import { SessionFsWriteFailure } from "./sessionFsProvider.js";
4
+ import {
5
+ CopilotRequestHandler,
6
+ CopilotWebSocketHandler,
7
+ CopilotWebSocketCloseStatus,
8
+ CopilotWebSocketForwarder
9
+ } from "./copilotRequestHandler.js";
10
+ const RuntimeConnection = {
11
+ /**
12
+ * Spawn a runtime child process and communicate over its stdin/stdout.
13
+ */
14
+ forStdio(opts = {}) {
15
+ return { kind: "stdio", path: opts.path, args: opts.args, env: opts.env };
16
+ },
17
+ /**
18
+ * Spawn a runtime child process that listens on a TCP socket and connect to it.
19
+ */
20
+ forTcp(opts = {}) {
21
+ return {
22
+ kind: "tcp",
23
+ port: opts.port,
24
+ connectionToken: opts.connectionToken,
25
+ path: opts.path,
26
+ args: opts.args,
27
+ env: opts.env
28
+ };
29
+ },
30
+ /**
31
+ * Connect to an already-running runtime at the given URL. The SDK does not
32
+ * spawn a process in this mode.
33
+ */
34
+ forUri(url, opts = {}) {
35
+ return { kind: "uri", url, connectionToken: opts.connectionToken };
36
+ },
37
+ /**
38
+ * Host the runtime in-process over the native runtime library's C ABI (FFI).
39
+ *
40
+ * The default when no connection or environment override is supplied.
41
+ * Runtime configuration from `gitHubToken`, `telemetry` and
42
+ * `baseDirectory` is scoped to this host, not the process environment.
43
+ * Client-level `env` and `workingDirectory` are unsupported.
44
+ */
45
+ forInProcess(options = {}) {
46
+ return { kind: "inprocess", ...options };
47
+ }
48
+ };
49
+ function convertMcpCallToolResult(callResult) {
50
+ const textParts = [];
51
+ const binaryResults = [];
52
+ for (const block of callResult.content) {
53
+ switch (block.type) {
54
+ case "text":
55
+ if (typeof block.text === "string") {
56
+ textParts.push(block.text);
57
+ }
58
+ break;
59
+ case "image":
60
+ if (typeof block.data === "string" && block.data && typeof block.mimeType === "string") {
61
+ binaryResults.push({
62
+ data: block.data,
63
+ mimeType: block.mimeType,
64
+ type: "image"
65
+ });
66
+ }
67
+ break;
68
+ case "resource": {
69
+ if (block.resource?.text) {
70
+ textParts.push(block.resource.text);
71
+ }
72
+ if (block.resource?.blob) {
73
+ const mimeType = block.resource.mimeType;
74
+ binaryResults.push({
75
+ data: block.resource.blob,
76
+ mimeType: typeof mimeType === "string" && mimeType ? mimeType : "application/octet-stream",
77
+ type: "resource",
78
+ description: block.resource.uri
79
+ });
80
+ }
81
+ break;
82
+ }
83
+ }
84
+ }
85
+ return {
86
+ textResultForLlm: textParts.join("\n"),
87
+ resultType: callResult.isError ? "failure" : "success",
88
+ ...binaryResults.length > 0 ? { binaryResultsForLlm: binaryResults } : {}
89
+ };
90
+ }
91
+ function defineTool(name, config) {
92
+ return { name, ...config };
93
+ }
94
+ const SYSTEM_MESSAGE_SECTIONS = {
95
+ preamble: { description: "Agent identity preamble and mode statement" },
96
+ identity: {
97
+ description: "Section group covering the identity preamble and its sibling sub-sections (tone, tool efficiency, etc.)"
98
+ },
99
+ tone: { description: "Response style, conciseness rules, output formatting preferences" },
100
+ tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
101
+ environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
102
+ code_change_rules: { description: "Coding rules, linting/testing, ecosystem tools, style" },
103
+ guidelines: { description: "Tips, behavioral best practices, behavioral guidelines" },
104
+ safety: { description: "Environment limitations, prohibited actions, security policies" },
105
+ tool_instructions: { description: "Per-tool usage instructions" },
106
+ custom_instructions: { description: "Repository and organization custom instructions" },
107
+ runtime_instructions: {
108
+ description: "Runtime-provided system-prompt context and instructions, such as system notifications, memories, workspace context, and content-exclusion policy. Mode-specific instructions can travel in transition messages instead."
109
+ },
110
+ last_instructions: {
111
+ description: "End-of-prompt instructions: parallel tool calling, persistence, task completion, and configured subagent-model guidance when the task tool is available"
112
+ }
113
+ };
114
+ function isAttributedPermissionResult(result) {
115
+ return result.kind === "attributed";
116
+ }
117
+ function createAttributedPermissionResult(result, decisionContext) {
118
+ const inner = isAttributedPermissionResult(result) ? result.result : result;
119
+ return { kind: "attributed", result: inner, decisionContext };
120
+ }
121
+ function createAttributedResult(result, decisionContext) {
122
+ if ("kind" in result && typeof result.kind === "string") {
123
+ return createAttributedPermissionResult(
124
+ result,
125
+ decisionContext
126
+ );
127
+ }
128
+ return { ...result, decisionContext };
129
+ }
130
+ const approveAll = (request, invocation) => {
131
+ if (invocation.managedSettingsEnabled) {
132
+ throw new Error("approveAll cannot be used when managed settings are enabled");
133
+ }
134
+ if ("managedApprovalRequired" in request) {
135
+ const managedApprovalRequired = request.managedApprovalRequired;
136
+ if (managedApprovalRequired !== void 0 && managedApprovalRequired !== false) {
137
+ return { kind: "no-result" };
138
+ }
139
+ }
140
+ return { kind: "approve-once" };
141
+ };
142
+ const defaultJoinSessionPermissionHandler = () => ({
143
+ kind: "no-result"
144
+ });
145
+ const DisableBypassPermissionsModes = {
146
+ /** Turn off bypass-permissions mode entirely. */
147
+ Disable: "disable",
148
+ /** Permit automatic bypass but block full allow-all. */
149
+ AllowAutoOnly: "allow-auto-only"
150
+ };
151
+ export {
152
+ CopilotRequestHandler,
153
+ CopilotWebSocketCloseStatus,
154
+ CopilotWebSocketForwarder,
155
+ CopilotWebSocketHandler,
156
+ DisableBypassPermissionsModes,
157
+ RuntimeConnection,
158
+ SYSTEM_MESSAGE_SECTIONS,
159
+ SessionFsSqliteTransactionFailure,
160
+ SessionFsWriteFailure,
161
+ approveAll,
162
+ convertMcpCallToolResult,
163
+ createAttributedPermissionResult,
164
+ createAttributedResult,
165
+ createSessionFsAdapter,
166
+ defaultJoinSessionPermissionHandler,
167
+ defineTool,
168
+ isAttributedPermissionResult
169
+ };
@@ -0,0 +1,413 @@
1
+ import type { WorkflowGetRunProgressRequest, WorkflowListRunsRequest, WorkflowListRunsResult, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunResult, WorkflowRunStatus, WorkflowRunSummary } from "./generated/rpc.js";
2
+ import type { ContextTier } from "./generated/session-events.js";
3
+ import type { CopilotSession } from "./session.js";
4
+ import type { CustomAgentConfig } from "./types.js";
5
+ export type { WorkflowRunResult };
6
+ /** A value that can be represented losslessly on the SDK JSON wire. */
7
+ export type JsonValue = null | boolean | number | string | JsonValue[] | {
8
+ [key: string]: JsonValue;
9
+ };
10
+ export type { WorkflowAgentContextObservation, WorkflowAgentModelObservation, WorkflowAgentReasoningEffortObservation, WorkflowAgentSummary, WorkflowPhaseStatus, WorkflowPhaseObservation, WorkflowProgressLine, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunStatus, WorkflowRunSummary, } from "./generated/rpc.js";
11
+ /**
12
+ * Options for paging durable workflow runs.
13
+ *
14
+ * @experimental Part of the experimental Dynamic Workflows surface and may
15
+ * change or be removed in future SDK or CLI releases.
16
+ */
17
+ export type WorkflowListRunsOptions = WorkflowListRunsRequest;
18
+ /**
19
+ * A page of durable workflow runs and its paging metadata.
20
+ *
21
+ * @experimental Part of the experimental Dynamic Workflows surface and may
22
+ * change or be removed in future SDK or CLI releases.
23
+ */
24
+ export type WorkflowRunsPage = WorkflowListRunsResult;
25
+ /**
26
+ * Whether a workflow run status is terminal.
27
+ *
28
+ * @experimental Part of the experimental Dynamic Workflows surface and may
29
+ * change or be removed in future SDK or CLI releases.
30
+ */
31
+ export declare function isWorkflowRunTerminal(status: WorkflowRunStatus): boolean;
32
+ declare const workflowHandleBrand: unique symbol;
33
+ declare const workflowAgentReferenceBrand: unique symbol;
34
+ /**
35
+ * A deeply immutable view of a value.
36
+ *
37
+ * Workflow factories deep-freeze the definitions they store, so public handles
38
+ * expose readonly views all the way down.
39
+ */
40
+ type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
41
+ readonly [K in keyof T]: DeepReadonly<T[K]>;
42
+ } : T;
43
+ /**
44
+ * Opaque reference to one custom agent owned by the currently executing workflow.
45
+ *
46
+ * References are available only through {@link WorkflowContext.agents}. They do
47
+ * not expose the definition, cannot be addressed through the session's global
48
+ * agent catalog, and are rejected by any other workflow.
49
+ *
50
+ * @experimental Part of the experimental Dynamic Workflows surface and may
51
+ * change or be removed in future SDK or CLI releases.
52
+ */
53
+ export interface WorkflowAgentReference {
54
+ readonly [workflowAgentReferenceBrand]: true;
55
+ }
56
+ type WorkflowAgentConfigMap = Record<string, CustomAgentConfig>;
57
+ /**
58
+ * Conservative JSON shape language accepted by the Dynamic Workflows surface, for
59
+ * both structured workflow agent output and a workflow's declared `argsSchema`.
60
+ *
61
+ * This is a best-effort structural guard — used to decide whether a subagent's
62
+ * structured output should be accepted or retried, and whether a caller's
63
+ * workflow `args` match the declared shape — **not** a full JSON Schema
64
+ * validator. Only these keywords are honored: `type`, `required`, `enum`,
65
+ * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type`
66
+ * is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or
67
+ * `object`, or a non-empty array of those (for example `["object", "null"]`).
68
+ *
69
+ * Everything else is **ignored, not enforced**. In particular, string
70
+ * constraints (`pattern`, `minLength`, `maxLength`, `format`), numeric ranges
71
+ * (`minimum`, `maximum`), and `additionalProperties` do not reject
72
+ * non-conforming output. Boolean schemas are outside this accepted shape.
73
+ * `oneOf` is treated like `anyOf` (at least one branch must match) rather than
74
+ * strict exactly-one. Author schemas within this subset; do not rely on
75
+ * unsupported constraints for correctness.
76
+ *
77
+ * @experimental Part of the experimental Dynamic Workflows surface and may
78
+ * change or be removed in future SDK or CLI releases.
79
+ */
80
+ export type WorkflowJsonSchema = {
81
+ [key: string]: JsonValue;
82
+ };
83
+ /**
84
+ * Static resource ceilings declared by a workflow before it runs.
85
+ *
86
+ * @experimental Part of the experimental Dynamic Workflows surface and may
87
+ * change or be removed in future SDK or CLI releases.
88
+ */
89
+ export interface WorkflowLimits {
90
+ /** Maximum number of workflow subagents that may run concurrently. Must be positive when present. */
91
+ maxConcurrentSubagents?: number;
92
+ /** Maximum total number of workflow subagents that may be spawned. Must be positive when present. */
93
+ maxTotalSubagents?: number;
94
+ /** Maximum AI credits consumed by workflow subagents and descendants. This post-paid ceiling is soft. */
95
+ maxAiCredits?: number;
96
+ /**
97
+ * Maximum accumulated active-execution time, in seconds. Active execution includes the entire extension body,
98
+ * subprocess waits, queued-agent waits, and sleeps. The limit is armed from the remaining headroom when a run
99
+ * resumes; time between attempts is not counted. Must be finite and positive when present.
100
+ */
101
+ timeoutSeconds?: number;
102
+ }
103
+ /**
104
+ * Registration metadata for an extension-authored workflow.
105
+ *
106
+ * @experimental Part of the experimental Dynamic Workflows surface and may
107
+ * change or be removed in future SDK or CLI releases.
108
+ */
109
+ export interface WorkflowMeta {
110
+ /** Stable workflow name used for invocation. */
111
+ name: string;
112
+ /** Human-readable workflow description. */
113
+ description: string;
114
+ /** Display metadata for the progress phases the workflow may report. */
115
+ phases: Array<{
116
+ title: string;
117
+ detail?: string;
118
+ }>;
119
+ /**
120
+ * Optional declared shape of the arguments this workflow expects as `ctx.args`.
121
+ *
122
+ * The runtime records and validates this schema when the workflow contribution
123
+ * is registered. Workflow bodies should still validate any semantic constraints
124
+ * they depend on because the public `session.workflow.run(...)` API forwards
125
+ * arguments directly.
126
+ */
127
+ argsSchema?: WorkflowJsonSchema;
128
+ /** Optional resource ceilings presented before execution. */
129
+ limits?: WorkflowLimits;
130
+ }
131
+ /**
132
+ * Options for one workflow-scoped subagent call.
133
+ *
134
+ * @experimental Part of the experimental Dynamic Workflows surface and may
135
+ * change or be removed in future SDK or CLI releases.
136
+ */
137
+ export interface WorkflowAgentOptions {
138
+ label?: string;
139
+ schema?: WorkflowJsonSchema;
140
+ model?: string;
141
+ reasoningEffort?: string;
142
+ contextTier?: ContextTier;
143
+ /**
144
+ * Ordinary catalog agent name, or an opaque workflow-scoped custom-agent
145
+ * reference from the currently executing workflow's `context.agents`.
146
+ */
147
+ agent?: string | WorkflowAgentReference;
148
+ /**
149
+ * Maximum seconds for this agent call's queueing, preparation and execution.
150
+ * Must be finite and positive, at most 2_147_483.647. The runtime cancels
151
+ * only this agent when it expires; cleanup may finish after the deadline.
152
+ * Omitting it leaves the call bounded only by the workflow's own limits.
153
+ */
154
+ timeoutSeconds?: number;
155
+ }
156
+ export declare const WORKFLOW_AGENT_OPTION_KEYS: readonly ["label", "schema", "model", "reasoningEffort", "contextTier", "agent", "timeoutSeconds"];
157
+ /**
158
+ * Options for a durable workflow step.
159
+ *
160
+ * @experimental Part of the experimental Dynamic Workflows surface and may
161
+ * change or be removed in future SDK or CLI releases.
162
+ */
163
+ export interface WorkflowStepOptions {
164
+ /** Skip the journal and always invoke the producer. */
165
+ volatile?: boolean;
166
+ }
167
+ /**
168
+ * Per-invocation workflow resource ceiling overrides.
169
+ *
170
+ * An omitted field preserves the existing/default ceiling, a number replaces
171
+ * it, and `null` explicitly makes that dimension unlimited.
172
+ *
173
+ * @experimental Part of the experimental Dynamic Workflows surface and may
174
+ * change or be removed in future SDK or CLI releases.
175
+ */
176
+ export interface WorkflowLimitOverrides {
177
+ maxConcurrentSubagents?: number | null;
178
+ maxTotalSubagents?: number | null;
179
+ maxAiCredits?: number | null;
180
+ timeoutSeconds?: number | null;
181
+ }
182
+ /**
183
+ * One stage in a per-item workflow pipeline.
184
+ *
185
+ * @experimental Part of the experimental Dynamic Workflows surface and may
186
+ * change or be removed in future SDK or CLI releases.
187
+ */
188
+ export type WorkflowPipelineStage<TInput = unknown, TResult = unknown> = (previous: TInput, item: unknown, index: number) => Promise<TResult> | TResult;
189
+ /**
190
+ * Context passed to an extension-authored workflow body.
191
+ *
192
+ * @experimental Part of the experimental Dynamic Workflows surface and may
193
+ * change or be removed in future SDK or CLI releases.
194
+ */
195
+ export interface WorkflowContext<TArgs extends JsonValue = JsonValue> {
196
+ /** Stable identifier for the current workflow run. */
197
+ readonly runId: string;
198
+ /** Opaque references to the custom agents declared by this workflow. */
199
+ readonly agents: Readonly<Record<string, WorkflowAgentReference>>;
200
+ /** Spawn and await one workflow-scoped subagent. */
201
+ agent(prompt: string, options?: WorkflowAgentOptions): Promise<unknown>;
202
+ /** Memoize an arbitrary producer under a stable author-supplied key. */
203
+ step(key: string, producer: () => Promise<JsonValue> | JsonValue, options?: WorkflowStepOptions): Promise<JsonValue>;
204
+ /**
205
+ * Pause this run at a durable, one-shot checkpoint.
206
+ *
207
+ * The first attempt to reach a key pauses and aborts cooperatively. A
208
+ * resumed attempt returns from the same key and continues.
209
+ */
210
+ pause(key: string): Promise<void>;
211
+ /**
212
+ * Run thunks concurrently and await all of them.
213
+ *
214
+ * A thunk that throws becomes `null` in the result array, so one failed
215
+ * item does not lose the rest. Cancellation and hard runtime failures
216
+ * (`ResponseError`, `ConnectionError`) are the exception: those propagate
217
+ * and reject the whole call, because they mean the run itself is in
218
+ * trouble rather than one item having failed.
219
+ */
220
+ parallel<TResult>(thunks: Array<() => Promise<TResult> | TResult>): Promise<Array<TResult | null>>;
221
+ /**
222
+ * Run each item through every stage without barriers between stages.
223
+ *
224
+ * A stage that throws drops that item to `null` and skips its remaining
225
+ * stages. As with {@link WorkflowContext.parallel}, cancellation and hard
226
+ * runtime failures propagate instead of being recorded per item.
227
+ */
228
+ pipeline(items: unknown[], ...stages: WorkflowPipelineStage[]): Promise<unknown[]>;
229
+ /** Start a named workflow progress phase. */
230
+ phase(title: string): void;
231
+ /** Emit a workflow progress line. */
232
+ log(message: string): void;
233
+ /** Reject because nested workflows are not supported. */
234
+ workflow(name: string, args?: JsonValue): Promise<JsonValue | void>;
235
+ /** Caller-supplied input, forwarded verbatim. */
236
+ args: TArgs;
237
+ /**
238
+ * The session instance returned by `joinSession`. It refuses calls that
239
+ * start, resume, or pause a workflow run.
240
+ */
241
+ session: CopilotSession;
242
+ /** Cooperative cancellation signal for the current workflow run. */
243
+ signal: AbortSignal;
244
+ }
245
+ /**
246
+ * Definition accepted by {@link defineWorkflow}.
247
+ *
248
+ * @experimental Part of the experimental Dynamic Workflows surface and may
249
+ * change or be removed in future SDK or CLI releases.
250
+ */
251
+ export interface WorkflowDefinition<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
252
+ meta: WorkflowMeta;
253
+ /**
254
+ * Restricted {@link CustomAgentConfig} definitions owned exclusively by this workflow.
255
+ *
256
+ * Each map key becomes an opaque reference on `context.agents`. Definitions
257
+ * never enter the session's global agent catalog.
258
+ */
259
+ agents?: WorkflowAgentConfigMap;
260
+ run(context: WorkflowContext<TArgs>): Promise<TResult>;
261
+ }
262
+ /**
263
+ * Opaque reusable reference to a defined workflow.
264
+ *
265
+ * @experimental Part of the experimental Dynamic Workflows surface and may
266
+ * change or be removed in future SDK or CLI releases.
267
+ */
268
+ export interface WorkflowHandle<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
269
+ readonly meta: DeepReadonly<WorkflowMeta>;
270
+ readonly [workflowHandleBrand]: {
271
+ readonly args: TArgs;
272
+ readonly result: TResult;
273
+ };
274
+ }
275
+ /**
276
+ * Options for invoking a workflow.
277
+ *
278
+ * @experimental Part of the experimental Dynamic Workflows surface and may
279
+ * change or be removed in future SDK or CLI releases.
280
+ */
281
+ export interface WorkflowRunOptions<TArgs extends JsonValue = JsonValue> {
282
+ /** Input surfaced as `context.args`. */
283
+ args?: TArgs;
284
+ /** Optional per-invocation resource ceiling overrides. */
285
+ limits?: WorkflowLimitOverrides;
286
+ /** Whether to notify the originating session when the workflow completes. */
287
+ notifyOnComplete?: boolean;
288
+ /** Whether to emit workflow phase names to the session transcript. */
289
+ logPhaseNames?: boolean;
290
+ }
291
+ /**
292
+ * Options for resuming a workflow run by ID.
293
+ *
294
+ * @experimental Part of the experimental Dynamic Workflows surface and may
295
+ * change or be removed in future SDK or CLI releases.
296
+ */
297
+ export interface WorkflowResumeOptions {
298
+ /** Optional per-invocation resource ceiling overrides. */
299
+ limits?: WorkflowLimitOverrides;
300
+ /** Whether to notify the originating session when the workflow completes. */
301
+ notifyOnComplete?: boolean;
302
+ /** Whether to emit workflow phase names to the session transcript. */
303
+ logPhaseNames?: boolean;
304
+ }
305
+ /**
306
+ * Machine-readable pre-execution workflow resume failure.
307
+ *
308
+ * @experimental Part of the experimental Dynamic Workflows surface and may
309
+ * change or be removed in future SDK or CLI releases.
310
+ */
311
+ 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" | "workflow_role_definition_mismatch";
312
+ /**
313
+ * Friendly workflow API exposed on a session.
314
+ *
315
+ * @experimental Part of the experimental Dynamic Workflows surface and may
316
+ * change or be removed in future SDK or CLI releases.
317
+ */
318
+ export interface SessionWorkflowApi {
319
+ /**
320
+ * Start a registered workflow and resolve as soon as the runtime admits it.
321
+ *
322
+ * Returns the admitted run's identity and current envelope without waiting
323
+ * for completion. Admission is not a successful terminal outcome: inspect
324
+ * the run through {@link SessionWorkflowApi.getRun} or await
325
+ * {@link SessionWorkflowApi.waitForRun}. Pre-admission failures reject just
326
+ * as they do for {@link SessionWorkflowApi.run}.
327
+ */
328
+ start(name: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
329
+ start<TArgs extends JsonValue>(workflow: WorkflowHandle<TArgs, JsonValue | void>, options?: WorkflowRunOptions<TArgs>): Promise<WorkflowRunResult>;
330
+ /**
331
+ * Run a registered workflow and wait for its current attempt to settle.
332
+ *
333
+ * The envelope is returned for every outcome, including `error`, `halted`,
334
+ * `paused`, and `cancelled` — inspect `status` and read `result` only when
335
+ * the run completed. `paused` settles the current attempt, but the same
336
+ * durable run can later resume under its existing run ID. SDK-initiated
337
+ * runs do not request permission, so they have no declined outcome.
338
+ * Failures that occur before a run exists (such as an unknown workflow or
339
+ * attempting to start a run while the session is at its active top-level
340
+ * run limit) still reject.
341
+ */
342
+ run(name: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
343
+ run<TArgs extends JsonValue>(workflow: WorkflowHandle<TArgs, JsonValue | void>, options?: WorkflowRunOptions<TArgs>): Promise<WorkflowRunResult>;
344
+ /**
345
+ * Resume a run from its persisted workflow name, arguments, journal, and accounting.
346
+ *
347
+ * Resolves with the run envelope like {@link SessionWorkflowApi.run}.
348
+ * SDK-initiated resumes do not request permission. A pre-execution failure
349
+ * with a documented resume code rejects with {@link WorkflowResumeError}.
350
+ */
351
+ resume(runId: string, options?: WorkflowResumeOptions): Promise<WorkflowRunResult>;
352
+ /** Read the latest durable envelope for a workflow run. */
353
+ getRun(runId: string): Promise<WorkflowRunResult>;
354
+ /**
355
+ * Wait for the current attempt to settle and resolve with its envelope.
356
+ *
357
+ * Resolves as soon as the run reaches `completed`, `error`, `halted`,
358
+ * `paused`, or `cancelled`, and resolves immediately when the current
359
+ * attempt has already settled. A `paused` envelope is an attempt-level
360
+ * snapshot: resuming the same durable run can later change the envelope
361
+ * returned by {@link SessionWorkflowApi.getRun}.
362
+ *
363
+ * This watches the runtime's `workflow.run_updated` event and
364
+ * periodically re-reads the durable envelope so a missed event cannot
365
+ * leave the wait hanging. Pass a `signal` to stop waiting; aborting rejects
366
+ * and has no effect on the run itself, which keeps executing. Use
367
+ * {@link SessionWorkflowApi.cancel} to actually stop it.
368
+ */
369
+ waitForRun(runId: string, options?: {
370
+ signal?: AbortSignal;
371
+ }): Promise<WorkflowRunResult>;
372
+ /**
373
+ * List the newest default page of this session's durable workflow runs.
374
+ *
375
+ * This backwards-compatible overload returns only the runs array. Pass
376
+ * paging options to receive the full page, including its cursors and
377
+ * truncation metadata.
378
+ */
379
+ listRuns(): Promise<WorkflowRunSummary[]>;
380
+ /**
381
+ * Page this session's durable workflow runs.
382
+ *
383
+ * `afterSeq` and `beforeSeq` are exclusive cursors. The result includes
384
+ * `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` so callers
385
+ * can continue paging without using the raw RPC client.
386
+ */
387
+ listRuns(options: WorkflowListRunsOptions): Promise<WorkflowRunsPage>;
388
+ /** Read durable phases, direct agents, and the latest progress tail for a run. */
389
+ getRunDetail(runId: string): Promise<WorkflowRunDetail>;
390
+ /** Page durable progress forward, backward, or from the latest tail. */
391
+ getRunProgress(runId: string, options?: Omit<WorkflowGetRunProgressRequest, "runId">): Promise<WorkflowProgressPage>;
392
+ /** Pause a running workflow attempt and return its `paused` envelope. */
393
+ pause(runId: string): Promise<WorkflowRunResult>;
394
+ /** Cancel a workflow run and return its terminal envelope. */
395
+ cancel(runId: string): Promise<WorkflowRunResult>;
396
+ }
397
+ /**
398
+ * Error thrown when a workflow cannot be resumed before execution begins.
399
+ *
400
+ * @experimental Part of the experimental Dynamic Workflows surface and may
401
+ * change or be removed in future SDK or CLI releases.
402
+ */
403
+ export declare class WorkflowResumeError extends Error {
404
+ readonly code: WorkflowResumeErrorCode;
405
+ constructor(code: WorkflowResumeErrorCode, message: string);
406
+ }
407
+ /**
408
+ * Defines an extension-authored workflow and returns an opaque registration handle.
409
+ *
410
+ * @experimental Part of the experimental Dynamic Workflows surface and may
411
+ * change or be removed in future SDK or CLI releases.
412
+ */
413
+ export declare function defineWorkflow<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void>(definition: WorkflowDefinition<TArgs, TResult>): WorkflowHandle<TArgs, TResult>;