@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
@@ -0,0 +1,130 @@
1
+ import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteTransactionErrorClass, SessionFsSqliteQueryType } from "./generated/rpc.js";
2
+ export type { SessionFsSqliteQueryType, SessionFsSqliteTransactionErrorClass };
3
+ /**
4
+ * File metadata returned by {@link SessionFsProvider.stat}.
5
+ * Same shape as the generated {@link SessionFsStatResult} but without the
6
+ * `error` field, since providers signal errors by throwing.
7
+ */
8
+ export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
9
+ /** Raw bytes and the authoritative total file byte length captured by the same read. */
10
+ export interface SessionFsByteRange {
11
+ /** Requested bytes; boundaries may split UTF-8 characters. */
12
+ content: Uint8Array;
13
+ /** Total file byte length, independent of the requested range. */
14
+ byteLength: number;
15
+ }
16
+ /**
17
+ * Result of a SQLite query execution via {@link SessionFsSqliteProvider.query}.
18
+ * Same shape as the generated {@link GeneratedSqliteQueryResult} but without the
19
+ * `error` field, since providers signal errors by throwing.
20
+ */
21
+ export type SessionFsSqliteQueryResult = Omit<GeneratedSqliteQueryResult, "error">;
22
+ /**
23
+ * One statement in an atomic SQLite transaction passed to
24
+ * {@link SessionFsSqliteProvider.transaction}.
25
+ */
26
+ export interface SessionFsSqliteStatement {
27
+ /** How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE. */
28
+ queryType: SessionFsSqliteQueryType;
29
+ /** SQL statement to execute. */
30
+ query: string;
31
+ /** Optional named bind parameters. */
32
+ params?: Record<string, string | number | null>;
33
+ }
34
+ /**
35
+ * Error thrown by {@link SessionFsSqliteProvider.transaction} to classify a
36
+ * transaction failure for the runtime.
37
+ *
38
+ * Any other thrown value is reported as `"fatal"`. Throw this with
39
+ * `"busyOrLocked"` when SQLite reported BUSY/LOCKED before commit and the
40
+ * transaction was rolled back, so the runtime knows the call is safe to retry.
41
+ */
42
+ export declare class SessionFsSqliteTransactionFailure extends Error {
43
+ /** Failure classification reported to the runtime. */
44
+ readonly errorClass: SessionFsSqliteTransactionErrorClass;
45
+ constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
46
+ }
47
+ /** Throw from `writeFile` only when the provider changed the target before failing. */
48
+ export declare class SessionFsWriteFailure extends Error {
49
+ readonly writeChanged = true;
50
+ }
51
+ /**
52
+ * SQLite operations for the per-session database.
53
+ * Implementers provide query execution and existence checking.
54
+ */
55
+ export interface SessionFsSqliteProvider {
56
+ /**
57
+ * Execute a SQLite query against the per-session database.
58
+ *
59
+ * @param queryType - How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE.
60
+ * @param query - SQL query to execute.
61
+ * @param params - Optional named bind parameters.
62
+ */
63
+ query(queryType: SessionFsSqliteQueryType, query: string, params?: Record<string, string | number | null>): Promise<SessionFsSqliteQueryResult | undefined>;
64
+ /**
65
+ * Execute `statements` atomically against the per-session database.
66
+ *
67
+ * Apply busy handling to every statement and roll back the whole batch if
68
+ * any statement fails. Throw {@link SessionFsSqliteTransactionFailure} to
69
+ * classify the failure; any other thrown value is reported as `"fatal"`.
70
+ *
71
+ * @param statements - Statements to execute in order inside a single transaction.
72
+ * @returns One result per statement, in the same order.
73
+ */
74
+ transaction?(statements: SessionFsSqliteStatement[]): Promise<SessionFsSqliteQueryResult[]>;
75
+ /**
76
+ * Check whether the per-session database already exists, without creating it.
77
+ */
78
+ exists(): Promise<boolean>;
79
+ }
80
+ /**
81
+ * Interface for session filesystem providers. Implementers use idiomatic
82
+ * TypeScript patterns: throw on error, return values directly. Use
83
+ * {@link createSessionFsAdapter} to convert a provider into the
84
+ * {@link SessionFsHandler} expected by the SDK.
85
+ *
86
+ * Errors with a `code` property of `"ENOENT"` are mapped to the ENOENT
87
+ * error code; all others map to UNKNOWN.
88
+ */
89
+ export interface SessionFsProvider {
90
+ /** Reads the full content of a file. Throw if the file does not exist. */
91
+ readFile(path: string): Promise<string>;
92
+ /** Read exact file bytes. Required when capabilities.binary is enabled. */
93
+ readFileBytes?(path: string): Promise<Uint8Array>;
94
+ /**
95
+ * Reads raw bytes starting at a non-negative safe integer byte offset.
96
+ * Omit length to read through EOF; zero returns only byte length.
97
+ * At or beyond EOF, content is empty. Advertise capabilities.readFileRange
98
+ * only when every provider implements bounded reads without full-file downloads.
99
+ * This capability is independent of binary reads and writes.
100
+ */
101
+ readFileRange?(path: string, offset: number, length?: number): Promise<SessionFsByteRange>;
102
+ /** Write exact file bytes. Required when capabilities.binary is enabled. */
103
+ writeFileBytes?(path: string, content: Uint8Array, mode?: number): Promise<void>;
104
+ /** Writes content to a file, creating parent directories if needed. Throw {@link SessionFsWriteFailure} if a failed write changed the target. */
105
+ writeFile(path: string, content: string, mode?: number): Promise<void>;
106
+ /** Appends content to a file, creating parent directories if needed. */
107
+ appendFile(path: string, content: string, mode?: number): Promise<void>;
108
+ /** Checks whether a path exists. */
109
+ exists(path: string): Promise<boolean>;
110
+ /** Gets metadata about a file or directory. Throw if it does not exist. */
111
+ stat(path: string): Promise<SessionFsFileInfo>;
112
+ /** Creates a directory. If recursive is true, creates parents as needed. */
113
+ mkdir(path: string, recursive: boolean, mode?: number): Promise<void>;
114
+ /** Lists entry names in a directory. Throw if it does not exist. */
115
+ readdir(path: string): Promise<string[]>;
116
+ /** Lists entries with type info. Throw if the directory does not exist. */
117
+ readdirWithTypes(path: string): Promise<SessionFsReaddirWithTypesEntry[]>;
118
+ /** Removes a file or directory. If force is true, do not throw on ENOENT. */
119
+ rm(path: string, recursive: boolean, force: boolean): Promise<void>;
120
+ /** Renames/moves a file or directory. */
121
+ rename(src: string, dest: string): Promise<void>;
122
+ /** Per-session SQLite database operations. Optional — omit if the provider does not support SQLite. */
123
+ sqlite?: SessionFsSqliteProvider;
124
+ }
125
+ /**
126
+ * Wraps a {@link SessionFsProvider} into the {@link SessionFsHandler}
127
+ * interface expected by the SDK, converting thrown errors into
128
+ * {@link SessionFsError} results.
129
+ */
130
+ export declare function createSessionFsAdapter(provider: SessionFsProvider): SessionFsHandler;
@@ -0,0 +1,257 @@
1
+ const MAX_BINARY_BYTES = (64 * 1024 * 1024 - 1024) / 4 * 3;
2
+ const MAX_BINARY_CONTENT_LENGTH = Math.ceil(MAX_BINARY_BYTES / 3) * 4;
3
+ class SessionFsSqliteTransactionFailure extends Error {
4
+ /** Failure classification reported to the runtime. */
5
+ errorClass;
6
+ constructor(message, errorClass = "fatal") {
7
+ super(message);
8
+ this.name = "SessionFsSqliteTransactionFailure";
9
+ this.errorClass = errorClass;
10
+ }
11
+ }
12
+ class SessionFsWriteFailure extends Error {
13
+ writeChanged = true;
14
+ }
15
+ function normalizeSqliteParams(params) {
16
+ if (!params) {
17
+ return void 0;
18
+ }
19
+ const normalized = {};
20
+ for (const [key, value] of Object.entries(params)) {
21
+ if (value !== void 0) {
22
+ normalized[key] = value;
23
+ }
24
+ }
25
+ return normalized;
26
+ }
27
+ function createSessionFsAdapter(provider) {
28
+ return {
29
+ readFileRange: async ({ path, offset, length }) => {
30
+ try {
31
+ if (!Number.isSafeInteger(offset) || offset < 0 || length !== void 0 && (!Number.isSafeInteger(length) || length < 0)) {
32
+ throw new RangeError(
33
+ "SessionFs byte offset and length must be non-negative safe integers"
34
+ );
35
+ }
36
+ if (!provider.readFileRange) {
37
+ throw new Error(
38
+ "Byte-range reads are not supported by this SessionFs provider"
39
+ );
40
+ }
41
+ const result = await provider.readFileRange(path, offset, length);
42
+ if (!Number.isSafeInteger(result.byteLength) || result.byteLength < 0) {
43
+ throw new Error("SessionFs byte length must be a non-negative safe integer");
44
+ }
45
+ const available = Math.max(0, result.byteLength - offset);
46
+ if (result.content.byteLength !== Math.min(length ?? available, available)) {
47
+ throw new Error("SessionFs returned an incorrect byte range length");
48
+ }
49
+ return {
50
+ content: Buffer.from(result.content).toString("base64"),
51
+ byteLength: result.byteLength
52
+ };
53
+ } catch (err) {
54
+ return { content: "", byteLength: 0, error: toSessionFsError(err) };
55
+ }
56
+ },
57
+ readFile: async ({ path }) => {
58
+ try {
59
+ const content = await provider.readFile(path);
60
+ return { content };
61
+ } catch (err) {
62
+ return { content: "", error: toSessionFsError(err) };
63
+ }
64
+ },
65
+ readFileBytes: async ({ path }) => {
66
+ if (!provider.readFileBytes) {
67
+ return {
68
+ content: "",
69
+ error: { code: "UNKNOWN", message: "Binary reads are not supported" }
70
+ };
71
+ }
72
+ try {
73
+ const bytes = await provider.readFileBytes(path);
74
+ if (bytes.length > MAX_BINARY_BYTES) {
75
+ return {
76
+ content: "",
77
+ error: {
78
+ code: "UNKNOWN",
79
+ message: "sessionFs.readFileBytes content exceeds the binary read limit"
80
+ }
81
+ };
82
+ }
83
+ return {
84
+ content: Buffer.from(bytes).toString("base64")
85
+ };
86
+ } catch (err) {
87
+ return { content: "", error: toSessionFsError(err) };
88
+ }
89
+ },
90
+ writeFile: async ({ path, content, mode }) => {
91
+ try {
92
+ await provider.writeFile(path, content, mode);
93
+ return void 0;
94
+ } catch (err) {
95
+ const error = toSessionFsError(err);
96
+ return err instanceof SessionFsWriteFailure ? { ...error, writeChanged: true } : error;
97
+ }
98
+ },
99
+ writeFileBytes: async ({ path, content, mode }) => {
100
+ if (!provider.writeFileBytes) {
101
+ return { code: "UNKNOWN", message: "Binary writes are not supported" };
102
+ }
103
+ if (content.length > MAX_BINARY_CONTENT_LENGTH) {
104
+ return {
105
+ code: "UNKNOWN",
106
+ message: "sessionFs.writeFileBytes content exceeds the binary write limit"
107
+ };
108
+ }
109
+ const bytes = Buffer.from(content, "base64");
110
+ if (bytes.toString("base64") !== content || bytes.length > MAX_BINARY_BYTES) {
111
+ return {
112
+ code: "UNKNOWN",
113
+ message: "invalid sessionFs.writeFileBytes base64 content"
114
+ };
115
+ }
116
+ try {
117
+ await provider.writeFileBytes(path, bytes, mode);
118
+ return void 0;
119
+ } catch (err) {
120
+ return toSessionFsError(err);
121
+ }
122
+ },
123
+ appendFile: async ({ path, content, mode }) => {
124
+ try {
125
+ await provider.appendFile(path, content, mode);
126
+ return void 0;
127
+ } catch (err) {
128
+ return toSessionFsError(err);
129
+ }
130
+ },
131
+ exists: async ({ path }) => {
132
+ try {
133
+ return { exists: await provider.exists(path) };
134
+ } catch {
135
+ return { exists: false };
136
+ }
137
+ },
138
+ stat: async ({ path }) => {
139
+ try {
140
+ return await provider.stat(path);
141
+ } catch (err) {
142
+ return {
143
+ isFile: false,
144
+ isDirectory: false,
145
+ size: 0,
146
+ mtime: (/* @__PURE__ */ new Date()).toISOString(),
147
+ birthtime: (/* @__PURE__ */ new Date()).toISOString(),
148
+ error: toSessionFsError(err)
149
+ };
150
+ }
151
+ },
152
+ mkdir: async ({ path, recursive, mode }) => {
153
+ try {
154
+ await provider.mkdir(path, recursive ?? false, mode);
155
+ return void 0;
156
+ } catch (err) {
157
+ return toSessionFsError(err);
158
+ }
159
+ },
160
+ readdir: async ({ path }) => {
161
+ try {
162
+ const entries = await provider.readdir(path);
163
+ return { entries };
164
+ } catch (err) {
165
+ return { entries: [], error: toSessionFsError(err) };
166
+ }
167
+ },
168
+ readdirWithTypes: async ({ path }) => {
169
+ try {
170
+ const entries = await provider.readdirWithTypes(path);
171
+ return { entries };
172
+ } catch (err) {
173
+ return { entries: [], error: toSessionFsError(err) };
174
+ }
175
+ },
176
+ rm: async ({ path, recursive, force }) => {
177
+ try {
178
+ await provider.rm(path, recursive ?? false, force ?? false);
179
+ return void 0;
180
+ } catch (err) {
181
+ return toSessionFsError(err);
182
+ }
183
+ },
184
+ rename: async ({ src, dest }) => {
185
+ try {
186
+ await provider.rename(src, dest);
187
+ return void 0;
188
+ } catch (err) {
189
+ return toSessionFsError(err);
190
+ }
191
+ },
192
+ // Unlike the FS methods above, SQLite methods let errors propagate to the JSON-RPC layer
193
+ // rather than catching and mapping via toSessionFsError. The FS error mapping is specifically
194
+ // for translating Node.js errno codes (e.g., ENOENT) into SessionFsError, which isn't
195
+ // meaningful for SQL errors. Letting exceptions propagate preserves the original error
196
+ // message in the JSON-RPC error response.
197
+ sqliteQuery: async ({ queryType, query, params: bindParams }) => {
198
+ if (!provider.sqlite) {
199
+ throw new Error("SQLite is not supported by this provider");
200
+ }
201
+ const result = await provider.sqlite.query(
202
+ queryType,
203
+ query,
204
+ normalizeSqliteParams(bindParams)
205
+ );
206
+ return result ?? { rows: [], columns: [], rowsAffected: 0 };
207
+ },
208
+ sqliteTransaction: async ({ statements }) => {
209
+ if (!provider.sqlite?.transaction) {
210
+ return {
211
+ results: [],
212
+ error: {
213
+ errorClass: "fatal",
214
+ message: "SQLite transactions are not supported by this provider"
215
+ }
216
+ };
217
+ }
218
+ try {
219
+ const results = await provider.sqlite.transaction(
220
+ statements.map((statement) => ({
221
+ queryType: statement.queryType,
222
+ query: statement.query,
223
+ params: normalizeSqliteParams(statement.params)
224
+ }))
225
+ );
226
+ return { results: results.map((result) => ({ ...result })) };
227
+ } catch (err) {
228
+ return { results: [], error: toSqliteTransactionError(err) };
229
+ }
230
+ },
231
+ sqliteExists: async () => {
232
+ if (!provider.sqlite) {
233
+ throw new Error("SQLite is not supported by this provider");
234
+ }
235
+ return { exists: await provider.sqlite.exists() };
236
+ }
237
+ };
238
+ }
239
+ function toSessionFsError(err) {
240
+ const e = err;
241
+ const code = e.code === "ENOENT" ? "ENOENT" : "UNKNOWN";
242
+ return { code, message: e.message ?? String(err) };
243
+ }
244
+ function toSqliteTransactionError(err) {
245
+ if (err instanceof SessionFsSqliteTransactionFailure) {
246
+ return { errorClass: err.errorClass, message: err.message };
247
+ }
248
+ return {
249
+ errorClass: "fatal",
250
+ message: err instanceof Error ? err.message : String(err)
251
+ };
252
+ }
253
+ export {
254
+ SessionFsSqliteTransactionFailure,
255
+ SessionFsWriteFailure,
256
+ createSessionFsAdapter
257
+ };
@@ -0,0 +1,8 @@
1
+ import type { TrajectoryJsonValue } from "./generated/rpc.js";
2
+ /**
3
+ * Parses archive JSON without rounding integers outside JavaScript's safe range.
4
+ * Such integers become bigint values, supported by taskAnalytics.classifyTrajectory.
5
+ * Pass an array directly as request events, or wrap a single ATIF document in an array.
6
+ * @experimental
7
+ */
8
+ export declare function parseTrajectoryJson(text: string): Promise<TrajectoryJsonValue>;
@@ -0,0 +1,12 @@
1
+ const rawHistoryResponse = /* @__PURE__ */ Symbol("rawHistoryResponse");
2
+ async function parseTrajectoryJson(text) {
3
+ const { parse, parseNumberAndBigInt } = await import("lossless-json");
4
+ return parse(text, void 0, (token) => {
5
+ const value = parseNumberAndBigInt(token);
6
+ return typeof value === "bigint" && Number.isSafeInteger(Number(value)) ? Number(value) : value;
7
+ });
8
+ }
9
+ export {
10
+ parseTrajectoryJson,
11
+ rawHistoryResponse
12
+ };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Trace-context helpers.
3
+ *
4
+ * The SDK does not depend on any OpenTelemetry packages. Instead, users
5
+ * provide an {@link TraceContextProvider} callback via client options.
6
+ *
7
+ * @module telemetry
8
+ */
9
+ import type { TraceContext, TraceContextProvider } from "./types.js";
10
+ /**
11
+ * Calls the user-provided {@link TraceContextProvider} to obtain the current
12
+ * W3C Trace Context. Returns `{}` when no provider is configured.
13
+ */
14
+ export declare function getTraceContext(provider?: TraceContextProvider): Promise<TraceContext>;
@@ -0,0 +1,11 @@
1
+ async function getTraceContext(provider) {
2
+ if (!provider) return {};
3
+ try {
4
+ return await provider() ?? {};
5
+ } catch {
6
+ return {};
7
+ }
8
+ }
9
+ export {
10
+ getTraceContext
11
+ };
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Builder that produces a list of source-qualified tool filter strings for
3
+ * {@link SessionConfigBase.availableTools}.
4
+ *
5
+ * Tools are classified by the runtime at registration time (not from name
6
+ * parsing), so `addBuiltIn("foo")` matches only tools the runtime registered
7
+ * as built-in, even if an MCP server or custom-agent extension happens to
8
+ * register a tool with the same wire name.
9
+ *
10
+ * @example
11
+ * ```typescript
12
+ * const tools = new ToolSet()
13
+ * .addBuiltIn(BuiltInTools.Isolated)
14
+ * .addMcp("*")
15
+ * .addCustom("*");
16
+ *
17
+ * const session = await client.createSession({
18
+ * availableTools: tools,
19
+ * // ...
20
+ * });
21
+ * ```
22
+ */
23
+ export declare class ToolSet {
24
+ private readonly items;
25
+ /**
26
+ * Adds one or more built-in tool patterns.
27
+ *
28
+ * @param name A specific built-in tool name (e.g. `"bash"`) or `"*"` to match all
29
+ * built-in tools.
30
+ */
31
+ addBuiltIn(name: string): ToolSet;
32
+ /**
33
+ * Adds a list of built-in tool patterns (e.g. {@link BuiltInTools.Isolated}).
34
+ */
35
+ addBuiltIn(names: readonly string[]): ToolSet;
36
+ /**
37
+ * Adds a custom tool pattern. Matches tools registered via the SDK's
38
+ * `tools` option or via custom agents.
39
+ *
40
+ * @param name A specific custom tool name or `"*"` to match all custom tools.
41
+ */
42
+ addCustom(name: string): ToolSet;
43
+ /**
44
+ * Adds an MCP tool pattern. Matches tools advertised by any configured
45
+ * MCP server.
46
+ *
47
+ * @param toolName The runtime's canonical wire name for the MCP tool
48
+ * (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
49
+ * any server.
50
+ */
51
+ addMcp(toolName: string): ToolSet;
52
+ /**
53
+ * Returns a defensive copy of the accumulated filter strings, suitable for
54
+ * passing as {@link SessionConfigBase.availableTools}.
55
+ */
56
+ toArray(): string[];
57
+ }
58
+ /**
59
+ * Curated sets of built-in tool names for common scenarios. Each constant is
60
+ * meant to be passed to {@link ToolSet.addBuiltIn}.
61
+ */
62
+ export declare const BuiltInTools: {
63
+ /**
64
+ * Built-in tools that operate only within the bounds of a single session —
65
+ * no host filesystem access outside the session, no cross-session state,
66
+ * no host environment access, no network. Safe to enable in `Mode = "empty"`
67
+ * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
68
+ *
69
+ * **Contract:** tools in this set MUST NOT be extended (even behind options
70
+ * or args) to read or write state outside the session boundary. Adding
71
+ * cross-session or host-state behavior to one of these tools is a
72
+ * breaking change that requires removing it from this set.
73
+ */
74
+ readonly Isolated: readonly string[];
75
+ };
@@ -0,0 +1,82 @@
1
+ const VALID_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
2
+ function validateName(kind, name) {
3
+ if (name === "*") {
4
+ return;
5
+ }
6
+ if (!VALID_TOOL_NAME.test(name)) {
7
+ throw new Error(
8
+ `Invalid ${kind} tool name '${name}': tool names must match /^[a-zA-Z0-9_-]+$/ or be the wildcard '*'.`
9
+ );
10
+ }
11
+ }
12
+ class ToolSet {
13
+ items = [];
14
+ addBuiltIn(nameOrNames) {
15
+ const names = typeof nameOrNames === "string" ? [nameOrNames] : nameOrNames;
16
+ for (const name of names) {
17
+ validateName("builtin", name);
18
+ this.items.push(`builtin:${name}`);
19
+ }
20
+ return this;
21
+ }
22
+ /**
23
+ * Adds a custom tool pattern. Matches tools registered via the SDK's
24
+ * `tools` option or via custom agents.
25
+ *
26
+ * @param name A specific custom tool name or `"*"` to match all custom tools.
27
+ */
28
+ addCustom(name) {
29
+ validateName("custom", name);
30
+ this.items.push(`custom:${name}`);
31
+ return this;
32
+ }
33
+ /**
34
+ * Adds an MCP tool pattern. Matches tools advertised by any configured
35
+ * MCP server.
36
+ *
37
+ * @param toolName The runtime's canonical wire name for the MCP tool
38
+ * (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
39
+ * any server.
40
+ */
41
+ addMcp(toolName) {
42
+ validateName("mcp", toolName);
43
+ this.items.push(`mcp:${toolName}`);
44
+ return this;
45
+ }
46
+ /**
47
+ * Returns a defensive copy of the accumulated filter strings, suitable for
48
+ * passing as {@link SessionConfigBase.availableTools}.
49
+ */
50
+ toArray() {
51
+ return [...this.items];
52
+ }
53
+ }
54
+ const BuiltInTools = {
55
+ /**
56
+ * Built-in tools that operate only within the bounds of a single session —
57
+ * no host filesystem access outside the session, no cross-session state,
58
+ * no host environment access, no network. Safe to enable in `Mode = "empty"`
59
+ * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
60
+ *
61
+ * **Contract:** tools in this set MUST NOT be extended (even behind options
62
+ * or args) to read or write state outside the session boundary. Adding
63
+ * cross-session or host-state behavior to one of these tools is a
64
+ * breaking change that requires removing it from this set.
65
+ */
66
+ Isolated: [
67
+ "ask_user",
68
+ "task_complete",
69
+ "exit_plan_mode",
70
+ "task",
71
+ "read_agent",
72
+ "write_agent",
73
+ "list_agents",
74
+ "send_inbox",
75
+ "context_board",
76
+ "skill"
77
+ ]
78
+ };
79
+ export {
80
+ BuiltInTools,
81
+ ToolSet
82
+ };