@finalai/agent-provider 0.2.3 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +61 -0
  2. package/dist/modules/sandbox/client.mjs +3 -0
  3. package/dist/modules/sandbox/client.mjs.map +2 -2
  4. package/dist/modules/sandbox/confined-files.d.mts +2 -2
  5. package/dist/modules/sandbox/confined-files.mjs +5 -2
  6. package/dist/modules/sandbox/confined-files.mjs.map +2 -2
  7. package/dist/modules/sandbox/execution-guard.d.mts +36 -0
  8. package/dist/modules/sandbox/execution-guard.mjs +322 -0
  9. package/dist/modules/sandbox/execution-guard.mjs.map +7 -0
  10. package/dist/modules/sandbox/file-kind.d.mts +6 -0
  11. package/dist/modules/sandbox/file-kind.mjs +11 -0
  12. package/dist/modules/sandbox/file-kind.mjs.map +7 -0
  13. package/dist/modules/sandbox/file-schemas.d.mts +15 -0
  14. package/dist/modules/sandbox/file-schemas.mjs +22 -0
  15. package/dist/modules/sandbox/file-schemas.mjs.map +7 -0
  16. package/dist/modules/sandbox/handle.d.mts +15 -0
  17. package/dist/modules/sandbox/handle.mjs +47 -0
  18. package/dist/modules/sandbox/handle.mjs.map +7 -0
  19. package/dist/modules/sandbox/index.d.mts +8 -0
  20. package/dist/modules/sandbox/index.mjs +30 -1
  21. package/dist/modules/sandbox/index.mjs.map +2 -2
  22. package/dist/modules/sandbox/mcp-channel.d.mts +8 -1
  23. package/dist/modules/sandbox/mcp-channel.mjs +217 -15
  24. package/dist/modules/sandbox/mcp-channel.mjs.map +3 -3
  25. package/dist/modules/sandbox/mcp-hosted-marker.d.mts +3 -0
  26. package/dist/modules/sandbox/mcp-hosted-marker.mjs +10 -0
  27. package/dist/modules/sandbox/mcp-hosted-marker.mjs.map +7 -0
  28. package/dist/modules/sandbox/mcp-hosted.d.mts +6 -1
  29. package/dist/modules/sandbox/mcp-hosted.mjs +127 -41
  30. package/dist/modules/sandbox/mcp-hosted.mjs.map +2 -2
  31. package/dist/modules/sandbox/mcp-shell.mjs +14 -4
  32. package/dist/modules/sandbox/mcp-shell.mjs.map +2 -2
  33. package/dist/modules/sandbox/mcp.d.mts +5 -2
  34. package/dist/modules/sandbox/mcp.mjs +102 -27
  35. package/dist/modules/sandbox/mcp.mjs.map +2 -2
  36. package/dist/modules/sandbox/networking.d.mts +73 -0
  37. package/dist/modules/sandbox/networking.mjs +149 -0
  38. package/dist/modules/sandbox/networking.mjs.map +7 -0
  39. package/dist/modules/sandbox/overrides.d.mts +2 -0
  40. package/dist/modules/sandbox/overrides.mjs +44 -0
  41. package/dist/modules/sandbox/overrides.mjs.map +7 -0
  42. package/dist/modules/sandbox/server.d.mts +1 -0
  43. package/dist/modules/sandbox/server.mjs +38 -2
  44. package/dist/modules/sandbox/server.mjs.map +2 -2
  45. package/dist/modules/sandbox/testing.d.mts +1 -0
  46. package/dist/modules/sandbox/testing.mjs +1 -0
  47. package/dist/modules/sandbox/testing.mjs.map +2 -2
  48. package/dist/modules/sandbox/tool-policy.d.mts +5 -0
  49. package/dist/modules/sandbox/tool-policy.mjs +62 -0
  50. package/dist/modules/sandbox/tool-policy.mjs.map +7 -0
  51. package/dist/modules/sandbox/types.d.mts +17 -16
  52. package/dist/modules/sandbox/types.mjs +54 -23
  53. package/dist/modules/sandbox/types.mjs.map +3 -3
  54. package/dist/modules/sandbox/wire.d.mts +23 -18
  55. package/dist/modules/sandbox/wire.mjs +21 -20
  56. package/dist/modules/sandbox/wire.mjs.map +3 -3
  57. package/dist/modules/sandbox/workspace-identity.d.mts +5 -0
  58. package/dist/modules/sandbox/workspace-identity.mjs +14 -0
  59. package/dist/modules/sandbox/workspace-identity.mjs.map +7 -0
  60. package/package.json +3 -3
@@ -0,0 +1,73 @@
1
+ import type { SandboxExecutionPolicyIface } from "./handle.mjs";
2
+ import { SandboxAccess } from "../manifest.mjs";
3
+ import { type SandboxExecutionContextIface } from "./execution-guard.mjs";
4
+ import { type NetworkPolicyIface, type NetworkSandboxSessionIface, type SandboxCapability, type SandboxOfferContextIface, type SandboxProviderHandleIface, type SandboxRunResultIface, type SandboxStartContextIface } from "./types.mjs";
5
+ export interface SandboxNetworkingContextIface {
6
+ access?: SandboxAccess;
7
+ ctx: SandboxOfferContextIface;
8
+ workspaceId: string;
9
+ }
10
+ export interface SandboxNetworkingControllerOptionsIface extends SandboxNetworkingContextIface {
11
+ sandbox: NetworkSandboxSessionIface;
12
+ access: SandboxAccess;
13
+ initialNetworkPolicy: NetworkPolicyIface;
14
+ privilegedRun?: (request: {
15
+ source: string;
16
+ input: string;
17
+ }) => Promise<SandboxRunResultIface>;
18
+ afterGuard: (policy?: NetworkPolicyIface) => Promise<void>;
19
+ afterBlock?: () => Promise<void>;
20
+ namespaceExists?: () => Promise<boolean>;
21
+ onClose?: () => void;
22
+ allowOwnerChange?: boolean;
23
+ log?: (message: string, fields?: Record<string, string | number | boolean | null>) => void;
24
+ }
25
+ export interface SandboxNetworkingControllerIface {
26
+ initialize(): Promise<void>;
27
+ guard(context?: SandboxExecutionContextIface): Promise<void>;
28
+ close(stop?: boolean): Promise<void>;
29
+ closeOnFailure(): Promise<void>;
30
+ extendSandbox<S extends NetworkSandboxSessionIface>(sandbox: S): S;
31
+ authorizeExternalAccess(): Promise<{
32
+ expiresAtMs: number | null;
33
+ }>;
34
+ }
35
+ export interface SandboxNetworkingExtensionIface {
36
+ readonly capabilities: readonly SandboxCapability[];
37
+ readonly fetch?: typeof globalThis.fetch;
38
+ validateWorkspaceId?(workspaceId: string): void;
39
+ enabled(args: SandboxNetworkingContextIface & {
40
+ teardown?: boolean;
41
+ }): Promise<boolean>;
42
+ prepare(args: SandboxNetworkingContextIface & {
43
+ policy: NetworkPolicyIface;
44
+ }): Promise<NetworkPolicyIface | void>;
45
+ suspend(args: SandboxNetworkingContextIface): Promise<void>;
46
+ controller(args: SandboxNetworkingControllerOptionsIface): SandboxNetworkingControllerIface;
47
+ attach?<S extends NetworkSandboxSessionIface>(args: Omit<AttachSandboxNetworkingOptionsIface<S>, 'extension'>): Promise<SandboxProviderHandleIface<S>>;
48
+ }
49
+ export interface WithSandboxNetworkingOptionsIface<S extends NetworkSandboxSessionIface> {
50
+ handle: SandboxProviderHandleIface<S>;
51
+ access: SandboxAccess;
52
+ controller?: SandboxNetworkingControllerIface;
53
+ admission?: () => Promise<void>;
54
+ beforeUse?: () => Promise<void>;
55
+ initialized?: boolean;
56
+ fetch?: typeof globalThis.fetch;
57
+ executionPolicy?: SandboxExecutionPolicyIface;
58
+ }
59
+ export declare const withSandboxNetworking: <S extends NetworkSandboxSessionIface>(options: WithSandboxNetworkingOptionsIface<S>) => Promise<SandboxProviderHandleIface<S>>;
60
+ export interface AttachSandboxNetworkingOptionsIface<S extends NetworkSandboxSessionIface> {
61
+ extension: SandboxNetworkingExtensionIface;
62
+ ctx: SandboxStartContextIface;
63
+ handle: SandboxProviderHandleIface<S>;
64
+ access: SandboxAccess;
65
+ workspaceId: string;
66
+ initialNetworkPolicy: NetworkPolicyIface;
67
+ restoreNetwork: (policy?: NetworkPolicyIface) => Promise<void>;
68
+ blockNetwork?: () => Promise<void>;
69
+ namespaceExists?: () => Promise<boolean>;
70
+ beforeUse: () => Promise<void>;
71
+ log?: SandboxNetworkingControllerOptionsIface['log'];
72
+ }
73
+ export declare const attachSandboxNetworking: <S extends NetworkSandboxSessionIface>(options: AttachSandboxNetworkingOptionsIface<S>) => Promise<SandboxProviderHandleIface<S>>;
@@ -0,0 +1,149 @@
1
+ import { createSandboxHandle } from "./handle.mjs";
2
+ import { withSandboxOverrides } from "./overrides.mjs";
3
+ import { SandboxAccess } from "../manifest.mjs";
4
+ import { WorkspaceEgressAction } from "@finalai/agent-protocol/device-egress";
5
+ import { SandboxExecutionOperation } from "./execution-guard.mjs";
6
+ import {
7
+ } from "./types.mjs";
8
+ const finishNetworking = async (args) => {
9
+ const failures = [];
10
+ try {
11
+ await args.close();
12
+ } catch (cause) {
13
+ failures.push(cause);
14
+ }
15
+ try {
16
+ await args.finish();
17
+ } catch (cause) {
18
+ failures.push(cause);
19
+ }
20
+ if (failures.length === 1) throw failures[0];
21
+ if (failures.length > 1)
22
+ throw new AggregateError(failures, "Sandbox networking and cleanup failed");
23
+ };
24
+ const withSandboxNetworking = async (options) => {
25
+ const { handle, controller } = options;
26
+ if (options.access === SandboxAccess.Read) return handle;
27
+ if (controller != null && options.initialized !== true) {
28
+ try {
29
+ await controller.initialize();
30
+ } catch (cause) {
31
+ await finishNetworking({
32
+ close: () => controller.closeOnFailure(),
33
+ finish: async () => {
34
+ throw cause;
35
+ }
36
+ });
37
+ }
38
+ }
39
+ const source = handle.sandbox;
40
+ const extended = controller?.extendSandbox(source) ?? source;
41
+ const egress = extended.egress?.bind(extended);
42
+ const sandbox = options.access === SandboxAccess.Execute && egress != null ? withSandboxOverrides(extended, {
43
+ egress: async (request) => {
44
+ if (request.action !== WorkspaceEgressAction.Status)
45
+ throw new Error("Workspace egress configuration requires write access");
46
+ return egress(request);
47
+ }
48
+ }) : extended;
49
+ return createSandboxHandle({
50
+ executionPolicy: options.executionPolicy,
51
+ handle: withSandboxOverrides(handle, {
52
+ sandbox: withSandboxOverrides(sandbox, {
53
+ stop: () => finishNetworking({
54
+ close: () => controller?.close(true) ?? Promise.resolve(),
55
+ finish: () => source.stop()
56
+ }),
57
+ destroy: () => finishNetworking({
58
+ close: () => controller?.close(true) ?? Promise.resolve(),
59
+ finish: () => source.destroy()
60
+ })
61
+ }),
62
+ executionPolicy: {
63
+ fetch: handle.executionPolicy?.fetch ?? options.fetch ?? options.executionPolicy?.fetch,
64
+ beforeExecution: async (context) => {
65
+ await handle.executionPolicy?.beforeExecution(context);
66
+ await options.admission?.();
67
+ await controller?.guard(context);
68
+ if (!context.background && ![
69
+ SandboxExecutionOperation.SetNetworkPolicy,
70
+ SandboxExecutionOperation.Egress
71
+ ].includes(context.operation))
72
+ await options.beforeUse?.();
73
+ }
74
+ },
75
+ onRuntimeShutdown: () => finishNetworking({
76
+ close: () => controller?.close(false) ?? Promise.resolve(),
77
+ finish: () => handle.onRuntimeShutdown()
78
+ }),
79
+ onSandboxStop: () => finishNetworking({
80
+ close: () => controller?.close(true) ?? Promise.resolve(),
81
+ finish: () => handle.onSandboxStop()
82
+ }),
83
+ onSandboxDelete: (args) => finishNetworking({
84
+ close: () => controller?.close(true) ?? Promise.resolve(),
85
+ finish: () => handle.onSandboxDelete(args)
86
+ })
87
+ })
88
+ });
89
+ };
90
+ const attachSandboxNetworking = async (options) => {
91
+ if (options.access === SandboxAccess.Read) return options.handle;
92
+ if (options.extension.attach != null) return options.extension.attach(options);
93
+ const controller = options.extension.controller({
94
+ ctx: {
95
+ organizationId: options.ctx.session.organizationId,
96
+ platformEgressHosts: options.ctx.platformEgressHosts,
97
+ platformNetworkPolicy: options.ctx.platformNetworkPolicy,
98
+ actingUser: options.ctx.actingUser,
99
+ bindings: options.ctx.bindings
100
+ },
101
+ sandbox: options.handle.sandbox,
102
+ access: options.access,
103
+ workspaceId: options.workspaceId,
104
+ initialNetworkPolicy: options.initialNetworkPolicy,
105
+ afterGuard: options.restoreNetwork,
106
+ afterBlock: options.blockNetwork,
107
+ namespaceExists: options.namespaceExists,
108
+ log: options.log
109
+ });
110
+ try {
111
+ await controller.initialize();
112
+ let ready = true;
113
+ try {
114
+ const setupContext = { operation: SandboxExecutionOperation.Run, background: false };
115
+ await options.ctx.executionPolicy?.beforeExecution(setupContext);
116
+ await options.handle.executionPolicy?.beforeExecution(setupContext);
117
+ await controller.guard();
118
+ } catch (cause) {
119
+ ready = false;
120
+ options.log?.("workspace_networking.setup_deferred", {
121
+ workspaceId: options.workspaceId,
122
+ reason: cause instanceof Error ? cause.name : "UnknownError"
123
+ });
124
+ }
125
+ if (ready) await options.beforeUse();
126
+ return await withSandboxNetworking({
127
+ handle: options.handle,
128
+ controller,
129
+ access: options.access,
130
+ beforeUse: options.beforeUse,
131
+ initialized: true,
132
+ fetch: options.extension.fetch,
133
+ executionPolicy: options.ctx.executionPolicy
134
+ });
135
+ } catch (cause) {
136
+ await finishNetworking({
137
+ close: () => controller.closeOnFailure(),
138
+ finish: async () => {
139
+ throw cause;
140
+ }
141
+ });
142
+ throw cause;
143
+ }
144
+ };
145
+ export {
146
+ attachSandboxNetworking,
147
+ withSandboxNetworking
148
+ };
149
+ //# sourceMappingURL=networking.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../../../../src/sandbox/networking.ts"],
4
+ "sourcesContent": ["import { createSandboxHandle } from \"./handle.mjs\";\nimport type { SandboxExecutionPolicyIface } from \"./handle.mjs\";\nimport { withSandboxOverrides } from \"./overrides.mjs\";\nimport { SandboxAccess } from \"../manifest.mjs\";\nimport { WorkspaceEgressAction } from '@finalai/agent-protocol/device-egress';\nimport { SandboxExecutionOperation, type SandboxExecutionContextIface } from \"./execution-guard.mjs\";\nimport {\n type NetworkPolicyIface,\n type NetworkSandboxSessionIface,\n type SandboxCapability,\n type SandboxOfferContextIface,\n type SandboxProviderHandleIface,\n type SandboxRunResultIface,\n type SandboxStartContextIface,\n} from \"./types.mjs\";\n\nexport interface SandboxNetworkingContextIface {\n access?: SandboxAccess;\n ctx: SandboxOfferContextIface;\n workspaceId: string;\n}\n\nexport interface SandboxNetworkingControllerOptionsIface extends SandboxNetworkingContextIface {\n sandbox: NetworkSandboxSessionIface;\n access: SandboxAccess;\n initialNetworkPolicy: NetworkPolicyIface;\n // Executes inside the sandbox's network namespace with its required privileges.\n privilegedRun?: (request: { source: string; input: string }) => Promise<SandboxRunResultIface>;\n afterGuard: (policy?: NetworkPolicyIface) => Promise<void>;\n afterBlock?: () => Promise<void>;\n namespaceExists?: () => Promise<boolean>;\n onClose?: () => void;\n allowOwnerChange?: boolean;\n log?: (message: string, fields?: Record<string, string | number | boolean | null>) => void;\n}\n\nexport interface SandboxNetworkingControllerIface {\n initialize(): Promise<void>;\n guard(context?: SandboxExecutionContextIface): Promise<void>;\n close(stop?: boolean): Promise<void>;\n closeOnFailure(): Promise<void>;\n // Extensions may expose networking operations; ordinary execution is guarded afterwards.\n extendSandbox<S extends NetworkSandboxSessionIface>(sandbox: S): S;\n authorizeExternalAccess(): Promise<{ expiresAtMs: number | null }>;\n}\n\n// A host composes an opinionated networking implementation with any compatible provider.\nexport interface SandboxNetworkingExtensionIface {\n readonly capabilities: readonly SandboxCapability[];\n readonly fetch?: typeof globalThis.fetch;\n validateWorkspaceId?(workspaceId: string): void;\n enabled(args: SandboxNetworkingContextIface & { teardown?: boolean }): Promise<boolean>;\n // Return the retained logical policy when it differs from the supplied provider snapshot.\n prepare(\n args: SandboxNetworkingContextIface & { policy: NetworkPolicyIface },\n ): Promise<NetworkPolicyIface | void>;\n suspend(args: SandboxNetworkingContextIface): Promise<void>;\n controller(args: SandboxNetworkingControllerOptionsIface): SandboxNetworkingControllerIface;\n // Custom attachment may coordinate provider setup; it owns admission and failure cleanup.\n attach?<S extends NetworkSandboxSessionIface>(\n args: Omit<AttachSandboxNetworkingOptionsIface<S>, 'extension'>,\n ): Promise<SandboxProviderHandleIface<S>>;\n}\n\nconst finishNetworking = async (args: {\n close: () => Promise<void>;\n finish: () => Promise<void>;\n}): Promise<void> => {\n const failures: unknown[] = [];\n try {\n await args.close();\n } catch (cause) {\n failures.push(cause);\n }\n try {\n await args.finish();\n } catch (cause) {\n failures.push(cause);\n }\n if (failures.length === 1) throw failures[0];\n if (failures.length > 1)\n throw new AggregateError(failures, 'Sandbox networking and cleanup failed');\n};\n\nexport interface WithSandboxNetworkingOptionsIface<S extends NetworkSandboxSessionIface> {\n handle: SandboxProviderHandleIface<S>;\n access: SandboxAccess;\n controller?: SandboxNetworkingControllerIface;\n admission?: () => Promise<void>;\n beforeUse?: () => Promise<void>;\n initialized?: boolean;\n fetch?: typeof globalThis.fetch;\n executionPolicy?: SandboxExecutionPolicyIface;\n}\n\nexport const withSandboxNetworking = async <S extends NetworkSandboxSessionIface>(\n options: WithSandboxNetworkingOptionsIface<S>,\n): Promise<SandboxProviderHandleIface<S>> => {\n const { handle, controller } = options;\n if (options.access === SandboxAccess.Read) return handle;\n if (controller != null && options.initialized !== true) {\n try {\n await controller.initialize();\n } catch (cause) {\n await finishNetworking({\n close: () => controller.closeOnFailure(),\n finish: async () => {\n throw cause;\n },\n });\n }\n }\n const source = handle.sandbox;\n const extended = controller?.extendSandbox(source) ?? source;\n const egress = extended.egress?.bind(extended);\n const sandbox =\n options.access === SandboxAccess.Execute && egress != null\n ? withSandboxOverrides(extended, {\n egress: async (request: Parameters<typeof egress>[0]) => {\n if (request.action !== WorkspaceEgressAction.Status)\n throw new Error('Workspace egress configuration requires write access');\n return egress(request);\n },\n })\n : extended;\n return createSandboxHandle({\n executionPolicy: options.executionPolicy,\n handle: withSandboxOverrides(handle, {\n sandbox: withSandboxOverrides(sandbox, {\n stop: () =>\n finishNetworking({\n close: () => controller?.close(true) ?? Promise.resolve(),\n finish: () => source.stop(),\n }),\n destroy: () =>\n finishNetworking({\n close: () => controller?.close(true) ?? Promise.resolve(),\n finish: () => source.destroy(),\n }),\n }),\n executionPolicy: {\n fetch: handle.executionPolicy?.fetch ?? options.fetch ?? options.executionPolicy?.fetch,\n beforeExecution: async (context: SandboxExecutionContextIface) => {\n await handle.executionPolicy?.beforeExecution(context);\n await options.admission?.();\n await controller?.guard(context);\n if (\n !context.background &&\n ![\n SandboxExecutionOperation.SetNetworkPolicy,\n SandboxExecutionOperation.Egress,\n ].includes(context.operation)\n )\n await options.beforeUse?.();\n },\n },\n onRuntimeShutdown: () =>\n finishNetworking({\n close: () => controller?.close(false) ?? Promise.resolve(),\n finish: () => handle.onRuntimeShutdown(),\n }),\n onSandboxStop: () =>\n finishNetworking({\n close: () => controller?.close(true) ?? Promise.resolve(),\n finish: () => handle.onSandboxStop(),\n }),\n onSandboxDelete: (args: Parameters<typeof handle.onSandboxDelete>[0]) =>\n finishNetworking({\n close: () => controller?.close(true) ?? Promise.resolve(),\n finish: () => handle.onSandboxDelete(args),\n }),\n }),\n });\n};\n\nexport interface AttachSandboxNetworkingOptionsIface<S extends NetworkSandboxSessionIface> {\n extension: SandboxNetworkingExtensionIface;\n ctx: SandboxStartContextIface;\n handle: SandboxProviderHandleIface<S>;\n access: SandboxAccess;\n workspaceId: string;\n initialNetworkPolicy: NetworkPolicyIface;\n restoreNetwork: (policy?: NetworkPolicyIface) => Promise<void>;\n blockNetwork?: () => Promise<void>;\n namespaceExists?: () => Promise<boolean>;\n beforeUse: () => Promise<void>;\n log?: SandboxNetworkingControllerOptionsIface['log'];\n}\n\nexport const attachSandboxNetworking = async <S extends NetworkSandboxSessionIface>(\n options: AttachSandboxNetworkingOptionsIface<S>,\n): Promise<SandboxProviderHandleIface<S>> => {\n if (options.access === SandboxAccess.Read) return options.handle;\n if (options.extension.attach != null) return options.extension.attach(options);\n const controller = options.extension.controller({\n ctx: {\n organizationId: options.ctx.session.organizationId,\n platformEgressHosts: options.ctx.platformEgressHosts,\n platformNetworkPolicy: options.ctx.platformNetworkPolicy,\n actingUser: options.ctx.actingUser,\n bindings: options.ctx.bindings,\n },\n sandbox: options.handle.sandbox,\n access: options.access,\n workspaceId: options.workspaceId,\n initialNetworkPolicy: options.initialNetworkPolicy,\n afterGuard: options.restoreNetwork,\n afterBlock: options.blockNetwork,\n namespaceExists: options.namespaceExists,\n log: options.log,\n });\n try {\n await controller.initialize();\n let ready = true;\n try {\n const setupContext = { operation: SandboxExecutionOperation.Run, background: false };\n await options.ctx.executionPolicy?.beforeExecution(setupContext);\n await options.handle.executionPolicy?.beforeExecution(setupContext);\n await controller.guard();\n } catch (cause) {\n ready = false;\n options.log?.('workspace_networking.setup_deferred', {\n workspaceId: options.workspaceId,\n reason: cause instanceof Error ? cause.name : 'UnknownError',\n });\n }\n if (ready) await options.beforeUse();\n return await withSandboxNetworking({\n handle: options.handle,\n controller,\n access: options.access,\n beforeUse: options.beforeUse,\n initialized: true,\n fetch: options.extension.fetch,\n executionPolicy: options.ctx.executionPolicy,\n });\n } catch (cause) {\n await finishNetworking({\n close: () => controller.closeOnFailure(),\n finish: async () => {\n throw cause;\n },\n });\n throw cause;\n }\n};\n"],
5
+ "mappings": "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",
6
+ "names": []
7
+ }
@@ -0,0 +1,2 @@
1
+ export declare const sandboxMethodSource: (value: unknown) => unknown;
2
+ export declare const withSandboxOverrides: <T extends object>(source: T, overrides: object) => T;
@@ -0,0 +1,44 @@
1
+ const methodSources = /* @__PURE__ */ new WeakMap();
2
+ const sandboxMethodSource = (value) => typeof value === "function" ? methodSources.get(value) ?? value : value;
3
+ const withSandboxOverrides = (source, overrides) => {
4
+ const facade = Object.create(Object.getPrototypeOf(source));
5
+ const boundMethods = /* @__PURE__ */ new Map();
6
+ const seen = /* @__PURE__ */ new Set();
7
+ const read = (property) => {
8
+ const owner = Object.hasOwn(overrides, property) ? overrides : source;
9
+ const value = Reflect.get(owner, property, owner);
10
+ if (typeof value !== "function") return value;
11
+ const existing = boundMethods.get(property);
12
+ if (existing != null && existing.original === value) return existing.bound;
13
+ const bound = value.bind(source);
14
+ methodSources.set(bound, methodSources.get(value) ?? value);
15
+ boundMethods.set(property, { original: value, bound });
16
+ return bound;
17
+ };
18
+ for (let current = overrides; current != null; current = current === overrides ? source : Object.getPrototypeOf(current)) {
19
+ if (current === Object.prototype) break;
20
+ for (const property of Reflect.ownKeys(current)) {
21
+ if (property === "constructor" || seen.has(property)) continue;
22
+ seen.add(property);
23
+ const descriptor = Reflect.getOwnPropertyDescriptor(current, property);
24
+ Object.defineProperty(facade, property, {
25
+ configurable: true,
26
+ enumerable: descriptor?.enumerable ?? true,
27
+ get: () => read(property),
28
+ ...descriptor?.writable === true || descriptor?.set != null ? {
29
+ set: (value) => {
30
+ const owner = Object.hasOwn(overrides, property) ? overrides : source;
31
+ if (!Reflect.set(owner, property, value, owner))
32
+ throw new TypeError("Sandbox property is readonly");
33
+ }
34
+ } : {}
35
+ });
36
+ }
37
+ }
38
+ return facade;
39
+ };
40
+ export {
41
+ sandboxMethodSource,
42
+ withSandboxOverrides
43
+ };
44
+ //# sourceMappingURL=overrides.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../../../../src/sandbox/overrides.ts"],
4
+ "sourcesContent": ["const methodSources = new WeakMap<object, object>();\n\nexport const sandboxMethodSource = (value: unknown): unknown =>\n typeof value === 'function' ? (methodSources.get(value) ?? value) : value;\n\n// Preserve prototype methods, getters and private-field receivers in external provider sessions.\nexport const withSandboxOverrides = <T extends object>(source: T, overrides: object): T => {\n const facade: T = Object.create(Object.getPrototypeOf(source));\n const boundMethods = new Map<PropertyKey, { original: unknown; bound: unknown }>();\n const seen = new Set<PropertyKey>();\n const read = (property: PropertyKey): unknown => {\n const owner = Object.hasOwn(overrides, property) ? overrides : source;\n const value = Reflect.get(owner, property, owner);\n if (typeof value !== 'function') return value;\n const existing = boundMethods.get(property);\n if (existing != null && existing.original === value) return existing.bound;\n const bound = value.bind(source);\n methodSources.set(bound, methodSources.get(value) ?? value);\n boundMethods.set(property, { original: value, bound });\n return bound;\n };\n for (\n let current: object | null = overrides;\n current != null;\n current = current === overrides ? source : Object.getPrototypeOf(current)\n ) {\n if (current === Object.prototype) break;\n for (const property of Reflect.ownKeys(current)) {\n if (property === 'constructor' || seen.has(property)) continue;\n seen.add(property);\n const descriptor = Reflect.getOwnPropertyDescriptor(current, property);\n Object.defineProperty(facade, property, {\n configurable: true,\n enumerable: descriptor?.enumerable ?? true,\n get: () => read(property),\n ...(descriptor?.writable === true || descriptor?.set != null\n ? {\n set: (value: unknown) => {\n const owner = Object.hasOwn(overrides, property) ? overrides : source;\n if (!Reflect.set(owner, property, value, owner))\n throw new TypeError('Sandbox property is readonly');\n },\n }\n : {}),\n });\n }\n }\n return facade;\n};\n"],
5
+ "mappings": "AAAA,MAAM,gBAAgB,oBAAI,QAAwB;AAE3C,MAAM,sBAAsB,CAAC,UAClC,OAAO,UAAU,aAAc,cAAc,IAAI,KAAK,KAAK,QAAS;AAG/D,MAAM,uBAAuB,CAAmB,QAAW,cAAyB;AACzF,QAAM,SAAY,OAAO,OAAO,OAAO,eAAe,MAAM,CAAC;AAC7D,QAAM,eAAe,oBAAI,IAAwD;AACjF,QAAM,OAAO,oBAAI,IAAiB;AAClC,QAAM,OAAO,CAAC,aAAmC;AAC/C,UAAM,QAAQ,OAAO,OAAO,WAAW,QAAQ,IAAI,YAAY;AAC/D,UAAM,QAAQ,QAAQ,IAAI,OAAO,UAAU,KAAK;AAChD,QAAI,OAAO,UAAU,WAAY,QAAO;AACxC,UAAM,WAAW,aAAa,IAAI,QAAQ;AAC1C,QAAI,YAAY,QAAQ,SAAS,aAAa,MAAO,QAAO,SAAS;AACrE,UAAM,QAAQ,MAAM,KAAK,MAAM;AAC/B,kBAAc,IAAI,OAAO,cAAc,IAAI,KAAK,KAAK,KAAK;AAC1D,iBAAa,IAAI,UAAU,EAAE,UAAU,OAAO,MAAM,CAAC;AACrD,WAAO;AAAA,EACT;AACA,WACM,UAAyB,WAC7B,WAAW,MACX,UAAU,YAAY,YAAY,SAAS,OAAO,eAAe,OAAO,GACxE;AACA,QAAI,YAAY,OAAO,UAAW;AAClC,eAAW,YAAY,QAAQ,QAAQ,OAAO,GAAG;AAC/C,UAAI,aAAa,iBAAiB,KAAK,IAAI,QAAQ,EAAG;AACtD,WAAK,IAAI,QAAQ;AACjB,YAAM,aAAa,QAAQ,yBAAyB,SAAS,QAAQ;AACrE,aAAO,eAAe,QAAQ,UAAU;AAAA,QACtC,cAAc;AAAA,QACd,YAAY,YAAY,cAAc;AAAA,QACtC,KAAK,MAAM,KAAK,QAAQ;AAAA,QACxB,GAAI,YAAY,aAAa,QAAQ,YAAY,OAAO,OACpD;AAAA,UACE,KAAK,CAAC,UAAmB;AACvB,kBAAM,QAAQ,OAAO,OAAO,WAAW,QAAQ,IAAI,YAAY;AAC/D,gBAAI,CAAC,QAAQ,IAAI,OAAO,UAAU,OAAO,KAAK;AAC5C,oBAAM,IAAI,UAAU,8BAA8B;AAAA,UACtD;AAAA,QACF,IACA,CAAC;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO;AACT;",
6
+ "names": []
7
+ }
@@ -42,6 +42,7 @@ export interface ServeSandboxHandleArgsIface {
42
42
  sandbox: NetworkSandboxSessionIface;
43
43
  handle?: HandleLifecycle;
44
44
  authorize: HandleAuthorizeFn;
45
+ authorizeOperation?: HandleRpcMessageHandlerOptionsIface['authorizeOperation'];
45
46
  access?: HandleAccessPolicyIface;
46
47
  binary?: boolean;
47
48
  mcpChannels?: boolean;
@@ -1,7 +1,10 @@
1
1
  import * as z from "zod";
2
+ import { WorkspaceEgressAction } from "@finalai/agent-protocol/device-egress";
2
3
  import { narrowerSandboxAccess, SandboxAccess, sandboxAccessAtLeast } from "../manifest.mjs";
3
4
  import { base64ToBytes, bytesToStream } from "./bytes.mjs";
4
5
  import { confinedReadDir, confinedReadFile, confinedStat } from "./confined-files.mjs";
6
+ import { hasSandboxExecutionGuard } from "./execution-guard.mjs";
7
+ import { hasHostedMcpEndpoints } from "./mcp-hosted-marker.mjs";
5
8
  import { createRpcPeer } from "./rpc-peer.mjs";
6
9
  import {
7
10
  isMcpChannelEndpoint,
@@ -26,8 +29,9 @@ const DEFAULT_HANDLE_ACCESS = {
26
29
  mode: SandboxAccess.Write,
27
30
  lifecycle: false
28
31
  };
32
+ const needsMcpChannels = (sandbox) => hasSandboxExecutionGuard(sandbox) && !hasHostedMcpEndpoints(sandbox);
29
33
  const servesComputerUse = async (sandbox) => {
30
- if (sandbox.computerUse == null) return false;
34
+ if (sandbox.computerUse == null || needsMcpChannels(sandbox)) return false;
31
35
  try {
32
36
  return !isMcpChannelEndpoint(await sandbox.computerUse());
33
37
  } catch {
@@ -38,10 +42,12 @@ const capabilitiesOf = async (sandbox, mcpChannels = false) => {
38
42
  const capabilities = [SandboxCapability.Files, SandboxCapability.Process];
39
43
  if (sandbox.ports.length > 0) capabilities.push(SandboxCapability.Ports);
40
44
  if (sandbox.setNetworkPolicy != null) capabilities.push(SandboxCapability.NetworkPolicy);
45
+ if (sandbox.egress != null) capabilities.push(SandboxCapability.Egress);
41
46
  if (mcpChannels ? sandbox.computerUse != null : await servesComputerUse(sandbox))
42
47
  capabilities.push(SandboxCapability.ComputerUse);
43
48
  if (sandbox.screen != null) capabilities.push(SandboxCapability.Screen);
44
- if (sandbox.localMcp != null) capabilities.push(SandboxCapability.LocalMcp);
49
+ if (sandbox.localMcp != null && (mcpChannels || !needsMcpChannels(sandbox)))
50
+ capabilities.push(SandboxCapability.LocalMcp);
45
51
  return capabilities;
46
52
  };
47
53
  const describeSandbox = async (sandbox, mcpChannels = false) => ({
@@ -184,6 +190,18 @@ const createServerConnection = (args) => {
184
190
  message: `${method} is not allowed without write access`
185
191
  });
186
192
  }
193
+ if (method === HandleRpcMethod.Egress && !sandboxAccessAtLeast(access.mode, SandboxAccess.Write)) {
194
+ throw handleRpcError({
195
+ code: HandleRpcErrorCode.Forbidden,
196
+ message: "Device egress requires write access"
197
+ });
198
+ }
199
+ if (method === HandleRpcMethod.SetNetworkPolicy && access.mode === SandboxAccess.Read) {
200
+ throw handleRpcError({
201
+ code: HandleRpcErrorCode.Forbidden,
202
+ message: `${method} is not allowed on a read-only binding`
203
+ });
204
+ }
187
205
  if (!access.lifecycle && HANDLE_RPC_LIFECYCLE_METHODS.includes(method)) {
188
206
  throw handleRpcError({
189
207
  code: HandleRpcErrorCode.Forbidden,
@@ -273,6 +291,11 @@ const createServerConnection = (args) => {
273
291
  });
274
292
  checkAccess(method, context.params);
275
293
  parseParams(handleRpcMethodSchemas[method].params, context.params);
294
+ if (method === HandleRpcMethod.Egress && parseParams(handleRpcMethodSchemas[HandleRpcMethod.Egress].params, context.params).action !== WorkspaceEgressAction.Status && args.authorizeOperation == null)
295
+ throw handleRpcError({
296
+ code: HandleRpcErrorCode.Forbidden,
297
+ message: "Device egress changes require an operation authorization hook"
298
+ });
276
299
  await args.authorizeOperation?.(context);
277
300
  if (context.signal.aborted)
278
301
  throw handleRpcError({ code: HandleRpcErrorCode.Cancelled, message: "request cancelled" });
@@ -440,8 +463,17 @@ const createServerConnection = (args) => {
440
463
  await target.setNetworkPolicy(params);
441
464
  return {};
442
465
  }
466
+ case HandleRpcMethod.Egress: {
467
+ const params = parseParams(handleRpcMethodSchemas[method].params, context.params);
468
+ if (target.egress == null) throw unsupported("Device egress");
469
+ return handleRpcMethodSchemas[HandleRpcMethod.Egress].result.parse(
470
+ await target.egress(params)
471
+ );
472
+ }
443
473
  case HandleRpcMethod.ComputerUse: {
444
474
  if (target.computerUse == null) throw unsupported("computer use");
475
+ if (needsMcpChannels(target) && args.mcpChannels !== true)
476
+ throw unsupported("guarded MCP transport; negotiate mcpChannels");
445
477
  const endpoint = await target.computerUse();
446
478
  return mcpDescriptor(endpoint, "computerUse");
447
479
  }
@@ -482,6 +514,8 @@ const createServerConnection = (args) => {
482
514
  }
483
515
  case HandleRpcMethod.LocalMcp:
484
516
  if (target.localMcp == null) throw unsupported("local MCP servers");
517
+ if (needsMcpChannels(target) && args.mcpChannels !== true)
518
+ throw unsupported("guarded MCP transport; negotiate mcpChannels");
485
519
  return {
486
520
  endpoints: (await target.localMcp()).flatMap(
487
521
  (endpoint, index) => args.mcpChannels !== true && isMcpChannelEndpoint(endpoint) ? [] : [mcpDescriptor(endpoint, `localMcp:${index}:${endpoint.name}`)]
@@ -532,6 +566,7 @@ const serveSandboxHandle = (args) => {
532
566
  const connection = createServerConnection({
533
567
  channel,
534
568
  authorize: args.authorize,
569
+ authorizeOperation: args.authorizeOperation,
535
570
  resolve,
536
571
  access,
537
572
  connectionToken: context?.token ?? null,
@@ -549,6 +584,7 @@ const serveSandboxHandle = (args) => {
549
584
  send: handlerArgs.send,
550
585
  close: handlerArgs.close,
551
586
  authorize: args.authorize,
587
+ authorizeOperation: args.authorizeOperation,
552
588
  resolve,
553
589
  access,
554
590
  connectionToken: handlerArgs.token ?? null,