@opengeni/runtime 0.4.0 → 0.5.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 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-BrdnxaAW.js';
 import 'modal';
 import '@opengeni/agent-proto';

package/dist/sandbox/index.js

@@ -95,7 +95,7 @@ import {
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken
-} from "../chunk-HGQ252FL.js";
+} from "../chunk-Q36E4MDM.js";
 export {
   ActiveBackendUnresolvableError,
   CAPABILITY_DESCRIPTORS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",

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/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,
     };