@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.
- package/README.md +2531 -2
- package/dist/canvas.d.ts +135 -0
- package/dist/canvas.js +51 -0
- package/dist/cjs/canvas.js +77 -0
- package/dist/cjs/cliVersion.js +31 -0
- package/dist/cjs/client.js +3941 -0
- package/dist/cjs/copilotRequestHandler.js +815 -0
- package/dist/cjs/decisions.js +139 -0
- package/dist/cjs/entra.js +83 -0
- package/dist/cjs/extension.js +79 -0
- package/dist/cjs/ffiRuntimeHost.js +400 -0
- package/dist/cjs/generated/lifecycle-diagnostics.js +16 -0
- package/dist/cjs/generated/rpc.js +5883 -0
- package/dist/cjs/generated/session-events.js +16 -0
- package/dist/cjs/host.js +83 -0
- package/dist/cjs/index.js +100 -0
- package/dist/cjs/installationConfirmation.js +98 -0
- package/dist/cjs/jsonrpcTypes.js +41 -0
- package/dist/cjs/localModelJson.js +103 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/providerConfiguration.js +39 -0
- package/dist/cjs/rpcCancellation.js +49 -0
- package/dist/cjs/runtimeArtifacts.js +255 -0
- package/dist/cjs/schema.js +40 -0
- package/dist/cjs/sdkProtocolVersion.js +33 -0
- package/dist/cjs/session.js +2764 -0
- package/dist/cjs/sessionFsProvider.js +283 -0
- package/dist/cjs/taskAnalyticsJson.js +47 -0
- package/dist/cjs/telemetry.js +35 -0
- package/dist/cjs/toolSet.js +107 -0
- package/dist/cjs/types.js +204 -0
- package/dist/cjs/workflow.js +278 -0
- package/dist/cliVersion.d.ts +2 -0
- package/dist/cliVersion.js +6 -0
- package/dist/client.d.ts +576 -0
- package/dist/client.js +3924 -0
- package/dist/copilotRequestHandler.d.ts +91 -0
- package/dist/copilotRequestHandler.js +787 -0
- package/dist/decisions.d.ts +65 -0
- package/dist/decisions.js +113 -0
- package/dist/entra.d.ts +3 -0
- package/dist/entra.js +59 -0
- package/dist/extension.d.ts +69 -0
- package/dist/extension.js +59 -0
- package/dist/ffiRuntimeHost.d.ts +44 -0
- package/dist/ffiRuntimeHost.js +366 -0
- package/dist/generated/lifecycle-diagnostics.d.ts +232 -0
- package/dist/generated/lifecycle-diagnostics.js +0 -0
- package/dist/generated/rpc.d.ts +47706 -0
- package/dist/generated/rpc.js +5854 -0
- package/dist/generated/session-events.d.ts +17349 -0
- package/dist/generated/session-events.js +0 -0
- package/dist/host.d.ts +143 -0
- package/dist/host.js +59 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +74 -0
- package/dist/installationConfirmation.d.ts +19 -0
- package/dist/installationConfirmation.js +74 -0
- package/dist/jsonrpcTypes.d.ts +16 -0
- package/dist/jsonrpcTypes.js +17 -0
- package/dist/localModelJson.d.ts +1 -0
- package/dist/localModelJson.js +69 -0
- package/dist/providerConfiguration.d.ts +3 -0
- package/dist/providerConfiguration.js +15 -0
- package/dist/rpcCancellation.d.ts +3 -0
- package/dist/rpcCancellation.js +25 -0
- package/dist/runtimeArtifacts.d.ts +18 -0
- package/dist/runtimeArtifacts.js +233 -0
- package/dist/schema.d.ts +4 -0
- package/dist/schema.js +14 -0
- package/dist/sdkProtocolVersion.d.ts +10 -0
- package/dist/sdkProtocolVersion.js +8 -0
- package/dist/session.d.ts +524 -0
- package/dist/session.js +2751 -0
- package/dist/sessionFsProvider.d.ts +130 -0
- package/dist/sessionFsProvider.js +257 -0
- package/dist/taskAnalyticsJson.d.ts +8 -0
- package/dist/taskAnalyticsJson.js +12 -0
- package/dist/telemetry.d.ts +14 -0
- package/dist/telemetry.js +11 -0
- package/dist/toolSet.d.ts +75 -0
- package/dist/toolSet.js +82 -0
- package/dist/types.d.ts +3864 -0
- package/dist/types.js +169 -0
- package/dist/workflow.d.ts +413 -0
- package/dist/workflow.js +248 -0
- package/docs/agent-author.md +372 -0
- package/docs/examples.md +747 -0
- package/docs/extensions.md +121 -0
- package/docs/workflows.md +303 -0
- 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>;
|