@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,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
3
  "sources": ["../../../../../src/sandbox/types.ts"],
4
- "sourcesContent": ["import { SandboxEntryType } from \"./file-kind.mjs\";\nexport { SandboxEntryType } from \"./file-kind.mjs\";\nimport type { HostedBindingsIface } from \"../hosted-bindings.mjs\";\nimport { createSandboxHandle, type SandboxExecutionPolicyIface } from \"./handle.mjs\";\nimport { withSandboxOverrides } from \"./overrides.mjs\";\nimport { WorkspaceNetworkPolicy as NetworkPolicy } from '@finalai/agent-protocol/device-egress';\nimport type {\n WorkspaceEgressRequestIface,\n WorkspaceEgressStatusIface,\n WorkspaceNetworkPolicyIface as NetworkPolicyIface,\n} from '@finalai/agent-protocol/device-egress';\nexport {\n WorkspaceNetworkPolicy as NetworkPolicy,\n type WorkspaceNetworkPolicyIface as NetworkPolicyIface,\n} from '@finalai/agent-protocol/device-egress';\nimport type {\n ProcessInspectionRequestIface,\n ProcessInspectionResultIface,\n} from '@finalai/agent-protocol/process-inspection';\nimport type { JsonValue } from \"../json.mjs\";\nimport type { ToolDescriptorIface } from \"../manifest.mjs\";\nimport {\n SandboxEditorOperation,\n type SandboxEditorRequestIface,\n type SandboxEditorResultIface,\n} from \"./editor.mjs\";\nimport { SandboxExecutionOperation } from \"./execution-guard.mjs\";\nimport { awaitableOpenRequest, type AwaitableSandboxOpenRequestIface } from \"./open-scope.mjs\";\nimport type { SandboxSnapshotRequestIface, SandboxSnapshotResponseIface } from \"./snapshots.mjs\";\n\n// Sandbox providers and consumers share the streaming session contract.\n\nexport interface AbortableIface {\n abortSignal?: AbortSignal;\n}\n\nexport interface SandboxProcessOptionsIface extends AbortableIface {\n command: string;\n args?: string[];\n cwd?: string;\n env?: Record<string, string>;\n // Run through the sandbox's login shell (`bash -lc`) instead of exec'ing.\n shell?: boolean;\n stdin?: ReadableStream<Uint8Array> | string;\n timeoutMs?: number;\n // Spawn only (`run` ignores it): ask for a durable process on a sandbox with\n // SandboxCapability.DurableProcesses; ignored elsewhere (the handle's `ref`\n // is then null). A durable process ends only on its own exit, `kill`,\n // `timeoutMs` (enforced inside the sandbox, not by a provider-side timer) or\n // sandbox stop/destroy. Dropping its handle (connection close, runtime\n // shutdown, `abortSignal`) detaches without killing: the handle's streams\n // fail and `wait` rejects, and `attachProcess` finds the process again.\n durable?: boolean;\n}\n\nexport interface SandboxProcessIface {\n readonly pid: string | null;\n // Opaque, provider-encoded (versioned) reference for `attachProcess`; non-null\n // only for a durable process on a sandbox with durable processes. Optional so\n // implementations without them need not set it.\n readonly ref?: string | null;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n // Writes to the process's stdin; closes stdin when `end` is true.\n write(data: Uint8Array | string, options?: { end?: boolean }): Promise<void>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\nexport interface SandboxAttachProcessOptionsIface extends AbortableIface {\n ref: string;\n // Bytes of each stream the caller already has; output resumes there.\n stdoutOffset: number;\n stderrOffset: number;\n}\n\n// A durable process found again by its ref. Its output is read from the\n// provider, which is the source of truth for output and exit; aborting\n// `abortSignal` detaches this handle as it does a spawned durable one.\n//\n// Limitation: stdin belongs to the spawning handle only. A re-attached\n// process can be watched, waited for and killed, but not written to; a process\n// that needs input after a re-attach must read it from somewhere else (a file).\nexport interface SandboxAttachedProcessIface {\n readonly ref: string;\n // Where the streams actually start: the requested offsets, or later when the\n // provider no longer retains the earlier bytes (see each provider's retention).\n readonly stdoutOffset: number;\n readonly stderrOffset: number;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\nexport interface SandboxRunResultIface {\n exitCode: number;\n stdout: string;\n stderr: string;\n}\n\nexport interface StatIface {\n path: string;\n type: SandboxEntryType;\n size: number;\n modifiedAt: string | null;\n mode: number | null;\n}\n\nexport interface DirEntryIface {\n name: string;\n path: string;\n type: SandboxEntryType;\n size: number | null;\n}\n\nexport interface ConfinedSandboxFilesIface {\n readFile(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n stat(options: { path: string; root: string } & AbortableIface): Promise<StatIface | null>;\n readDir(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<DirEntryIface[] | null>;\n}\n\nexport interface SandboxSessionIface {\n readonly description: string;\n readonly confinedFileReader?: ConfinedSandboxFilesIface;\n // On the RPC surface, root confines viewer reads to this directory, rejects\n // symlink ancestors and requires Python 3 in the sandbox (confinedFiles feature).\n readFile(\n options: { path: string; root?: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n readBinaryFile(options: { path: string } & AbortableIface): Promise<Uint8Array | null>;\n readTextFile(\n options: {\n path: string;\n encoding?: string;\n startLine?: number;\n endLine?: number;\n } & AbortableIface,\n ): Promise<string | null>;\n writeFile(\n options: { path: string; content: ReadableStream<Uint8Array> } & AbortableIface,\n ): Promise<void>;\n writeBinaryFile(options: { path: string; content: Uint8Array } & AbortableIface): Promise<void>;\n // Writes create missing parent directories.\n writeTextFile(\n options: { path: string; content: string; encoding?: string } & AbortableIface,\n ): Promise<void>;\n spawn(options: SandboxProcessOptionsIface): Promise<SandboxProcessIface>;\n // Present on sandboxes with durable processes. Null when the process is\n // unknown: the sandbox restarted or was deleted, or the ref expired, is\n // malformed or belongs to another sandbox. Attaching after the process\n // exited still yields its retained output and exit code.\n attachProcess?(\n options: SandboxAttachProcessOptionsIface,\n ): Promise<SandboxAttachedProcessIface | null>;\n run(options: SandboxProcessOptionsIface): Promise<SandboxRunResultIface>;\n stat(options: { path: string; root?: string } & AbortableIface): Promise<StatIface | null>;\n readDir(options: { path: string; root?: string } & AbortableIface): Promise<DirEntryIface[]>;\n resolvePath(path: string): string;\n removePath(\n options: { path: string; recursive?: boolean; force?: boolean } & AbortableIface,\n ): Promise<void>;\n}\n\nexport enum PortProtocol {\n Http = 'http',\n Https = 'https',\n Ws = 'ws',\n}\n\n// An MCP transport the sandbox serves for an optional capability: an HTTP MCP\n// endpoint the harness (or the host) can dial.\nexport interface McpEndpointIface {\n name: string;\n url: string;\n headers: Record<string, string>;\n}\n\n// A JSON-RPC message channel to an MCP server the sandbox hosts, for backends\n// whose API reaches it some other way than HTTP MCP (a byte pipe, a socket).\n// Messages are JSON-RPC objects, in order.\nexport interface McpChannelIface {\n send(message: JsonValue, options?: AbortableIface): Promise<void>;\n // The messages that arrived since the last call; [] when none did.\n receive(options?: AbortableIface): Promise<JsonValue[]>;\n close(): Promise<void>;\n}\n\n// An MCP server the sandbox hosts, opened in process by whoever runs the handle.\n// It cannot cross the handle RPC wire.\nexport interface McpChannelEndpointIface {\n name: string;\n connect(options?: AbortableIface): Promise<McpChannelIface>;\n}\n\nexport type SandboxMcpEndpoint = McpEndpointIface | McpChannelEndpointIface;\n\n// The tools of a sandbox's hosted MCP servers, as far as they are known without\n// starting it. Null: unknown until the sandbox is attached and asked.\nexport interface SandboxMcpCatalogIface {\n computerUse: ToolDescriptorIface[] | null;\n // Local MCP server name \u2192 its tools.\n localMcp: Record<string, ToolDescriptorIface[]> | null;\n // Partial discovery retains known tools and must be retried, including after caching.\n localMcpIncomplete?: boolean;\n}\n\nexport const isMcpChannelEndpoint = (\n endpoint: SandboxMcpEndpoint,\n): endpoint is McpChannelEndpointIface => 'connect' in endpoint;\n\nexport interface ScreenOptionsIface {\n // View-only by default; explicit input control requires execute access.\n viewOnly?: boolean;\n}\n\nexport interface ScreenSessionIface {\n // A short-lived viewer grant; providers enforce the requested input access.\n url: string;\n token: string;\n expiresAt: string;\n}\n\nexport interface NetworkSandboxSessionIface extends SandboxSessionIface {\n readonly id: string;\n readonly defaultWorkingDirectory: string;\n readonly ports: readonly number[];\n getPortEndpoint(options: {\n port: number;\n protocol?: PortProtocol;\n }): Promise<{ url: string; headers?: Record<string, string> }>;\n getPortUrl(options: { port: number; protocol?: PortProtocol }): Promise<string>;\n stop(): Promise<void>;\n destroy(): Promise<void>;\n setNetworkPolicy?(policy: NetworkPolicyIface): Promise<void>;\n egress?(request: WorkspaceEgressRequestIface): Promise<WorkspaceEgressStatusIface>;\n computerUse?(): Promise<SandboxMcpEndpoint>;\n screen?(options?: ScreenOptionsIface): Promise<ScreenSessionIface>;\n localMcp?(): Promise<SandboxMcpEndpoint[]>;\n}\n\n// Capabilities a started sandbox advertises (and the handle RPC exposes).\nexport enum SandboxCapability {\n Files = 'files',\n Process = 'process',\n Ports = 'ports',\n NetworkPolicy = 'networkPolicy',\n Egress = 'egress',\n ComputerUse = 'computerUse',\n Screen = 'screen',\n LocalMcp = 'localMcp',\n Browser = 'browser',\n // `spawn({ durable: true })` and `attachProcess` (see SandboxProcessOptionsIface.durable).\n DurableProcesses = 'durableProcesses',\n}\n\nexport interface SandboxProviderHandleIface<S extends SandboxSessionIface> {\n readonly sandbox: S;\n // Pending policy; the generic handle constructor consumes it before exposing execution.\n readonly executionPolicy?: SandboxExecutionPolicyIface;\n onSandboxStop(): Promise<void>;\n onSandboxDelete(options?: { reason?: string }): Promise<void>;\n onRuntimeShutdown(): Promise<void>;\n}\n\n// A saved computer setup guide version: Build's versioned build-\n// and start-time inputs for a sandbox, as the host serves them.\nexport interface SandboxGuideVersionIface {\n guideId: string;\n versionId: string;\n slug: string;\n title: string;\n number: number;\n image: string;\n // `.final/sandbox-template.yaml` v2 as JSON.\n templateConfig: JsonValue;\n // The start-time parameters this version defaults to.\n defaultParameters: JsonValue;\n instructionsMarkdown: string | null;\n // A ready build from the guide's provider, reusable independently of workspace seeds.\n preparedArtifact?: { providerRef: string; key: string; artifact: JsonValue };\n}\n\n// The organization's computer setup guides, read through the host.\n// Every provider gets the same reader; a provider whose\n// environments name no guide never calls it.\nexport interface SandboxGuidesIface {\n get(args: { ref: string; version: number | 'latest' }): Promise<SandboxGuideVersionIface | null>;\n // The organization's default guide; null when it has none.\n default(): Promise<SandboxGuideVersionIface | null>;\n}\n\n// Where to clone a repository from, with a short-lived read credential that\n// must reach only the clone process (never a repository's git config).\nexport interface SandboxRepositoryCloneSourceIface {\n url: string;\n // Checked out after the clone; null keeps the default branch.\n ref: string | null;\n // An HTTP Authorization header value for the clone, or null.\n authorization: string | null;\n}\n\n// Repository credentials for the repositories an environment names (a Final\n// repository id, a GitHub owner/name), resolved by the host for the session's\n// organization only. Null: not a repository it can resolve.\nexport interface SandboxRepositoriesIface {\n cloneSource(args: {\n repository: string;\n ref: string | null;\n }): Promise<SandboxRepositoryCloneSourceIface | null>;\n}\n\n// Reads a named variable (a secret managed in Build) for the session. Values are\n// injected into the sandbox only, never stored in a manifest, a state or the log.\nexport interface SandboxVariablesIface {\n get(name: string): Promise<string | null>;\n}\n\nexport const noSandboxGuides: SandboxGuidesIface = {\n get: async () => null,\n default: async () => null,\n};\n\nexport const noSandboxRepositories: SandboxRepositoriesIface = {\n cloneSource: async () => null,\n};\n\nexport const noSandboxVariables: SandboxVariablesIface = { get: async () => null };\n\n// The user a session acts for: the author of its running turn, else its owner,\n// else the user whose Home its conversation is. A call a person makes through\n// the platform's sandbox viewer acts for that person instead. Null when it acts\n// for no user (a turn nobody prompted in a shared conversation) and outside any\n// session (a guide build). Read on each call, because it changes between turns\n// and between callers.\nexport interface SandboxActingUserIface {\n current(): Promise<string | null>;\n}\n\nexport const noSandboxActingUser: SandboxActingUserIface = { current: async () => null };\n\n// Access to a Final API: its origin and a short-lived bearer token. The token\n// determines the organization and project, so requests name neither.\nexport interface FinalPlatformAccessIface {\n // The API origin; requests go to `<baseUrl>/v1/...`.\n baseUrl: string;\n token: string;\n}\n\n// Credentials the host supplies with a sandbox context. Providers read no secrets\n// and name no project themselves.\nexport interface SandboxCredentialsIface {\n // Access to the Computers API (the `computer` sandbox); null when the host grants\n // none. `refresh` asks for a new token after the API rejected the last one.\n computersAccess(args?: { refresh?: boolean }): Promise<FinalPlatformAccessIface | null>;\n // Access to the Device API (the `device` sandbox and workspace Device egress),\n // acting for `actingUserId` when given (null or absent: service access for\n // workspace networking); null when the host grants none.\n deviceAccess(args?: {\n actingUserId?: string | null;\n refresh?: boolean;\n }): Promise<FinalPlatformAccessIface | null>;\n // The value of the secret a provider's `credential.secretRef` names; null when it\n // is not set.\n secret(args: { secretRef: string }): Promise<string | null>;\n}\n\nexport const noSandboxCredentials: SandboxCredentialsIface = {\n computersAccess: async () => null,\n deviceAccess: async () => null,\n secret: async () => null,\n};\n\n// What an environment's pre-start reads (capabilities, mcpCatalog) are given.\nexport interface SandboxOfferContextIface {\n executionPolicy?: SandboxExecutionPolicyIface;\n platformNetworkPolicy?: (policy: NetworkPolicyIface) => Promise<void>;\n // Retain platform transport access when an extension restores an allowlist.\n platformEgressHosts?: string[];\n // Logical identity when inspecting an existing workspace or opening an execution extension.\n workspaceId?: string;\n bindings?: HostedBindingsIface;\n organizationId: string;\n credentials?: SandboxCredentialsIface;\n actingUser: SandboxActingUserIface;\n}\n\n// What an environment's hooks are given before anything starts.\nexport interface SandboxEnvironmentContextIface {\n bindings?: HostedBindingsIface;\n organizationId: string;\n guides: SandboxGuidesIface;\n}\n\n// Scoped by the host to this organization and provider. Providers can retain\n// reusable intermediate artifacts independently of a revision's seed files.\nexport interface SandboxArtifactsIface {\n get(key: string): Promise<JsonValue | null>;\n put(key: string, artifact: JsonValue): Promise<void>;\n}\n\nexport interface SandboxPreparationSourceIface {\n sourceRevision: string;\n read(): Promise<{ files: Record<string, string>; resources: Record<string, JsonValue> }>;\n}\n\nexport interface SandboxPrepareContextIface {\n bindings?: HostedBindingsIface;\n // A host-persisted resource source; artifacts may retain its identity instead of seed contents.\n preparation?: SandboxPreparationSourceIface;\n artifacts?: SandboxArtifactsIface;\n // Agent revisions supply workspace-relative seeds; setup-guide builds supply\n // guide.json and optional instructions.md. Resources name workspace, skills or guide.\n // Model instructions remain harness config.\n files: Record<string, string>;\n resources: Record<string, JsonValue>;\n sourceRevision: string;\n storagePath: string;\n organizationId: string;\n credentials?: SandboxCredentialsIface;\n // The guide inputs (build-time) an environment names, resolved by the platform.\n guides: SandboxGuidesIface;\n // Who the session the artifact is prepared for acts for, for environments that\n // name a backend resource relative to that user; the key must then name it.\n actingUser: SandboxActingUserIface;\n log?: (message: string) => void;\n}\n\nexport interface SandboxStartContextIface {\n // Host policy composes before the provider's policy, on every exposed execution path.\n executionPolicy?: SandboxExecutionPolicyIface;\n bindings?: HostedBindingsIface;\n /** Passive recovery only: never wake, create, seed, or restart backend services. */\n passive?: boolean;\n preparation?: SandboxPreparationSourceIface;\n session: {\n id: string;\n organizationId: string;\n conversationId: string | null;\n definitionId: string;\n bindingId: string;\n // Stable logical identity supplied by the host, independent of provider resource names.\n workspaceId?: string;\n target: string;\n };\n credentials?: SandboxCredentialsIface;\n storagePath: string;\n // Start-time inputs: guides, the variables to inject, repository credentials.\n guides: SandboxGuidesIface;\n variables: SandboxVariablesIface;\n repositories: SandboxRepositoriesIface;\n actingUser: SandboxActingUserIface;\n // Variables the platform sets in every process of this sandbox: the egress\n // proxy, trust for its CA, and one placeholder per bound secret. Evaluated\n // again for every spawn/run, never once per session: a secret bound\n // mid-session must reach the next command. May resolve to {} (no proxy\n // configured, or not ready yet). Platform values override the spec's env.\n platformEnvironment?: () => Promise<Record<string, string>>;\n // Hosts the sandbox must be able to reach for the proxy to work, to append\n // to any allowlist-mode network policy the spec declares.\n platformEgressHosts?: string[];\n // Reports the network policy now in force on the sandbox, exactly as the\n // provider applied it to its backend (after withPlatformEgressHosts). The\n // platform permits only those destinations.\n // Called after awaitRunning and before platformFiles or any command, on start,\n // resume and a reused sandbox; never for a session's own setNetworkPolicy,\n // which the platform records itself. A rejection fails the start or resume.\n platformNetworkPolicy: (policy: NetworkPolicyIface) => Promise<void>;\n // Files the platform needs in the sandbox before any clone, setup step or\n // service runs: written right after the sandbox exists, on start and resume.\n // Paths are absolute; missing parent directories are created.\n platformFiles?: () => Promise<Record<string, string>>;\n}\n\n// The variables `platformEnvironment` owns. A spec that sets one (as a plain\n// value or a named variable) is refused at start.\nexport const PLATFORM_ENVIRONMENT_NAMES: ReadonlySet<string> = new Set([\n 'HTTPS_PROXY',\n 'HTTP_PROXY',\n 'NO_PROXY',\n 'NODE_USE_ENV_PROXY',\n 'SSL_CERT_FILE',\n 'CURL_CA_BUNDLE',\n 'REQUESTS_CA_BUNDLE',\n 'GIT_SSL_CAINFO',\n 'CARGO_HTTP_CAINFO',\n 'DENO_CERT',\n 'NODE_EXTRA_CA_CERTS',\n 'FINAL_EGRESS_URL',\n 'FINAL_EGRESS_TOKEN',\n 'GH_TOKEN',\n 'GITHUB_TOKEN',\n]);\n\n// A process's base environment: the spec's variables under the platform's,\n// read again on every call.\nexport const platformProcessEnvironment =\n (\n ctx: Pick<SandboxStartContextIface, 'platformEnvironment'>,\n specEnv: Record<string, string>,\n ): (() => Promise<Record<string, string>>) =>\n async () => ({ ...specEnv, ...(await ctx.platformEnvironment?.()) });\n\n// Writes `platformFiles` into a sandbox that now exists, before it runs anything.\n// Relies on writeTextFile creating missing parent directories.\nexport const writePlatformFiles = async (\n ctx: Pick<SandboxStartContextIface, 'platformFiles'>,\n sandbox: Pick<SandboxSessionIface, 'writeTextFile'>,\n): Promise<void> => {\n for (const [path, content] of Object.entries((await ctx.platformFiles?.()) ?? {}))\n await sandbox.writeTextFile({ path, content });\n};\n\n// Reports the policy a provider just applied to its backend: `allow` only for an\n// allowlist, its entries (hosts, `*.suffix` patterns, CIDRs) unchanged.\nexport const reportPlatformNetworkPolicy = async (\n ctx: Pick<SandboxStartContextIface, 'platformNetworkPolicy'>,\n policy: NetworkPolicyIface,\n): Promise<void> =>\n ctx.platformNetworkPolicy(\n policy.mode === NetworkPolicy.Allowlist\n ? { mode: policy.mode, allow: [...(policy.allow ?? [])] }\n : { mode: policy.mode },\n );\n\n// An allowlist policy with the platform's egress hosts appended; any other\n// policy unchanged.\nexport const withPlatformEgressHosts = (\n ctx: Pick<SandboxStartContextIface, 'platformEgressHosts'>,\n policy: NetworkPolicyIface,\n): NetworkPolicyIface => {\n const hosts = ctx.platformEgressHosts ?? [];\n if (policy.mode !== NetworkPolicy.Allowlist || hosts.length === 0) return policy;\n return { ...policy, allow: [...new Set([...(policy.allow ?? []), ...hosts])] };\n};\n\nexport enum SandboxSessionEndReason {\n Completed = 'completed',\n Expired = 'expired',\n Failed = 'failed',\n}\n\n// How long an environment's sandbox outlives a session: `session`\n// keeps it for the session's life; `conversation` gives every session in the\n// conversation one shared sandbox per target, surviving session resets;\n// `ephemeral` discards it when released.\nexport enum SandboxWorkspace {\n Session = 'session',\n Conversation = 'conversation',\n Ephemeral = 'ephemeral',\n}\n\nexport interface SandboxProviderImplementationIface<\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n // The workspace this environment declares, read before anything starts so the\n // host knows which sessions share a binding. Absent or null: session.\n workspace?(ctx: SandboxEnvironmentContextIface): Promise<SandboxWorkspace | null>;\n // The capabilities this environment's sandboxes offer, read before anything\n // starts through the backend's own API. Absent or null: unknown\n // until started; local MCP is then not projected.\n capabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;\n // Known positive offers when the rest of the pre-start capability set is unknown.\n additionalCapabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[]>;\n // The hosted MCP servers' tool catalogs the backend can give without starting\n // a sandbox (from its own records), so the MCP projection lists them from the\n // first `tools/list`. The projection checks a server's catalog against the\n // live server when a call first opens that server (servers a session never\n // uses stay closed) and announces a change with\n // `notifications/tools/list_changed`.\n //\n // Trade-off: a catalog left unknown (absent hook, null, or a null field) can\n // only be learned from the live sandbox, so the first `tools/list` that finds\n // it unknown starts the sandbox in the background, at session start rather\n // than on the first tool call. Otherwise those tools would never be listed,\n // and nothing would ever call them. Providers that can give the catalog keep\n // attach lazy.\n mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;\n // Reads committed files without starting/resuming a sandbox. Null means the backend\n // is live or offers no snapshot. An unavailable sleeping snapshot must throw,\n // never fall through to a read that wakes it. Pin subsequent ranges by snapshotId.\n readSnapshot?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxSnapshotRequestIface,\n ): Promise<SandboxSnapshotResponseIface | null>;\n // Inspect retained backend processes without opening, resuming or extending a sandbox.\n // Stop requires execute access; the provider also enforces backend ownership.\n processes?(\n ctx: SandboxOfferContextIface & { bindingId: string },\n state: State,\n request: ProcessInspectionRequestIface,\n ): Promise<ProcessInspectionResultIface>;\n // Browser editor for this provider's existing workspace. The host checks write\n // authorization; this hook never creates or wakes a backend. Credentials stay\n // in the authentication form, never the editor URL or stored provider state.\n editor?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxEditorRequestIface,\n ): Promise<SandboxEditorResultIface>;\n // Content-addressed by `artifactKey`; the host caches artifacts and calls\n // prepare only on a miss.\n artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;\n prepare(ctx: SandboxPrepareContextIface): Promise<Artifact>;\n // Resolves once the backend sandbox named by `state` is running and will\n // accept a command or a file write; rejects with a clear error after\n // `timeoutMs`. Backend-specific: the provider chooses the readiness signal,\n // the polling cadence and the backoff for its API's rate limits. The\n // platform never polls a backend itself.\n //\n // `start`, `resume` and `resumePassive` call it on the sandbox they just\n // created, started or reused, before anything touches it: create or start \u2192\n // state \u2192 awaitRunning \u2192 platformNetworkPolicy \u2192 platformFiles \u2192 repositories,\n // seeds, setup, services \u2192 handle. On timeout `start` fails and tears down.\n awaitRunning(\n ctx: SandboxStartContextIface,\n state: State,\n options: { timeoutMs: number },\n ): Promise<void>;\n // `region`: where the backend placed the sandbox (its own region name), so the\n // host can place the harness near it; null when unknown.\n start(\n ctx: SandboxStartContextIface,\n options: OpenOptions | undefined,\n artifact: Artifact,\n ): Promise<{ handle: SandboxProviderHandleIface<S>; state: State; region?: string | null }>;\n resume(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Reconnect to an already running backend after host restart for a read-only viewer.\n // Absent: viewers can use a retained live handle but cannot trigger resume.\n resumePassive?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Park: pause or stop the sandbox, returning the state resume needs.\n park?(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<State>;\n onSessionEnd?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n options: { reason: SandboxSessionEndReason },\n ): Promise<void>;\n}\n\nexport interface SandboxProviderDefinitionIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n name: string;\n // The version of `State`'s shape. The host records it with each\n // binding and refuses to resume a state written under another version (the\n // next call starts the sandbox again instead).\n stateProtocolVersion?: number;\n environment(\n options?: EnvOptions,\n ): SandboxProviderImplementationIface<OpenOptions, Artifact, State, S>;\n}\n\n// A defined provider: the definition plus authoring sugar. `environment(opts)`\n// returns an environment whose `.open(openOptions)` records a sandbox binding\n// target when authored, and is what the host drives at run time.\nexport interface SandboxProviderIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n readonly definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>;\n readonly name: string;\n environment(options?: EnvOptions): AwaitableSandboxEnvironmentIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly options: EnvOptions | undefined;\n // Provider-authored notices shown by the compiler and Build before publication.\n readonly authoringWarnings?: readonly string[];\n // Authoring: records the open options (access, ...) for this target.\n open(options?: OpenOptions): SandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\n// An environment whose open request a sandbox.ts selector can await to get\n// the live session (open-scope.ts); what defineSandboxProvider and the\n// installed helpers return.\nexport interface AwaitableSandboxEnvironmentIface<\n EnvOptions,\n OpenOptions,\n> extends SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n open(options?: OpenOptions): AwaitableSandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxOpenRequestIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly environmentOptions: EnvOptions | undefined;\n readonly openOptions: OpenOptions | undefined;\n readonly authoringWarnings?: readonly string[];\n}\n\nexport const defineSandboxProvider = <\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n>(\n definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>,\n): SandboxProviderIface<EnvOptions, OpenOptions, Artifact, State, S> => ({\n definition: withSandboxOverrides(definition, {\n environment: (options?: EnvOptions) => {\n const implementation = definition.environment(options);\n if (typeof implementation.awaitRunning !== 'function')\n throw new Error(`sandbox provider ${definition.name} does not implement awaitRunning`);\n const overrides: Partial<typeof implementation> = {\n start: async (ctx, openOptions, artifact) => {\n const started = await implementation.start(ctx, openOptions, artifact);\n return {\n ...started,\n handle: createSandboxHandle({\n handle: started.handle,\n executionPolicy: ctx.executionPolicy,\n }),\n };\n },\n resume: async (ctx, artifact, state) =>\n createSandboxHandle({\n handle: await implementation.resume(ctx, artifact, state),\n executionPolicy: ctx.executionPolicy,\n }),\n };\n if (implementation.editor != null) {\n const editor = implementation.editor.bind(implementation);\n overrides.editor = async (ctx, state, request) => {\n if (\n request.operation === SandboxEditorOperation.Open ||\n request.operation === SandboxEditorOperation.Refresh\n )\n await ctx.executionPolicy?.beforeExecution({\n operation: SandboxExecutionOperation.Editor,\n background: false,\n });\n return editor(ctx, state, request);\n };\n }\n if (implementation.resumePassive != null) {\n const resumePassive = implementation.resumePassive.bind(implementation);\n overrides.resumePassive = async (ctx, artifact, state) =>\n createSandboxHandle({\n handle: await resumePassive(ctx, artifact, state),\n executionPolicy: ctx.executionPolicy,\n });\n }\n return withSandboxOverrides(implementation, overrides);\n },\n }),\n name: definition.name,\n environment: (options) => ({\n providerName: definition.name,\n options,\n open: (openOptions) =>\n awaitableOpenRequest({\n providerName: definition.name,\n environmentOptions: options,\n openOptions,\n }),\n }),\n});\n\n// Erased form a host stores in its provider registry.\nexport type AnySandboxProviderIface = SandboxProviderIface<\n JsonValue,\n JsonValue,\n JsonValue,\n JsonValue,\n NetworkSandboxSessionIface\n>;\n\n// Events emitted through a sandbox provider's process lifecycle.\nexport enum SandboxEventKind {\n ProcessExited = 'process_exited',\n}\n"],
5
- "mappings": "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",
6
- "names": ["SandboxEntryType", "PortProtocol", "SandboxCapability", "SandboxSessionEndReason", "SandboxWorkspace", "SandboxEventKind"]
4
+ "sourcesContent": ["import { Capability, RuntimeKind, type CapabilityAccess } from '@finalai/agent-protocol';\nimport * as z from 'zod';\nimport { SandboxEntryType } from \"./file-kind.mjs\";\nexport { SandboxEntryType } from \"./file-kind.mjs\";\nimport { createSandboxHandle, type SandboxExecutionPolicyIface } from \"./handle.mjs\";\nimport { withSandboxOverrides } from \"./overrides.mjs\";\nimport { WorkspaceNetworkPolicy as NetworkPolicy } from '@finalai/agent-protocol/device-egress';\nimport type {\n WorkspaceEgressRequestIface,\n WorkspaceEgressStatusIface,\n WorkspaceNetworkPolicyIface as NetworkPolicyIface,\n} from '@finalai/agent-protocol/device-egress';\nexport {\n WorkspaceNetworkPolicy as NetworkPolicy,\n type WorkspaceNetworkPolicyIface as NetworkPolicyIface,\n} from '@finalai/agent-protocol/device-egress';\nimport type {\n ProcessInspectionRequestIface,\n ProcessInspectionResultIface,\n} from '@finalai/agent-protocol/process-inspection';\nimport type { JsonValue } from \"../json.mjs\";\nimport type { ToolDescriptorIface } from \"../tool-descriptor.mjs\";\nimport {\n SandboxEditorOperation,\n type SandboxEditorRequestIface,\n type SandboxEditorResultIface,\n} from \"./editor.mjs\";\nimport { SandboxExecutionOperation } from \"./execution-guard.mjs\";\nimport type { SandboxSetupIface } from \"./setup/schema.mjs\";\nimport type { SandboxSnapshotRequestIface, SandboxSnapshotResponseIface } from \"./snapshots.mjs\";\n\n// Sandbox providers and consumers share the streaming session contract.\n\nexport interface AbortableIface {\n abortSignal?: AbortSignal;\n}\n\nexport interface SandboxProcessOptionsIface extends AbortableIface {\n command: string;\n args?: string[];\n cwd?: string;\n env?: Record<string, string>;\n // Run through the sandbox's login shell (`bash -lc`) instead of exec'ing.\n shell?: boolean;\n stdin?: ReadableStream<Uint8Array> | string;\n timeoutMs?: number;\n // Spawn only (`run` ignores it): ask for a durable process on a sandbox with\n // SandboxCapability.DurableProcesses; ignored elsewhere (the handle's `ref`\n // is then null). A durable process ends only on its own exit, `kill`,\n // `timeoutMs` (enforced inside the sandbox, not by a provider-side timer) or\n // sandbox stop/destroy. Dropping its handle (connection close, runtime\n // shutdown, `abortSignal`) detaches without killing: the handle's streams\n // fail and `wait` rejects, and `attachProcess` finds the process again.\n durable?: boolean;\n}\n\nexport interface SandboxProcessIface {\n readonly pid: string | null;\n // Opaque, provider-encoded (versioned) reference for `attachProcess`; non-null\n // only for a durable process on a sandbox with durable processes. Optional so\n // implementations without them need not set it.\n readonly ref?: string | null;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n // Writes to the process's stdin; closes stdin when `end` is true.\n write(data: Uint8Array | string, options?: { end?: boolean }): Promise<void>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\n// A program built for the sandbox's worker runtime, started for one harness\n// session. Its handle is a process's: what is written to it is its input\n// stream, stdout its output stream, stderr its diagnostics.\nexport interface SandboxWorkerOptionsIface extends AbortableIface {\n program: string;\n env?: Record<string, string>;\n // Handed to the program when it starts.\n input?: JsonValue;\n // As for spawn: survives the handle on a sandbox with durable processes.\n durable?: boolean;\n // A platform-identity assertion for the program's run (variant `harness-run`),\n // for a runtime that authenticates the programs it starts.\n identity?: string;\n}\n\nexport enum SandboxWorkerEndpointTransport {\n Ws = 'ws',\n Http = 'http',\n Relay = 'relay',\n}\n\n// Where a started worker program serves its stream itself, for the caller to\n// dial directly: an ACP endpoint by URL, or a relay channel.\nexport type SandboxWorkerEndpointType =\n | {\n transport: SandboxWorkerEndpointTransport.Ws | SandboxWorkerEndpointTransport.Http;\n url: string;\n headers: Record<string, string>;\n }\n | { transport: SandboxWorkerEndpointTransport.Relay; channel: string; token: string };\n\nexport interface SandboxWorkerEndpointIface {\n readonly endpoint: SandboxWorkerEndpointType;\n}\n\n// A started worker program: a process whose streams carry its stream, or an\n// endpoint it serves.\nexport type SandboxWorkerStartType = SandboxProcessIface | SandboxWorkerEndpointIface;\n\nexport const isSandboxWorkerEndpoint = (\n started: SandboxWorkerStartType,\n): started is SandboxWorkerEndpointIface => 'endpoint' in started;\n\nexport interface SandboxAttachProcessOptionsIface extends AbortableIface {\n ref: string;\n // Bytes of each stream the caller already has; output resumes there.\n stdoutOffset: number;\n stderrOffset: number;\n}\n\n// A durable process found again by its ref. Its output is read from the\n// provider, which is the source of truth for output and exit; aborting\n// `abortSignal` detaches this handle as it does a spawned durable one.\n//\n// Limitation: stdin belongs to the spawning handle only. A re-attached\n// process can be watched, waited for and killed, but not written to; a process\n// that needs input after a re-attach must read it from somewhere else (a file).\nexport interface SandboxAttachedProcessIface {\n readonly ref: string;\n // Where the streams actually start: the requested offsets, or later when the\n // provider no longer retains the earlier bytes (see each provider's retention).\n readonly stdoutOffset: number;\n readonly stderrOffset: number;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\nexport interface SandboxRunResultIface {\n exitCode: number;\n stdout: string;\n stderr: string;\n}\n\nexport interface StatIface {\n path: string;\n type: SandboxEntryType;\n size: number;\n modifiedAt: string | null;\n mode: number | null;\n}\n\nexport interface DirEntryIface {\n name: string;\n path: string;\n type: SandboxEntryType;\n size: number | null;\n}\n\nexport interface ConfinedSandboxFilesIface {\n readFile(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n stat(options: { path: string; root: string } & AbortableIface): Promise<StatIface | null>;\n readDir(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<DirEntryIface[] | null>;\n}\n\nexport interface SandboxSessionIface {\n readonly description: string;\n readonly confinedFileReader?: ConfinedSandboxFilesIface;\n // On the RPC surface, root confines viewer reads to this directory, rejects\n // symlink ancestors and requires Python 3 in the sandbox (confinedFiles feature).\n readFile(\n options: { path: string; root?: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n readBinaryFile(options: { path: string } & AbortableIface): Promise<Uint8Array | null>;\n readTextFile(\n options: {\n path: string;\n encoding?: string;\n startLine?: number;\n endLine?: number;\n } & AbortableIface,\n ): Promise<string | null>;\n writeFile(\n options: { path: string; content: ReadableStream<Uint8Array> } & AbortableIface,\n ): Promise<void>;\n writeBinaryFile(options: { path: string; content: Uint8Array } & AbortableIface): Promise<void>;\n // Writes create missing parent directories.\n writeTextFile(\n options: { path: string; content: string; encoding?: string } & AbortableIface,\n ): Promise<void>;\n spawn(options: SandboxProcessOptionsIface): Promise<SandboxProcessIface>;\n // Present on sandboxes with durable processes. Null when the process is\n // unknown: the sandbox restarted or was deleted, or the ref expired, is\n // malformed or belongs to another sandbox. Attaching after the process\n // exited still yields its retained output and exit code.\n attachProcess?(\n options: SandboxAttachProcessOptionsIface,\n ): Promise<SandboxAttachedProcessIface | null>;\n run(options: SandboxProcessOptionsIface): Promise<SandboxRunResultIface>;\n stat(options: { path: string; root?: string } & AbortableIface): Promise<StatIface | null>;\n readDir(options: { path: string; root?: string } & AbortableIface): Promise<DirEntryIface[]>;\n resolvePath(path: string): string;\n removePath(\n options: { path: string; recursive?: boolean; force?: boolean } & AbortableIface,\n ): Promise<void>;\n}\n\nexport enum PortProtocol {\n Http = 'http',\n Https = 'https',\n Ws = 'ws',\n}\n\n// An MCP transport the sandbox serves for an optional capability: an HTTP MCP\n// endpoint the harness (or the host) can dial.\nexport interface McpEndpointIface {\n name: string;\n url: string;\n headers: Record<string, string>;\n}\n\n// A JSON-RPC message channel to an MCP server the sandbox hosts, for backends\n// whose API reaches it some other way than HTTP MCP (a byte pipe, a socket).\n// Messages are JSON-RPC objects, in order.\nexport interface McpChannelIface {\n send(message: JsonValue, options?: AbortableIface): Promise<void>;\n // The messages that arrived since the last call; [] when none did.\n receive(options?: AbortableIface): Promise<JsonValue[]>;\n close(): Promise<void>;\n}\n\n// An MCP server the sandbox hosts, opened in process by whoever runs the handle.\n// It cannot cross the handle RPC wire.\nexport interface McpChannelEndpointIface {\n name: string;\n connect(options?: AbortableIface): Promise<McpChannelIface>;\n}\n\nexport type SandboxMcpEndpoint = McpEndpointIface | McpChannelEndpointIface;\n\n// The tools of a sandbox's hosted MCP servers, as far as they are known without\n// starting it. Null: unknown until the sandbox is attached and asked.\nexport interface SandboxMcpCatalogIface {\n computerUse: ToolDescriptorIface[] | null;\n // Local MCP server name \u2192 its tools.\n localMcp: Record<string, ToolDescriptorIface[]> | null;\n // Partial discovery retains known tools and must be retried, including after caching.\n localMcpIncomplete?: boolean;\n}\n\nexport const isMcpChannelEndpoint = (\n endpoint: SandboxMcpEndpoint,\n): endpoint is McpChannelEndpointIface => 'connect' in endpoint;\n\nexport interface ScreenOptionsIface {\n // View-only by default; explicit input control requires execute access.\n viewOnly?: boolean;\n}\n\nexport interface ScreenSessionIface {\n // A short-lived viewer grant; providers enforce the requested input access.\n url: string;\n token: string;\n expiresAt: string;\n}\n\nexport interface NetworkSandboxSessionIface extends SandboxSessionIface {\n readonly id: string;\n readonly defaultWorkingDirectory: string;\n readonly ports: readonly number[];\n getPortEndpoint(options: {\n port: number;\n protocol?: PortProtocol;\n }): Promise<{ url: string; headers?: Record<string, string> }>;\n getPortUrl(options: { port: number; protocol?: PortProtocol }): Promise<string>;\n stop(): Promise<void>;\n destroy(): Promise<void>;\n setNetworkPolicy?(policy: NetworkPolicyIface): Promise<void>;\n egress?(request: WorkspaceEgressRequestIface): Promise<WorkspaceEgressStatusIface>;\n computerUse?(): Promise<SandboxMcpEndpoint>;\n // Present on sandboxes whose provider offers RuntimeKind.Worker.\n startWorker?(options: SandboxWorkerOptionsIface): Promise<SandboxWorkerStartType>;\n screen?(options?: ScreenOptionsIface): Promise<ScreenSessionIface>;\n localMcp?(): Promise<SandboxMcpEndpoint[]>;\n}\n\n// Features a live sandbox handle advertises over the handle RPC (`describe`).\n// Finer than the model's capabilities (`Capability`): `files` is served by the\n// file methods, `shell` by processes and ports, `computerUse` by computer use\n// and the screen; the rest are handle extensions a capability may use.\nexport enum SandboxCapability {\n Files = 'files',\n Process = 'process',\n Ports = 'ports',\n NetworkPolicy = 'networkPolicy',\n Egress = 'egress',\n ComputerUse = 'computerUse',\n Screen = 'screen',\n LocalMcp = 'localMcp',\n Browser = 'browser',\n // `spawn({ durable: true })` and `attachProcess` (see SandboxProcessOptionsIface.durable).\n DurableProcesses = 'durableProcesses',\n // `startWorker`: the sandbox runs worker programs.\n Workers = 'workers',\n}\n\n// The capabilities a provider's sandboxes serve, each with the most access a\n// session can be granted on it. A capability left out is not served.\nexport type SandboxCapabilityOffer = Partial<Record<Capability, CapabilityAccess>>;\n\nexport interface SandboxProviderHandleIface<S extends SandboxSessionIface> {\n readonly sandbox: S;\n // Pending policy; the generic handle constructor consumes it before exposing execution.\n readonly executionPolicy?: SandboxExecutionPolicyIface;\n onSandboxStop(): Promise<void>;\n onSandboxDelete(options?: { reason?: string }): Promise<void>;\n onRuntimeShutdown(): Promise<void>;\n}\n\n// Where to clone a repository from, with a short-lived read credential that\n// must reach only the clone process (never a repository's git config).\nexport interface SandboxRepositoryCloneSourceIface {\n url: string;\n // Checked out after the clone; null keeps the default branch.\n ref: string | null;\n // An HTTP Authorization header value for the clone, or null.\n authorization: string | null;\n}\n\n// Clone sources for the repositories a sandbox setup names (`owner/name`, a\n// git URL), authorised against the sandbox's project. Null: not a repository\n// the project can reach.\nexport interface SandboxRepositoriesIface {\n cloneSource(args: {\n repository: string;\n ref: string | null;\n }): Promise<SandboxRepositoryCloneSourceIface | null>;\n}\n\nexport const noSandboxRepositories: SandboxRepositoriesIface = {\n cloneSource: async () => null,\n};\n\n// The person a sandbox acts for on this call: the author of the running turn,\n// else whoever opened the sandbox's viewer. Null when it acts for no person\n// (an unprompted turn, a preparation). Read on each call: it changes between\n// turns and between callers.\nexport interface SandboxActingUserIface {\n current(): Promise<string | null>;\n}\n\nexport const noSandboxActingUser: SandboxActingUserIface = { current: async () => null };\n\n// Credentials the host supplies to a provider. A provider reads no secrets of\n// its own and names no project: it gets the value of the secret its\n// environment's `credential.secretRef` names, resolved in the sandbox's project.\nexport interface SandboxCredentialsIface {\n secret(args: { secretRef: string }): Promise<string | null>;\n}\n\nexport const noSandboxCredentials: SandboxCredentialsIface = { secret: async () => null };\n\n// A provider's credential by reference, in its environment options: the name\n// of a project secret, never its value.\nexport const sandboxCredentialRefSchema = z.strictObject({\n secretRef: z.string().min(1).max(256),\n});\n\nexport type SandboxCredentialRefIface = z.infer<typeof sandboxCredentialRefSchema>;\n\n// A platform-identity assertion (`@finalai/agent-protocol/identity`) for one\n// backend audience, valid until `expiresAt`.\nexport interface SandboxIdentityTokenIface {\n token: string;\n expiresAt: string;\n}\n\n// How a provider authenticates to a backend it needs (its vendor's API): an\n// assertion for `audience`, which the platform issues only for audiences the\n// provider's registration was granted. It names the sandbox's organization,\n// project and sandbox, and the acting user at the time it was issued. Ask\n// before each backend call (hosts cache it); `refresh` asks for a new one\n// after the backend rejected the last.\nexport type SandboxIdentityFn = (args: {\n audience: string;\n refresh?: boolean;\n}) => Promise<SandboxIdentityTokenIface>;\n\nexport const noSandboxIdentity: SandboxIdentityFn = async ({ audience }) => {\n throw new Error(`no identity was granted for ${audience}`);\n};\n\n// What every provider call is given: the project the sandbox belongs to, the\n// host's credentials and the provider's identity for the backends it was\n// granted.\nexport interface SandboxProviderContextIface {\n organizationId: string;\n projectId: string;\n credentials: SandboxCredentialsIface;\n actingUser: SandboxActingUserIface;\n identity: SandboxIdentityFn;\n log?: (message: string, fields?: Record<string, string | number | boolean | null>) => void;\n}\n\n// How the platform runs a sandbox's lifecycle, for the provider to align its\n// backend with: after `parkAfterIdleMs` of idleness the platform parks the\n// sandbox (null: the provider's own default), so a backend idle timeout\n// should be longer.\nexport interface SandboxLifecycleIface {\n parkAfterIdleMs: number | null;\n}\n\n// What reads that start nothing are given (capabilities, catalogs, snapshots,\n// process inspection, the editor). `sandboxId` is set for reads about an\n// existing sandbox.\nexport interface SandboxOfferContextIface extends SandboxProviderContextIface {\n sandboxId?: string;\n executionPolicy?: SandboxExecutionPolicyIface;\n platformNetworkPolicy?: (policy: NetworkPolicyIface) => Promise<void>;\n // Retain platform transport access when an extension restores an allowlist.\n platformEgressHosts?: string[];\n}\n\n// Scoped by the host to this project and provider. Providers can retain\n// reusable intermediate artifacts independently of a sandbox's seed files.\nexport interface SandboxArtifactsIface {\n get(key: string): Promise<JsonValue | null>;\n put(key: string, artifact: JsonValue): Promise<void>;\n}\n\nexport interface SandboxPreparationSourceIface {\n sourceRevision: string;\n read(): Promise<{ files: Record<string, string>; resources: Record<string, JsonValue> }>;\n}\n\n// A preparation builds what an environment's sandboxes start from (an image\n// built into a base, a snapshot). It depends on the environment's options and\n// the seed files only, never on a sandbox setup.\nexport interface SandboxPrepareContextIface extends SandboxProviderContextIface {\n // A host-persisted resource source; artifacts may retain its identity instead of seed contents.\n preparation?: SandboxPreparationSourceIface;\n artifacts?: SandboxArtifactsIface;\n // Workspace-relative seed files and named resources.\n files: Record<string, string>;\n resources: Record<string, JsonValue>;\n sourceRevision: string;\n storagePath: string;\n}\n\n// What a provider is given for one sandbox: its create, attach, detach, park\n// and delete calls.\nexport interface SandboxResourceContextIface extends SandboxProviderContextIface {\n // The platform's id for the sandbox, stable for its whole life.\n sandboxId: string;\n lifecycle: SandboxLifecycleIface;\n // Host policy composes before the provider's policy, on every exposed execution path.\n executionPolicy?: SandboxExecutionPolicyIface;\n preparation?: SandboxPreparationSourceIface;\n storagePath: string;\n // Variables the platform sets in every process of this sandbox: the egress\n // proxy, trust for its CA, one placeholder per bound secret and the sandbox\n // setup's variables. Evaluated again for every spawn/run, never once per\n // attach: a secret bound later must reach the next command. May resolve to\n // {}. Platform values override the environment's own.\n platformEnvironment?: () => Promise<Record<string, string>>;\n // Hosts the sandbox must be able to reach for the proxy to work, appended\n // to any allowlist network policy.\n platformEgressHosts?: string[];\n // Reports the network policy now in force, exactly as the provider applied\n // it to its backend (after withPlatformEgressHosts); the platform permits\n // only those destinations. Called on every attach after awaitRunning and\n // before platformFiles or any command; never for a session's own\n // setNetworkPolicy. A rejection fails the attach.\n platformNetworkPolicy: (policy: NetworkPolicyIface) => Promise<void>;\n // Files the platform needs before any command runs: written right after the\n // sandbox is running, on every attach. Paths are absolute; missing parent\n // directories are created.\n platformFiles?: () => Promise<Record<string, string>>;\n}\n\n// The variables `platformEnvironment` owns. An environment that sets one is\n// refused at create.\nexport const PLATFORM_ENVIRONMENT_NAMES: ReadonlySet<string> = new Set([\n 'HTTPS_PROXY',\n 'HTTP_PROXY',\n 'NO_PROXY',\n 'NODE_USE_ENV_PROXY',\n 'SSL_CERT_FILE',\n 'CURL_CA_BUNDLE',\n 'REQUESTS_CA_BUNDLE',\n 'GIT_SSL_CAINFO',\n 'CARGO_HTTP_CAINFO',\n 'DENO_CERT',\n 'NODE_EXTRA_CA_CERTS',\n 'FINAL_EGRESS_URL',\n 'FINAL_EGRESS_TOKEN',\n 'GH_TOKEN',\n 'GITHUB_TOKEN',\n]);\n\n// A process's base environment: the environment's variables under the\n// platform's, read again on every call.\nexport const platformProcessEnvironment =\n (\n ctx: Pick<SandboxResourceContextIface, 'platformEnvironment'>,\n specEnv: Record<string, string>,\n ): (() => Promise<Record<string, string>>) =>\n async () => ({ ...specEnv, ...(await ctx.platformEnvironment?.()) });\n\n// Writes `platformFiles` into a sandbox that is now running, before it runs anything.\n// Relies on writeTextFile creating missing parent directories.\nexport const writePlatformFiles = async (\n ctx: Pick<SandboxResourceContextIface, 'platformFiles'>,\n sandbox: Pick<SandboxSessionIface, 'writeTextFile'>,\n): Promise<void> => {\n for (const [path, content] of Object.entries((await ctx.platformFiles?.()) ?? {}))\n await sandbox.writeTextFile({ path, content });\n};\n\n// Reports the policy a provider just applied to its backend: `allow` only for an\n// allowlist, its entries (hosts, `*.suffix` patterns, CIDRs) unchanged.\nexport const reportPlatformNetworkPolicy = async (\n ctx: Pick<SandboxResourceContextIface, 'platformNetworkPolicy'>,\n policy: NetworkPolicyIface,\n): Promise<void> =>\n ctx.platformNetworkPolicy(\n policy.mode === NetworkPolicy.Allowlist\n ? { mode: policy.mode, allow: [...(policy.allow ?? [])] }\n : { mode: policy.mode },\n );\n\n// An allowlist policy with the platform's egress hosts appended; any other\n// policy unchanged.\nexport const withPlatformEgressHosts = (\n ctx: Pick<SandboxResourceContextIface, 'platformEgressHosts'>,\n policy: NetworkPolicyIface,\n): NetworkPolicyIface => {\n const hosts = ctx.platformEgressHosts ?? [];\n if (policy.mode !== NetworkPolicy.Allowlist || hosts.length === 0) return policy;\n return { ...policy, allow: [...new Set([...(policy.allow ?? []), ...hosts])] };\n};\n\n// One attach of a sandbox: the live handle, and what the attach lost, so the\n// platform knows which phases of the sandbox setup to redo.\nexport interface SandboxAttachmentIface<\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n handle: SandboxProviderHandleIface<S>;\n // The state to keep for the next call (a resumed backend may change ids).\n state: State;\n // The disk is new: nothing written by a setup, the workspace seeds or a\n // session survives on it (first attach, or a backend that lost it).\n fresh: boolean;\n // The machine started on this attach: no process from before is running.\n booted: boolean;\n // Where the backend runs the sandbox (its own region name), so the host can\n // place the harness near it; null when unknown.\n region?: string | null;\n}\n\n// One environment of a provider, as the host drives it. A sandbox is a\n// resource the platform owns: `create` makes it (nothing need boot), `attach`\n// makes it reachable for a while, `detach` lets it go idle, `park` makes it as\n// cheap as the provider can while keeping its disk, `delete` destroys it.\n//\n// Order on attach: attach (boot or resume) \u2192 awaitRunning \u2192\n// platformNetworkPolicy \u2192 platformFiles \u2192 handle; the platform then applies\n// the sandbox setup through the handle (./setup). A provider never runs a\n// setup's steps itself.\nexport interface SandboxEnvironmentImplementationIface<\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n // The capabilities this environment's sandboxes serve and the most access\n // each grants, known without creating one.\n capabilities(ctx: SandboxOfferContextIface): Promise<SandboxCapabilityOffer>;\n // What a harness can run in this environment's sandboxes: processes, worker\n // programs (`startWorker`), or both. Absent: processes when it offers `shell`.\n runtimes?(ctx: SandboxOfferContextIface): Promise<RuntimeKind[]>;\n // Handle features this environment's sandboxes advertise, read before\n // anything starts. Absent or null: unknown until attached; local MCP is then\n // not projected.\n features?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;\n // Known positive features when the rest of the pre-attach set is unknown.\n additionalFeatures?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[]>;\n // The hosted MCP servers' tool catalogs the backend can give without\n // attaching, so the MCP projection lists them from the first `tools/list`.\n // A catalog left unknown can only be learned from a live sandbox, so the\n // first `tools/list` that finds it unknown attaches in the background.\n mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;\n // Reads committed files without attaching. Null means the backend is live\n // or offers no snapshot. An unavailable sleeping snapshot must throw, never\n // fall through to a read that wakes it. Pin later ranges by snapshotId.\n readSnapshot?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxSnapshotRequestIface,\n ): Promise<SandboxSnapshotResponseIface | null>;\n // Inspect retained backend processes without attaching or extending a sandbox.\n // Stopping one requires shell access; the provider also enforces backend ownership.\n processes?(\n ctx: SandboxOfferContextIface & { sandboxId: string },\n state: State,\n request: ProcessInspectionRequestIface,\n ): Promise<ProcessInspectionResultIface>;\n // Browser editor for an existing sandbox. The host checks write\n // authorization; this hook never creates or wakes a backend. Credentials stay\n // in the authentication form, never the editor URL or stored provider state.\n editor?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxEditorRequestIface,\n ): Promise<SandboxEditorResultIface>;\n // Content-addressed by `artifactKey`; the host caches artifacts and calls\n // prepare only on a miss.\n artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;\n prepare(ctx: SandboxPrepareContextIface): Promise<Artifact>;\n // Makes the sandbox's backend resource. The setup is given so the\n // provider enforces its network policy from the first boot (or refuses);\n // its repositories, steps and services are applied by the platform.\n create(\n ctx: SandboxResourceContextIface,\n args: { artifact: Artifact; setup: SandboxSetupIface | null },\n ): Promise<{ state: State; region?: string | null }>;\n // Resolves once the backend named by `state` is running and will accept a\n // command or a file write; rejects with a clear error after `timeoutMs`.\n // The provider chooses the readiness signal and backoff; the platform never\n // polls a backend itself.\n awaitRunning(\n ctx: SandboxResourceContextIface,\n state: State,\n options: { timeoutMs: number },\n ): Promise<void>;\n // Boots or resumes the sandbox and returns a live handle.\n attach(\n ctx: SandboxResourceContextIface,\n args: { artifact: Artifact; state: State },\n ): Promise<SandboxAttachmentIface<State, S>>;\n // Reconnects to an already running backend for a read-only viewer: never\n // boots, creates, seeds or restarts anything. Absent: viewers use a live\n // handle or nothing.\n attachPassive?(\n ctx: SandboxResourceContextIface,\n args: { artifact: Artifact; state: State },\n ): Promise<SandboxProviderHandleIface<S>>;\n // The host is done with its handle for now; the sandbox may go idle on the\n // provider's own policy. Returns the state the next attach needs.\n detach(ctx: SandboxResourceContextIface, args: { state: State }): Promise<State>;\n // Pauses or stops the sandbox, keeping its disk. Returns the state the next attach needs.\n park(\n ctx: SandboxResourceContextIface,\n args: { artifact: Artifact; state: State },\n ): Promise<State>;\n // Destroys the backend resource and its disk. Deleting one already gone succeeds.\n delete(ctx: SandboxResourceContextIface, args: { state: State }): Promise<void>;\n}\n\nexport interface SandboxProviderDefinitionIface<\n EnvOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n name: string;\n // The version of `State`'s shape. The host records it with each sandbox and\n // refuses to attach a state written under another version.\n stateProtocolVersion?: number;\n // Validates the options and returns the environment they describe.\n environment(options?: EnvOptions): SandboxEnvironmentImplementationIface<Artifact, State, S>;\n}\n\n// What `project.sandboxes.create(environment, \u2026)` takes: a provider by name\n// and that provider's own environment options, as plain data.\nexport interface SandboxEnvironmentValueIface<EnvOptions = JsonValue> {\n provider: string;\n environment: EnvOptions;\n}\n\n// A defined provider: the definition the host drives, and `environment(opts)`\n// returning the plain value a caller creates sandboxes from.\nexport interface SandboxProviderIface<\n EnvOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n readonly definition: SandboxProviderDefinitionIface<EnvOptions, Artifact, State, S>;\n readonly name: string;\n environment(options: EnvOptions): SandboxEnvironmentValueIface<EnvOptions>;\n}\n\nexport const defineSandboxProvider = <\n EnvOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n>(\n definition: SandboxProviderDefinitionIface<EnvOptions, Artifact, State, S>,\n): SandboxProviderIface<EnvOptions, Artifact, State, S> => ({\n definition: withSandboxOverrides(definition, {\n environment: (options?: EnvOptions) => {\n const implementation = definition.environment(options);\n for (const method of [\n 'create',\n 'attach',\n 'detach',\n 'park',\n 'delete',\n 'awaitRunning',\n ] as const)\n if (typeof implementation[method] !== 'function')\n throw new Error(`sandbox provider ${definition.name} does not implement ${method}`);\n const overrides: Partial<typeof implementation> = {\n attach: async (ctx, args) => {\n const attached = await implementation.attach(ctx, args);\n return {\n ...attached,\n handle: createSandboxHandle({\n handle: attached.handle,\n executionPolicy: ctx.executionPolicy,\n }),\n };\n },\n };\n if (implementation.editor != null) {\n const editor = implementation.editor.bind(implementation);\n overrides.editor = async (ctx, state, request) => {\n if (\n request.operation === SandboxEditorOperation.Open ||\n request.operation === SandboxEditorOperation.Refresh\n )\n await ctx.executionPolicy?.beforeExecution({\n operation: SandboxExecutionOperation.Editor,\n background: false,\n });\n return editor(ctx, state, request);\n };\n }\n if (implementation.attachPassive != null) {\n const attachPassive = implementation.attachPassive.bind(implementation);\n overrides.attachPassive = async (ctx, args) =>\n createSandboxHandle({\n handle: await attachPassive(ctx, args),\n executionPolicy: ctx.executionPolicy,\n });\n }\n return withSandboxOverrides(implementation, overrides);\n },\n }),\n name: definition.name,\n environment: (options) => ({ provider: definition.name, environment: options }),\n});\n\n// The runtime kinds an environment declares, or its default.\nexport const sandboxRuntimesOf = async (\n environment: Pick<\n SandboxEnvironmentImplementationIface<JsonValue, JsonValue, NetworkSandboxSessionIface>,\n 'capabilities' | 'runtimes'\n >,\n ctx: SandboxOfferContextIface,\n): Promise<RuntimeKind[]> => {\n if (environment.runtimes != null) return environment.runtimes(ctx);\n const offer = await environment.capabilities(ctx);\n return offer[Capability.Shell] == null ? [] : [RuntimeKind.Process];\n};\n\n// Erased form a host stores in its provider registry.\nexport type AnySandboxProviderIface = SandboxProviderIface<\n JsonValue,\n JsonValue,\n JsonValue,\n NetworkSandboxSessionIface\n>;\n\n// Events emitted through a sandbox provider's process lifecycle.\nexport enum SandboxEventKind {\n ProcessExited = 'process_exited',\n}\n"],
5
+ "mappings": "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",
6
+ "names": ["SandboxEntryType", "SandboxWorkerEndpointTransport", "PortProtocol", "SandboxCapability", "SandboxEventKind"]
7
7
  }
@@ -2,7 +2,7 @@ export { statSchema, dirEntrySchema } from "./file-schemas.mjs";
2
2
  import * as z from 'zod';
3
3
  import { workspaceEgressRequestSchema, workspaceEgressStatusSchema } from '@finalai/agent-protocol/device-egress';
4
4
  import { type JsonValue } from "../json.mjs";
5
- import { NetworkPolicy, PortProtocol, SandboxCapability } from "./types.mjs";
5
+ import { NetworkPolicy, PortProtocol, SandboxCapability, SandboxWorkerEndpointTransport } from "./types.mjs";
6
6
  export declare const HANDLE_RPC_VERSION = 1;
7
7
  export declare const HANDLE_RPC_SUBPROTOCOL = "final.handle-rpc.v1";
8
8
  export declare const HANDLE_RPC_BEARER_PROTOCOL_PREFIX = "bearer.";
@@ -41,6 +41,7 @@ export declare enum HandleRpcMethod {
41
41
  ReadTextFile = "sandbox/readTextFile",
42
42
  WriteFile = "sandbox/writeFile",
43
43
  Spawn = "sandbox/spawn",
44
+ StartWorker = "sandbox/startWorker",
44
45
  Run = "sandbox/run",
45
46
  Stat = "sandbox/stat",
46
47
  ReadDir = "sandbox/readDir",
@@ -64,7 +65,8 @@ export declare enum HandleRpcMethod {
64
65
  ProcessKill = "process/kill",
65
66
  ProcessAttach = "process/attach",
66
67
  ProcessDetach = "process/detach",
67
- AuthRefresh = "auth/refresh"
68
+ AuthRefresh = "auth/refresh",
69
+ IdentityRefresh = "identity/refresh"
68
70
  }
69
71
  export declare enum HandleRpcNotification {
70
72
  CancelRequest = "$/cancel_request",
@@ -168,6 +170,7 @@ export declare const describeResultSchema: z.ZodObject<{
168
170
  export declare const initializeParamsSchema: z.ZodObject<{
169
171
  handleRpcVersion: z.ZodLiteral<1>;
170
172
  token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
173
+ identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
171
174
  client: z.ZodOptional<z.ZodObject<{
172
175
  name: z.ZodString;
173
176
  version: z.ZodString;
@@ -226,6 +229,48 @@ export declare const spawnResultSchema: z.ZodObject<{
226
229
  pid: z.ZodNullable<z.ZodString>;
227
230
  ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
228
231
  }, z.core.$strip>;
232
+ export declare const startWorkerParamsSchema: z.ZodObject<{
233
+ program: z.ZodString;
234
+ env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
235
+ input: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
236
+ processId: z.ZodString;
237
+ stdinStreamId: z.ZodNullable<z.ZodNumber>;
238
+ stdoutStreamId: z.ZodNumber;
239
+ stderrStreamId: z.ZodNumber;
240
+ durable: z.ZodOptional<z.ZodBoolean>;
241
+ identity: z.ZodOptional<z.ZodString>;
242
+ }, z.core.$strip>;
243
+ export declare const workerEndpointSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
244
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Ws>;
245
+ url: z.ZodString;
246
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
247
+ }, z.core.$strip>, z.ZodObject<{
248
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Http>;
249
+ url: z.ZodString;
250
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
251
+ }, z.core.$strip>, z.ZodObject<{
252
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Relay>;
253
+ channel: z.ZodString;
254
+ token: z.ZodString;
255
+ }, z.core.$strip>], "transport">;
256
+ export declare const startWorkerResultSchema: z.ZodUnion<readonly [z.ZodObject<{
257
+ endpoint: z.ZodDiscriminatedUnion<[z.ZodObject<{
258
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Ws>;
259
+ url: z.ZodString;
260
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
261
+ }, z.core.$strip>, z.ZodObject<{
262
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Http>;
263
+ url: z.ZodString;
264
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
265
+ }, z.core.$strip>, z.ZodObject<{
266
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Relay>;
267
+ channel: z.ZodString;
268
+ token: z.ZodString;
269
+ }, z.core.$strip>], "transport">;
270
+ }, z.core.$strip>, z.ZodObject<{
271
+ pid: z.ZodNullable<z.ZodString>;
272
+ ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
273
+ }, z.core.$strip>]>;
229
274
  export declare const runParamsSchema: z.ZodObject<{
230
275
  stdin: z.ZodOptional<z.ZodString>;
231
276
  command: z.ZodString;
@@ -336,6 +381,12 @@ export declare const authRefreshParamsSchema: z.ZodObject<{
336
381
  export declare const authRefreshResultSchema: z.ZodObject<{
337
382
  expiresAt: z.ZodNullable<z.ZodString>;
338
383
  }, z.core.$strip>;
384
+ export declare const identityRefreshParamsSchema: z.ZodObject<{
385
+ assertion: z.ZodString;
386
+ }, z.core.$strip>;
387
+ export declare const identityRefreshResultSchema: z.ZodObject<{
388
+ expiresAt: z.ZodNullable<z.ZodString>;
389
+ }, z.core.$strip>;
339
390
  export declare const cancelRequestParamsSchema: z.ZodObject<{
340
391
  requestId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
341
392
  }, z.core.$strip>;
@@ -367,6 +418,7 @@ export declare const handleRpcMethodSchemas: {
367
418
  readonly params: z.ZodObject<{
368
419
  handleRpcVersion: z.ZodLiteral<1>;
369
420
  token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
421
+ identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
370
422
  client: z.ZodOptional<z.ZodObject<{
371
423
  name: z.ZodString;
372
424
  version: z.ZodString;
@@ -449,6 +501,37 @@ export declare const handleRpcMethodSchemas: {
449
501
  ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
450
502
  }, z.core.$strip>;
451
503
  };
504
+ readonly "sandbox/startWorker": {
505
+ readonly params: z.ZodObject<{
506
+ program: z.ZodString;
507
+ env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
508
+ input: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
509
+ processId: z.ZodString;
510
+ stdinStreamId: z.ZodNullable<z.ZodNumber>;
511
+ stdoutStreamId: z.ZodNumber;
512
+ stderrStreamId: z.ZodNumber;
513
+ durable: z.ZodOptional<z.ZodBoolean>;
514
+ identity: z.ZodOptional<z.ZodString>;
515
+ }, z.core.$strip>;
516
+ readonly result: z.ZodUnion<readonly [z.ZodObject<{
517
+ endpoint: z.ZodDiscriminatedUnion<[z.ZodObject<{
518
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Ws>;
519
+ url: z.ZodString;
520
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
521
+ }, z.core.$strip>, z.ZodObject<{
522
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Http>;
523
+ url: z.ZodString;
524
+ headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
525
+ }, z.core.$strip>, z.ZodObject<{
526
+ transport: z.ZodLiteral<SandboxWorkerEndpointTransport.Relay>;
527
+ channel: z.ZodString;
528
+ token: z.ZodString;
529
+ }, z.core.$strip>], "transport">;
530
+ }, z.core.$strip>, z.ZodObject<{
531
+ pid: z.ZodNullable<z.ZodString>;
532
+ ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
533
+ }, z.core.$strip>]>;
534
+ };
452
535
  readonly "sandbox/run": {
453
536
  readonly params: z.ZodObject<{
454
537
  stdin: z.ZodOptional<z.ZodString>;
@@ -662,6 +745,14 @@ export declare const handleRpcMethodSchemas: {
662
745
  expiresAt: z.ZodNullable<z.ZodString>;
663
746
  }, z.core.$strip>;
664
747
  };
748
+ readonly "identity/refresh": {
749
+ readonly params: z.ZodObject<{
750
+ assertion: z.ZodString;
751
+ }, z.core.$strip>;
752
+ readonly result: z.ZodObject<{
753
+ expiresAt: z.ZodNullable<z.ZodString>;
754
+ }, z.core.$strip>;
755
+ };
665
756
  };
666
757
  export declare const handleRpcNotificationSchemas: {
667
758
  readonly "$/cancel_request": z.ZodObject<{
@@ -698,10 +789,6 @@ export type HandleRpcResultParsers = {
698
789
  export declare const handleRpcResultParsers: HandleRpcResultParsers;
699
790
  export declare const parseHandleRpcResult: <M extends HandleRpcMethod>(method: M, raw: JsonValue) => HandleRpcResult<M>;
700
791
  export declare const parseHandleRpcMethod: (method: string) => HandleRpcMethod | null;
701
- export declare const HANDLE_RPC_FILE_WRITE_METHODS: readonly HandleRpcMethod[];
702
- export declare const HANDLE_RPC_EXECUTE_METHODS: readonly HandleRpcMethod[];
703
- export declare const HANDLE_RPC_WRITE_METHODS: readonly HandleRpcMethod[];
704
- export declare const HANDLE_RPC_LIFECYCLE_METHODS: readonly HandleRpcMethod[];
705
792
  export declare const HANDLE_RPC_IDEMPOTENT_METHODS: readonly HandleRpcMethod[];
706
793
  export declare const encodeChunkFrame: (streamId: number, payload: Uint8Array) => Uint8Array;
707
794
  export declare const decodeBinaryFrame: (frame: Uint8Array) => {
@@ -6,7 +6,12 @@ import {
6
6
  workspaceEgressStatusSchema
7
7
  } from "@finalai/agent-protocol/device-egress";
8
8
  import { jsonValueSchema } from "../json.mjs";
9
- import { NetworkPolicy, PortProtocol, SandboxCapability } from "./types.mjs";
9
+ import {
10
+ NetworkPolicy,
11
+ PortProtocol,
12
+ SandboxCapability,
13
+ SandboxWorkerEndpointTransport
14
+ } from "./types.mjs";
10
15
  const HANDLE_RPC_VERSION = 1;
11
16
  const HANDLE_RPC_SUBPROTOCOL = "final.handle-rpc.v1";
12
17
  const HANDLE_RPC_BEARER_PROTOCOL_PREFIX = "bearer.";
@@ -49,6 +54,7 @@ var HandleRpcMethod = /* @__PURE__ */ ((HandleRpcMethod2) => {
49
54
  HandleRpcMethod2["ReadTextFile"] = "sandbox/readTextFile";
50
55
  HandleRpcMethod2["WriteFile"] = "sandbox/writeFile";
51
56
  HandleRpcMethod2["Spawn"] = "sandbox/spawn";
57
+ HandleRpcMethod2["StartWorker"] = "sandbox/startWorker";
52
58
  HandleRpcMethod2["Run"] = "sandbox/run";
53
59
  HandleRpcMethod2["Stat"] = "sandbox/stat";
54
60
  HandleRpcMethod2["ReadDir"] = "sandbox/readDir";
@@ -73,6 +79,7 @@ var HandleRpcMethod = /* @__PURE__ */ ((HandleRpcMethod2) => {
73
79
  HandleRpcMethod2["ProcessAttach"] = "process/attach";
74
80
  HandleRpcMethod2["ProcessDetach"] = "process/detach";
75
81
  HandleRpcMethod2["AuthRefresh"] = "auth/refresh";
82
+ HandleRpcMethod2["IdentityRefresh"] = "identity/refresh";
76
83
  return HandleRpcMethod2;
77
84
  })(HandleRpcMethod || {});
78
85
  var HandleRpcNotification = /* @__PURE__ */ ((HandleRpcNotification2) => {
@@ -165,6 +172,8 @@ const describeResultSchema = z.object({
165
172
  const initializeParamsSchema = z.object({
166
173
  handleRpcVersion: z.literal(HANDLE_RPC_VERSION),
167
174
  token: z.string().nullable().optional(),
175
+ // A platform-identity assertion, on a sandbox provider's attach socket.
176
+ identity: z.string().min(1).nullable().optional(),
168
177
  client: z.object({ name: z.string(), version: z.string() }).optional()
169
178
  });
170
179
  const initializeResultSchema = describeResultSchema.extend({
@@ -220,6 +229,39 @@ const spawnResultSchema = z.object({
220
229
  pid: z.string().nullable(),
221
230
  ref: z.string().nullable().optional()
222
231
  });
232
+ const startWorkerParamsSchema = z.object({
233
+ program: z.string().min(1),
234
+ env: z.record(z.string(), z.string()).optional(),
235
+ // Handed to the program when it starts.
236
+ input: jsonValueSchema.optional(),
237
+ processId: z.string().min(1),
238
+ stdinStreamId: streamIdSchema.nullable(),
239
+ stdoutStreamId: streamIdSchema,
240
+ stderrStreamId: streamIdSchema,
241
+ durable: z.boolean().optional(),
242
+ identity: z.string().min(1).optional()
243
+ });
244
+ const workerEndpointSchema = z.discriminatedUnion("transport", [
245
+ z.object({
246
+ transport: z.literal(SandboxWorkerEndpointTransport.Ws),
247
+ url: z.string().url(),
248
+ headers: z.record(z.string(), z.string()).default({})
249
+ }),
250
+ z.object({
251
+ transport: z.literal(SandboxWorkerEndpointTransport.Http),
252
+ url: z.string().url(),
253
+ headers: z.record(z.string(), z.string()).default({})
254
+ }),
255
+ z.object({
256
+ transport: z.literal(SandboxWorkerEndpointTransport.Relay),
257
+ channel: z.string().min(1),
258
+ token: z.string().min(1)
259
+ })
260
+ ]);
261
+ const startWorkerResultSchema = z.union([
262
+ z.object({ endpoint: workerEndpointSchema }),
263
+ spawnResultSchema
264
+ ]);
223
265
  const runParamsSchema = z.object({
224
266
  ...processOptionFields,
225
267
  stdin: z.string().optional()
@@ -277,6 +319,8 @@ const processAttachResultSchema = z.object({
277
319
  });
278
320
  const authRefreshParamsSchema = z.object({ token: z.string().min(1) });
279
321
  const authRefreshResultSchema = z.object({ expiresAt: z.string().nullable() });
322
+ const identityRefreshParamsSchema = z.object({ assertion: z.string().min(1) });
323
+ const identityRefreshResultSchema = z.object({ expiresAt: z.string().nullable() });
280
324
  const cancelRequestParamsSchema = z.object({ requestId: jsonRpcIdSchema });
281
325
  const streamChunkParamsSchema = z.object({ streamId: streamIdSchema, data: z.string() });
282
326
  const streamEndParamsSchema = z.object({ streamId: streamIdSchema });
@@ -304,6 +348,10 @@ const handleRpcMethodSchemas = {
304
348
  },
305
349
  ["sandbox/writeFile" /* WriteFile */]: { params: writeFileParamsSchema, result: emptyResultSchema },
306
350
  ["sandbox/spawn" /* Spawn */]: { params: spawnParamsSchema, result: spawnResultSchema },
351
+ ["sandbox/startWorker" /* StartWorker */]: {
352
+ params: startWorkerParamsSchema,
353
+ result: startWorkerResultSchema
354
+ },
307
355
  ["sandbox/run" /* Run */]: { params: runParamsSchema, result: runResultSchema },
308
356
  ["sandbox/stat" /* Stat */]: { params: pathParamsSchema, result: statResultSchema },
309
357
  ["sandbox/readDir" /* ReadDir */]: { params: pathParamsSchema, result: readDirResultSchema },
@@ -345,6 +393,10 @@ const handleRpcMethodSchemas = {
345
393
  ["auth/refresh" /* AuthRefresh */]: {
346
394
  params: authRefreshParamsSchema,
347
395
  result: authRefreshResultSchema
396
+ },
397
+ ["identity/refresh" /* IdentityRefresh */]: {
398
+ params: identityRefreshParamsSchema,
399
+ result: identityRefreshResultSchema
348
400
  }
349
401
  };
350
402
  const handleRpcNotificationSchemas = {
@@ -362,6 +414,7 @@ const handleRpcResultParsers = {
362
414
  ["sandbox/readTextFile" /* ReadTextFile */]: (raw) => handleRpcMethodSchemas["sandbox/readTextFile" /* ReadTextFile */].result.parse(raw),
363
415
  ["sandbox/writeFile" /* WriteFile */]: (raw) => handleRpcMethodSchemas["sandbox/writeFile" /* WriteFile */].result.parse(raw),
364
416
  ["sandbox/spawn" /* Spawn */]: (raw) => handleRpcMethodSchemas["sandbox/spawn" /* Spawn */].result.parse(raw),
417
+ ["sandbox/startWorker" /* StartWorker */]: (raw) => handleRpcMethodSchemas["sandbox/startWorker" /* StartWorker */].result.parse(raw),
365
418
  ["sandbox/run" /* Run */]: (raw) => handleRpcMethodSchemas["sandbox/run" /* Run */].result.parse(raw),
366
419
  ["sandbox/stat" /* Stat */]: (raw) => handleRpcMethodSchemas["sandbox/stat" /* Stat */].result.parse(raw),
367
420
  ["sandbox/readDir" /* ReadDir */]: (raw) => handleRpcMethodSchemas["sandbox/readDir" /* ReadDir */].result.parse(raw),
@@ -385,43 +438,12 @@ const handleRpcResultParsers = {
385
438
  ["process/kill" /* ProcessKill */]: (raw) => handleRpcMethodSchemas["process/kill" /* ProcessKill */].result.parse(raw),
386
439
  ["process/attach" /* ProcessAttach */]: (raw) => handleRpcMethodSchemas["process/attach" /* ProcessAttach */].result.parse(raw),
387
440
  ["process/detach" /* ProcessDetach */]: (raw) => handleRpcMethodSchemas["process/detach" /* ProcessDetach */].result.parse(raw),
388
- ["auth/refresh" /* AuthRefresh */]: (raw) => handleRpcMethodSchemas["auth/refresh" /* AuthRefresh */].result.parse(raw)
441
+ ["auth/refresh" /* AuthRefresh */]: (raw) => handleRpcMethodSchemas["auth/refresh" /* AuthRefresh */].result.parse(raw),
442
+ ["identity/refresh" /* IdentityRefresh */]: (raw) => handleRpcMethodSchemas["identity/refresh" /* IdentityRefresh */].result.parse(raw)
389
443
  };
390
444
  const parseHandleRpcResult = (method, raw) => handleRpcResultParsers[method](raw);
391
445
  const isHandleRpcMethod = (value) => Object.values(HandleRpcMethod).some((method) => method === value);
392
446
  const parseHandleRpcMethod = (method) => isHandleRpcMethod(method) ? method : null;
393
- const HANDLE_RPC_FILE_WRITE_METHODS = [
394
- "sandbox/writeFile" /* WriteFile */,
395
- "sandbox/removePath" /* RemovePath */
396
- ];
397
- const HANDLE_RPC_EXECUTE_METHODS = [
398
- "sandbox/spawn" /* Spawn */,
399
- "sandbox/run" /* Run */,
400
- "process/wait" /* ProcessWait */,
401
- "process/kill" /* ProcessKill */,
402
- "process/attach" /* ProcessAttach */,
403
- "process/detach" /* ProcessDetach */,
404
- "sandbox/computerUse" /* ComputerUse */,
405
- "sandbox/localMcp" /* LocalMcp */,
406
- "mcp/open" /* McpOpen */,
407
- "mcp/send" /* McpSend */,
408
- "mcp/receive" /* McpReceive */,
409
- "mcp/close" /* McpClose */
410
- ];
411
- const HANDLE_RPC_WRITE_METHODS = [
412
- ...HANDLE_RPC_FILE_WRITE_METHODS,
413
- ...HANDLE_RPC_EXECUTE_METHODS,
414
- "sandbox/egress" /* Egress */
415
- ];
416
- const HANDLE_RPC_LIFECYCLE_METHODS = [
417
- "handle/onSandboxStop" /* OnSandboxStop */,
418
- "handle/onSandboxDelete" /* OnSandboxDelete */,
419
- "handle/onRuntimeShutdown" /* OnRuntimeShutdown */,
420
- "sandbox/stop" /* Stop */,
421
- "sandbox/destroy" /* Destroy */,
422
- "sandbox/setNetworkPolicy" /* SetNetworkPolicy */,
423
- "sandbox/egress" /* Egress */
424
- ];
425
447
  const HANDLE_RPC_IDEMPOTENT_METHODS = [
426
448
  "sandbox/describe" /* Describe */,
427
449
  "sandbox/readTextFile" /* ReadTextFile */,
@@ -482,13 +504,9 @@ export {
482
504
  BINARY_FRAME_MAGIC,
483
505
  BinaryFrameKind,
484
506
  HANDLE_RPC_BEARER_PROTOCOL_PREFIX,
485
- HANDLE_RPC_EXECUTE_METHODS,
486
- HANDLE_RPC_FILE_WRITE_METHODS,
487
507
  HANDLE_RPC_IDEMPOTENT_METHODS,
488
- HANDLE_RPC_LIFECYCLE_METHODS,
489
508
  HANDLE_RPC_SUBPROTOCOL,
490
509
  HANDLE_RPC_VERSION,
491
- HANDLE_RPC_WRITE_METHODS,
492
510
  HandleRpcCloseCode,
493
511
  HandleRpcErrorCode,
494
512
  HandleRpcMethod,
@@ -514,6 +532,8 @@ export {
514
532
  handleRpcNotificationSchemas,
515
533
  handleRpcResultParsers,
516
534
  handleRpcTokenFromRequest,
535
+ identityRefreshParamsSchema,
536
+ identityRefreshResultSchema,
517
537
  initializeParamsSchema,
518
538
  initializeResultSchema,
519
539
  isHandleRpcError,
@@ -554,6 +574,8 @@ export {
554
574
  setNetworkPolicyParamsSchema,
555
575
  spawnParamsSchema,
556
576
  spawnResultSchema,
577
+ startWorkerParamsSchema,
578
+ startWorkerResultSchema,
557
579
  statResultSchema,
558
580
  statSchema2 as statSchema,
559
581
  streamCancelParamsSchema,
@@ -561,6 +583,7 @@ export {
561
583
  streamCreditParamsSchema,
562
584
  streamEndParamsSchema,
563
585
  streamErrorParamsSchema,
586
+ workerEndpointSchema,
564
587
  workspaceEgressRequestSchema,
565
588
  workspaceEgressStatusSchema,
566
589
  writeFileParamsSchema