@finalai/agent-provider 0.9.0 → 0.11.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 (206) hide show
  1. package/HOSTING.md +334 -245
  2. package/README.md +106 -20
  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 +51 -15
  7. package/dist/modules/channel.mjs +1 -0
  8. package/dist/modules/channel.mjs.map +2 -2
  9. package/dist/modules/code-host/host.d.mts +10 -0
  10. package/dist/modules/code-host/host.mjs +88 -0
  11. package/dist/modules/code-host/host.mjs.map +7 -0
  12. package/dist/modules/code-host/in-process.d.mts +24 -0
  13. package/dist/modules/code-host/in-process.mjs +89 -0
  14. package/dist/modules/code-host/in-process.mjs.map +7 -0
  15. package/dist/modules/code-host/index.d.mts +4 -0
  16. package/dist/modules/code-host/index.mjs +5 -0
  17. package/dist/modules/code-host/index.mjs.map +7 -0
  18. package/dist/modules/code-host/serverless.d.mts +63 -0
  19. package/dist/modules/code-host/serverless.mjs +27 -0
  20. package/dist/modules/code-host/serverless.mjs.map +7 -0
  21. package/dist/modules/code-host/types.d.mts +152 -0
  22. package/dist/modules/code-host/types.mjs +85 -0
  23. package/dist/modules/code-host/types.mjs.map +7 -0
  24. package/dist/modules/conformance/agent.mjs +72 -6
  25. package/dist/modules/conformance/agent.mjs.map +2 -2
  26. package/dist/modules/conformance/harness-kit.d.mts +9 -2
  27. package/dist/modules/conformance/harness-kit.mjs +224 -63
  28. package/dist/modules/conformance/harness-kit.mjs.map +3 -3
  29. package/dist/modules/conformance/local-harness.d.mts +1 -4
  30. package/dist/modules/conformance/local-harness.mjs +21 -22
  31. package/dist/modules/conformance/local-harness.mjs.map +2 -2
  32. package/dist/modules/conformance/protocol.d.mts +1 -0
  33. package/dist/modules/conformance/protocol.mjs +2 -0
  34. package/dist/modules/conformance/protocol.mjs.map +2 -2
  35. package/dist/modules/conformance/sandbox-kit.d.mts +12 -4
  36. package/dist/modules/conformance/sandbox-kit.mjs +189 -103
  37. package/dist/modules/conformance/sandbox-kit.mjs.map +2 -2
  38. package/dist/modules/conformance/scripted-model/chat-completions.mjs +1 -0
  39. package/dist/modules/conformance/scripted-model/chat-completions.mjs.map +2 -2
  40. package/dist/modules/conformance/scripted-model/directives.d.mts +3 -0
  41. package/dist/modules/conformance/scripted-model/directives.mjs +26 -10
  42. package/dist/modules/conformance/scripted-model/directives.mjs.map +2 -2
  43. package/dist/modules/conformance/scripted-model/messages.mjs +1 -0
  44. package/dist/modules/conformance/scripted-model/messages.mjs.map +2 -2
  45. package/dist/modules/conformance/scripted-model/responses.mjs +2 -0
  46. package/dist/modules/conformance/scripted-model/responses.mjs.map +2 -2
  47. package/dist/modules/conformance/stdio.d.mts +21 -0
  48. package/dist/modules/conformance/stdio.mjs +158 -0
  49. package/dist/modules/conformance/stdio.mjs.map +7 -0
  50. package/dist/modules/credential-routes.d.mts +3 -3
  51. package/dist/modules/credential-routes.mjs +2 -2
  52. package/dist/modules/credential-routes.mjs.map +2 -2
  53. package/dist/modules/document.d.mts +358 -0
  54. package/dist/modules/document.mjs +193 -0
  55. package/dist/modules/document.mjs.map +7 -0
  56. package/dist/modules/harness-configuration.d.mts +16 -0
  57. package/dist/modules/harness-configuration.mjs +83 -0
  58. package/dist/modules/harness-configuration.mjs.map +7 -0
  59. package/dist/modules/harness-definition.d.mts +280 -0
  60. package/dist/modules/harness-definition.mjs +430 -0
  61. package/dist/modules/harness-definition.mjs.map +7 -0
  62. package/dist/modules/harness-provider.d.mts +197 -0
  63. package/dist/modules/harness-provider.mjs +108 -0
  64. package/dist/modules/harness-provider.mjs.map +7 -0
  65. package/dist/modules/harness-requirements.d.mts +19 -0
  66. package/dist/modules/harness-requirements.mjs +40 -0
  67. package/dist/modules/harness-requirements.mjs.map +7 -0
  68. package/dist/modules/harness-start.d.mts +33 -0
  69. package/dist/modules/harness-start.mjs +107 -0
  70. package/dist/modules/harness-start.mjs.map +7 -0
  71. package/dist/modules/harness.d.mts +84 -109
  72. package/dist/modules/harness.mjs +56 -111
  73. package/dist/modules/harness.mjs.map +3 -3
  74. package/dist/modules/identity.d.mts +1 -0
  75. package/dist/modules/identity.mjs +2 -0
  76. package/dist/modules/identity.mjs.map +7 -0
  77. package/dist/modules/index.d.mts +12 -7
  78. package/dist/modules/index.mjs +12 -7
  79. package/dist/modules/index.mjs.map +2 -2
  80. package/dist/modules/inference.d.mts +35 -0
  81. package/dist/modules/inference.mjs +74 -0
  82. package/dist/modules/inference.mjs.map +7 -0
  83. package/dist/modules/local-channel-context.d.mts +1 -1
  84. package/dist/modules/local-channel-context.mjs +1 -1
  85. package/dist/modules/local-channel-context.mjs.map +2 -2
  86. package/dist/modules/requirements-check.d.mts +30 -0
  87. package/dist/modules/requirements-check.mjs +164 -0
  88. package/dist/modules/requirements-check.mjs.map +7 -0
  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/body.d.mts +1 -0
  114. package/dist/modules/sandbox/remote/body.mjs +27 -0
  115. package/dist/modules/sandbox/remote/body.mjs.map +7 -0
  116. package/dist/modules/sandbox/remote/errors.d.mts +10 -0
  117. package/dist/modules/sandbox/remote/errors.mjs +62 -0
  118. package/dist/modules/sandbox/remote/errors.mjs.map +7 -0
  119. package/dist/modules/sandbox/remote/index.d.mts +5 -0
  120. package/dist/modules/sandbox/remote/index.mjs +6 -0
  121. package/dist/modules/sandbox/remote/index.mjs.map +7 -0
  122. package/dist/modules/sandbox/remote/ndjson.d.mts +6 -0
  123. package/dist/modules/sandbox/remote/ndjson.mjs +80 -0
  124. package/dist/modules/sandbox/remote/ndjson.mjs.map +7 -0
  125. package/dist/modules/sandbox/remote/platform-api.d.mts +8 -0
  126. package/dist/modules/sandbox/remote/platform-api.mjs +15 -0
  127. package/dist/modules/sandbox/remote/platform-api.mjs.map +7 -0
  128. package/dist/modules/sandbox/remote/preamble.d.mts +7 -0
  129. package/dist/modules/sandbox/remote/preamble.mjs +51 -0
  130. package/dist/modules/sandbox/remote/preamble.mjs.map +7 -0
  131. package/dist/modules/sandbox/remote/serve.d.mts +34 -0
  132. package/dist/modules/sandbox/remote/serve.mjs +520 -0
  133. package/dist/modules/sandbox/remote/serve.mjs.map +7 -0
  134. package/dist/modules/sandbox/remote/testing.d.mts +34 -0
  135. package/dist/modules/sandbox/remote/testing.mjs +275 -0
  136. package/dist/modules/sandbox/remote/testing.mjs.map +7 -0
  137. package/dist/modules/sandbox/seeds.d.mts +2 -2
  138. package/dist/modules/sandbox/seeds.mjs +2 -2
  139. package/dist/modules/sandbox/seeds.mjs.map +2 -2
  140. package/dist/modules/sandbox/server.d.mts +4 -6
  141. package/dist/modules/sandbox/server.mjs +93 -49
  142. package/dist/modules/sandbox/server.mjs.map +2 -2
  143. package/dist/modules/sandbox/setup/apply.d.mts +40 -0
  144. package/dist/modules/sandbox/setup/apply.mjs +190 -0
  145. package/dist/modules/sandbox/setup/apply.mjs.map +7 -0
  146. package/dist/modules/sandbox/setup/describe.d.mts +10 -0
  147. package/dist/modules/sandbox/setup/describe.mjs +62 -0
  148. package/dist/modules/sandbox/setup/describe.mjs.map +7 -0
  149. package/dist/modules/sandbox/setup/index.d.mts +6 -0
  150. package/dist/modules/sandbox/setup/index.mjs +17 -0
  151. package/dist/modules/sandbox/setup/index.mjs.map +7 -0
  152. package/dist/modules/sandbox/setup/paths.d.mts +8 -0
  153. package/dist/modules/sandbox/setup/paths.mjs +18 -0
  154. package/dist/modules/sandbox/setup/paths.mjs.map +7 -0
  155. package/dist/modules/sandbox/setup/schema.d.mts +43 -0
  156. package/dist/modules/sandbox/setup/schema.mjs +58 -0
  157. package/dist/modules/sandbox/setup/schema.mjs.map +7 -0
  158. package/dist/modules/sandbox/tool-policy.d.mts +1 -1
  159. package/dist/modules/sandbox/tool-policy.mjs +1 -1
  160. package/dist/modules/sandbox/tool-policy.mjs.map +2 -2
  161. package/dist/modules/sandbox/types.d.mts +117 -142
  162. package/dist/modules/sandbox/types.mjs +47 -57
  163. package/dist/modules/sandbox/types.mjs.map +3 -3
  164. package/dist/modules/sandbox/wire.d.mts +93 -6
  165. package/dist/modules/sandbox/wire.mjs +61 -38
  166. package/dist/modules/sandbox/wire.mjs.map +2 -2
  167. package/dist/modules/schemas.d.mts +5 -76
  168. package/dist/modules/schemas.mjs +18 -85
  169. package/dist/modules/schemas.mjs.map +2 -2
  170. package/dist/modules/tool-annotations.d.mts +15 -6
  171. package/dist/modules/tool-annotations.mjs +9 -3
  172. package/dist/modules/tool-annotations.mjs.map +2 -2
  173. package/dist/modules/tool-descriptor.d.mts +16 -0
  174. package/dist/modules/tool-descriptor.mjs +19 -0
  175. package/dist/modules/tool-descriptor.mjs.map +7 -0
  176. package/dist/modules/tool-patterns.d.mts +7 -7
  177. package/dist/modules/tool-patterns.mjs +10 -9
  178. package/dist/modules/tool-patterns.mjs.map +2 -2
  179. package/package.json +86 -41
  180. package/dist/modules/credentials.d.mts +0 -206
  181. package/dist/modules/credentials.mjs +0 -207
  182. package/dist/modules/credentials.mjs.map +0 -7
  183. package/dist/modules/dynamic.d.mts +0 -40
  184. package/dist/modules/dynamic.mjs +0 -79
  185. package/dist/modules/dynamic.mjs.map +0 -7
  186. package/dist/modules/hosted-bindings.d.mts +0 -15
  187. package/dist/modules/hosted-bindings.mjs +0 -21
  188. package/dist/modules/hosted-bindings.mjs.map +0 -7
  189. package/dist/modules/manifest.d.mts +0 -791
  190. package/dist/modules/manifest.mjs +0 -322
  191. package/dist/modules/manifest.mjs.map +0 -7
  192. package/dist/modules/provider-ref.d.mts +0 -29
  193. package/dist/modules/provider-ref.mjs +0 -55
  194. package/dist/modules/provider-ref.mjs.map +0 -7
  195. package/dist/modules/room-surface.d.mts +0 -355
  196. package/dist/modules/room-surface.mjs +0 -156
  197. package/dist/modules/room-surface.mjs.map +0 -7
  198. package/dist/modules/sandbox/open-scope-node.d.mts +0 -4
  199. package/dist/modules/sandbox/open-scope-node.mjs +0 -19
  200. package/dist/modules/sandbox/open-scope-node.mjs.map +0 -7
  201. package/dist/modules/sandbox/open-scope.d.mts +0 -16
  202. package/dist/modules/sandbox/open-scope.mjs +0 -66
  203. package/dist/modules/sandbox/open-scope.mjs.map +0 -7
  204. package/dist/modules/sandbox/workspace-identity.d.mts +0 -5
  205. package/dist/modules/sandbox/workspace-identity.mjs +0 -14
  206. 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,81 +239,45 @@ 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
- export interface SandboxRepositoryCloneSourceIface {
236
- url: string;
237
- ref: string | null;
238
- authorization: string | null;
239
- }
240
- export interface SandboxRepositoriesIface {
241
- cloneSource(args: {
242
- repository: string;
243
- ref: string | null;
244
- }): Promise<SandboxRepositoryCloneSourceIface | null>;
245
- }
246
- export interface SandboxVariablesIface {
247
- get(name: string): Promise<string | null>;
248
- }
249
- export declare const noSandboxGuides: SandboxGuidesIface;
250
- export declare const noSandboxRepositories: SandboxRepositoriesIface;
251
- export declare const noSandboxVariables: SandboxVariablesIface;
252
242
  export interface SandboxActingUserIface {
253
243
  current(): Promise<string | null>;
254
244
  }
255
245
  export declare const noSandboxActingUser: SandboxActingUserIface;
256
- export interface FinalPlatformAccessIface {
257
- baseUrl: string;
258
- token: string;
259
- }
260
246
  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
247
  secret(args: {
269
248
  secretRef: string;
270
249
  }): Promise<string | null>;
271
250
  }
272
251
  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;
252
+ export declare const sandboxCredentialRefSchema: z.ZodObject<{
253
+ secretRef: z.ZodString;
254
+ }, z.core.$strict>;
255
+ export type SandboxCredentialRefIface = z.infer<typeof sandboxCredentialRefSchema>;
256
+ export interface SandboxIdentityTokenIface {
257
+ token: string;
258
+ expiresAt: string;
259
+ }
260
+ export type SandboxIdentityFn = (args: {
261
+ audience: string;
262
+ refresh?: boolean;
263
+ }) => Promise<SandboxIdentityTokenIface>;
264
+ export declare const noSandboxIdentity: SandboxIdentityFn;
265
+ export interface SandboxProviderContextIface {
279
266
  organizationId: string;
280
- credentials?: SandboxCredentialsIface;
267
+ projectId: string;
268
+ credentials: SandboxCredentialsIface;
281
269
  actingUser: SandboxActingUserIface;
270
+ identity: SandboxIdentityFn;
271
+ log?: (message: string, fields?: Record<string, string | number | boolean | null>) => void;
282
272
  }
283
- export interface SandboxEnvironmentContextIface {
284
- bindings?: HostedBindingsIface;
285
- organizationId: string;
286
- guides: SandboxGuidesIface;
273
+ export interface SandboxLifecycleIface {
274
+ parkAfterIdleMs: number | null;
275
+ }
276
+ export interface SandboxOfferContextIface extends SandboxProviderContextIface {
277
+ sandboxId?: string;
278
+ executionPolicy?: SandboxExecutionPolicyIface;
279
+ platformNetworkPolicy?: (policy: NetworkPolicyIface) => Promise<void>;
280
+ platformEgressHosts?: string[];
287
281
  }
288
282
  export interface SandboxArtifactsIface {
289
283
  get(key: string): Promise<JsonValue | null>;
@@ -296,115 +290,96 @@ export interface SandboxPreparationSourceIface {
296
290
  resources: Record<string, JsonValue>;
297
291
  }>;
298
292
  }
299
- export interface SandboxPrepareContextIface {
300
- bindings?: HostedBindingsIface;
293
+ export interface SandboxPrepareContextIface extends SandboxProviderContextIface {
301
294
  preparation?: SandboxPreparationSourceIface;
302
295
  artifacts?: SandboxArtifactsIface;
303
296
  files: Record<string, string>;
304
297
  resources: Record<string, JsonValue>;
305
298
  sourceRevision: string;
306
299
  storagePath: string;
307
- organizationId: string;
308
- credentials?: SandboxCredentialsIface;
309
- guides: SandboxGuidesIface;
310
- actingUser: SandboxActingUserIface;
311
- log?: (message: string) => void;
312
300
  }
313
- export interface SandboxStartContextIface {
301
+ export interface SandboxResourceContextIface extends SandboxProviderContextIface {
302
+ sandboxId: string;
303
+ lifecycle: SandboxLifecycleIface;
314
304
  executionPolicy?: SandboxExecutionPolicyIface;
315
- bindings?: HostedBindingsIface;
316
- /** Passive recovery only: never wake, create, seed, or restart backend services. */
317
- passive?: boolean;
318
305
  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
306
  storagePath: string;
330
- guides: SandboxGuidesIface;
331
- variables: SandboxVariablesIface;
332
- repositories: SandboxRepositoriesIface;
333
- actingUser: SandboxActingUserIface;
334
307
  platformEnvironment?: () => Promise<Record<string, string>>;
335
308
  platformEgressHosts?: string[];
336
309
  platformNetworkPolicy: (policy: NetworkPolicyIface) => Promise<void>;
337
310
  platformFiles?: () => Promise<Record<string, string>>;
338
311
  }
339
312
  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[]>;
313
+ export declare const platformProcessEnvironment: (ctx: Pick<SandboxResourceContextIface, "platformEnvironment">, specEnv: Record<string, string>) => (() => Promise<Record<string, string>>);
314
+ export declare const writePlatformFiles: (ctx: Pick<SandboxResourceContextIface, "platformFiles">, sandbox: Pick<SandboxSessionIface, "writeTextFile">) => Promise<void>;
315
+ export declare const reportPlatformNetworkPolicy: (ctx: Pick<SandboxResourceContextIface, "platformNetworkPolicy">, policy: NetworkPolicyIface) => Promise<void>;
316
+ export declare const withPlatformEgressHosts: (ctx: Pick<SandboxResourceContextIface, "platformEgressHosts">, policy: NetworkPolicyIface) => NetworkPolicyIface;
317
+ export interface SandboxAttachmentIface<State extends JsonValue, S extends NetworkSandboxSessionIface> {
318
+ handle: SandboxProviderHandleIface<S>;
319
+ state: State;
320
+ fresh: boolean;
321
+ booted: boolean;
322
+ region?: string | null;
323
+ }
324
+ export interface SandboxEnvironmentImplementationIface<Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
325
+ capabilities(ctx: SandboxOfferContextIface): Promise<SandboxCapabilityOffer>;
326
+ runtimes?(ctx: SandboxOfferContextIface): Promise<RuntimeKind[]>;
327
+ features?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;
328
+ additionalFeatures?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[]>;
358
329
  mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;
359
330
  readSnapshot?(ctx: SandboxOfferContextIface, state: State, request: SandboxSnapshotRequestIface): Promise<SandboxSnapshotResponseIface | null>;
360
331
  processes?(ctx: SandboxOfferContextIface & {
361
- bindingId: string;
332
+ sandboxId: string;
362
333
  }, state: State, request: ProcessInspectionRequestIface): Promise<ProcessInspectionResultIface>;
363
334
  editor?(ctx: SandboxOfferContextIface, state: State, request: SandboxEditorRequestIface): Promise<SandboxEditorResultIface>;
364
335
  artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;
365
336
  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>;
337
+ create(ctx: SandboxResourceContextIface, args: {
338
+ artifact: Artifact;
339
+ setup: SandboxSetupIface | null;
340
+ }): Promise<{
371
341
  state: State;
372
342
  region?: string | null;
373
343
  }>;
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;
344
+ awaitRunning(ctx: SandboxResourceContextIface, state: State, options: {
345
+ timeoutMs: number;
346
+ }): Promise<void>;
347
+ attach(ctx: SandboxResourceContextIface, args: {
348
+ artifact: Artifact;
349
+ state: State;
350
+ }): Promise<SandboxAttachmentIface<State, S>>;
351
+ attachPassive?(ctx: SandboxResourceContextIface, args: {
352
+ artifact: Artifact;
353
+ state: State;
354
+ }): Promise<SandboxProviderHandleIface<S>>;
355
+ detach(ctx: SandboxResourceContextIface, args: {
356
+ state: State;
357
+ }): Promise<State>;
358
+ park(ctx: SandboxResourceContextIface, args: {
359
+ artifact: Artifact;
360
+ state: State;
361
+ }): Promise<State>;
362
+ delete(ctx: SandboxResourceContextIface, args: {
363
+ state: State;
379
364
  }): Promise<void>;
380
365
  }
381
- export interface SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
366
+ export interface SandboxProviderDefinitionIface<EnvOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
382
367
  name: string;
383
368
  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>;
369
+ environment(options?: EnvOptions): SandboxEnvironmentImplementationIface<Artifact, State, S>;
390
370
  }
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>;
371
+ export interface SandboxEnvironmentValueIface<EnvOptions = JsonValue> {
372
+ provider: string;
373
+ environment: EnvOptions;
396
374
  }
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[];
375
+ export interface SandboxProviderIface<EnvOptions, Artifact extends JsonValue, State extends JsonValue, S extends NetworkSandboxSessionIface> {
376
+ readonly definition: SandboxProviderDefinitionIface<EnvOptions, Artifact, State, S>;
377
+ readonly name: string;
378
+ environment(options: EnvOptions): SandboxEnvironmentValueIface<EnvOptions>;
405
379
  }
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>;
380
+ 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>;
381
+ export declare const sandboxRuntimesOf: (environment: Pick<SandboxEnvironmentImplementationIface<JsonValue, JsonValue, NetworkSandboxSessionIface>, "capabilities" | "runtimes">, ctx: SandboxOfferContextIface) => Promise<RuntimeKind[]>;
382
+ export type AnySandboxProviderIface = SandboxProviderIface<JsonValue, JsonValue, JsonValue, NetworkSandboxSessionIface>;
408
383
  export declare enum SandboxEventKind {
409
384
  ProcessExited = "process_exited"
410
385
  }
@@ -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,16 @@ 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
- const noSandboxRepositories = {
39
- cloneSource: async () => null
40
- };
41
- const noSandboxVariables = { get: async () => null };
42
43
  const noSandboxActingUser = { current: async () => null };
43
- const noSandboxCredentials = {
44
- computersAccess: async () => null,
45
- deviceAccess: async () => null,
46
- secret: async () => null
44
+ const noSandboxCredentials = { secret: async () => null };
45
+ const sandboxCredentialRefSchema = z.strictObject({
46
+ secretRef: z.string().min(1).max(256)
47
+ });
48
+ const noSandboxIdentity = async ({ audience }) => {
49
+ throw new Error(`no identity was granted for ${audience}`);
47
50
  };
48
51
  const PLATFORM_ENVIRONMENT_NAMES = /* @__PURE__ */ new Set([
49
52
  "HTTPS_PROXY",
@@ -58,9 +61,7 @@ const PLATFORM_ENVIRONMENT_NAMES = /* @__PURE__ */ new Set([
58
61
  "DENO_CERT",
59
62
  "NODE_EXTRA_CA_CERTS",
60
63
  "FINAL_EGRESS_URL",
61
- "FINAL_EGRESS_TOKEN",
62
- "GH_TOKEN",
63
- "GITHUB_TOKEN"
64
+ "FINAL_EGRESS_TOKEN"
64
65
  ]);
65
66
  const platformProcessEnvironment = (ctx, specEnv) => async () => ({ ...specEnv, ...await ctx.platformEnvironment?.() });
66
67
  const writePlatformFiles = async (ctx, sandbox) => {
@@ -75,39 +76,31 @@ const withPlatformEgressHosts = (ctx, policy) => {
75
76
  if (policy.mode !== NetworkPolicy.Allowlist || hosts.length === 0) return policy;
76
77
  return { ...policy, allow: [.../* @__PURE__ */ new Set([...policy.allow ?? [], ...hosts])] };
77
78
  };
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
79
  const defineSandboxProvider = (definition) => ({
91
80
  definition: withSandboxOverrides(definition, {
92
81
  environment: (options) => {
93
82
  const implementation = definition.environment(options);
94
- if (typeof implementation.awaitRunning !== "function")
95
- throw new Error(`sandbox provider ${definition.name} does not implement awaitRunning`);
83
+ for (const method of [
84
+ "create",
85
+ "attach",
86
+ "detach",
87
+ "park",
88
+ "delete",
89
+ "awaitRunning"
90
+ ])
91
+ if (typeof implementation[method] !== "function")
92
+ throw new Error(`sandbox provider ${definition.name} does not implement ${method}`);
96
93
  const overrides = {
97
- start: async (ctx, openOptions, artifact) => {
98
- const started = await implementation.start(ctx, openOptions, artifact);
94
+ attach: async (ctx, args) => {
95
+ const attached = await implementation.attach(ctx, args);
99
96
  return {
100
- ...started,
97
+ ...attached,
101
98
  handle: createSandboxHandle({
102
- handle: started.handle,
99
+ handle: attached.handle,
103
100
  executionPolicy: ctx.executionPolicy
104
101
  })
105
102
  };
106
- },
107
- resume: async (ctx, artifact, state) => createSandboxHandle({
108
- handle: await implementation.resume(ctx, artifact, state),
109
- executionPolicy: ctx.executionPolicy
110
- })
103
+ }
111
104
  };
112
105
  if (implementation.editor != null) {
113
106
  const editor = implementation.editor.bind(implementation);
@@ -120,10 +113,10 @@ const defineSandboxProvider = (definition) => ({
120
113
  return editor(ctx, state, request);
121
114
  };
122
115
  }
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),
116
+ if (implementation.attachPassive != null) {
117
+ const attachPassive = implementation.attachPassive.bind(implementation);
118
+ overrides.attachPassive = async (ctx, args) => createSandboxHandle({
119
+ handle: await attachPassive(ctx, args),
127
120
  executionPolicy: ctx.executionPolicy
128
121
  });
129
122
  }
@@ -131,16 +124,13 @@ const defineSandboxProvider = (definition) => ({
131
124
  }
132
125
  }),
133
126
  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
- })
127
+ environment: (options) => ({ provider: definition.name, environment: options })
143
128
  });
129
+ const sandboxRuntimesOf = async (environment, ctx) => {
130
+ if (environment.runtimes != null) return environment.runtimes(ctx);
131
+ const offer = await environment.capabilities(ctx);
132
+ return offer[Capability.Shell] == null ? [] : [RuntimeKind.Process];
133
+ };
144
134
  var SandboxEventKind = /* @__PURE__ */ ((SandboxEventKind2) => {
145
135
  SandboxEventKind2["ProcessExited"] = "process_exited";
146
136
  return SandboxEventKind2;
@@ -152,17 +142,17 @@ export {
152
142
  SandboxCapability,
153
143
  SandboxEntryType2 as SandboxEntryType,
154
144
  SandboxEventKind,
155
- SandboxSessionEndReason,
156
- SandboxWorkspace,
145
+ SandboxWorkerEndpointTransport,
157
146
  defineSandboxProvider,
158
147
  isMcpChannelEndpoint,
148
+ isSandboxWorkerEndpoint,
159
149
  noSandboxActingUser,
160
150
  noSandboxCredentials,
161
- noSandboxGuides,
162
- noSandboxRepositories,
163
- noSandboxVariables,
151
+ noSandboxIdentity,
164
152
  platformProcessEnvironment,
165
153
  reportPlatformNetworkPolicy,
154
+ sandboxCredentialRefSchema,
155
+ sandboxRuntimesOf,
166
156
  withPlatformEgressHosts,
167
157
  writePlatformFiles
168
158
  };