@finalai/final-agent-provider 0.3.4 → 0.4.1

package/dist/modules/sandboxes/computer.mjs

@@ -7,6 +7,9 @@ import {
 } from "@finalai/agent-provider";
 import {
   defineSandboxProvider,
+  withSandboxNetworking,
+  mapSandboxHandle,
+  SandboxExecutionOperation,
   materializeSandboxSeeds,
   PLATFORM_ENVIRONMENT_NAMES,
   platformProcessEnvironment,
@@ -18,6 +21,7 @@ import {
   sandboxSeedFiles,
   sandboxSeedFilesForStart,
   sandboxSeedIdentity,
+  sandboxWorkspaceId,
   SandboxWorkspace,
   withPlatformEgressHosts,
   writePlatformFiles
@@ -70,6 +74,7 @@ import {
   startServices,
   WORKSPACE_ROOT
 } from "./workspace-setup.mjs";
+const computerWorkspaceName = async (options) => options.conversationWorkspace && options.conversationId != null ? `ac-${(await sha256Hex(`${options.conversationId}:${options.target}`)).slice(0, 24)}` : `ab-${compactId(options.bindingId)}`;
 import {
   COMPUTER_SANDBOX_SPECIFIER as COMPUTER_SANDBOX_SPECIFIER2,
   COMPUTERS_API_KEY_SECRET,
@@ -97,7 +102,10 @@ const computerStateSchema = z.object({
   workspace: z.nativeEnum(ComputerWorkspacePolicy),
   access: z.nativeEnum(SandboxAccess),
   guideVersionId: z.string().nullable(),
-  setupHash: z.string().nullable()
+  setupHash: z.string().nullable(),
+  setupPending: z.boolean().default(false),
+  workspaceId: z.string().optional(),
+  networkPolicySaved: z.boolean().optional()
 });
 const computerSandboxError = (code, message) => Object.assign(new Error(message), { name: "ComputerSandboxError", code });
 const RESERVED_ENV = /* @__PURE__ */ new Set([
@@ -136,6 +144,10 @@ const CAPTURE_SCRUBBED_PATHS = [
   "/home/user/.ssh"
 ];
 const BUILDER_IDLE_TIMEOUT_SECONDS = 2 * 60 * 60;
+const networkPolicyFor = (network) => ({
+  mode: network?.egress === ComputerEgressPolicy.Internet ? NetworkPolicy.AllowAll : network?.egress === ComputerEgressPolicy.Allowlist ? NetworkPolicy.Allowlist : NetworkPolicy.DenyAll,
+  allow: network?.allow ?? []
+});
 const computerEgressOf = (policy) => {
   if (policy.mode === NetworkPolicy.AllowAll) return { egress: ComputerEgressPolicy.Internet };
   if (policy.mode === NetworkPolicy.DenyAll) return { egress: ComputerEgressPolicy.None };
@@ -235,6 +247,19 @@ const createComputerSandboxProvider = (config) => {
     );
     for (const result of results) if (result.status === "rejected") throw result.reason;
   };
+  const deletedAfterFenceError = async (options) => {
+    if (isComputersApiStatus(options.cause, 404)) return true;
+    if (!isComputersApiStatus(options.cause, 409)) return false;
+    try {
+      const current = await options.client.getComputer(options.computerId);
+      return current == null || current.state === ComputerState.Deleted;
+    } catch (lookup) {
+      throw new AggregateError(
+        [options.cause, lookup],
+        "Computer fence and deletion lookup failed"
+      );
+    }
+  };
   const buildHandle = async (args) => {
     const { client, info, spec } = args;
     const commands = await guideCommands(spec.template);
@@ -263,10 +288,23 @@ ${commandHelp}`}`,
         ports,
         // The computer's hostname with a preview token, which opens its HTTP ports only.
         getPortEndpoint: async ({ port, protocol }) => {
+          const managed = args.networkingManaged === true || args.access === SandboxAccess.Read && await needsWorkspaceNetworking(
+            args.ctx,
+            sandboxWorkspaceId({
+              session: args.ctx.session,
+              workspace: sandboxWorkspaceOf[args.spec.parameters.workspace]
+            }),
+            { access: args.access }
+          );
+          if (managed && args.networking == null)
+            throw new Error("Managed workspace previews require an active write binding");
+          const deadline = (await args.networking?.authorizeExternalAccess())?.expiresAtMs;
+          if (deadline != null && deadline <= now())
+            throw new Error("Refresh workspace networking before preview access");
           const hostname = info.hostname ?? (await client.getComputer(info.id))?.hostname ?? null;
           if (hostname == null) throw new Error(`computer ${info.name} has no public hostname`);
-          if (httpToken == null || httpToken.expiresAtMs - now() < HTTP_TOKEN_RENEW_MS) {
-            const expiresAtMs = now() + HTTP_TOKEN_LIFETIME_MS;
+          if (httpToken == null || httpToken.expiresAtMs - now() < HTTP_TOKEN_RENEW_MS || deadline != null && httpToken.expiresAtMs > deadline) {
+            const expiresAtMs = Math.min(now() + HTTP_TOKEN_LIFETIME_MS, deadline ?? Infinity);
             const token = await client.createPreviewToken({
               computerId: info.id,
               name: `agent sandbox ${args.ctx.session.bindingId}`,
@@ -281,17 +319,80 @@ ${commandHelp}`}`,
           };
         },
         stop: async () => {
-          await closeComputerMcp(info.id);
-          await client.action(info.id, "stop");
-        },
-        destroy: async () => {
-          await closeComputerMcp(info.id);
-          transport.close();
+          const failures = [];
           try {
-            await client.action(info.id, "delete");
-          } catch (error) {
-            if (!isComputersApiStatus(error, 404)) throw error;
+            if (args.networking != null)
+              await client.setNetworkPolicy(
+                info.id,
+                { egress: ComputerEgressPolicy.None },
+                { autoResume: false }
+              );
+            else if (args.access !== SandboxAccess.Read)
+              await teardownComputer({
+                ctx: args.ctx,
+                computerId: info.id,
+                computerName: info.name,
+                workspace: spec.parameters.workspace,
+                policySaved: args.networkingManaged === true,
+                workspaceId: args.ctx.session.workspaceId,
+                fence: true,
+                finish: async () => {
+                }
+              });
+          } catch (cause) {
+            try {
+              if (!await deletedAfterFenceError({ client, computerId: info.id, cause }))
+                failures.push(cause);
+            } catch (lookup) {
+              failures.push(lookup);
+            }
+          }
+          try {
+            await closeComputerMcp(info.id);
+          } catch (cause) {
+            if (!isComputersApiStatus(cause, 404)) failures.push(cause);
+          }
+          try {
+            await client.action(info.id, "stop");
+          } catch (cause) {
+            if (!isComputersApiStatus(cause, 404)) failures.push(cause);
           }
+          transport.close();
+          args.closeSetup?.();
+          if (failures.length === 1) throw failures[0];
+          if (failures.length > 1)
+            throw new AggregateError(failures, "Computer stop or networking fence failed");
+        },
+        destroy: async () => {
+          const finish = async () => {
+            const failures = [];
+            try {
+              await closeComputerMcp(info.id);
+            } catch (cause) {
+              failures.push(cause);
+            }
+            transport.close();
+            try {
+              await client.action(info.id, "delete");
+            } catch (cause) {
+              if (!isComputersApiStatus(cause, 404)) failures.push(cause);
+            }
+            if (failures.length === 1) throw failures[0];
+            if (failures.length > 1)
+              throw new AggregateError(failures, "Computer delete or MCP cleanup failed");
+          };
+          if (args.networking == null && args.access !== SandboxAccess.Read)
+            await teardownComputer({
+              ctx: args.ctx,
+              computerId: info.id,
+              computerName: info.name,
+              workspace: spec.parameters.workspace,
+              policySaved: args.networkingManaged === true,
+              workspaceId: args.ctx.session.workspaceId,
+              fence: true,
+              finish
+            });
+          else await finish();
         }
       }
     });
@@ -331,6 +432,8 @@ ${commandHelp}`}`,
     if (computerUse != null) capabilities.push(SandboxCapability.ComputerUse);
     if (args.access !== SandboxAccess.Read)
       capabilities.push(SandboxCapability.Process, SandboxCapability.NetworkPolicy);
+    if (args.access === SandboxAccess.Write && args.networking != null)
+      capabilities.push(...config.networking?.capabilities ?? []);
     const description = {
       provider: "computer",
       computerId: info.id,
@@ -364,38 +467,126 @@ ${commandHelp}`}`,
     if (screenAvailable) {
       full.screen = (options) => client.openScreen(info.id, options);
     }
-    const sandbox = sessionForAccess(full, args.access);
-    return {
-      handle: {
-        sandbox,
-        onSandboxStop: async () => {
+    const sandbox = full;
+    let handle = {
+      sandbox,
+      onSandboxStop: async () => {
+        const failures = [];
+        try {
+          if (args.networking != null)
+            await client.setNetworkPolicy(
+              info.id,
+              { egress: ComputerEgressPolicy.None },
+              { autoResume: false }
+            );
+          else
+            await teardownComputer({
+              ctx: args.ctx,
+              computerId: info.id,
+              computerName: info.name,
+              workspace: spec.parameters.workspace,
+              policySaved: args.networkingManaged === true,
+              workspaceId: args.ctx.session.workspaceId,
+              fence: true,
+              finish: async () => {
+              }
+            });
+        } catch (cause) {
           try {
-            await closeMcp();
-          } finally {
-            transport.close();
+            if (!await deletedAfterFenceError({ client, computerId: info.id, cause }))
+              failures.push(cause);
+          } catch (lookup) {
+            failures.push(lookup);
           }
-        },
-        onSandboxDelete: async () => {
+        }
+        for (const finish of [closeMcp, () => transport.close(), () => args.closeSetup?.()]) {
           try {
-            await closeMcp();
-          } finally {
-            transport.close();
+            await finish();
+          } catch (cause) {
+            failures.push(cause);
           }
+        }
+        if (failures.length === 1) throw failures[0];
+        if (failures.length > 1)
+          throw new AggregateError(failures, "Computer fence and MCP cleanup failed");
+      },
+      onSandboxDelete: async () => {
+        const finish = async () => {
+          const failures = [];
           try {
-            await client.action(info.id, "delete");
-          } catch (error) {
-            if (!isComputersApiStatus(error, 404)) throw error;
+            await closeMcp();
+          } catch (cause) {
+            failures.push(cause);
           }
-        },
-        onRuntimeShutdown: async () => {
+          transport.close();
+          args.closeSetup?.();
           try {
-            await closeMcp();
-          } finally {
-            transport.close();
+            await client.action(info.id, "delete");
+          } catch (cause) {
+            if (!isComputersApiStatus(cause, 404)) failures.push(cause);
           }
+          if (failures.length === 1) throw failures[0];
+          if (failures.length > 1)
+            throw new AggregateError(failures, "Computer delete or MCP cleanup failed");
+        };
+        if (args.networking == null)
+          await teardownComputer({
+            ctx: args.ctx,
+            computerId: info.id,
+            computerName: info.name,
+            workspace: spec.parameters.workspace,
+            policySaved: args.networkingManaged === true,
+            workspaceId: args.ctx.session.workspaceId,
+            fence: true,
+            finish
+          });
+        else await finish();
+      },
+      onRuntimeShutdown: async () => {
+        try {
+          await closeMcp();
+        } finally {
+          transport.close();
+          args.closeSetup?.();
         }
       }
     };
+    if (args.networking != null)
+      handle = await withSandboxNetworking({
+        handle,
+        controller: args.networking,
+        access: args.access,
+        initialized: true,
+        fetch: config.networking?.fetch,
+        executionPolicy: args.ctx.executionPolicy,
+        beforeUse: args.beforeUse
+      });
+    else if (config.networking != null)
+      handle = await withSandboxNetworking({
+        handle,
+        access: args.access,
+        fetch: config.networking?.fetch,
+        executionPolicy: args.ctx.executionPolicy,
+        admission: async () => {
+          if (await needsWorkspaceNetworking(
+            args.ctx,
+            sandboxWorkspaceId({
+              session: args.ctx.session,
+              workspace: sandboxWorkspaceOf[args.spec.parameters.workspace]
+            }),
+            { access: args.access }
+          ))
+            throw new Error(
+              "Workspace networking changed; reconnect this sandbox before running tools"
+            );
+        }
+      });
+    return {
+      handle: mapSandboxHandle({
+        handle,
+        mapSandbox: (sandbox2) => sessionForAccess(sandbox2, args.access)
+      })
+    };
   };
   const setupSession = (args) => {
     const transport = createComputersApiTransport({
@@ -420,6 +611,170 @@ ${commandHelp}`}`,
     });
     return { sandbox, transport };
   };
+  const createNetworkingController = (options) => {
+    try {
+      if (config.networking == null) throw new Error("Workspace networking extension is required");
+      return config.networking.controller(options);
+    } catch (cause) {
+      options.onClose?.();
+      throw cause;
+    }
+  };
+  const workspaceNetworking = (args) => {
+    if (config.networking == null || !args.enabled) return void 0;
+    return createNetworkingController({
+      ctx: {
+        platformEgressHosts: args.ctx.platformEgressHosts,
+        platformNetworkPolicy: args.ctx.platformNetworkPolicy,
+        organizationId: args.ctx.session.organizationId,
+        actingUser: args.ctx.actingUser,
+        bindings: args.ctx.bindings
+      },
+      sandbox: args.sandbox,
+      workspaceId: sandboxWorkspaceId({
+        session: args.ctx.session,
+        workspace: sandboxWorkspaceOf[args.spec.parameters.workspace]
+      }),
+      access: args.access,
+      onClose: args.onClose,
+      initialNetworkPolicy: args.initialNetworkPolicy,
+      namespaceExists: async () => {
+        const current = await args.client.getComputer(args.info.id);
+        return current?.state === ComputerState.Running;
+      },
+      log,
+      afterBlock: () => args.client.setNetworkPolicy(
+        args.info.id,
+        { egress: ComputerEgressPolicy.None },
+        { autoResume: false }
+      ),
+      afterGuard: (policy) => args.client.setNetworkPolicy(
+        args.info.id,
+        egressFor(args.ctx, policy ?? { mode: NetworkPolicy.DenyAll }),
+        { autoResume: false }
+      )
+    });
+  };
+  const managedWorkspaces = /* @__PURE__ */ new Set();
+  const savedPolicyWorkspaces = /* @__PURE__ */ new Set();
+  const preservePolicy = async (args) => {
+    if (config.networking == null) throw new Error("Workspace networking extension is required");
+    const retained = await config.networking.prepare({
+      ctx: {
+        platformEgressHosts: args.ctx.platformEgressHosts,
+        platformNetworkPolicy: args.ctx.platformNetworkPolicy,
+        organizationId: args.ctx.session.organizationId,
+        actingUser: args.ctx.actingUser,
+        bindings: args.ctx.bindings
+      },
+      workspaceId: args.workspaceId,
+      policy: args.policy
+    });
+    await reportPlatformNetworkPolicy(args.ctx, retained ?? args.policy);
+    savedPolicyWorkspaces.add(args.ctx.session.organizationId + ":" + args.workspaceId);
+  };
+  const needsWorkspaceNetworking = async (ctx, workspaceId, query = {}) => {
+    const needed = await config.networking?.enabled({
+      ctx: {
+        platformEgressHosts: ctx.platformEgressHosts,
+        organizationId: ctx.session.organizationId,
+        actingUser: ctx.actingUser,
+        bindings: ctx.bindings
+      },
+      workspaceId,
+      access: SandboxAccess.Write,
+      ...query
+    }) ?? false;
+    if (needed) managedWorkspaces.add(ctx.session.organizationId + ":" + workspaceId);
+    return needed || managedWorkspaces.has(ctx.session.organizationId + ":" + workspaceId);
+  };
+  const teardownComputer = async (args) => {
+    let workspaceId;
+    try {
+      workspaceId = args.workspaceId ?? sandboxWorkspaceId({
+        session: args.ctx.session,
+        workspace: sandboxWorkspaceOf[args.workspace]
+      });
+    } catch (cause) {
+      try {
+        await args.finish();
+      } catch (cleanup) {
+        throw new AggregateError([cause, cleanup], "Computer identity and teardown failed");
+      }
+      throw cause;
+    }
+    const failures = [];
+    let managed = args.policySaved || managedWorkspaces.has(args.ctx.session.organizationId + ":" + workspaceId);
+    let queryFailed = false;
+    try {
+      managed = await needsWorkspaceNetworking(args.ctx, workspaceId, { teardown: true }) || args.policySaved;
+    } catch (cause) {
+      failures.push(cause);
+      queryFailed = true;
+    }
+    const results = await Promise.allSettled([
+      (async () => {
+        if (managed && args.fence) {
+          const client = clientFor(args.ctx.session.organizationId);
+          let mayFence = args.policySaved || savedPolicyWorkspaces.has(args.ctx.session.organizationId + ":" + workspaceId);
+          try {
+            if (config.networking != null) {
+              await preservePolicy({
+                ctx: args.ctx,
+                workspaceId,
+                policy: networkPolicyFor(await client.getNetworkPolicy(args.computerId))
+              });
+              mayFence = true;
+            }
+          } catch (cause) {
+            if (isComputersApiStatus(cause, 404)) mayFence = false;
+            else failures.push(cause);
+          }
+          if (mayFence) {
+            try {
+              await client.setNetworkPolicy(
+                args.computerId,
+                { egress: ComputerEgressPolicy.None },
+                { autoResume: false }
+              );
+            } catch (cause) {
+              let settled = isComputersApiStatus(cause, 404);
+              if (!settled && isComputersApiStatus(cause, 409)) {
+                try {
+                  const latest = await client.getComputer(args.computerId);
+                  settled = latest == null || latest.state === ComputerState.Deleted;
+                } catch (lookup) {
+                  failures.push(lookup);
+                }
+              }
+              if (!settled) failures.push(cause);
+            }
+          }
+        }
+        await args.finish();
+      })(),
+      (async () => {
+        if (managed && config.networking == null)
+          throw new Error(
+            "Managed Computer teardown requires the workspace egress integration to revoke Device access"
+          );
+        if (config.networking != null && (managed || queryFailed))
+          await config.networking.suspend({
+            ctx: {
+              organizationId: args.ctx.session.organizationId,
+              actingUser: args.ctx.actingUser,
+              bindings: args.ctx.bindings
+            },
+            workspaceId
+          });
+      })()
+    ]);
+    for (const result of results) if (result.status === "rejected") failures.push(result.reason);
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1)
+      throw new AggregateError(failures, "Computer teardown and egress revocation failed");
+    return workspaceId;
+  };
   const awaitBase = async (client, baseId, key) => {
     const deadline = now() + (config.buildWaitMs ?? 30 * 6e4);
     for (; ; ) {
@@ -625,18 +980,72 @@ ${step.run}`,
         );
         return request.operation === ProcessInspectionOperation.Available && "available" in result ? { ...result, canStop: state.access !== SandboxAccess.Read } : result;
       },
-      editor: async (_ctx, rawState, request) => {
+      editor: async (ctx, rawState, request) => {
         const state = computerStateSchema.parse(rawState);
         if (state.access !== SandboxAccess.Write) {
           if (request.operation === "available") return { available: false };
           throw new Error("editor requires write access");
         }
-        return computerEditor({
-          client: clientFor(_ctx.organizationId),
+        const client = clientFor(ctx.organizationId);
+        const open = (expiresAtMs) => computerEditor({
+          client,
           computerId: state.computerId,
           request,
-          randomUuid
+          randomUuid,
+          expiresAtMs
         });
+        if (request.operation === "available" || request.operation === "close") return open();
+        const workspaceId = ctx.workspaceId ?? state.workspaceId;
+        if (state.networkPolicySaved === true && ctx.workspaceId != null && state.workspaceId != null && ctx.workspaceId !== state.workspaceId)
+          throw new Error("Editor workspace identity does not match its retained provider state");
+        if (config.networking == null) {
+          if (state.networkPolicySaved === true)
+            throw new Error("Device networking control is required before opening this editor");
+          return open();
+        }
+        if (workspaceId == null)
+          throw new Error(
+            "The host must supply logical workspace identity before opening an egress-aware editor"
+          );
+        const managedKey = ctx.organizationId + ":" + workspaceId;
+        const managed = state.networkPolicySaved === true || managedWorkspaces.has(managedKey) || await config.networking.enabled({ ctx, workspaceId, access: SandboxAccess.Write });
+        if (!managed) return open();
+        managedWorkspaces.add(managedKey);
+        config.networking.validateWorkspaceId?.(workspaceId);
+        const info = await client.getComputer(state.computerId);
+        if (info == null || info.state !== ComputerState.Running)
+          throw new Error("Computer must be running before editor access");
+        const initialNetworkPolicy = networkPolicyFor(await client.getNetworkPolicy(info.id));
+        const setup = setupSession({ client, info, env: async () => ({}) });
+        const manager = createNetworkingController({
+          sandbox: setup.sandbox,
+          onClose: () => setup.transport.close(),
+          workspaceId,
+          ctx,
+          access: SandboxAccess.Write,
+          initialNetworkPolicy,
+          afterBlock: () => client.setNetworkPolicy(
+            info.id,
+            { egress: ComputerEgressPolicy.None },
+            { autoResume: false }
+          ),
+          afterGuard: async (policy) => client.setNetworkPolicy(
+            info.id,
+            policy == null ? { egress: ComputerEgressPolicy.None } : egressFor(ctx, policy),
+            { autoResume: false }
+          ),
+          allowOwnerChange: false
+        });
+        const { expiresAtMs: deadline } = await manager.authorizeExternalAccess().finally(async () => {
+          try {
+            await manager.close();
+          } finally {
+            setup.transport.close();
+          }
+        });
+        if (deadline != null && deadline <= now())
+          throw new Error("Refresh workspace egress before opening the editor");
+        return open(deadline ?? void 0);
       },
       readSnapshot: async (ctx, rawState, request) => {
         const state = computerStateSchema.parse(rawState);
@@ -648,6 +1057,8 @@ ${step.run}`,
       },
       // The merged parameters' workspace: the binding's, else the saved version's default.
       workspace: async (ctx) => sandboxWorkspaceOf[(await resolve(ctx.guides)).parameters.workspace],
+      // Screen and computer-use availability is known only after attaching the actual Computer.
+      additionalCapabilities: async () => config.networking?.capabilities.slice() ?? [],
       artifactKey: async (ctx) => keyFor(await resolve(ctx.guides), seedsFor(ctx)),
       // Registers an image reference so its version builds ahead of the first start;
       // a lineage needs nothing until then.
@@ -737,18 +1148,50 @@ ${step.run}`,
         const env = platformProcessEnvironment(ctx, await loadVariables(ctx, spec));
         const client = clientFor(ctx.session.organizationId);
         const workspace = spec.parameters.workspace;
-        const name = workspace === ComputerWorkspacePolicy.Conversation && ctx.session.conversationId != null ? `ac-${(await sha256Hex(`${ctx.session.conversationId}:${ctx.session.target}`)).slice(0, 24)}` : `ab-${compactId(ctx.session.bindingId)}`;
+        const name = await computerWorkspaceName({
+          ...ctx.session,
+          conversationWorkspace: workspace === ComputerWorkspacePolicy.Conversation
+        });
+        const workspaceId = sandboxWorkspaceId({
+          session: ctx.session,
+          workspace: sandboxWorkspaceOf[workspace]
+        });
+        const manageNetworking = await needsWorkspaceNetworking(ctx, workspaceId) || access !== SandboxAccess.Read && await needsWorkspaceNetworking(ctx, workspaceId, { access });
+        if (manageNetworking)
+          config.networking?.validateWorkspaceId?.(
+            sandboxWorkspaceId({ session: ctx.session, workspace: sandboxWorkspaceOf[workspace] })
+          );
         const existing = await client.getComputer(name);
         if (existing?.state === ComputerState.Error)
           throw computerSandboxError(
             "computer_gone",
             `Computer ${existing.id} (${name}) is in the Error state. Recover it through the Computers API before retrying; its workspace is preserved.`
           );
+        if (manageNetworking && access === SandboxAccess.Read && existing != null && existing.state !== ComputerState.Deleted && existing.state !== ComputerState.Running)
+          throw new Error("A managed Computer requires a write binding to resume networking");
+        const initialNetworkPolicy = manageNetworking && existing != null && existing.state !== ComputerState.Deleted ? networkPolicyFor(await client.getNetworkPolicy(existing.id)) : networkPolicyFor(egress);
+        if (manageNetworking && access !== SandboxAccess.Read && existing?.state === ComputerState.Running)
+          await client.disableAutoResume(existing.id);
+        if (manageNetworking && config.networking != null)
+          await preservePolicy({
+            ctx,
+            workspaceId: sandboxWorkspaceId({
+              session: ctx.session,
+              workspace: sandboxWorkspaceOf[workspace]
+            }),
+            policy: initialNetworkPolicy
+          });
         let info;
         let fresh = true;
         if (existing != null && existing.state !== ComputerState.Deleted) {
           info = existing;
           fresh = !isRunningState(existing.state);
+          if (manageNetworking && existing.state !== ComputerState.Running)
+            await client.setNetworkPolicy(
+              existing.id,
+              { egress: ComputerEgressPolicy.None },
+              { autoResume: false }
+            );
           if (existing.state === ComputerState.Paused) await client.action(existing.id, "resume");
           else if (fresh) await client.action(existing.id, "start");
         } else {
@@ -758,11 +1201,11 @@ ${step.run}`,
             ...source,
             ...config.machine,
             env: {},
-            autoResume: true,
+            autoResume: !manageNetworking,
             idleTimeoutSeconds: config.idleTimeoutSeconds ?? 15 * 60,
             // Provider teardown owns deletion; VM-level ephemeral disks cannot be paused.
             ephemeral: false,
-            network: egress,
+            network: manageNetworking ? { egress: ComputerEgressPolicy.None } : egress,
             tags: [
               "final-agent-sandbox",
               `agent-binding:${ctx.session.bindingId}`,
@@ -772,37 +1215,109 @@ ${step.run}`,
           };
           body.idlePolicy = ComputerIdlePolicy.Pause;
           if (config.regionSlug != null) body.regionSlug = config.regionSlug;
-          const idempotencyKey = `agent-sandbox-${(await sha256Hex(`${ctx.session.bindingId}:${name}:${source.baseId ?? source.imageVersionId}`)).slice(0, 32)}`;
+          const idempotencyKey = `agent-sandbox-${(await sha256Hex(`${ctx.session.bindingId}:${name}:${source.baseId ?? source.imageVersionId}:${manageNetworking}`)).slice(0, 32)}`;
           info = await client.createComputer(body, idempotencyKey);
         }
         const reused = existing != null && existing.id === info.id;
         log("computer_sandbox.started", { computerId: info.id, reused });
+        let cleanupSetup = null;
         try {
           info = await awaitRunning(ctx, { computerId: info.id }, { timeoutMs: runningWaitMs });
-          if (reused) await client.setNetworkPolicy(info.id, egress);
-          await reportPlatformNetworkPolicy(ctx, policy);
+          if (!manageNetworking) {
+            if (reused) await client.setNetworkPolicy(info.id, egress);
+            await reportPlatformNetworkPolicy(ctx, policy);
+          }
           const setup = setupSession({ client, info, env });
-          await writePlatformFiles(ctx, setup.sandbox);
-          await mountRepositories({
+          cleanupSetup = async () => setup.transport.close();
+          if (!manageNetworking || access !== SandboxAccess.Read)
+            await writePlatformFiles(ctx, setup.sandbox);
+          const manager = workspaceNetworking({
+            ctx,
+            enabled: manageNetworking && access !== SandboxAccess.Read,
+            access,
             sandbox: setup.sandbox,
-            repositories: spec.parameters.repositories,
-            resolver: ctx.repositories,
-            log
+            client,
+            info,
+            spec,
+            onClose: () => setup.transport.close(),
+            initialNetworkPolicy
           });
-          await materializeSandboxSeeds({
-            sandbox: setup.sandbox,
-            root: WORKSPACE_ROOT,
-            files: await sandboxSeedFilesForStart(ctx, artifact.data)
+          cleanupSetup = async () => {
+            try {
+              await manager?.closeOnFailure();
+            } finally {
+              setup.transport.close();
+            }
+          };
+          const servicesMarker = WORKSPACE_ROOT + "/.final-workspace-services";
+          if (fresh && manageNetworking)
+            await setup.sandbox.writeTextFile({ path: servicesMarker, content: "pending" });
+          await manager?.initialize();
+          const preparationMarker = WORKSPACE_ROOT + "/.final/workspace-prepared/" + await sha256Hex(artifact.data.key);
+          let preparation = null;
+          const prepareWorkspace = () => preparation ??= (async () => {
+            await mountRepositories({
+              sandbox: setup.sandbox,
+              repositories: spec.parameters.repositories,
+              resolver: ctx.repositories,
+              log
+            });
+            await materializeSandboxSeeds({
+              sandbox: setup.sandbox,
+              root: WORKSPACE_ROOT,
+              files: await sandboxSeedFilesForStart(ctx, artifact.data)
+            });
+            await installGuideCommands({ sandbox: setup.sandbox, template: spec.template });
+            const result = await runWorkspaceSetup({
+              sandbox: setup.sandbox,
+              template: spec.template,
+              repositories: spec.parameters.repositories,
+              log
+            });
+            const servicesPending = manager != null && await setup.sandbox.stat({ path: servicesMarker }) != null && await setup.sandbox.readTextFile({ path: servicesMarker }) === "pending";
+            if (fresh || servicesPending) {
+              await startServicesFor({ setup, spec, env });
+              if (manageNetworking)
+                await setup.sandbox.writeTextFile({ path: servicesMarker, content: "complete" });
+            }
+            if (manager != null)
+              await setup.sandbox.writeTextFile({ path: preparationMarker, content: "complete" });
+            return result;
+          })().catch((cause) => {
+            preparation = null;
+            throw cause;
           });
-          await installGuideCommands({ sandbox: setup.sandbox, template: spec.template });
-          const setupHash = await runWorkspaceSetup({
-            sandbox: setup.sandbox,
-            template: spec.template,
-            repositories: spec.parameters.repositories,
-            log
+          let ready = !manageNetworking || access !== SandboxAccess.Read;
+          if (manager != null) {
+            try {
+              await ctx.executionPolicy?.beforeExecution({
+                operation: SandboxExecutionOperation.Run,
+                background: false
+              });
+              await manager.guard();
+            } catch {
+              log("workspace_networking.setup_deferred", {
+                provider: "computer",
+                computerId: info.id
+              });
+              ready = false;
+            }
+          }
+          const setupHash = ready ? await prepareWorkspace() : null;
+          const { handle } = await buildHandle({
+            ctx,
+            client,
+            info,
+            spec,
+            access,
+            env,
+            networking: manager,
+            networkingManaged: manageNetworking,
+            closeSetup: () => setup.transport.close(),
+            beforeUse: async () => {
+              await prepareWorkspace();
+            }
           });
-          if (fresh) await startServicesFor({ setup, spec, env });
-          const { handle } = await buildHandle({ ctx, client, info, spec, access, env });
           return {
             handle,
             region: info.regionSlug ?? config.regionSlug ?? null,
@@ -813,25 +1328,44 @@ ${step.run}`,
               workspace,
               access,
               guideVersionId: spec.guide?.versionId ?? null,
-              setupHash
+              setupHash,
+              setupPending: !ready,
+              workspaceId: sandboxWorkspaceId({
+                session: ctx.session,
+                workspace: sandboxWorkspaceOf[workspace]
+              }),
+              networkPolicySaved: manageNetworking
             }
           };
         } catch (error) {
+          let cause = error;
+          try {
+            await cleanupSetup?.();
+          } catch (cleanupError) {
+            cause = new AggregateError(
+              [error, cleanupError],
+              "Computer setup and egress cleanup failed"
+            );
+          }
           if (!reused) {
             try {
               await client.action(info.id, "delete");
             } catch (cleanupError) {
               throw new AggregateError(
-                [error, cleanupError],
+                [cause, cleanupError],
                 `computer ${info.name} setup and cleanup failed`
               );
             }
           }
-          throw error;
+          throw cause;
         }
       },
       resumePassive: async (ctx, _artifact, rawState) => {
         const state = computerStateSchema.parse(rawState);
+        if (ctx.session.workspaceId == null && state.workspaceId != null)
+          ctx = { ...ctx, session: { ...ctx.session, workspaceId: state.workspaceId } };
+        if (state.networkPolicySaved === true && state.workspaceId != null && ctx.session.workspaceId !== state.workspaceId)
+          throw new Error("Passive workspace identity does not match retained provider state");
         const client = clientFor(ctx.session.organizationId);
         const info = await client.getComputer(state.computerId);
         if (info == null || info.state !== ComputerState.Running)
@@ -842,80 +1376,277 @@ ${step.run}`,
         await awaitRunning(ctx, state, { timeoutMs: runningWaitMs });
         const spec = await resolve(ctx.guides);
         const env = platformProcessEnvironment(ctx, await loadVariables(ctx, spec));
-        return (await buildHandle({ ctx, client, info, spec, access: state.access, env })).handle;
+        return (await buildHandle({
+          ctx,
+          client,
+          info,
+          spec,
+          access: SandboxAccess.Read,
+          env,
+          networkingManaged: state.networkPolicySaved === true
+        })).handle;
       },
       resume: async (ctx, _artifact, rawState) => {
         const state = computerStateSchema.parse(rawState);
+        if (state.networkPolicySaved === true) {
+          if (config.networking == null)
+            throw new Error("Device networking control is required before resume");
+        }
+        if (state.workspaceId != null) {
+          if (state.networkPolicySaved === true && ctx.session.workspaceId != null && ctx.session.workspaceId !== state.workspaceId)
+            throw new Error("Resume workspace identity does not match retained provider state");
+          if (ctx.session.workspaceId == null)
+            ctx = { ...ctx, session: { ...ctx.session, workspaceId: state.workspaceId } };
+        }
+        if (ctx.session.workspaceId == null)
+          ctx = {
+            ...ctx,
+            session: {
+              ...ctx.session,
+              workspaceId: sandboxWorkspaceId({
+                session: ctx.session,
+                workspace: sandboxWorkspaceOf[state.workspace]
+              })
+            }
+          };
         const client = clientFor(ctx.session.organizationId);
+        const workspaceId = sandboxWorkspaceId({
+          session: ctx.session,
+          workspace: sandboxWorkspaceOf[state.workspace]
+        });
+        const manageNetworking = state.networkPolicySaved === true || await needsWorkspaceNetworking(ctx, workspaceId) || state.access !== SandboxAccess.Read && await needsWorkspaceNetworking(ctx, workspaceId, { access: state.access });
+        if (manageNetworking)
+          config.networking?.validateWorkspaceId?.(
+            sandboxWorkspaceId({
+              session: ctx.session,
+              workspace: sandboxWorkspaceOf[state.workspace]
+            })
+          );
         const info = await client.getComputer(state.computerId);
         if (info == null || info.state === ComputerState.Deleted || info.state === ComputerState.Error) {
           throw computerSandboxError("computer_gone", `computer ${state.computerName} is gone`);
         }
+        if (manageNetworking && state.access === SandboxAccess.Read && info.state !== ComputerState.Running)
+          throw new Error("A managed Computer requires a write binding to resume networking");
+        const initialNetworkPolicy = manageNetworking ? networkPolicyFor(await client.getNetworkPolicy(info.id)) : null;
+        if (initialNetworkPolicy != null && state.access !== SandboxAccess.Read && info.state === ComputerState.Running)
+          await client.disableAutoResume(info.id);
         const rebooted = !isRunningState(info.state);
+        if (manageNetworking && config.networking != null && initialNetworkPolicy != null)
+          await preservePolicy({
+            ctx,
+            workspaceId: sandboxWorkspaceId({
+              session: ctx.session,
+              workspace: sandboxWorkspaceOf[state.workspace]
+            }),
+            policy: initialNetworkPolicy
+          });
+        if (manageNetworking && info.state !== ComputerState.Running)
+          await client.setNetworkPolicy(
+            info.id,
+            { egress: ComputerEgressPolicy.None },
+            { autoResume: false }
+          );
         if (info.state === ComputerState.Paused) await client.action(info.id, "resume");
         else if (rebooted) await client.action(info.id, "start");
         const running = await awaitRunning(ctx, state, { timeoutMs: runningWaitMs });
         const spec = await resolve(ctx.guides);
         const env = platformProcessEnvironment(ctx, await loadVariables(ctx, spec));
-        const policy = withPlatformEgressHosts(ctx, spec.parameters.networkPolicy);
-        await client.setNetworkPolicy(running.id, computerEgressOf(policy));
-        await reportPlatformNetworkPolicy(ctx, policy);
+        if (!manageNetworking) {
+          const policy = withPlatformEgressHosts(ctx, spec.parameters.networkPolicy);
+          await client.setNetworkPolicy(running.id, computerEgressOf(policy));
+          await reportPlatformNetworkPolicy(ctx, policy);
+        }
         const setup = setupSession({ client, info: running, env });
-        await writePlatformFiles(ctx, setup.sandbox);
-        await installGuideCommands({ sandbox: setup.sandbox, template: spec.template });
-        if (rebooted) await startServicesFor({ setup, spec, env });
-        const { handle } = await buildHandle({
+        const manager = workspaceNetworking({
           ctx,
+          enabled: manageNetworking && state.access !== SandboxAccess.Read,
+          access: state.access,
+          sandbox: setup.sandbox,
           client,
           info: running,
           spec,
-          access: state.access,
-          env
+          onClose: () => setup.transport.close(),
+          initialNetworkPolicy: initialNetworkPolicy ?? networkPolicyFor(egressFor(ctx, spec.parameters.networkPolicy))
         });
-        return handle;
-      },
-      park: async (ctx, _artifact, rawState) => {
-        const state = computerStateSchema.parse(rawState);
-        await closeComputerMcp(state.computerId);
-        const client = clientFor(ctx.session.organizationId);
-        const current = await client.getComputer(state.computerId);
-        if (current == null || hasNothingToPause(current.state)) {
-          log("computer_sandbox.park_at_rest", {
-            computerId: state.computerId,
-            state: current?.state ?? null
-          });
-          return state;
-        }
         try {
-          await client.action(state.computerId, "pause");
-        } catch (error) {
-          if (!pauseMayHaveSettled(error)) throw error;
-          const settled = await client.getComputer(state.computerId);
-          if (settled != null && settled.state !== ComputerState.Paused && !hasNothingToPause(settled.state))
-            throw error;
-          log("computer_sandbox.park_at_rest", {
-            computerId: state.computerId,
-            state: settled?.state ?? null
+          if (!manageNetworking || state.access !== SandboxAccess.Read)
+            await writePlatformFiles(ctx, setup.sandbox);
+          if (manageNetworking && rebooted)
+            await setup.sandbox.writeTextFile({
+              path: WORKSPACE_ROOT + "/.final-workspace-services",
+              content: "pending"
+            });
+          await manager?.initialize();
+          let preparation = null;
+          const prepareWorkspace = () => preparation ??= (async () => {
+            const artifact = state.setupPending ? computerArtifactSchema.parse(_artifact) : null;
+            const marker = artifact == null ? null : WORKSPACE_ROOT + "/.final/workspace-prepared/" + await sha256Hex(artifact.key);
+            const pending = marker != null && await setup.sandbox.stat({ path: marker }) == null;
+            if (pending && artifact != null) {
+              await mountRepositories({
+                sandbox: setup.sandbox,
+                repositories: spec.parameters.repositories,
+                resolver: ctx.repositories,
+                log
+              });
+              await materializeSandboxSeeds({
+                sandbox: setup.sandbox,
+                root: WORKSPACE_ROOT,
+                files: await sandboxSeedFilesForStart(ctx, artifact)
+              });
+            }
+            await installGuideCommands({ sandbox: setup.sandbox, template: spec.template });
+            if (pending)
+              await runWorkspaceSetup({
+                sandbox: setup.sandbox,
+                template: spec.template,
+                repositories: spec.parameters.repositories,
+                log
+              });
+            const servicesMarker = WORKSPACE_ROOT + "/.final-workspace-services";
+            const servicesPending = manageNetworking && await setup.sandbox.stat({ path: servicesMarker }) != null && await setup.sandbox.readTextFile({ path: servicesMarker }) === "pending";
+            if (rebooted || servicesPending) {
+              await startServicesFor({ setup, spec, env });
+              if (manageNetworking)
+                await setup.sandbox.writeTextFile({ path: servicesMarker, content: "complete" });
+            }
+            if (pending && marker != null)
+              await setup.sandbox.writeTextFile({ path: marker, content: "complete" });
+          })().catch((cause) => {
+            preparation = null;
+            throw cause;
+          });
+          let ready = !manageNetworking || state.access !== SandboxAccess.Read;
+          if (manager != null) {
+            try {
+              await ctx.executionPolicy?.beforeExecution({
+                operation: SandboxExecutionOperation.Run,
+                background: false
+              });
+              await manager.guard();
+            } catch {
+              log("workspace_networking.setup_deferred", {
+                provider: "computer",
+                computerId: info.id
+              });
+              ready = false;
+            }
+          }
+          if (ready) await prepareWorkspace();
+          const { handle } = await buildHandle({
+            ctx,
+            client,
+            info: running,
+            spec,
+            access: state.access,
+            env,
+            networking: manager,
+            networkingManaged: manageNetworking,
+            closeSetup: () => setup.transport.close(),
+            beforeUse: prepareWorkspace
           });
+          return handle;
+        } catch (error) {
+          try {
+            await manager?.closeOnFailure();
+          } catch (cleanupError) {
+            throw new AggregateError(
+              [error, cleanupError],
+              "Computer resume and egress cleanup failed"
+            );
+          } finally {
+            setup.transport.close();
+          }
+          throw error;
         }
-        return state;
+      },
+      park: async (ctx, _artifact, rawState) => {
+        const state = computerStateSchema.parse(rawState);
+        const workspaceId = await teardownComputer({
+          ctx,
+          computerId: state.computerId,
+          computerName: state.computerName,
+          workspace: state.workspace,
+          policySaved: state.networkPolicySaved === true,
+          workspaceId: state.networkPolicySaved === true ? state.workspaceId : ctx.session.workspaceId ?? state.workspaceId,
+          fence: true,
+          finish: async () => {
+            const failures = [];
+            try {
+              await closeComputerMcp(state.computerId);
+            } catch (cause) {
+              failures.push(cause);
+            }
+            try {
+              const client = clientFor(ctx.session.organizationId);
+              let current;
+              try {
+                current = await client.getComputer(state.computerId);
+              } catch (cause) {
+                failures.push(cause);
+              }
+              if (current !== void 0 && (current == null || hasNothingToPause(current.state))) {
+                log("computer_sandbox.park_at_rest", {
+                  computerId: state.computerId,
+                  state: current?.state ?? null
+                });
+              } else {
+                try {
+                  await client.action(state.computerId, "pause");
+                } catch (error) {
+                  if (!pauseMayHaveSettled(error)) throw error;
+                  const settled = await client.getComputer(state.computerId);
+                  if (settled != null && settled.state !== ComputerState.Paused && !hasNothingToPause(settled.state))
+                    throw error;
+                  log("computer_sandbox.park_at_rest", {
+                    computerId: state.computerId,
+                    state: settled?.state ?? null
+                  });
+                }
+              }
+            } catch (cause) {
+              failures.push(cause);
+            }
+            if (failures.length === 1) throw failures[0];
+            if (failures.length > 1) throw new AggregateError(failures, "Computer pause failed");
+          }
+        });
+        const key = ctx.session.organizationId + ":" + workspaceId;
+        return {
+          ...state,
+          workspaceId,
+          networkPolicySaved: state.networkPolicySaved === true || savedPolicyWorkspaces.has(key)
+        };
       },
       onSessionEnd: async (ctx, _artifact, rawState, { reason }) => {
         const state = computerStateSchema.parse(rawState);
         const client = clientFor(ctx.session.organizationId);
-        const action = state.workspace === ComputerWorkspacePolicy.Conversation ? "stop" : "delete";
-        log("computer_sandbox.session_end", { computerId: state.computerId, reason, action });
-        try {
-          await client.action(state.computerId, action);
-        } catch (error) {
-          if (isComputersApiStatus(error, 404)) return;
-          if (!isComputersApiStatus(error, 409)) throw error;
-          const current = await client.getComputer(state.computerId);
-          const settled = current == null || current.state === ComputerState.Deleted || action === "stop" && current.state === ComputerState.Shelved;
-          if (!settled) throw error;
-          return;
-        }
-        if (action === "stop") await awaitShelved(client, state.computerId);
+        const finish = async () => {
+          const action = state.workspace === ComputerWorkspacePolicy.Conversation ? "stop" : "delete";
+          log("computer_sandbox.session_end", { computerId: state.computerId, reason, action });
+          try {
+            await client.action(state.computerId, action);
+          } catch (error) {
+            if (isComputersApiStatus(error, 404)) return;
+            if (!isComputersApiStatus(error, 409)) throw error;
+            const current = await client.getComputer(state.computerId);
+            const settled = current == null || current.state === ComputerState.Deleted || action === "stop" && current.state === ComputerState.Shelved;
+            if (!settled) throw error;
+            return;
+          }
+          if (action === "stop") await awaitShelved(client, state.computerId);
+        };
+        await teardownComputer({
+          ctx,
+          computerId: state.computerId,
+          computerName: state.computerName,
+          workspace: state.workspace,
+          policySaved: state.networkPolicySaved === true,
+          workspaceId: state.networkPolicySaved === true ? state.workspaceId : ctx.session.workspaceId ?? state.workspaceId,
+          fence: state.workspace === ComputerWorkspacePolicy.Conversation,
+          finish
+        });
       }
     };
   };
@@ -930,6 +1661,7 @@ export {
   COMPUTERS_API_TEAM_SECRET,
   COMPUTER_SANDBOX_SPECIFIER2 as COMPUTER_SANDBOX_SPECIFIER,
   computeComputerArtifactKey2 as computeComputerArtifactKey,
+  computerWorkspaceName,
   createComputerSandboxProvider
 };
 //# sourceMappingURL=computer.mjs.map