@opengeni/runtime 0.4.0 → 0.6.0

package/dist/sandbox/index.d.ts

@@ -1,6 +1,6 @@
 export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
 export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
 import '@openai/agents/sandbox';
-export { A as ActiveBackendResolverDeps, a as ActiveBackendUnresolvableError, b as ActivePointer, C as ChannelAConflictError, c as ChannelAEmitter, d as ChannelAExecArgs, e as ChannelAExecResult, f as ChannelANotFoundError, g as ChannelASession, h as ChannelAUnsupportedError, i as ChannelAValidationError, j as ControlRpc, D as DEFAULT_DESKTOP_GEOMETRY, k as DISPLAY_STACK_TIMEOUT_MS, l as DesktopGeometry, m as DisplayStackError, n as DisplayStackUnsupportedError, E as EnsureDisplayStackOptions, o as EnsureDisplayStackResult, p as EnsureTerminalServerOptions, q as EnsureTerminalServerResult, r as EstablishedSandboxSession, s as ExposeStreamPortInput, t as ExposeStreamPortResult, u as ExposedPortEndpoint, F as FinalizeRecordingResult, L as LiveModalSandboxLeaseAttribution, M as MintStreamTokenInput, v as MockAgentResponder, w as MockAgentResponderOptions, x as MockExecHandler, y as ModalOrphanSweepResult, z as ModalSandboxAttribution, N as NatsControlRpc, B as NatsRequestConnection, G as NegotiationContext, H as NumstatEntry, P as PROVIDER_REGISTRY, I as ProviderConstructionContext, J as ProviderRegistration, K as RecordingCodec, O as RecordingContentType, Q as RecordingError, S as RecordingProcess, T as RecordingUnavailableError, U as ResolvedActiveBackend, V as RoutableBackendSession, W as RoutableSandbox, X as RoutingSandboxSession, Y as RoutingSandboxSessionDeps, Z as RoutingTransitionEvent, _ as RoutingUnsupportedError, $ as SELFHOSTED_DEFAULT_TIMEOUT_MS, a0 as SELFHOSTED_RECONNECT_WINDOW_MS, a1 as SELFHOSTED_RELAY_STREAM_PATH, a2 as STREAM_PORT, a3 as STREAM_TOKEN_DEFAULT_TTL_SECONDS, a4 as SandboxChannelAService, a5 as SandboxChannelAServiceOptions, a6 as SandboxConfigError, a7 as SandboxCreatedCallback, a8 as SandboxProviderUnavailableError, a9 as SelfhostedApplyDiff, aa as SelfhostedControlError, ab as SelfhostedEditor, ac as SelfhostedEnrollment, ad as SelfhostedExecArgs, ae as SelfhostedExecResult, af as SelfhostedImageOutput, ag as SelfhostedLivenessState, ah as SelfhostedNegotiationInput, ai as SelfhostedRelayConfig, aj as SelfhostedSandboxClient, ak as SelfhostedSession, al as SelfhostedSessionBuild, am as SelfhostedSessionDeps, an as SelfhostedSessionState, ao as SelfhostedUnavailableReason, ap as StartRecordingInput, aq as StreamPortUnavailableError, ar as TERMINAL_SERVER_TIMEOUT_MS, as as TerminalServerError, at as TerminalServerUnsupportedError, au as agentErrorToControlError, av as assertDescriptorRegistryInvariants, aw as assertProviderRegistryInvariants, ax as assertSafeRelPath, ay as backendSupportsOs, az as buildDisplayStackScript, aA as buildSelfhostedBackendSession, aB as buildStreamUrl, aC as buildTerminalServerScript, aD as contentTypeForCodec, aE as createSandboxClient, aF as createSandboxClientForBackend, aG as decodeModalSnapshotId, aH as deletePriorPersistedSnapshot, aI as deleteRecordingArtifacts, aJ as deserializeSandboxSessionStateEnvelope, aK as desktopCapableBackend, aL as ensureDisplayStack, aM as ensureTerminalServer, aN as establishSandboxSessionFromEnvelope, aO as exposeStreamPort, aP as extForCodec, aQ as isExecSessionLostBanner, aR as isProviderSandboxNotFoundError, aS as isSelfhostedProviderNotFoundError, aT as isWorkspaceEscapeError, aU as makeActiveBackendResolver, aV as mintStreamToken, aW as modalSandboxAttributionEnvironment, aX as modalSandboxAttributionTags, aY as negotiateCapabilities, aZ as negotiateSelfhostedCapabilities, a_ as offlineAgentError, a$ as offlineControlResponse, b0 as parseExecBannerSessionId, b1 as parseNumstatZ, b2 as parsePorcelainV2, b3 as parseUnifiedPatch, b4 as readRecordingBytes, b5 as readWorkspaceArchiveFromEnvelopeSessionState, b6 as recordingStorageKey, b7 as restoredSandboxSessionStateFromEntry, b8 as sandboxStateEntryFromRunState, b9 as selectBackend, ba as selfhostedLiveness, bb as serializeEstablishedSandboxEnvelope, bc as setSelfhostedApplyDiff, bd as startRecording, be as stopRecording, bf as stripExecBanner, bg as subjectFor, bh as sweepModalOrphanSandboxes, bi as tagModalSandbox, bj as tearDownDisplayStack, bk as tearDownTerminalServer, bl as terminateModalSandboxById, bm as timeoutAgentError, bn as timeoutControlResponse, bo as verifyStreamToken } from '../index-CSGkld-v.js';
+export { A as ActiveBackendResolverDeps, a as ActiveBackendUnresolvableError, b as ActivePointer, C as ChannelAConflictError, c as ChannelAEmitter, d as ChannelAExecArgs, e as ChannelAExecResult, f as ChannelANotFoundError, g as ChannelASession, h as ChannelAUnsupportedError, i as ChannelAValidationError, j as ControlRpc, D as DEFAULT_DESKTOP_GEOMETRY, k as DISPLAY_STACK_TIMEOUT_MS, l as DesktopGeometry, m as DisplayStackError, n as DisplayStackUnsupportedError, E as EnsureDisplayStackOptions, o as EnsureDisplayStackResult, p as EnsureTerminalServerOptions, q as EnsureTerminalServerResult, r as EstablishedSandboxSession, s as ExposeStreamPortInput, t as ExposeStreamPortResult, u as ExposedPortEndpoint, F as FinalizeRecordingResult, L as LiveModalSandboxLeaseAttribution, M as MintStreamTokenInput, v as MockAgentResponder, w as MockAgentResponderOptions, x as MockExecHandler, y as ModalModuleLoader, z as ModalOrphanSweepResult, B as ModalSandboxAttribution, N as NatsControlRpc, G as NatsRequestConnection, H as NegotiationContext, I as NumstatEntry, P as PROVIDER_REGISTRY, J as ProviderConstructionContext, K as ProviderRegistration, O as RecordingCodec, Q as RecordingContentType, S as RecordingError, T as RecordingProcess, U as RecordingUnavailableError, V as ResolvedActiveBackend, W as RoutableBackendSession, X as RoutableSandbox, Y as RoutingSandboxSession, Z as RoutingSandboxSessionDeps, _ as RoutingTransitionEvent, $ as RoutingUnsupportedError, a0 as SELFHOSTED_DEFAULT_TIMEOUT_MS, a1 as SELFHOSTED_RECONNECT_WINDOW_MS, a2 as SELFHOSTED_RELAY_STREAM_PATH, a3 as STREAM_PORT, a4 as STREAM_TOKEN_DEFAULT_TTL_SECONDS, a5 as SandboxChannelAService, a6 as SandboxChannelAServiceOptions, a7 as SandboxConfigError, a8 as SandboxCreatedCallback, a9 as SandboxProviderUnavailableError, aa as SelfhostedApplyDiff, ab as SelfhostedControlError, ac as SelfhostedEditor, ad as SelfhostedEnrollment, ae as SelfhostedExecArgs, af as SelfhostedExecResult, ag as SelfhostedImageOutput, ah as SelfhostedLivenessState, ai as SelfhostedNegotiationInput, aj as SelfhostedRelayConfig, ak as SelfhostedSandboxClient, al as SelfhostedSession, am as SelfhostedSessionBuild, an as SelfhostedSessionDeps, ao as SelfhostedSessionState, ap as SelfhostedUnavailableReason, aq as StartRecordingInput, ar as StreamPortUnavailableError, as as TERMINAL_SERVER_TIMEOUT_MS, at as TerminalServerError, au as TerminalServerUnsupportedError, av as agentErrorToControlError, aw as assertDescriptorRegistryInvariants, ax as assertProviderRegistryInvariants, ay as assertSafeRelPath, az as backendSupportsOs, aA as buildDisplayStackScript, aB as buildSelfhostedBackendSession, aC as buildStreamUrl, aD as buildTerminalServerScript, aE as contentTypeForCodec, aF as createSandboxClient, aG as createSandboxClientForBackend, aH as decodeModalSnapshotId, aI as deletePriorPersistedSnapshot, aJ as deleteRecordingArtifacts, aK as deserializeSandboxSessionStateEnvelope, aL as desktopCapableBackend, aM as ensureDisplayStack, aN as ensureModalRegistryImage, aO as ensureTerminalServer, aP as establishSandboxSessionFromEnvelope, aQ as exposeStreamPort, aR as extForCodec, aS as isExecSessionLostBanner, aT as isProviderSandboxNotFoundError, aU as isSelfhostedProviderNotFoundError, aV as isWorkspaceEscapeError, aW as makeActiveBackendResolver, aX as mintStreamToken, aY as modalSandboxAttributionEnvironment, aZ as modalSandboxAttributionTags, a_ as negotiateCapabilities, a$ as negotiateSelfhostedCapabilities, b0 as offlineAgentError, b1 as offlineControlResponse, b2 as parseExecBannerSessionId, b3 as parseNumstatZ, b4 as parsePorcelainV2, b5 as parseUnifiedPatch, b6 as readRecordingBytes, b7 as readWorkspaceArchiveFromEnvelopeSessionState, b8 as recordingStorageKey, b9 as restoredSandboxSessionStateFromEntry, ba as sandboxStateEntryFromRunState, bb as selectBackend, bc as selfhostedLiveness, bd as serializeEstablishedSandboxEnvelope, be as setSelfhostedApplyDiff, bf as startRecording, bg as stopRecording, bh as stripExecBanner, bi as subjectFor, bj as sweepModalOrphanSandboxes, bk as tagModalSandbox, bl as tearDownDisplayStack, bm as tearDownTerminalServer, bn as terminateModalSandboxById, bo as timeoutAgentError, bp as timeoutControlResponse, bq as verifyStreamToken } from '../index-otZkoLYq.js';
 import 'modal';
 import '@opengeni/agent-proto';

package/dist/sandbox/index.js

@@ -53,6 +53,7 @@ import {
   deserializeSandboxSessionStateEnvelope,
   desktopCapableBackend,
   ensureDisplayStack,
+  ensureModalRegistryImage,
   ensureTerminalServer,
   establishSandboxSessionFromEnvelope,
   exposeStreamPort,
@@ -95,7 +96,7 @@ import {
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken
-} from "../chunk-HGQ252FL.js";
+} from "../chunk-BHA2SU3H.js";
 export {
   ActiveBackendUnresolvableError,
   CAPABILITY_DESCRIPTORS,
@@ -151,6 +152,7 @@ export {
   deserializeSandboxSessionStateEnvelope,
   desktopCapableBackend,
   ensureDisplayStack,
+  ensureModalRegistryImage,
   ensureTerminalServer,
   establishSandboxSessionFromEnvelope,
   exposeStreamPort,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@opengeni/agent-proto": "^0.2.1",
-    "@opengeni/config": "^0.3.0",
+    "@opengeni/config": "^0.4.0",
     "@opengeni/contracts": "^0.9.0",
     "@openai/agents": "^0.11.6",
     "@openai/agents-extensions": "^0.11.6",

package/src/index.ts

@@ -937,6 +937,25 @@ export function appendSessionInstructions(composed: string, sessionInstructions?
   return trimmed ? `${composed} ${trimmed}` : composed;
 }
 
+/**
+ * Appends the generic programmatic-tool-calling (toolspace) directive to the
+ * composed workspace + CORE instructions, joined by " ". This is GENERIC
+ * substrate prompting — the same text for every host, never per-host copy.
+ *
+ * Included ONLY when `toolspaceAvailable` is true, which the caller sets from the
+ * exact condition that gates the sandbox token mint: the toolspace feature is
+ * enabled AND a toolspace token was minted for THIS turn. That mint now happens
+ * on every backend including selfhosted (connected machines get the token too),
+ * so the block appears there as well; a turn with no minted token (feature off)
+ * has no toolspace URL/token in its sandbox and must not advertise a capability
+ * that is not there — the gate is false and this is a no-op. Placed BEFORE the
+ * per-session instructions so host/session specificity still wins over this
+ * substrate note.
+ */
+export function appendToolspaceInstructions(composed: string, toolspaceAvailable: boolean): string {
+  return toolspaceAvailable ? `${composed} ${TOOLSPACE_PROGRAMMATIC_DIRECTIVE}` : composed;
+}
+
 /**
  * Appends the one-shot genesis title directive (genesis turn only), joined by
  * " " and always LAST so a white-label persona template or a per-session
@@ -1030,14 +1049,21 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
     // Persona composition order (all one system-level instructions string):
     //   1. workspace instructionsTemplate (or deployment default) with the
     //      non-bypassable CORE substituted at {{core}} — composeAgentInstructions,
-    //   2. + the per-session persona instructions (session-specific, LAST so it
-    //      refines the workspace persona),
-    //   3. + the one-shot genesis title directive (genesis turn only).
-    // With no session instructions and no genesis hint this is byte-identical to
-    // the historical composed instructions.
+    //   2. + the generic programmatic-tool-calling (toolspace) directive, ONLY
+    //      when a toolspace token was minted for this turn (feature enabled + a
+    //      per-turn seed — the mint gate, which includes selfhosted turns since
+    //      they now receive the token too) — appendToolspaceInstructions,
+    //   3. + the per-session persona instructions (session-specific, so it
+    //      refines both the workspace persona and the substrate note),
+    //   4. + the one-shot genesis title directive (genesis turn only).
+    // With no toolspace token, no session instructions, and no genesis hint this
+    // is byte-identical to the historical composed instructions.
     instructions: appendGenesisTitleDirective(
       appendSessionInstructions(
-        composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+        appendToolspaceInstructions(
+          composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+          settings.toolspaceEnabled && Boolean(options.toolspaceTokenSeed),
+        ),
         options.sessionInstructions,
       ),
       options.genesisTitleHint,
@@ -2194,6 +2220,13 @@ export type ContextRobustnessFilterOptions = {
 export const GENESIS_TITLE_DIRECTIVE =
   "This is the first turn of a new session. Before responding to the user, call the opengeni__set_session_title tool with a concise 3-7 word title that summarizes what this session is about, then address the user's request normally.";
 
+// Generic substrate prompting for programmatic tool calling (toolspace). Same
+// text for every host; gated per-turn by appendToolspaceInstructions on the
+// presence of a minted toolspace token, so it only appears when the sandbox
+// actually exposes the ogtool CLI + $OPENGENI_TOOLSPACE_URL/_TOKEN_FILE.
+export const TOOLSPACE_PROGRAMMATIC_DIRECTIVE =
+  "Every tool on your MCP surface is also callable programmatically from the sandbox shell, so scripts can invoke tools without a model round trip per call. Run `ogtool list` to see the available tools and their input schemas (from tools/list), then `ogtool call <tool-name> '<json-args>'`; equivalently, POST MCP JSON-RPC to $OPENGENI_TOOLSPACE_URL with the bearer token read from $OPENGENI_TOOLSPACE_TOKEN_FILE. Prefer programmatic calls for loops, polling, and bulk filtering: their results stay in the sandbox and do not consume your context window. Tools that require human approval must still be invoked normally — called programmatically they return a typed error.";
+
 /**
  * callModelInputFilter that removes provider-assigned item ids (rs_/msg_/fc_…)
  * from every input item immediately before each model call. Responses-API
@@ -2398,6 +2431,22 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
           ...(runAs ? { runAs } : {}),
         });
       }
+    } else {
+      // SELFHOSTED TOOLSPACE (parity): the platform setup hooks (repository clone,
+      // az login) and file materialization stay OFF the user's real machine — but
+      // the toolspace token seed is the ONE piece of per-turn material that must
+      // reach it. It writes a scoped, own-session-bound token to
+      // $OPENGENI_TOOLSPACE_TOKEN_FILE over the SAME exec channel the clone-seed
+      // uses (off-manifest, value never on the manifest), and it grants no more
+      // than the machine owner's own authority (toolspace:call, this session, turn
+      // TTL, budgeted, approval-tools excluded) — the invariant that makes it safe
+      // to cross to a user machine when the git token is not. It is also the
+      // machine's only path to programmatic tool calling. Seed it (only) here; the
+      // hook list is empty when no toolspace token was minted for this turn.
+      const toolspaceHooks = sandboxToolspaceTokenHooksForAgent(agent);
+      if (toolspaceHooks.length > 0) {
+        await runBeforeAgentStartHooks(setupSession, toolspaceHooks, ownedHookContext);
+      }
     }
     // Keep the decoration as a safety net for any session the SDK does create/resume
     // through the client during this run (it is inert for the provided session).

package/src/sandbox/index.ts

@@ -55,12 +55,14 @@ export {
   type ProviderConstructionContext,
 } from "./providers";
 export {
+  ensureModalRegistryImage,
   modalSandboxAttributionEnvironment,
   modalSandboxAttributionTags,
   sweepModalOrphanSandboxes,
   tagModalSandbox,
   terminateModalSandboxById,
   type LiveModalSandboxLeaseAttribution,
+  type ModalModuleLoader,
   type ModalOrphanSweepResult,
   type ModalSandboxAttribution,
 } from "./providers/modal";

package/src/sandbox/providers/modal.ts

@@ -87,8 +87,9 @@ export const modalProvider: ProviderRegistration = {
     if (settings.modalWorkspacePersistence) {
       options.workspacePersistence = settings.modalWorkspacePersistence;
     }
-    if (settings.modalImageRef) {
-      options.image = ModalImageSelector.fromTag(settings.modalImageRef);
+    const imageSelector = resolveModalImageSelector(settings);
+    if (imageSelector) {
+      options.image = imageSelector;
     }
     if (settings.modalTokenId) {
       options.tokenId = settings.modalTokenId;
@@ -106,6 +107,110 @@ export const modalProvider: ProviderRegistration = {
 type ModalModule = typeof import("modal");
 type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
 
+// --- Private-registry image resolution (OPENGENI_MODAL_IMAGE_REGISTRY_SECRET) ------
+//
+// The Agents-extension Modal backend resolves `modalImageRef` via
+// `Image.fromRegistry(tag)` with NO secret, so it can only pull PUBLIC images. To run
+// a PRIVATE image we resolve the named Modal Secret and pre-build the authenticated
+// `fromRegistry(tag, secret)` image ONCE per process, then hand the provider `build`
+// a `ModalImageSelector.fromImage(...)`. `build` is synchronous and modal is imported
+// lazily (never loaded for non-modal backends), so resolution can't happen inside
+// `build`; the worker boot awaits `ensureModalRegistryImage` first and `build` reads
+// the settled result. Modal images are lazy, workspace-scoped definitions, so an image
+// built by this module's client is usable by the ModalSandboxClient's own client.
+
+/** Loader seam so unit tests can inject a fake modal module. */
+export type ModalModuleLoader = () => Promise<
+  Pick<ModalModule, "ModalClient" | "Secret">
+>;
+
+const defaultModalLoader: ModalModuleLoader = () => import("modal");
+
+/** Settled, synchronously-readable resolved images, keyed per config. */
+const resolvedRegistryImages = new Map<string, unknown>();
+/** In-flight resolutions, for cross-call de-duplication. */
+const inFlightRegistryImages = new Map<string, Promise<void>>();
+
+function registryImageCacheKey(settings: Settings): string {
+  return [
+    settings.modalImageRef ?? "",
+    settings.modalImageRegistrySecret ?? "",
+    settings.modalEnvironment ?? "",
+  ].join("|");
+}
+
+/**
+ * Resolve + cache the private-registry Modal image. No-op unless BOTH
+ * `modalImageRef` and `modalImageRegistrySecret` are set. Memoized per
+ * (imageRef, secret, environment) so it runs once per worker process. Awaited at
+ * worker boot BEFORE the first sandbox is created; `build` then reads the resolved
+ * image and otherwise falls back to the public `fromTag` path.
+ */
+export async function ensureModalRegistryImage(
+  settings: Settings,
+  loadModal: ModalModuleLoader = defaultModalLoader,
+): Promise<void> {
+  if (!settings.modalImageRegistrySecret || !settings.modalImageRef) {
+    return;
+  }
+  const key = registryImageCacheKey(settings);
+  if (resolvedRegistryImages.has(key)) {
+    return;
+  }
+  let pending = inFlightRegistryImages.get(key);
+  if (!pending) {
+    pending = (async () => {
+      const modal = await loadModal();
+      const client = new modal.ModalClient(modalClientOptions(settings));
+      const secret = await modal.Secret.fromName(
+        settings.modalImageRegistrySecret!,
+        settings.modalEnvironment ? { environment: settings.modalEnvironment } : undefined,
+      );
+      // fromRegistry is synchronous and returns a lazy image definition (built
+      // server-side at sandbox create); the resolved secretId travels with it.
+      const image = client.images.fromRegistry(settings.modalImageRef!, secret);
+      resolvedRegistryImages.set(key, image);
+    })().finally(() => {
+      inFlightRegistryImages.delete(key);
+    });
+    inFlightRegistryImages.set(key, pending);
+  }
+  await pending;
+}
+
+/** The resolved private-registry image for these settings, or undefined if none. */
+function cachedModalRegistryImage(settings: Settings): unknown | undefined {
+  if (!settings.modalImageRegistrySecret || !settings.modalImageRef) {
+    return undefined;
+  }
+  return resolvedRegistryImages.get(registryImageCacheKey(settings));
+}
+
+/**
+ * Choose the image selector for a Modal sandbox client from settings. Returns:
+ *  - `fromImage(resolved)` when a private-registry secret is configured AND the
+ *    image has been resolved (ensureModalRegistryImage ran at worker boot);
+ *  - `fromTag(modalImageRef)` for the public path (no secret, or cold cache — the
+ *    resume/attach paths never pull an image so the tag branch is harmless there);
+ *  - `undefined` when no image ref is set (Modal uses its default image).
+ * Exported for unit tests.
+ */
+export function resolveModalImageSelector(settings: Settings): ModalImageSelector | undefined {
+  if (!settings.modalImageRef) {
+    return undefined;
+  }
+  const registryImage = cachedModalRegistryImage(settings);
+  return registryImage
+    ? ModalImageSelector.fromImage(registryImage as Parameters<typeof ModalImageSelector.fromImage>[0])
+    : ModalImageSelector.fromTag(settings.modalImageRef);
+}
+
+/** Test-only: clear the resolved/in-flight image caches. */
+export function __resetModalRegistryImageCacheForTest(): void {
+  resolvedRegistryImages.clear();
+  inFlightRegistryImages.clear();
+}
+
 function modalClientOptions(settings: Settings): ConstructorParameters<ModalModule["ModalClient"]>[0] {
   return {
     ...(settings.modalTokenId ? { tokenId: settings.modalTokenId } : {}),

package/src/sandbox/selfhosted/session.ts

@@ -144,6 +144,28 @@ export interface SelfhostedImageOutput {
  *  (the turn pauses + retries); it is NOT a hard failure. */
 export const SELFHOSTED_DEFAULT_TIMEOUT_MS = 30_000;
 
+/**
+ * The ONLY manifest-environment keys exported into a selfhosted machine's exec
+ * shell. The manifest env is otherwise NOT consumed by selfhosted exec — the
+ * machine owns its own environment, and pushing HOME, GIT_ vars, and the like
+ * onto a real computer would clobber it. The toolspace pointers are the exception:
+ * `ogtool` (and the token-seed hook) need the non-secret programmatic-calling URL
+ * and the token-FILE PATH to reach the tool surface. The token VALUE never rides
+ * here — it is seeded to that file off-manifest over the same exec channel.
+ */
+const SELFHOSTED_EXEC_ENV_ALLOWLIST = ["OPENGENI_TOOLSPACE_URL", "OPENGENI_TOOLSPACE_TOKEN_FILE"] as const;
+
+function selfhostedExecEnv(environment: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SELFHOSTED_EXEC_ENV_ALLOWLIST) {
+    const value = environment[key];
+    if (value) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
 /** The relay-URL shape config the session needs to build a stream endpoint. M8b
  *  wires the real relay deployment behind THIS seam so `buildStreamUrl` works
  *  unchanged behind `resolveExposedPort`. */
@@ -181,9 +203,11 @@ export interface SelfhostedSessionDeps {
    * session delta; `validateNoEnvironmentDelta` throws "Live sandbox sessions cannot
    * change manifest environment variables" on ANY env mismatch. So `state.manifest`'s
    * `environment` MUST EQUAL the turn's environment for the delta to be empty. The
-   * selfhosted exec routes over NATS and does NOT consume the env, but the manifest
-   * must carry it for parity. Omitted → `{}` (the negotiation-only / test path,
-   * which never applies a turn manifest, so there is no delta to validate).
+   * selfhosted exec routes over NATS and does NOT consume this env wholesale (the
+   * machine owns its own shell), EXCEPT the allowlisted toolspace pointers it
+   * exports per exec so `ogtool` works — see SELFHOSTED_EXEC_ENV_ALLOWLIST. The
+   * manifest carries the full env for parity. Omitted → `{}` (the negotiation-only
+   * / test path, which never applies a turn manifest, so there is no delta).
    */
   environment?: Record<string, string>;
   /**
@@ -340,7 +364,11 @@ export class SelfhostedSession {
       // SELFHOSTED_VIRTUAL_ROOT). Empty → the session workingDir (itself "" by
       // default ⇒ the agent runs in its workspace_root).
       cwd: toMachinePath(args.workdir, this.workingDir),
-      env: {},
+      // The machine owns its own shell environment; the manifest env is NOT
+      // exported here. The ONE exception is the non-secret toolspace pointers
+      // (URL + token-file path), so a programmatic `ogtool` call and the token-
+      // seed hook can find the tool surface. See SELFHOSTED_EXEC_ENV_ALLOWLIST.
+      env: selfhostedExecEnv(this.state.environment),
       stdin: new Uint8Array(0),
       timeoutMs: 0,
     };