@finalai/agent-provider 0.8.0 → 0.10.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 (200) hide show
  1. package/HOSTING.md +334 -245
  2. package/README.md +93 -14
  3. package/dist/modules/canonical-json.d.mts +4 -0
  4. package/dist/modules/canonical-json.mjs +33 -0
  5. package/dist/modules/canonical-json.mjs.map +7 -0
  6. package/dist/modules/channel.d.mts +9 -3
  7. package/dist/modules/channel.mjs.map +2 -2
  8. package/dist/modules/code-host/host.d.mts +10 -0
  9. package/dist/modules/code-host/host.mjs +88 -0
  10. package/dist/modules/code-host/host.mjs.map +7 -0
  11. package/dist/modules/code-host/in-process.d.mts +24 -0
  12. package/dist/modules/code-host/in-process.mjs +89 -0
  13. package/dist/modules/code-host/in-process.mjs.map +7 -0
  14. package/dist/modules/code-host/index.d.mts +4 -0
  15. package/dist/modules/code-host/index.mjs +5 -0
  16. package/dist/modules/code-host/index.mjs.map +7 -0
  17. package/dist/modules/code-host/serverless.d.mts +63 -0
  18. package/dist/modules/code-host/serverless.mjs +27 -0
  19. package/dist/modules/code-host/serverless.mjs.map +7 -0
  20. package/dist/modules/code-host/types.d.mts +152 -0
  21. package/dist/modules/code-host/types.mjs +85 -0
  22. package/dist/modules/code-host/types.mjs.map +7 -0
  23. package/dist/modules/conformance/agent.mjs +72 -6
  24. package/dist/modules/conformance/agent.mjs.map +2 -2
  25. package/dist/modules/conformance/harness-kit.d.mts +9 -2
  26. package/dist/modules/conformance/harness-kit.mjs +224 -63
  27. package/dist/modules/conformance/harness-kit.mjs.map +3 -3
  28. package/dist/modules/conformance/local-harness.d.mts +1 -4
  29. package/dist/modules/conformance/local-harness.mjs +21 -22
  30. package/dist/modules/conformance/local-harness.mjs.map +2 -2
  31. package/dist/modules/conformance/protocol.d.mts +1 -0
  32. package/dist/modules/conformance/protocol.mjs +2 -0
  33. package/dist/modules/conformance/protocol.mjs.map +2 -2
  34. package/dist/modules/conformance/sandbox-kit.d.mts +12 -4
  35. package/dist/modules/conformance/sandbox-kit.mjs +189 -103
  36. package/dist/modules/conformance/sandbox-kit.mjs.map +2 -2
  37. package/dist/modules/conformance/scripted-model/chat-completions.mjs +1 -0
  38. package/dist/modules/conformance/scripted-model/chat-completions.mjs.map +2 -2
  39. package/dist/modules/conformance/scripted-model/directives.d.mts +3 -0
  40. package/dist/modules/conformance/scripted-model/directives.mjs +26 -10
  41. package/dist/modules/conformance/scripted-model/directives.mjs.map +2 -2
  42. package/dist/modules/conformance/scripted-model/messages.mjs +1 -0
  43. package/dist/modules/conformance/scripted-model/messages.mjs.map +2 -2
  44. package/dist/modules/conformance/scripted-model/responses.mjs +2 -0
  45. package/dist/modules/conformance/scripted-model/responses.mjs.map +2 -2
  46. package/dist/modules/conformance/stdio.d.mts +21 -0
  47. package/dist/modules/conformance/stdio.mjs +158 -0
  48. package/dist/modules/conformance/stdio.mjs.map +7 -0
  49. package/dist/modules/credential-routes.d.mts +2 -0
  50. package/dist/modules/credential-routes.mjs +2 -0
  51. package/dist/modules/credential-routes.mjs.map +2 -2
  52. package/dist/modules/document.d.mts +376 -0
  53. package/dist/modules/document.mjs +208 -0
  54. package/dist/modules/document.mjs.map +7 -0
  55. package/dist/modules/harness-configuration.d.mts +16 -0
  56. package/dist/modules/harness-configuration.mjs +83 -0
  57. package/dist/modules/harness-configuration.mjs.map +7 -0
  58. package/dist/modules/harness-definition.d.mts +280 -0
  59. package/dist/modules/harness-definition.mjs +430 -0
  60. package/dist/modules/harness-definition.mjs.map +7 -0
  61. package/dist/modules/harness-provider.d.mts +197 -0
  62. package/dist/modules/harness-provider.mjs +108 -0
  63. package/dist/modules/harness-provider.mjs.map +7 -0
  64. package/dist/modules/harness-requirements.d.mts +19 -0
  65. package/dist/modules/harness-requirements.mjs +40 -0
  66. package/dist/modules/harness-requirements.mjs.map +7 -0
  67. package/dist/modules/harness-start.d.mts +33 -0
  68. package/dist/modules/harness-start.mjs +107 -0
  69. package/dist/modules/harness-start.mjs.map +7 -0
  70. package/dist/modules/harness.d.mts +84 -109
  71. package/dist/modules/harness.mjs +56 -111
  72. package/dist/modules/harness.mjs.map +3 -3
  73. package/dist/modules/identity.d.mts +1 -0
  74. package/dist/modules/identity.mjs +2 -0
  75. package/dist/modules/identity.mjs.map +7 -0
  76. package/dist/modules/index.d.mts +12 -6
  77. package/dist/modules/index.mjs +12 -6
  78. package/dist/modules/index.mjs.map +2 -2
  79. package/dist/modules/inference.d.mts +35 -0
  80. package/dist/modules/inference.mjs +74 -0
  81. package/dist/modules/inference.mjs.map +7 -0
  82. package/dist/modules/local-channel-context.mjs +3 -1
  83. package/dist/modules/local-channel-context.mjs.map +2 -2
  84. package/dist/modules/requirements-check.d.mts +30 -0
  85. package/dist/modules/requirements-check.mjs +164 -0
  86. package/dist/modules/requirements-check.mjs.map +7 -0
  87. package/dist/modules/room-surface.d.mts +0 -5
  88. package/dist/modules/room-surface.mjs.map +2 -2
  89. package/dist/modules/sandbox/client.d.mts +3 -0
  90. package/dist/modules/sandbox/client.mjs +101 -18
  91. package/dist/modules/sandbox/client.mjs.map +2 -2
  92. package/dist/modules/sandbox/grant.d.mts +78 -0
  93. package/dist/modules/sandbox/grant.mjs +134 -0
  94. package/dist/modules/sandbox/grant.mjs.map +7 -0
  95. package/dist/modules/sandbox/index.d.mts +3 -3
  96. package/dist/modules/sandbox/index.mjs +4 -5
  97. package/dist/modules/sandbox/index.mjs.map +2 -2
  98. package/dist/modules/sandbox/mcp-hosted.d.mts +1 -1
  99. package/dist/modules/sandbox/mcp-hosted.mjs +4 -7
  100. package/dist/modules/sandbox/mcp-hosted.mjs.map +2 -2
  101. package/dist/modules/sandbox/mcp.d.mts +4 -2
  102. package/dist/modules/sandbox/mcp.mjs +14 -7
  103. package/dist/modules/sandbox/mcp.mjs.map +2 -2
  104. package/dist/modules/sandbox/memory-sandbox.d.mts +2 -1
  105. package/dist/modules/sandbox/memory-sandbox.mjs +71 -41
  106. package/dist/modules/sandbox/memory-sandbox.mjs.map +2 -2
  107. package/dist/modules/sandbox/networking.d.mts +7 -7
  108. package/dist/modules/sandbox/networking.mjs +16 -9
  109. package/dist/modules/sandbox/networking.mjs.map +2 -2
  110. package/dist/modules/sandbox/remote/adapter.d.mts +30 -0
  111. package/dist/modules/sandbox/remote/adapter.mjs +381 -0
  112. package/dist/modules/sandbox/remote/adapter.mjs.map +7 -0
  113. package/dist/modules/sandbox/remote/errors.d.mts +10 -0
  114. package/dist/modules/sandbox/remote/errors.mjs +62 -0
  115. package/dist/modules/sandbox/remote/errors.mjs.map +7 -0
  116. package/dist/modules/sandbox/remote/index.d.mts +5 -0
  117. package/dist/modules/sandbox/remote/index.mjs +6 -0
  118. package/dist/modules/sandbox/remote/index.mjs.map +7 -0
  119. package/dist/modules/sandbox/remote/ndjson.d.mts +6 -0
  120. package/dist/modules/sandbox/remote/ndjson.mjs +80 -0
  121. package/dist/modules/sandbox/remote/ndjson.mjs.map +7 -0
  122. package/dist/modules/sandbox/remote/platform-api.d.mts +8 -0
  123. package/dist/modules/sandbox/remote/platform-api.mjs +15 -0
  124. package/dist/modules/sandbox/remote/platform-api.mjs.map +7 -0
  125. package/dist/modules/sandbox/remote/preamble.d.mts +7 -0
  126. package/dist/modules/sandbox/remote/preamble.mjs +51 -0
  127. package/dist/modules/sandbox/remote/preamble.mjs.map +7 -0
  128. package/dist/modules/sandbox/remote/serve.d.mts +34 -0
  129. package/dist/modules/sandbox/remote/serve.mjs +519 -0
  130. package/dist/modules/sandbox/remote/serve.mjs.map +7 -0
  131. package/dist/modules/sandbox/remote/testing.d.mts +34 -0
  132. package/dist/modules/sandbox/remote/testing.mjs +275 -0
  133. package/dist/modules/sandbox/remote/testing.mjs.map +7 -0
  134. package/dist/modules/sandbox/seeds.d.mts +2 -2
  135. package/dist/modules/sandbox/seeds.mjs +2 -2
  136. package/dist/modules/sandbox/seeds.mjs.map +2 -2
  137. package/dist/modules/sandbox/server.d.mts +4 -6
  138. package/dist/modules/sandbox/server.mjs +93 -49
  139. package/dist/modules/sandbox/server.mjs.map +2 -2
  140. package/dist/modules/sandbox/setup/apply.d.mts +41 -0
  141. package/dist/modules/sandbox/setup/apply.mjs +204 -0
  142. package/dist/modules/sandbox/setup/apply.mjs.map +7 -0
  143. package/dist/modules/sandbox/setup/describe.d.mts +10 -0
  144. package/dist/modules/sandbox/setup/describe.mjs +62 -0
  145. package/dist/modules/sandbox/setup/describe.mjs.map +7 -0
  146. package/dist/modules/sandbox/setup/index.d.mts +6 -0
  147. package/dist/modules/sandbox/setup/index.mjs +17 -0
  148. package/dist/modules/sandbox/setup/index.mjs.map +7 -0
  149. package/dist/modules/sandbox/setup/paths.d.mts +8 -0
  150. package/dist/modules/sandbox/setup/paths.mjs +18 -0
  151. package/dist/modules/sandbox/setup/paths.mjs.map +7 -0
  152. package/dist/modules/sandbox/setup/schema.d.mts +42 -0
  153. package/dist/modules/sandbox/setup/schema.mjs +58 -0
  154. package/dist/modules/sandbox/setup/schema.mjs.map +7 -0
  155. package/dist/modules/sandbox/tool-policy.d.mts +1 -1
  156. package/dist/modules/sandbox/tool-policy.mjs +1 -1
  157. package/dist/modules/sandbox/tool-policy.mjs.map +2 -2
  158. package/dist/modules/sandbox/types.d.mts +117 -130
  159. package/dist/modules/sandbox/types.mjs +46 -50
  160. package/dist/modules/sandbox/types.mjs.map +3 -3
  161. package/dist/modules/sandbox/wire.d.mts +93 -6
  162. package/dist/modules/sandbox/wire.mjs +61 -38
  163. package/dist/modules/sandbox/wire.mjs.map +2 -2
  164. package/dist/modules/schemas.d.mts +5 -76
  165. package/dist/modules/schemas.mjs +18 -85
  166. package/dist/modules/schemas.mjs.map +2 -2
  167. package/dist/modules/tool-annotations.d.mts +15 -6
  168. package/dist/modules/tool-annotations.mjs +9 -3
  169. package/dist/modules/tool-annotations.mjs.map +2 -2
  170. package/dist/modules/tool-descriptor.d.mts +16 -0
  171. package/dist/modules/tool-descriptor.mjs +19 -0
  172. package/dist/modules/tool-descriptor.mjs.map +7 -0
  173. package/dist/modules/tool-patterns.d.mts +7 -7
  174. package/dist/modules/tool-patterns.mjs +10 -9
  175. package/dist/modules/tool-patterns.mjs.map +2 -2
  176. package/package.json +86 -36
  177. package/dist/modules/credentials.d.mts +0 -206
  178. package/dist/modules/credentials.mjs +0 -207
  179. package/dist/modules/credentials.mjs.map +0 -7
  180. package/dist/modules/dynamic.d.mts +0 -40
  181. package/dist/modules/dynamic.mjs +0 -79
  182. package/dist/modules/dynamic.mjs.map +0 -7
  183. package/dist/modules/hosted-bindings.d.mts +0 -15
  184. package/dist/modules/hosted-bindings.mjs +0 -21
  185. package/dist/modules/hosted-bindings.mjs.map +0 -7
  186. package/dist/modules/manifest.d.mts +0 -787
  187. package/dist/modules/manifest.mjs +0 -320
  188. package/dist/modules/manifest.mjs.map +0 -7
  189. package/dist/modules/provider-ref.d.mts +0 -29
  190. package/dist/modules/provider-ref.mjs +0 -55
  191. package/dist/modules/provider-ref.mjs.map +0 -7
  192. package/dist/modules/sandbox/open-scope-node.d.mts +0 -4
  193. package/dist/modules/sandbox/open-scope-node.mjs +0 -19
  194. package/dist/modules/sandbox/open-scope-node.mjs.map +0 -7
  195. package/dist/modules/sandbox/open-scope.d.mts +0 -16
  196. package/dist/modules/sandbox/open-scope.mjs +0 -66
  197. package/dist/modules/sandbox/open-scope.mjs.map +0 -7
  198. package/dist/modules/sandbox/workspace-identity.d.mts +0 -5
  199. package/dist/modules/sandbox/workspace-identity.mjs +0 -14
  200. package/dist/modules/sandbox/workspace-identity.mjs.map +0 -7
@@ -1,14 +1,15 @@
1
+ import { Capability, RuntimeKind, type CapabilityAccess } from '@finalai/agent-protocol';
2
+ import * as z from 'zod';
1
3
  import { SandboxEntryType } from "./file-kind.mjs";
2
4
  export { SandboxEntryType } from "./file-kind.mjs";
3
- import type { HostedBindingsIface } from "../hosted-bindings.mjs";
4
5
  import { type SandboxExecutionPolicyIface } from "./handle.mjs";
5
6
  import type { WorkspaceEgressRequestIface, WorkspaceEgressStatusIface, WorkspaceNetworkPolicyIface as NetworkPolicyIface } from '@finalai/agent-protocol/device-egress';
6
7
  export { WorkspaceNetworkPolicy as NetworkPolicy, type WorkspaceNetworkPolicyIface as NetworkPolicyIface, } from '@finalai/agent-protocol/device-egress';
7
8
  import type { ProcessInspectionRequestIface, ProcessInspectionResultIface } from '@finalai/agent-protocol/process-inspection';
8
9
  import type { JsonValue } from "../json.mjs";
9
- import type { ToolDescriptorIface } from "../manifest.mjs";
10
+ import type { ToolDescriptorIface } from "../tool-descriptor.mjs";
10
11
  import { type SandboxEditorRequestIface, type SandboxEditorResultIface } from "./editor.mjs";
11
- import { type AwaitableSandboxOpenRequestIface } from "./open-scope.mjs";
12
+ import type { SandboxSetupIface } from "./setup/schema.mjs";
12
13
  import type { SandboxSnapshotRequestIface, SandboxSnapshotResponseIface } from "./snapshots.mjs";
13
14
  export interface AbortableIface {
14
15
  abortSignal?: AbortSignal;
@@ -36,6 +37,32 @@ export interface SandboxProcessIface {
36
37
  }>;
37
38
  kill(signal?: string): Promise<void>;
38
39
  }
40
+ export interface SandboxWorkerOptionsIface extends AbortableIface {
41
+ program: string;
42
+ env?: Record<string, string>;
43
+ input?: JsonValue;
44
+ durable?: boolean;
45
+ identity?: string;
46
+ }
47
+ export declare enum SandboxWorkerEndpointTransport {
48
+ Ws = "ws",
49
+ Http = "http",
50
+ Relay = "relay"
51
+ }
52
+ export type SandboxWorkerEndpointType = {
53
+ transport: SandboxWorkerEndpointTransport.Ws | SandboxWorkerEndpointTransport.Http;
54
+ url: string;
55
+ headers: Record<string, string>;
56
+ } | {
57
+ transport: SandboxWorkerEndpointTransport.Relay;
58
+ channel: string;
59
+ token: string;
60
+ };
61
+ export interface SandboxWorkerEndpointIface {
62
+ readonly endpoint: SandboxWorkerEndpointType;
63
+ }
64
+ export type SandboxWorkerStartType = SandboxProcessIface | SandboxWorkerEndpointIface;
65
+ export declare const isSandboxWorkerEndpoint: (started: SandboxWorkerStartType) => started is SandboxWorkerEndpointIface;
39
66
  export interface SandboxAttachProcessOptionsIface extends AbortableIface {
40
67
  ref: string;
41
68
  stdoutOffset: number;
@@ -185,6 +212,7 @@ export interface NetworkSandboxSessionIface extends SandboxSessionIface {
185
212
  setNetworkPolicy?(policy: NetworkPolicyIface): Promise<void>;
186
213
  egress?(request: WorkspaceEgressRequestIface): Promise<WorkspaceEgressStatusIface>;
187
214
  computerUse?(): Promise<SandboxMcpEndpoint>;
215
+ startWorker?(options: SandboxWorkerOptionsIface): Promise<SandboxWorkerStartType>;
188
216
  screen?(options?: ScreenOptionsIface): Promise<ScreenSessionIface>;
189
217
  localMcp?(): Promise<SandboxMcpEndpoint[]>;
190
218
  }
@@ -198,8 +226,10 @@ export declare enum SandboxCapability {
198
226
  Screen = "screen",
199
227
  LocalMcp = "localMcp",
200
228
  Browser = "browser",
201
- DurableProcesses = "durableProcesses"
229
+ DurableProcesses = "durableProcesses",
230
+ Workers = "workers"
202
231
  }
232
+ export type SandboxCapabilityOffer = Partial<Record<Capability, CapabilityAccess>>;
203
233
  export interface SandboxProviderHandleIface<S extends SandboxSessionIface> {
204
234
  readonly sandbox: S;
205
235
  readonly executionPolicy?: SandboxExecutionPolicyIface;
@@ -209,29 +239,6 @@ export interface SandboxProviderHandleIface<S extends SandboxSessionIface> {
209
239
  }): Promise<void>;
210
240
  onRuntimeShutdown(): Promise<void>;
211
241
  }
212
- export interface SandboxGuideVersionIface {
213
- guideId: string;
214
- versionId: string;
215
- slug: string;
216
- title: string;
217
- number: number;
218
- image: string;
219
- templateConfig: JsonValue;
220
- defaultParameters: JsonValue;
221
- instructionsMarkdown: string | null;
222
- preparedArtifact?: {
223
- providerRef: string;
224
- key: string;
225
- artifact: JsonValue;
226
- };
227
- }
228
- export interface SandboxGuidesIface {
229
- get(args: {
230
- ref: string;
231
- version: number | 'latest';
232
- }): Promise<SandboxGuideVersionIface | null>;
233
- default(): Promise<SandboxGuideVersionIface | null>;
234
- }
235
242
  export interface SandboxRepositoryCloneSourceIface {
236
243
  url: string;
237
244
  ref: string | null;
@@ -243,47 +250,46 @@ export interface SandboxRepositoriesIface {
243
250
  ref: string | null;
244
251
  }): Promise<SandboxRepositoryCloneSourceIface | null>;
245
252
  }
246
- export interface SandboxVariablesIface {
247
- get(name: string): Promise<string | null>;
248
- }
249
- export declare const noSandboxGuides: SandboxGuidesIface;
250
253
  export declare const noSandboxRepositories: SandboxRepositoriesIface;
251
- export declare const noSandboxVariables: SandboxVariablesIface;
252
254
  export interface SandboxActingUserIface {
253
255
  current(): Promise<string | null>;
254
256
  }
255
257
  export declare const noSandboxActingUser: SandboxActingUserIface;
256
- export interface FinalPlatformAccessIface {
257
- baseUrl: string;
258
- token: string;
259
- }
260
258
  export interface SandboxCredentialsIface {
261
- computersAccess(args?: {
262
- refresh?: boolean;
263
- }): Promise<FinalPlatformAccessIface | null>;
264
- deviceAccess(args?: {
265
- actingUserId?: string | null;
266
- refresh?: boolean;
267
- }): Promise<FinalPlatformAccessIface | null>;
268
259
  secret(args: {
269
260
  secretRef: string;
270
261
  }): Promise<string | null>;
271
262
  }
272
263
  export declare const noSandboxCredentials: SandboxCredentialsIface;
273
- export interface SandboxOfferContextIface {
274
- executionPolicy?: SandboxExecutionPolicyIface;
275
- platformNetworkPolicy?: (policy: NetworkPolicyIface) => Promise<void>;
276
- platformEgressHosts?: string[];
277
- workspaceId?: string;
278
- bindings?: HostedBindingsIface;
264
+ export declare const sandboxCredentialRefSchema: z.ZodObject<{
265
+ secretRef: z.ZodString;
266
+ }, z.core.$strict>;
267
+ export type SandboxCredentialRefIface = z.infer<typeof sandboxCredentialRefSchema>;
268
+ export interface SandboxIdentityTokenIface {
269
+ token: string;
270
+ expiresAt: string;
271
+ }
272
+ export type SandboxIdentityFn = (args: {
273
+ audience: string;
274
+ refresh?: boolean;
275
+ }) => Promise<SandboxIdentityTokenIface>;
276
+ export declare const noSandboxIdentity: SandboxIdentityFn;
277
+ export interface SandboxProviderContextIface {
279
278
  organizationId: string;
280
- credentials?: SandboxCredentialsIface;
279
+ projectId: string;
280
+ credentials: SandboxCredentialsIface;
281
281
  actingUser: SandboxActingUserIface;
282
+ identity: SandboxIdentityFn;
283
+ log?: (message: string, fields?: Record<string, string | number | boolean | null>) => void;
282
284
  }
283
- export interface SandboxEnvironmentContextIface {
284
- bindings?: HostedBindingsIface;
285
- organizationId: string;
286
- guides: SandboxGuidesIface;
285
+ export interface SandboxLifecycleIface {
286
+ parkAfterIdleMs: number | null;
287
+ }
288
+ export interface SandboxOfferContextIface extends SandboxProviderContextIface {
289
+ sandboxId?: string;
290
+ executionPolicy?: SandboxExecutionPolicyIface;
291
+ platformNetworkPolicy?: (policy: NetworkPolicyIface) => Promise<void>;
292
+ platformEgressHosts?: string[];
287
293
  }
288
294
  export interface SandboxArtifactsIface {
289
295
  get(key: string): Promise<JsonValue | null>;
@@ -296,115 +302,96 @@ export interface SandboxPreparationSourceIface {
296
302
  resources: Record<string, JsonValue>;
297
303
  }>;
298
304
  }
299
- export interface SandboxPrepareContextIface {
300
- bindings?: HostedBindingsIface;
305
+ export interface SandboxPrepareContextIface extends SandboxProviderContextIface {
301
306
  preparation?: SandboxPreparationSourceIface;
302
307
  artifacts?: SandboxArtifactsIface;
303
308
  files: Record<string, string>;
304
309
  resources: Record<string, JsonValue>;
305
310
  sourceRevision: string;
306
311
  storagePath: string;
307
- organizationId: string;
308
- credentials?: SandboxCredentialsIface;
309
- guides: SandboxGuidesIface;
310
- actingUser: SandboxActingUserIface;
311
- log?: (message: string) => void;
312
312
  }
313
- export interface SandboxStartContextIface {
313
+ export interface SandboxResourceContextIface extends SandboxProviderContextIface {
314
+ sandboxId: string;
315
+ lifecycle: SandboxLifecycleIface;
314
316
  executionPolicy?: SandboxExecutionPolicyIface;
315
- bindings?: HostedBindingsIface;
316
- /** Passive recovery only: never wake, create, seed, or restart backend services. */
317
- passive?: boolean;
318
317
  preparation?: SandboxPreparationSourceIface;
319
- session: {
320
- id: string;
321
- organizationId: string;
322
- conversationId: string | null;
323
- definitionId: string;
324
- bindingId: string;
325
- workspaceId?: string;
326
- target: string;
327
- };
328
- credentials?: SandboxCredentialsIface;
329
318
  storagePath: string;
330
- guides: SandboxGuidesIface;
331
- variables: SandboxVariablesIface;
332
- repositories: SandboxRepositoriesIface;
333
- actingUser: SandboxActingUserIface;
334
319
  platformEnvironment?: () => Promise<Record<string, string>>;
335
320
  platformEgressHosts?: string[];
336
321
  platformNetworkPolicy: (policy: NetworkPolicyIface) => Promise<void>;
337
322
  platformFiles?: () => Promise<Record<string, string>>;
338
323
  }
339
324
  export declare const PLATFORM_ENVIRONMENT_NAMES: ReadonlySet<string>;
340
- export declare const platformProcessEnvironment: (ctx: Pick<SandboxStartContextIface, "platformEnvironment">, specEnv: Record<string, string>) => (() => Promise<Record<string, string>>);
341
- export declare const writePlatformFiles: (ctx: Pick<SandboxStartContextIface, "platformFiles">, sandbox: Pick<SandboxSessionIface, "writeTextFile">) => Promise<void>;
342
- export declare const reportPlatformNetworkPolicy: (ctx: Pick<SandboxStartContextIface, "platformNetworkPolicy">, policy: NetworkPolicyIface) => Promise<void>;
343
- export declare const withPlatformEgressHosts: (ctx: Pick<SandboxStartContextIface, "platformEgressHosts">, policy: NetworkPolicyIface) => NetworkPolicyIface;
344
- export declare enum SandboxSessionEndReason {
345
- Completed = "completed",
346
- Expired = "expired",
347
- Failed = "failed"
348
- }
349
- export declare enum SandboxWorkspace {
350
- Session = "session",
351
- Conversation = "conversation",
352
- Ephemeral = "ephemeral"
353
- }
354
- export interface SandboxProviderImplementationIface<OpenOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
355
- workspace?(ctx: SandboxEnvironmentContextIface): Promise<SandboxWorkspace | null>;
356
- capabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;
357
- additionalCapabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[]>;
325
+ export declare const platformProcessEnvironment: (ctx: Pick<SandboxResourceContextIface, "platformEnvironment">, specEnv: Record<string, string>) => (() => Promise<Record<string, string>>);
326
+ export declare const writePlatformFiles: (ctx: Pick<SandboxResourceContextIface, "platformFiles">, sandbox: Pick<SandboxSessionIface, "writeTextFile">) => Promise<void>;
327
+ export declare const reportPlatformNetworkPolicy: (ctx: Pick<SandboxResourceContextIface, "platformNetworkPolicy">, policy: NetworkPolicyIface) => Promise<void>;
328
+ export declare const withPlatformEgressHosts: (ctx: Pick<SandboxResourceContextIface, "platformEgressHosts">, policy: NetworkPolicyIface) => NetworkPolicyIface;
329
+ export interface SandboxAttachmentIface<State extends JsonValue, S extends NetworkSandboxSessionIface> {
330
+ handle: SandboxProviderHandleIface<S>;
331
+ state: State;
332
+ fresh: boolean;
333
+ booted: boolean;
334
+ region?: string | null;
335
+ }
336
+ export interface SandboxEnvironmentImplementationIface<Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
337
+ capabilities(ctx: SandboxOfferContextIface): Promise<SandboxCapabilityOffer>;
338
+ runtimes?(ctx: SandboxOfferContextIface): Promise<RuntimeKind[]>;
339
+ features?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;
340
+ additionalFeatures?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[]>;
358
341
  mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;
359
342
  readSnapshot?(ctx: SandboxOfferContextIface, state: State, request: SandboxSnapshotRequestIface): Promise<SandboxSnapshotResponseIface | null>;
360
343
  processes?(ctx: SandboxOfferContextIface & {
361
- bindingId: string;
344
+ sandboxId: string;
362
345
  }, state: State, request: ProcessInspectionRequestIface): Promise<ProcessInspectionResultIface>;
363
346
  editor?(ctx: SandboxOfferContextIface, state: State, request: SandboxEditorRequestIface): Promise<SandboxEditorResultIface>;
364
347
  artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;
365
348
  prepare(ctx: SandboxPrepareContextIface): Promise<Artifact>;
366
- awaitRunning(ctx: SandboxStartContextIface, state: State, options: {
367
- timeoutMs: number;
368
- }): Promise<void>;
369
- start(ctx: SandboxStartContextIface, options: OpenOptions | undefined, artifact: Artifact): Promise<{
370
- handle: SandboxProviderHandleIface<S>;
349
+ create(ctx: SandboxResourceContextIface, args: {
350
+ artifact: Artifact;
351
+ setup: SandboxSetupIface | null;
352
+ }): Promise<{
371
353
  state: State;
372
354
  region?: string | null;
373
355
  }>;
374
- resume(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<SandboxProviderHandleIface<S>>;
375
- resumePassive?(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<SandboxProviderHandleIface<S>>;
376
- park?(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<State>;
377
- onSessionEnd?(ctx: SandboxStartContextIface, artifact: Artifact, state: State, options: {
378
- reason: SandboxSessionEndReason;
356
+ awaitRunning(ctx: SandboxResourceContextIface, state: State, options: {
357
+ timeoutMs: number;
358
+ }): Promise<void>;
359
+ attach(ctx: SandboxResourceContextIface, args: {
360
+ artifact: Artifact;
361
+ state: State;
362
+ }): Promise<SandboxAttachmentIface<State, S>>;
363
+ attachPassive?(ctx: SandboxResourceContextIface, args: {
364
+ artifact: Artifact;
365
+ state: State;
366
+ }): Promise<SandboxProviderHandleIface<S>>;
367
+ detach(ctx: SandboxResourceContextIface, args: {
368
+ state: State;
369
+ }): Promise<State>;
370
+ park(ctx: SandboxResourceContextIface, args: {
371
+ artifact: Artifact;
372
+ state: State;
373
+ }): Promise<State>;
374
+ delete(ctx: SandboxResourceContextIface, args: {
375
+ state: State;
379
376
  }): Promise<void>;
380
377
  }
381
- export interface SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
378
+ export interface SandboxProviderDefinitionIface<EnvOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
382
379
  name: string;
383
380
  stateProtocolVersion?: number;
384
- environment(options?: EnvOptions): SandboxProviderImplementationIface<OpenOptions, Artifact, State, S>;
385
- }
386
- export interface SandboxProviderIface<EnvOptions, OpenOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
387
- readonly definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>;
388
- readonly name: string;
389
- environment(options?: EnvOptions): AwaitableSandboxEnvironmentIface<EnvOptions, OpenOptions>;
381
+ environment(options?: EnvOptions): SandboxEnvironmentImplementationIface<Artifact, State, S>;
390
382
  }
391
- export interface SandboxEnvironmentIface<EnvOptions, OpenOptions> {
392
- readonly providerName: string;
393
- readonly options: EnvOptions | undefined;
394
- readonly authoringWarnings?: readonly string[];
395
- open(options?: OpenOptions): SandboxOpenRequestIface<EnvOptions, OpenOptions>;
383
+ export interface SandboxEnvironmentValueIface<EnvOptions = JsonValue> {
384
+ provider: string;
385
+ environment: EnvOptions;
396
386
  }
397
- export interface AwaitableSandboxEnvironmentIface<EnvOptions, OpenOptions> extends SandboxEnvironmentIface<EnvOptions, OpenOptions> {
398
- open(options?: OpenOptions): AwaitableSandboxOpenRequestIface<EnvOptions, OpenOptions>;
399
- }
400
- export interface SandboxOpenRequestIface<EnvOptions, OpenOptions> {
401
- readonly providerName: string;
402
- readonly environmentOptions: EnvOptions | undefined;
403
- readonly openOptions: OpenOptions | undefined;
404
- readonly authoringWarnings?: readonly string[];
387
+ export interface SandboxProviderIface<EnvOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
388
+ readonly definition: SandboxProviderDefinitionIface<EnvOptions, Artifact, State, S>;
389
+ readonly name: string;
390
+ environment(options: EnvOptions): SandboxEnvironmentValueIface<EnvOptions>;
405
391
  }
406
- export declare const defineSandboxProvider: <EnvOptions, OpenOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface>(definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>) => SandboxProviderIface<EnvOptions, OpenOptions, Artifact, State, S>;
407
- export type AnySandboxProviderIface = SandboxProviderIface<JsonValue, JsonValue, JsonValue, JsonValue, NetworkSandboxSessionIface>;
392
+ export declare const defineSandboxProvider: <EnvOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface>(definition: SandboxProviderDefinitionIface<EnvOptions, Artifact, State, S>) => SandboxProviderIface<EnvOptions, Artifact, State, S>;
393
+ export declare const sandboxRuntimesOf: (environment: Pick<SandboxEnvironmentImplementationIface<JsonValue, JsonValue, NetworkSandboxSessionIface>, "capabilities" | "runtimes">, ctx: SandboxOfferContextIface) => Promise<RuntimeKind[]>;
394
+ export type AnySandboxProviderIface = SandboxProviderIface<JsonValue, JsonValue, JsonValue, NetworkSandboxSessionIface>;
408
395
  export declare enum SandboxEventKind {
409
396
  ProcessExited = "process_exited"
410
397
  }
@@ -1,3 +1,5 @@
1
+ import { Capability, RuntimeKind } from "@finalai/agent-protocol";
2
+ import * as z from "zod";
1
3
  import { SandboxEntryType } from "./file-kind.mjs";
2
4
  import { SandboxEntryType as SandboxEntryType2 } from "./file-kind.mjs";
3
5
  import { createSandboxHandle } from "./handle.mjs";
@@ -10,7 +12,13 @@ import {
10
12
  SandboxEditorOperation
11
13
  } from "./editor.mjs";
12
14
  import { SandboxExecutionOperation } from "./execution-guard.mjs";
13
- import { awaitableOpenRequest } from "./open-scope.mjs";
15
+ var SandboxWorkerEndpointTransport = /* @__PURE__ */ ((SandboxWorkerEndpointTransport2) => {
16
+ SandboxWorkerEndpointTransport2["Ws"] = "ws";
17
+ SandboxWorkerEndpointTransport2["Http"] = "http";
18
+ SandboxWorkerEndpointTransport2["Relay"] = "relay";
19
+ return SandboxWorkerEndpointTransport2;
20
+ })(SandboxWorkerEndpointTransport || {});
21
+ const isSandboxWorkerEndpoint = (started) => "endpoint" in started;
14
22
  var PortProtocol = /* @__PURE__ */ ((PortProtocol2) => {
15
23
  PortProtocol2["Http"] = "http";
16
24
  PortProtocol2["Https"] = "https";
@@ -29,21 +37,19 @@ var SandboxCapability = /* @__PURE__ */ ((SandboxCapability2) => {
29
37
  SandboxCapability2["LocalMcp"] = "localMcp";
30
38
  SandboxCapability2["Browser"] = "browser";
31
39
  SandboxCapability2["DurableProcesses"] = "durableProcesses";
40
+ SandboxCapability2["Workers"] = "workers";
32
41
  return SandboxCapability2;
33
42
  })(SandboxCapability || {});
34
- const noSandboxGuides = {
35
- get: async () => null,
36
- default: async () => null
37
- };
38
43
  const noSandboxRepositories = {
39
44
  cloneSource: async () => null
40
45
  };
41
- const noSandboxVariables = { get: async () => null };
42
46
  const noSandboxActingUser = { current: async () => null };
43
- const noSandboxCredentials = {
44
- computersAccess: async () => null,
45
- deviceAccess: async () => null,
46
- secret: async () => null
47
+ const noSandboxCredentials = { secret: async () => null };
48
+ const sandboxCredentialRefSchema = z.strictObject({
49
+ secretRef: z.string().min(1).max(256)
50
+ });
51
+ const noSandboxIdentity = async ({ audience }) => {
52
+ throw new Error(`no identity was granted for ${audience}`);
47
53
  };
48
54
  const PLATFORM_ENVIRONMENT_NAMES = /* @__PURE__ */ new Set([
49
55
  "HTTPS_PROXY",
@@ -75,39 +81,31 @@ const withPlatformEgressHosts = (ctx, policy) => {
75
81
  if (policy.mode !== NetworkPolicy.Allowlist || hosts.length === 0) return policy;
76
82
  return { ...policy, allow: [.../* @__PURE__ */ new Set([...policy.allow ?? [], ...hosts])] };
77
83
  };
78
- var SandboxSessionEndReason = /* @__PURE__ */ ((SandboxSessionEndReason2) => {
79
- SandboxSessionEndReason2["Completed"] = "completed";
80
- SandboxSessionEndReason2["Expired"] = "expired";
81
- SandboxSessionEndReason2["Failed"] = "failed";
82
- return SandboxSessionEndReason2;
83
- })(SandboxSessionEndReason || {});
84
- var SandboxWorkspace = /* @__PURE__ */ ((SandboxWorkspace2) => {
85
- SandboxWorkspace2["Session"] = "session";
86
- SandboxWorkspace2["Conversation"] = "conversation";
87
- SandboxWorkspace2["Ephemeral"] = "ephemeral";
88
- return SandboxWorkspace2;
89
- })(SandboxWorkspace || {});
90
84
  const defineSandboxProvider = (definition) => ({
91
85
  definition: withSandboxOverrides(definition, {
92
86
  environment: (options) => {
93
87
  const implementation = definition.environment(options);
94
- if (typeof implementation.awaitRunning !== "function")
95
- throw new Error(`sandbox provider ${definition.name} does not implement awaitRunning`);
88
+ for (const method of [
89
+ "create",
90
+ "attach",
91
+ "detach",
92
+ "park",
93
+ "delete",
94
+ "awaitRunning"
95
+ ])
96
+ if (typeof implementation[method] !== "function")
97
+ throw new Error(`sandbox provider ${definition.name} does not implement ${method}`);
96
98
  const overrides = {
97
- start: async (ctx, openOptions, artifact) => {
98
- const started = await implementation.start(ctx, openOptions, artifact);
99
+ attach: async (ctx, args) => {
100
+ const attached = await implementation.attach(ctx, args);
99
101
  return {
100
- ...started,
102
+ ...attached,
101
103
  handle: createSandboxHandle({
102
- handle: started.handle,
104
+ handle: attached.handle,
103
105
  executionPolicy: ctx.executionPolicy
104
106
  })
105
107
  };
106
- },
107
- resume: async (ctx, artifact, state) => createSandboxHandle({
108
- handle: await implementation.resume(ctx, artifact, state),
109
- executionPolicy: ctx.executionPolicy
110
- })
108
+ }
111
109
  };
112
110
  if (implementation.editor != null) {
113
111
  const editor = implementation.editor.bind(implementation);
@@ -120,10 +118,10 @@ const defineSandboxProvider = (definition) => ({
120
118
  return editor(ctx, state, request);
121
119
  };
122
120
  }
123
- if (implementation.resumePassive != null) {
124
- const resumePassive = implementation.resumePassive.bind(implementation);
125
- overrides.resumePassive = async (ctx, artifact, state) => createSandboxHandle({
126
- handle: await resumePassive(ctx, artifact, state),
121
+ if (implementation.attachPassive != null) {
122
+ const attachPassive = implementation.attachPassive.bind(implementation);
123
+ overrides.attachPassive = async (ctx, args) => createSandboxHandle({
124
+ handle: await attachPassive(ctx, args),
127
125
  executionPolicy: ctx.executionPolicy
128
126
  });
129
127
  }
@@ -131,16 +129,13 @@ const defineSandboxProvider = (definition) => ({
131
129
  }
132
130
  }),
133
131
  name: definition.name,
134
- environment: (options) => ({
135
- providerName: definition.name,
136
- options,
137
- open: (openOptions) => awaitableOpenRequest({
138
- providerName: definition.name,
139
- environmentOptions: options,
140
- openOptions
141
- })
142
- })
132
+ environment: (options) => ({ provider: definition.name, environment: options })
143
133
  });
134
+ const sandboxRuntimesOf = async (environment, ctx) => {
135
+ if (environment.runtimes != null) return environment.runtimes(ctx);
136
+ const offer = await environment.capabilities(ctx);
137
+ return offer[Capability.Shell] == null ? [] : [RuntimeKind.Process];
138
+ };
144
139
  var SandboxEventKind = /* @__PURE__ */ ((SandboxEventKind2) => {
145
140
  SandboxEventKind2["ProcessExited"] = "process_exited";
146
141
  return SandboxEventKind2;
@@ -152,17 +147,18 @@ export {
152
147
  SandboxCapability,
153
148
  SandboxEntryType2 as SandboxEntryType,
154
149
  SandboxEventKind,
155
- SandboxSessionEndReason,
156
- SandboxWorkspace,
150
+ SandboxWorkerEndpointTransport,
157
151
  defineSandboxProvider,
158
152
  isMcpChannelEndpoint,
153
+ isSandboxWorkerEndpoint,
159
154
  noSandboxActingUser,
160
155
  noSandboxCredentials,
161
- noSandboxGuides,
156
+ noSandboxIdentity,
162
157
  noSandboxRepositories,
163
- noSandboxVariables,
164
158
  platformProcessEnvironment,
165
159
  reportPlatformNetworkPolicy,
160
+ sandboxCredentialRefSchema,
161
+ sandboxRuntimesOf,
166
162
  withPlatformEgressHosts,
167
163
  writePlatformFiles
168
164
  };