@withgateway/sdk 0.4.0 → 0.9.1

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 (157) hide show
  1. package/dist/agents/index.d.mts +573 -0
  2. package/dist/agents/index.d.ts +573 -0
  3. package/dist/agents/index.js +1443 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1394 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +5655 -1890
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5769 -2005
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +418 -120
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +418 -120
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
  24. package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +2862 -438
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2820 -431
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/replay/index.d.mts +1 -1
  34. package/dist/replay/index.d.ts +1 -1
  35. package/dist/replay/index.js.map +1 -1
  36. package/dist/replay/index.mjs.map +1 -1
  37. package/dist/traces/index.d.mts +3 -1
  38. package/dist/traces/index.d.ts +3 -1
  39. package/dist/traces/index.js +418 -120
  40. package/dist/traces/index.js.map +1 -1
  41. package/dist/traces/index.mjs +418 -120
  42. package/dist/traces/index.mjs.map +1 -1
  43. package/dist/tracing/index.d.mts +3 -2
  44. package/dist/tracing/index.d.ts +3 -2
  45. package/dist/tracing/index.js +257 -16
  46. package/dist/tracing/index.js.map +1 -1
  47. package/dist/tracing/index.mjs +257 -16
  48. package/dist/tracing/index.mjs.map +1 -1
  49. package/dist/transport-CpRe7zgd.d.mts +123 -0
  50. package/dist/transport-CpRe7zgd.d.ts +123 -0
  51. package/dist/worlds/index.d.mts +2086 -1749
  52. package/dist/worlds/index.d.ts +2086 -1749
  53. package/dist/worlds/index.js +1471 -269
  54. package/dist/worlds/index.js.map +1 -1
  55. package/dist/worlds/index.mjs +1466 -265
  56. package/dist/worlds/index.mjs.map +1 -1
  57. package/package.json +6 -1
  58. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  59. package/runtime/gatewaysdk/environment/_world.py +24 -1
  60. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  61. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  62. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  63. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  64. package/runtime/gatewaysdk/environment/schema/api.py +27 -7
  65. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  66. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
  67. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  68. package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
  69. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  70. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  71. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  72. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  74. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  75. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  76. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  77. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  81. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  82. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  83. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  84. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  86. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  87. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  88. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  89. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  90. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  91. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  92. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  93. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  94. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  95. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  96. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  97. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  98. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  99. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  100. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  101. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  102. package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
  103. package/runtime/gatewaysdk/environment/schema/local.py +33 -7
  104. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  105. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  106. package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
  107. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  108. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  109. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  110. package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
  111. package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
  112. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  113. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  114. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  115. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
  116. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
  117. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  118. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  119. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
  120. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  121. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  122. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  123. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  124. package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
  125. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  126. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  127. package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
  128. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  129. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  130. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  131. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  132. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  133. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  134. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  135. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  136. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  137. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  138. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  139. package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
  140. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  141. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  142. package/runtime/gatewaysdk/environment/world.py +34 -43
  143. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  144. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  145. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  146. package/skills/connector-schema-authoring/SKILL.md +20 -24
  147. package/skills/connector-schema-authoring/connector-worlds.md +155 -13
  148. package/skills/connector-schema-authoring/world-schema.md +36 -29
  149. package/skills/world-data-ingestion/SKILL.md +11 -11
  150. package/skills/worlds-getting-started/SKILL.md +9 -9
  151. package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  152. package/skills/worlds-getting-started/references/gotchas.md +40 -9
  153. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  154. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  155. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  156. package/dist/media-BIApiPzS.d.mts +0 -102
  157. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -0,0 +1,573 @@
1
+ import { A as ApiError } from '../apiError-DHpfbmdx.js';
2
+ import { P as PlatformTransport, e as PlatformMethod } from '../transport-CpRe7zgd.js';
3
+ export { U as UnreachableError } from '../transport-CpRe7zgd.js';
4
+
5
+ /** The models an agent may run on; the platform's default is `claude-opus-5`. Pinned to `gatewaysdk/fixtures/agents/definition-catalogue.json`. */
6
+ declare const AGENT_MODELS: readonly ["claude-opus-5", "claude-sonnet-5"];
7
+ type AgentModel = (typeof AGENT_MODELS)[number];
8
+ declare const AGENT_EFFORTS: readonly ["low", "medium", "high", "xhigh"];
9
+ type AgentEffort = (typeof AGENT_EFFORTS)[number];
10
+ /** The tool servers a definition may grant, each with the tool names `only` may name. Pinned to `definition-catalogue.json`. */
11
+ declare const TOOL_SERVERS: {
12
+ readonly docs: readonly ["search_docs"];
13
+ readonly drive: readonly ["get_drive_file", "list_drive_files", "save_drive_file"];
14
+ readonly sandbox: readonly ["copy_file", "execute_python", "grep_files", "ingest_sessions_to_sandbox", "list_files", "query_json", "read_file", "run_bash", "run_gateway_cli", "write_file"];
15
+ readonly web: readonly ["download_url_to_drive", "fetch_url"];
16
+ };
17
+ type ToolServer = keyof typeof TOOL_SERVERS;
18
+ type ToolName<S extends ToolServer> = (typeof TOOL_SERVERS)[S][number];
19
+ /** One server granted to an agent: all of its tools, or `only` the ones named. */
20
+ type TypedGrant<S extends ToolServer = ToolServer> = {
21
+ readonly server: S;
22
+ readonly only?: readonly ToolName<S>[];
23
+ };
24
+ /** A tool as a definition or `agent.tools.attach` takes it: a server name, or a typed grant from `tools`. */
25
+ type AgentToolInput = ToolServer | TypedGrant;
26
+ /** Typed tool grants: `tools.web()` is the whole server, `tools.sandbox({ only: ["run_gateway_cli"] })` one tool of it. */
27
+ declare const tools: Readonly<{
28
+ sandbox: (options?: {
29
+ only?: readonly ("copy_file" | "execute_python" | "grep_files" | "ingest_sessions_to_sandbox" | "list_files" | "query_json" | "read_file" | "run_bash" | "run_gateway_cli" | "write_file")[] | undefined;
30
+ }) => TypedGrant<"sandbox">;
31
+ drive: (options?: {
32
+ only?: readonly ("get_drive_file" | "list_drive_files" | "save_drive_file")[] | undefined;
33
+ }) => TypedGrant<"drive">;
34
+ web: (options?: {
35
+ only?: readonly ("download_url_to_drive" | "fetch_url")[] | undefined;
36
+ }) => TypedGrant<"web">;
37
+ docs: (options?: {
38
+ only?: readonly "search_docs"[] | undefined;
39
+ }) => TypedGrant<"docs">;
40
+ }>;
41
+
42
+ type RunStatus = "queued" | "running" | "requires_action" | "completed" | "failed" | "cancelled";
43
+ /** What a waiting run needs from a person: an answer to `question` (or one of `options`), or an approval of `toolName`, before `expiresAt`. */
44
+ type RunAction = {
45
+ id: string;
46
+ kind: "question" | "approval";
47
+ toolName: string;
48
+ question: string | null;
49
+ options: string[] | null;
50
+ expiresAt: string;
51
+ };
52
+ /** `not_found` ends the events of a run that no longer exists (a new request for it answers 404). */
53
+ type RunErrorCode = "run_failed" | "runtime_lost" | "never_started" | "key_revoked" | "model_key_invalid" | "not_found";
54
+ /** Why a run failed: a stable `code` to act on, and fixed text (the stored error stays on the server). */
55
+ type RunError = {
56
+ code: RunErrorCode;
57
+ message: string;
58
+ };
59
+ /** A run of a thread, as `GET /api/public/threads/{threadId}/runs/{runId}` answers it; `output` is the run's final assistant message. */
60
+ type Run = {
61
+ id: string;
62
+ threadId: string;
63
+ status: RunStatus;
64
+ agent: {
65
+ name: string;
66
+ versionId: string;
67
+ buildHash: string | null;
68
+ };
69
+ trigger: "api";
70
+ createdAt: string;
71
+ startedAt: string | null;
72
+ completedAt: string | null;
73
+ action: RunAction | null;
74
+ error: RunError | null;
75
+ output: string | null;
76
+ };
77
+ /** What a thread lets its runs do without asking; every flag defaults off on the platform. */
78
+ type ThreadAutonomy = {
79
+ provisionWorlds?: boolean;
80
+ maxWorlds?: number;
81
+ maxConcurrentWorldSessions?: number;
82
+ allowBilledRuns?: boolean;
83
+ allowConnectorWrites?: boolean;
84
+ allowSelfSchedule?: boolean;
85
+ allowSubagents?: boolean;
86
+ maxSubagents?: number;
87
+ };
88
+ /** A granted tool the key's capabilities cannot activate: the thread is created, and that tool stays off. */
89
+ type ThreadWarning = {
90
+ code: "grant_not_held";
91
+ tool: string;
92
+ needs: string[];
93
+ };
94
+ /** A thread as the thread doors answer it; `warnings` only on create. */
95
+ type ThreadRecord = {
96
+ id: string;
97
+ agent: string;
98
+ title: string | null;
99
+ autonomy: Required<ThreadAutonomy>;
100
+ activeRun: {
101
+ id: string;
102
+ status: RunStatus;
103
+ } | null;
104
+ createdAt: string;
105
+ warnings?: ThreadWarning[];
106
+ };
107
+ type EventOf<T extends string, Fields = object> = {
108
+ type: T;
109
+ runId: string;
110
+ threadId: string;
111
+ } & Fields;
112
+ /**
113
+ * One event of a run's stream. `step.attempt` means the run started over in a new attempt: drop any text of the earlier
114
+ * attempt still open. `run.error`'s `message` is the platform's fixed text for its `errorType`, never the raw error. The
115
+ * stream ends at `run.completed`, `run.failed` or `run.cancelled`, and at `action.required` while the run waits.
116
+ */
117
+ type RunEvent = EventOf<"run.started", {
118
+ attempt: number;
119
+ }> | EventOf<"step.attempt", {
120
+ attempt: number;
121
+ }> | EventOf<"message.delta", {
122
+ text: string;
123
+ }> | EventOf<"step.completed"> | EventOf<"tool.started", {
124
+ toolCallId: string | null;
125
+ toolName: string | null;
126
+ input: unknown;
127
+ }> | EventOf<"tool.completed", {
128
+ toolCallId: string | null;
129
+ isError: boolean;
130
+ output: string;
131
+ truncated: boolean;
132
+ }> | EventOf<"run.error", {
133
+ message: string;
134
+ errorType: string | null;
135
+ hint: string | null;
136
+ }> | EventOf<"action.required", {
137
+ action: RunAction;
138
+ }> | EventOf<"run.completed", {
139
+ status: "completed";
140
+ output: string | null;
141
+ }> | EventOf<"run.failed", {
142
+ status: "failed";
143
+ error: RunError;
144
+ }> | EventOf<"run.cancelled", {
145
+ status: "cancelled";
146
+ }>;
147
+ type RunEventType = RunEvent["type"];
148
+ /** The JSON `defineAgent` produces and `agents.push` sends; the platform derives its `buildHash` from exactly this. */
149
+ type AgentDefinitionSpec = {
150
+ name: string;
151
+ instructions: string;
152
+ model: string;
153
+ effort?: AgentEffort;
154
+ maxTurns: number;
155
+ tools: ToolGrant[];
156
+ };
157
+ /** One tool server granted to an agent: all of its tools, or only the ones named. */
158
+ type ToolGrant = {
159
+ server: string;
160
+ only?: string[];
161
+ };
162
+ /** Who pushed a version, when the caller knows (a CI job, a commit). */
163
+ type AgentAttribution = {
164
+ source?: "runtime" | "ci" | "platform";
165
+ githubLogin?: string;
166
+ authorEmail?: string;
167
+ commitSha?: string;
168
+ prNumber?: number;
169
+ prUrl?: string;
170
+ repo?: string;
171
+ branch?: string;
172
+ };
173
+ /** A pushed definition: an immutable version of an agent, identified by `id` and by the platform's `buildHash`. */
174
+ type AgentVersion = {
175
+ id: string;
176
+ agent: string;
177
+ buildHash: string;
178
+ kind: "defined";
179
+ labels: string[];
180
+ deployed: boolean;
181
+ created: boolean;
182
+ changes: unknown | null;
183
+ createdAt: string;
184
+ };
185
+ /** One build of an agent as `GET /api/public/agent-builds?agentId=` lists it, newest first. */
186
+ type AgentBuildRecord = {
187
+ id: string;
188
+ agentId: string;
189
+ buildHash: string;
190
+ kind: "observed" | "defined";
191
+ semanticVer: string | null;
192
+ manifest: Record<string, unknown>;
193
+ state: string;
194
+ attribution: Record<string, unknown>;
195
+ labels: string[];
196
+ createdAt: string;
197
+ };
198
+ /** A move of the `production` label to `versionId`: the build hash it was on (null when none) and the one it is on now. */
199
+ type AgentDeployment = {
200
+ agentId: string;
201
+ label: string;
202
+ versionId: string;
203
+ fromBuildHash: string | null;
204
+ toBuildHash: string;
205
+ };
206
+ /** A live agent as the platform answers it: the version edits apply to (the one `production` runs, else the newest). */
207
+ type LiveAgentRecord = {
208
+ name: string;
209
+ versionId: string;
210
+ version: number;
211
+ buildHash: string;
212
+ deployed: boolean;
213
+ definition: AgentDefinitionSpec;
214
+ };
215
+ /** What one edit made: the version it wrote or found, whether anything changed, and its changes against the version it edited. */
216
+ type AgentEditResult = LiveAgentRecord & {
217
+ changed: boolean;
218
+ created: boolean;
219
+ changes: unknown | null;
220
+ };
221
+ /** One version in an agent's history, newest first; `changes` is against the version before it. */
222
+ type AgentVersionEntry = {
223
+ id: string;
224
+ version: number;
225
+ buildHash: string;
226
+ isDeployed: boolean;
227
+ definition: AgentDefinitionSpec;
228
+ changes: unknown | null;
229
+ createdAt: string;
230
+ };
231
+
232
+ type Path = (string | number)[];
233
+ type AgentDefinitionIssueCode = "invalid_type" | "invalid_name" | "too_small" | "too_large" | "unknown_field" | "duplicate_tool_server" | "duplicate_tool";
234
+ /** One broken rule of a definition: where (`path` into the normalized definition), which rule (`code`), and why. */
235
+ type AgentDefinitionIssue = {
236
+ path: Path;
237
+ code: AgentDefinitionIssueCode;
238
+ message: string;
239
+ };
240
+ /** What `defineAgent` and `agents.create` take. A tool is a server name (`"sandbox"`: all of its tools) or a grant from `tools` (`tools.web({ only: ["fetch_url"] })`). */
241
+ type AgentDefinitionInput = {
242
+ name: string;
243
+ instructions: string;
244
+ model?: AgentModel;
245
+ effort?: AgentEffort;
246
+ maxTurns?: number;
247
+ tools?: readonly AgentToolInput[];
248
+ };
249
+ /** A definition `defineAgent` refused before anything was sent: every broken rule, each with its path and code. The platform checks the rest (model, effort, tool servers and names). */
250
+ declare class AgentDefinitionError extends Error {
251
+ readonly issues: readonly AgentDefinitionIssue[];
252
+ constructor(issues: readonly AgentDefinitionIssue[]);
253
+ }
254
+ type FrozenGrant = {
255
+ readonly server: string;
256
+ readonly only?: readonly string[];
257
+ };
258
+ /** An agent as code: frozen and normalized, so the JSON it sends is the JSON the platform hashes into the version's `buildHash`. */
259
+ declare class AgentDefinition {
260
+ readonly name: string;
261
+ readonly instructions: string;
262
+ readonly model: string;
263
+ readonly effort: AgentEffort | undefined;
264
+ readonly maxTurns: number;
265
+ readonly tools: readonly FrozenGrant[];
266
+ private constructor();
267
+ /** Validate and normalize any value (a parsed JSON file included); throws `AgentDefinitionError` listing every broken rule. */
268
+ static from(input: unknown): AgentDefinition;
269
+ /** The normalized definition: defaults filled, tool shorthands expanded, `only` sorted, `effort` present only when set. */
270
+ toJSON(): AgentDefinitionSpec;
271
+ }
272
+ /** Define an agent: `model` defaults to `claude-opus-5`, `maxTurns` to 50 (1–200), `tools` to none. */
273
+ declare function defineAgent(input: AgentDefinitionInput): AgentDefinition;
274
+
275
+ /** The fields `agent.update` changes; `effort: null` removes the effort. The name is the agent's identity and never changes. */
276
+ type AgentUpdate = {
277
+ instructions?: string;
278
+ model?: AgentModel;
279
+ effort?: AgentEffort | null;
280
+ maxTurns?: number;
281
+ };
282
+ type AgentPatchJSON = {
283
+ set?: Record<string, unknown>;
284
+ attach?: ToolGrant[];
285
+ detach?: string[];
286
+ };
287
+ /**
288
+ * One edit of a live agent as the platform takes it (`patch` of `POST …/definitions/{name}/versions`). The platform
289
+ * applies it to the version `production` runs and validates the result; the SDK only shapes it. Pinned to
290
+ * `gatewaysdk/fixtures/agents/patch-vectors.json`.
291
+ */
292
+ declare class AgentPatch {
293
+ private readonly json;
294
+ private constructor();
295
+ static update(fields: AgentUpdate): AgentPatch;
296
+ static attach(grants: AgentToolInput | readonly AgentToolInput[]): AgentPatch;
297
+ static detach(servers: string | readonly string[]): AgentPatch;
298
+ toJSON(): AgentPatchJSON;
299
+ }
300
+
301
+ /** The time an `AgentRun` reads and waits on; tests pass a fake. */
302
+ interface RunClock {
303
+ now(): number;
304
+ sleep(ms: number, signal?: AbortSignal): Promise<void>;
305
+ }
306
+ declare const SYSTEM_CLOCK: RunClock;
307
+ /** How `events()` gets back onto a run's stream: one wait per reconnect in a row (so their count is the limit), and how long a connection may stay silent. */
308
+ declare class ReconnectPolicy {
309
+ readonly delaysMs: readonly number[];
310
+ readonly idleMs: number;
311
+ static readonly DEFAULT: ReconnectPolicy;
312
+ constructor(delaysMs: readonly number[], idleMs: number);
313
+ }
314
+ type AgentRunOptions = {
315
+ clock?: RunClock;
316
+ reconnect?: ReconnectPolicy;
317
+ };
318
+ type RunEventsOptions = {
319
+ after?: string | null;
320
+ signal?: AbortSignal;
321
+ };
322
+ type RequestOptions = {
323
+ signal?: AbortSignal;
324
+ };
325
+ /** One run of a thread: its events as they happen, resumed across dropped connections from the last event delivered, and the run's state. */
326
+ declare class AgentRun {
327
+ #private;
328
+ constructor(transport: PlatformTransport, run: Run, options?: AgentRunOptions);
329
+ get id(): string;
330
+ get threadId(): string;
331
+ /** The run as last read from the platform. */
332
+ get snapshot(): Run;
333
+ /** The id of the last event delivered by any reader; pass it as `after` to resume this run's events elsewhere. */
334
+ get cursor(): string | null;
335
+ /**
336
+ * The run's events from `after` (default: where the last `events()` stopped, else the start). A dropped connection, a
337
+ * silence past the idle budget (60 s), a 502/503/504, a 429 `too_many_streams` or the platform closing the stream
338
+ * reconnects with `Last-Event-ID`,
339
+ * so each event arrives once; after 5 reconnects in a row with no event delivered (a clean close after at least the idle
340
+ * budget also counts as working) it throws `EventStreamError`. Ends after `run.completed`, `run.failed` (`not_found` when
341
+ * the run no longer exists) or `run.cancelled`, and at an `action.required` the platform ends the stream on (the run waits
342
+ * for a person); an `action.required` followed by more events was a wait already answered, and the events go on. A key
343
+ * holds at most 64 open streams: past that the platform answers 429 `too_many_streams`, which counts against the same
344
+ * five reconnects.
345
+ */
346
+ events(options?: RunEventsOptions): AsyncGenerator<RunEvent, void, undefined>;
347
+ /** The run once it has finished, or once it waits for a person (`status: "requires_action"` with its `action`). Throws `EventStreamError` `run_not_finished` when the stream ended the run and the platform still reads it as active after the reconnect delays, and the platform's 404 `ApiError` (`not_found`) for a run that no longer exists. */
348
+ wait(options?: RequestOptions): Promise<Run>;
349
+ /** The run as the platform reads it now; a gateway 5xx or a dropped connection is retried with the first reconnect delays. `signal` aborts the request and its retry waits. */
350
+ refresh(options?: RequestOptions): Promise<Run>;
351
+ /** Stop the run; a run already finished answers with its status. */
352
+ cancel(options?: RequestOptions): Promise<Run>;
353
+ /** Answer the question the run waits on; the run is queued again and `events()` continues from where it stopped. */
354
+ resolve(answer: {
355
+ actionId: string;
356
+ answer: string;
357
+ }, options?: RequestOptions): Promise<Run>;
358
+ private settled;
359
+ private advance;
360
+ private pause;
361
+ private take;
362
+ private connect;
363
+ private open;
364
+ private accepted;
365
+ private read;
366
+ private moveTo;
367
+ private note;
368
+ }
369
+
370
+ /** `agent` is an agent's name, or the `Agent` that `agents.create` / `agents.get` returned. */
371
+ type CreateThreadOptions = {
372
+ agent: string | {
373
+ readonly name: string;
374
+ };
375
+ title?: string;
376
+ autonomy?: ThreadAutonomy;
377
+ };
378
+ type SendOptions = {
379
+ version?: string;
380
+ multitask?: "reject";
381
+ };
382
+ /** A conversation with a deployed agent, owned by the project of the key that created it. */
383
+ declare class Thread {
384
+ #private;
385
+ readonly id: string;
386
+ readonly agent: string;
387
+ readonly title: string | null;
388
+ readonly autonomy: Readonly<Required<ThreadAutonomy>>;
389
+ readonly activeRun: Readonly<{
390
+ id: string;
391
+ status: RunStatus;
392
+ }> | null;
393
+ readonly createdAt: string;
394
+ /** Granted tools this key cannot activate; only on the thread `create` returns. */
395
+ readonly warnings: readonly ThreadWarning[];
396
+ constructor(transport: PlatformTransport, record: ThreadRecord, runs?: AgentRunOptions);
397
+ /** Start a run on the agent's deployed version (or `version`); refused with 409 `thread_busy` while another run is active. */
398
+ send(input: string, options?: SendOptions): Promise<AgentRun>;
399
+ /** A run of this thread by id, as it is now. */
400
+ run(runId: string): Promise<AgentRun>;
401
+ }
402
+ /** The project's threads: create one per conversation with a deployed agent, or open one by id. */
403
+ declare class Threads {
404
+ #private;
405
+ constructor(transport: PlatformTransport, runs?: AgentRunOptions);
406
+ /** A thread for a deployed agent; `allowSelfSchedule` or `allowSubagents` set to `true` is refused (400 `autonomy_unsupported`). */
407
+ create(options: CreateThreadOptions): Promise<Thread>;
408
+ get(threadId: string): Promise<Thread>;
409
+ }
410
+
411
+ type PushOptions = {
412
+ attribution?: AgentAttribution;
413
+ deploy?: boolean;
414
+ };
415
+ /** `deploy` named a version that is not one of that agent's; no label moved. */
416
+ declare class AgentVersionNotFoundError extends Error {
417
+ readonly agent: string;
418
+ readonly versionId: string;
419
+ readonly code = "version_not_found";
420
+ constructor(agent: string, versionId: string);
421
+ }
422
+ /** The project's defined agents: create one live and edit it in place, or push a definition from code and deploy a version of it. */
423
+ declare class Agents {
424
+ #private;
425
+ constructor(transport: PlatformTransport, threads: Threads);
426
+ /** Create an agent, live in one call: version 1, deployed. A definition `defineAgent` would refuse throws `AgentDefinitionError` before anything is sent; a name the project already holds is 409 `agent_exists`. */
427
+ create(input: AgentDefinitionInput): Promise<Agent>;
428
+ /** The live agent named `name`, to edit or run; 404 `agent_not_found` when the project has none. */
429
+ get(name: string): Promise<Agent>;
430
+ /** The version of `name` that edits apply to: the one `production` runs, else the newest. */
431
+ live(name: string): Promise<LiveAgentRecord>;
432
+ /** Apply one patch to `name` as a new version, live unless `deploy: false`. With `from`, a version that is no longer the live one is refused (`AgentVersionConflictError`) and nothing is written. */
433
+ edit(name: string, patch: AgentPatch, options?: EditOptions & {
434
+ from?: string;
435
+ }): Promise<AgentEditResult>;
436
+ /** Move `production` of `name` to one of its versions, with the audit row; `force` crosses a breaking tool change. */
437
+ rollback(name: string, versionId: string, options?: {
438
+ from?: string;
439
+ force?: boolean;
440
+ }): Promise<LiveAgentRecord>;
441
+ /** Every version of the live agent `name`, newest first, each with `isDeployed` and its changes against the one before; a version written while the pages are read never repeats one. */
442
+ history(name: string): Promise<AgentVersionEntry[]>;
443
+ /** Push a definition: a new version, or the identical one already pushed (`created: false`); the platform derives its `buildHash`. With `deploy`, `production` moves to it; when that move is refused the version still exists, and pushing again returns it. */
444
+ push(definition: AgentDefinition, options?: PushOptions): Promise<AgentVersion>;
445
+ /** Move `production` to `versionId`, after checking it is a defined version of `name` (an observed build of that name is not one). Rolling back is deploying an older version; `force` crosses a breaking tool change. */
446
+ deploy(name: string, versionId: string, options?: {
447
+ force?: boolean;
448
+ }): Promise<AgentDeployment>;
449
+ /** Every version of `name`, newest first. */
450
+ versions(name: string): Promise<AgentBuildRecord[]>;
451
+ private conflictAware;
452
+ private move;
453
+ }
454
+
455
+ /** An edit or rollback made from a version that is no longer the live one: nothing was written. `refresh()` the agent, then edit again. */
456
+ declare class AgentVersionConflictError extends ApiError {
457
+ readonly currentVersionId: string | null;
458
+ constructor(status: number, method: PlatformMethod, path: string, text: string);
459
+ }
460
+ /** `deploy` (default true) moves `production` to the version the edit writes; `false` stages it. */
461
+ type EditOptions = {
462
+ deploy?: boolean;
463
+ };
464
+ type AgentRunInput = Omit<CreateThreadOptions, "agent"> & {
465
+ version?: string;
466
+ };
467
+ /** The agent's tools: each attach or detach is a new version, live unless `deploy: false`. */
468
+ declare class AgentTools {
469
+ private readonly agent;
470
+ constructor(agent: Agent);
471
+ /** Grant servers: one already attached keeps its place and takes the new grant. */
472
+ attach(grants: AgentToolInput | readonly AgentToolInput[], options?: EditOptions): Promise<AgentEditResult>;
473
+ /** Remove servers; one that is not attached changes nothing. */
474
+ detach(servers: string | readonly string[], options?: EditOptions): Promise<AgentEditResult>;
475
+ }
476
+ /** Threads with this agent. */
477
+ declare class AgentThreads {
478
+ private readonly threads;
479
+ private readonly name;
480
+ constructor(threads: Threads, name: string);
481
+ create(options?: Omit<CreateThreadOptions, "agent">): Promise<Thread>;
482
+ }
483
+ /**
484
+ * A live agent: every change is a call on it, and each one is an immutable version the platform keeps. An edit carries
485
+ * the version this handle holds, so a change someone else made in between is refused (`AgentVersionConflictError`)
486
+ * rather than overwritten. A run keeps the version it was sent on.
487
+ */
488
+ declare class Agent {
489
+ #private;
490
+ readonly tools: AgentTools;
491
+ readonly threads: AgentThreads;
492
+ constructor(agents: Agents, record: LiveAgentRecord, threads: Threads);
493
+ get name(): string;
494
+ /** The version edits apply to: the one `production` runs (else, never deployed, the newest). */
495
+ get versionId(): string;
496
+ get version(): number;
497
+ get buildHash(): string;
498
+ get deployed(): boolean;
499
+ get definition(): Readonly<AgentDefinitionSpec>;
500
+ /** Change fields: a new version, live unless `deploy: false`; a change to the values it already has writes nothing. */
501
+ update(fields: AgentUpdate, options?: EditOptions): Promise<AgentEditResult>;
502
+ /** Apply one patch made of `AgentPatch.update`, `.attach` or `.detach`. */
503
+ edit(patch: AgentPatch, options?: EditOptions): Promise<AgentEditResult>;
504
+ /** Move `production` to one of this agent's versions (an earlier one, or one staged with `deploy: false`); `force` crosses a breaking tool change. */
505
+ rollback(versionId: string, options?: {
506
+ force?: boolean;
507
+ }): Promise<LiveAgentRecord>;
508
+ /** Every version, newest first, with whether it is live and its changes against the version before it. */
509
+ versions(): Promise<AgentVersionEntry[]>;
510
+ /** Read the live version again, after a conflict or someone else's change. */
511
+ refresh(): Promise<this>;
512
+ /** Start a thread with this agent and send it `input`: the run uses the version `production` runs now (or `version`). */
513
+ run(input: string, options?: AgentRunInput): Promise<AgentRun>;
514
+ toJSON(): LiveAgentRecord;
515
+ }
516
+
517
+ type GatewayOptions = {
518
+ host?: string;
519
+ publicKey?: string;
520
+ secretKey?: string;
521
+ transport?: PlatformTransport;
522
+ } & AgentRunOptions;
523
+ /**
524
+ * One project's agent primitives, authenticated by its secret key: `agents` (create and edit live agents, or push and deploy definitions) and `threads`
525
+ * (talk to a deployed agent). Keys come from the options, else `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
526
+ * `GATEWAY_SECRET_KEY`; they are never printed, logged or serialized.
527
+ */
528
+ declare class Gateway {
529
+ readonly agents: Agents;
530
+ readonly threads: Threads;
531
+ constructor(options?: GatewayOptions);
532
+ }
533
+
534
+ /** A dispatched server-sent event: its name (`message` when the server named none), its data lines joined by `\n`, and the stream's last event id at that point. */
535
+ type SseMessage = {
536
+ event: string;
537
+ data: string;
538
+ lastEventId: string | null;
539
+ };
540
+ type EventStreamErrorCode = "line_too_large" | "event_too_large" | "malformed_event" | "reconnects_exhausted" | "run_not_finished";
541
+ /** A run's event stream that cannot be read on: a line or an event past the parser's caps, an event that is not the run's JSON, too many reconnects in a row, or a run the stream ended that the platform still reads as active. Never retried. */
542
+ declare class EventStreamError extends Error {
543
+ readonly code: EventStreamErrorCode;
544
+ constructor(code: EventStreamErrorCode, message: string);
545
+ }
546
+ /** The parser's memory bound, in characters: one line, and one event's data lines together. */
547
+ declare class SseLimits {
548
+ readonly maxLineLength: number;
549
+ readonly maxEventLength: number;
550
+ static readonly DEFAULT: SseLimits;
551
+ constructor(maxLineLength: number, maxEventLength: number);
552
+ }
553
+ /**
554
+ * Server-sent events from bytes, as the WHATWG EventSource reads them: CRLF, LF or CR line ends (also split across
555
+ * chunks), comments ignored, `data` lines joined, `retry` ignored, the last event id kept across events. Lines and events
556
+ * past `SseLimits` throw `EventStreamError`, so a hostile stream cannot grow the buffer without bound.
557
+ */
558
+ declare class SseParser {
559
+ #private;
560
+ constructor(lastEventId?: string | null, limits?: SseLimits);
561
+ /** The id a reconnect sends as `Last-Event-ID`: the last one set before a dispatched event, or null. */
562
+ get lastEventId(): string | null;
563
+ /** Feed the next bytes; returns the events they completed, in order. */
564
+ push(chunk: Uint8Array): SseMessage[];
565
+ private lines;
566
+ private lineEnd;
567
+ private skipLineFeed;
568
+ private capped;
569
+ private line;
570
+ private dispatch;
571
+ }
572
+
573
+ export { AGENT_EFFORTS, AGENT_MODELS, Agent, type AgentAttribution, type AgentBuildRecord, AgentDefinition, AgentDefinitionError, type AgentDefinitionInput, type AgentDefinitionIssue, type AgentDefinitionIssueCode, type AgentDefinitionSpec, type AgentDeployment, type AgentEditResult, type AgentEffort, type AgentModel, AgentPatch, type AgentPatchJSON, AgentRun, type AgentRunInput, type AgentRunOptions, AgentThreads, type AgentToolInput, AgentTools, type AgentUpdate, type AgentVersion, AgentVersionConflictError, type AgentVersionEntry, AgentVersionNotFoundError, Agents, ApiError, type CreateThreadOptions, type EditOptions, EventStreamError, type EventStreamErrorCode, Gateway, type GatewayOptions, type LiveAgentRecord, PlatformTransport, type PushOptions, ReconnectPolicy, type RequestOptions, type Run, type RunAction, type RunClock, type RunError, type RunErrorCode, type RunEvent, type RunEventType, type RunEventsOptions, type RunStatus, SYSTEM_CLOCK, type SendOptions, SseLimits, type SseMessage, SseParser, TOOL_SERVERS, Thread, type ThreadAutonomy, type ThreadRecord, type ThreadWarning, Threads, type ToolGrant, type ToolName, type ToolServer, type TypedGrant, defineAgent, tools };