@opengeni/runtime 0.4.0 → 0.6.0

package/dist/{index-CSGkld-v.d.ts → index-otZkoLYq.d.ts}

@@ -99,6 +99,16 @@ declare function modalSandboxAttributionEnvironment(input: ModalSandboxAttributi
 declare function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string>;
 type ModalModule = typeof modal;
 type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
+/** Loader seam so unit tests can inject a fake modal module. */
+type ModalModuleLoader = () => Promise<Pick<ModalModule, "ModalClient" | "Secret">>;
+/**
+ * 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.
+ */
+declare function ensureModalRegistryImage(settings: Settings, loadModal?: ModalModuleLoader): Promise<void>;
 declare function tagModalSandbox(settings: Settings, sandboxId: string, attribution: ModalSandboxAttribution): Promise<boolean>;
 declare function terminateModalSandboxById(settings: Settings, sandboxId: string): Promise<boolean>;
 declare function sweepModalOrphanSandboxes(settings: Settings, liveLeases: LiveModalSandboxLeaseAttribution[], options?: {
@@ -922,9 +932,11 @@ 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>;
     /**
@@ -1798,4 +1810,4 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
  */
 declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
 
-export { SELFHOSTED_DEFAULT_TIMEOUT_MS as $, type ActiveBackendResolverDeps as A, type NatsRequestConnection as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, type FinalizeRecordingResult as F, type NegotiationContext as G, type NumstatEntry as H, type ProviderConstructionContext as I, type ProviderRegistration as J, type RecordingCodec as K, type LiveModalSandboxLeaseAttribution as L, type MintStreamTokenInput as M, NatsControlRpc as N, type RecordingContentType as O, PROVIDER_REGISTRY as P, RecordingError as Q, type RuntimeMetricsHooks as R, type RecordingProcess as S, RecordingUnavailableError as T, type ResolvedActiveBackend as U, type RoutableBackendSession as V, type RoutableSandbox as W, RoutingSandboxSession as X, type RoutingSandboxSessionDeps as Y, type RoutingTransitionEvent as Z, RoutingUnsupportedError as _, ActiveBackendUnresolvableError as a, offlineControlResponse as a$, SELFHOSTED_RECONNECT_WINDOW_MS as a0, SELFHOSTED_RELAY_STREAM_PATH as a1, STREAM_PORT as a2, STREAM_TOKEN_DEFAULT_TTL_SECONDS as a3, SandboxChannelAService as a4, type SandboxChannelAServiceOptions as a5, SandboxConfigError as a6, type SandboxCreatedCallback as a7, SandboxProviderUnavailableError as a8, type SelfhostedApplyDiff as a9, buildSelfhostedBackendSession as aA, buildStreamUrl as aB, buildTerminalServerScript as aC, contentTypeForCodec as aD, createSandboxClient as aE, createSandboxClientForBackend as aF, decodeModalSnapshotId as aG, deletePriorPersistedSnapshot as aH, deleteRecordingArtifacts as aI, deserializeSandboxSessionStateEnvelope as aJ, desktopCapableBackend as aK, ensureDisplayStack as aL, ensureTerminalServer as aM, establishSandboxSessionFromEnvelope as aN, exposeStreamPort as aO, extForCodec as aP, isExecSessionLostBanner as aQ, isProviderSandboxNotFoundError as aR, isSelfhostedProviderNotFoundError as aS, isWorkspaceEscapeError as aT, makeActiveBackendResolver as aU, mintStreamToken as aV, modalSandboxAttributionEnvironment as aW, modalSandboxAttributionTags as aX, negotiateCapabilities as aY, negotiateSelfhostedCapabilities as aZ, offlineAgentError as a_, SelfhostedControlError as aa, type SelfhostedEditor as ab, type SelfhostedEnrollment as ac, type SelfhostedExecArgs as ad, type SelfhostedExecResult as ae, type SelfhostedImageOutput as af, type SelfhostedLivenessState as ag, type SelfhostedNegotiationInput as ah, type SelfhostedRelayConfig as ai, SelfhostedSandboxClient as aj, SelfhostedSession as ak, type SelfhostedSessionBuild as al, type SelfhostedSessionDeps as am, type SelfhostedSessionState as an, type SelfhostedUnavailableReason as ao, type StartRecordingInput as ap, StreamPortUnavailableError as aq, TERMINAL_SERVER_TIMEOUT_MS as ar, TerminalServerError as as, TerminalServerUnsupportedError as at, agentErrorToControlError as au, assertDescriptorRegistryInvariants as av, assertProviderRegistryInvariants as aw, assertSafeRelPath as ax, backendSupportsOs as ay, buildDisplayStackScript as az, type ActivePointer as b, parseExecBannerSessionId as b0, parseNumstatZ as b1, parsePorcelainV2 as b2, parseUnifiedPatch as b3, readRecordingBytes as b4, readWorkspaceArchiveFromEnvelopeSessionState as b5, recordingStorageKey as b6, restoredSandboxSessionStateFromEntry as b7, sandboxStateEntryFromRunState as b8, selectBackend as b9, selfhostedLiveness as ba, serializeEstablishedSandboxEnvelope as bb, setSelfhostedApplyDiff as bc, startRecording as bd, stopRecording as be, stripExecBanner as bf, subjectFor as bg, sweepModalOrphanSandboxes as bh, tagModalSandbox as bi, tearDownDisplayStack as bj, tearDownTerminalServer as bk, terminateModalSandboxById as bl, timeoutAgentError as bm, timeoutControlResponse as bn, verifyStreamToken as bo, type ChannelAEmitter as c, type ChannelAExecArgs as d, type ChannelAExecResult as e, ChannelANotFoundError as f, type ChannelASession as g, ChannelAUnsupportedError as h, ChannelAValidationError as i, type ControlRpc as j, DISPLAY_STACK_TIMEOUT_MS as k, type DesktopGeometry as l, DisplayStackError as m, DisplayStackUnsupportedError as n, type EnsureDisplayStackResult as o, type EnsureTerminalServerOptions as p, type EnsureTerminalServerResult as q, type EstablishedSandboxSession as r, type ExposeStreamPortInput as s, type ExposeStreamPortResult as t, type ExposedPortEndpoint as u, MockAgentResponder as v, type MockAgentResponderOptions as w, type MockExecHandler as x, type ModalOrphanSweepResult as y, type ModalSandboxAttribution as z };
+export { RoutingUnsupportedError as $, type ActiveBackendResolverDeps as A, type ModalSandboxAttribution as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, type FinalizeRecordingResult as F, type NatsRequestConnection as G, type NegotiationContext as H, type NumstatEntry as I, type ProviderConstructionContext as J, type ProviderRegistration as K, type LiveModalSandboxLeaseAttribution as L, type MintStreamTokenInput as M, NatsControlRpc as N, type RecordingCodec as O, PROVIDER_REGISTRY as P, type RecordingContentType as Q, type RuntimeMetricsHooks as R, RecordingError as S, type RecordingProcess as T, RecordingUnavailableError as U, type ResolvedActiveBackend as V, type RoutableBackendSession as W, type RoutableSandbox as X, RoutingSandboxSession as Y, type RoutingSandboxSessionDeps as Z, type RoutingTransitionEvent as _, ActiveBackendUnresolvableError as a, negotiateSelfhostedCapabilities as a$, SELFHOSTED_DEFAULT_TIMEOUT_MS as a0, SELFHOSTED_RECONNECT_WINDOW_MS as a1, SELFHOSTED_RELAY_STREAM_PATH as a2, STREAM_PORT as a3, STREAM_TOKEN_DEFAULT_TTL_SECONDS as a4, SandboxChannelAService as a5, type SandboxChannelAServiceOptions as a6, SandboxConfigError as a7, type SandboxCreatedCallback as a8, SandboxProviderUnavailableError as a9, buildDisplayStackScript as aA, buildSelfhostedBackendSession as aB, buildStreamUrl as aC, buildTerminalServerScript as aD, contentTypeForCodec as aE, createSandboxClient as aF, createSandboxClientForBackend as aG, decodeModalSnapshotId as aH, deletePriorPersistedSnapshot as aI, deleteRecordingArtifacts as aJ, deserializeSandboxSessionStateEnvelope as aK, desktopCapableBackend as aL, ensureDisplayStack as aM, ensureModalRegistryImage as aN, ensureTerminalServer as aO, establishSandboxSessionFromEnvelope as aP, exposeStreamPort as aQ, extForCodec as aR, isExecSessionLostBanner as aS, isProviderSandboxNotFoundError as aT, isSelfhostedProviderNotFoundError as aU, isWorkspaceEscapeError as aV, makeActiveBackendResolver as aW, mintStreamToken as aX, modalSandboxAttributionEnvironment as aY, modalSandboxAttributionTags as aZ, negotiateCapabilities as a_, type SelfhostedApplyDiff as aa, SelfhostedControlError as ab, type SelfhostedEditor as ac, type SelfhostedEnrollment as ad, type SelfhostedExecArgs as ae, type SelfhostedExecResult as af, type SelfhostedImageOutput as ag, type SelfhostedLivenessState as ah, type SelfhostedNegotiationInput as ai, type SelfhostedRelayConfig as aj, SelfhostedSandboxClient as ak, SelfhostedSession as al, type SelfhostedSessionBuild as am, type SelfhostedSessionDeps as an, type SelfhostedSessionState as ao, type SelfhostedUnavailableReason as ap, type StartRecordingInput as aq, StreamPortUnavailableError as ar, TERMINAL_SERVER_TIMEOUT_MS as as, TerminalServerError as at, TerminalServerUnsupportedError as au, agentErrorToControlError as av, assertDescriptorRegistryInvariants as aw, assertProviderRegistryInvariants as ax, assertSafeRelPath as ay, backendSupportsOs as az, type ActivePointer as b, offlineAgentError as b0, offlineControlResponse as b1, parseExecBannerSessionId as b2, parseNumstatZ as b3, parsePorcelainV2 as b4, parseUnifiedPatch as b5, readRecordingBytes as b6, readWorkspaceArchiveFromEnvelopeSessionState as b7, recordingStorageKey as b8, restoredSandboxSessionStateFromEntry as b9, sandboxStateEntryFromRunState as ba, selectBackend as bb, selfhostedLiveness as bc, serializeEstablishedSandboxEnvelope as bd, setSelfhostedApplyDiff as be, startRecording as bf, stopRecording as bg, stripExecBanner as bh, subjectFor as bi, sweepModalOrphanSandboxes as bj, tagModalSandbox as bk, tearDownDisplayStack as bl, tearDownTerminalServer as bm, terminateModalSandboxById as bn, timeoutAgentError as bo, timeoutControlResponse as bp, verifyStreamToken as bq, type ChannelAEmitter as c, type ChannelAExecArgs as d, type ChannelAExecResult as e, ChannelANotFoundError as f, type ChannelASession as g, ChannelAUnsupportedError as h, ChannelAValidationError as i, type ControlRpc as j, DISPLAY_STACK_TIMEOUT_MS as k, type DesktopGeometry as l, DisplayStackError as m, DisplayStackUnsupportedError as n, type EnsureDisplayStackResult as o, type EnsureTerminalServerOptions as p, type EnsureTerminalServerResult as q, type EstablishedSandboxSession as r, type ExposeStreamPortInput as s, type ExposeStreamPortResult as t, type ExposedPortEndpoint as u, MockAgentResponder as v, type MockAgentResponderOptions as w, type MockExecHandler as x, type ModalModuleLoader as y, type ModalOrphanSweepResult as z };

package/dist/index.d.ts

@@ -7,8 +7,8 @@ import { ReasoningEffort, SessionEventType, ResourceRef, ToolRef, Permission, Mc
 export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
 import { Capability, SandboxSessionLike, SandboxSessionState, Manifest, Capabilities, LocalDirLazySkillSource, SandboxClient } from '@openai/agents/sandbox';
 import OpenAI from 'openai';
-import { R as RuntimeMetricsHooks } 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-CSGkld-v.js';
+import { R as RuntimeMetricsHooks } from './index-otZkoLYq.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';
 
@@ -673,6 +673,22 @@ declare function composeAgentInstructions(template: string, workspaceEnvironment
  * is a no-op that returns the composed string byte-for-byte.
  */
 declare function appendSessionInstructions(composed: string, sessionInstructions?: string): string;
+/**
+ * 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.
+ */
+declare function appendToolspaceInstructions(composed: string, toolspaceAvailable: boolean): string;
 /**
  * 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
@@ -789,6 +805,7 @@ type ContextRobustnessFilterOptions = {
     throwOnCompactionNeeded?: boolean;
 };
 declare 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.";
+declare 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 \u2014 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
@@ -945,4 +962,4 @@ declare function azureOpenAIDefaultQuery(settings: Pick<Settings, "azureOpenaiAp
  */
 declare function lazySkillSourceWithPackSkills(packSkills: PackSkill[]): LocalDirLazySkillSource;
 
-export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_PROMPT, COMPACTION_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, type ClientCompactionDecision, CodexSubscriptionUnavailableError, type CompactionItem, CompactionNeededError, ComputerActionError, ComputerReadOnlyError, type ComputerToolMode, ComputerUnavailableError, type ComputerUseArgs, ComputerUseCapability, type ContextRobustnessFilterOptions, DEFAULT_COMPACTION_THRESHOLD_RATIO, type ElideStaleScreenshotsOptions, type ElideStaleScreenshotsResult, GENESIS_TITLE_DIRECTIVE, type HistoryItem, MAX_COMPACTION_THRESHOLD_RATIO, MIN_COMPACTION_THRESHOLD_RATIO, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type ResolveConnectionCredentialInput, type ResolveConnectionCredentialResult, type RunAgentStreamOptions, RuntimeMetricsHooks, SCREENSHOT_OMITTED_PLACEHOLDER, SUMMARY_BUFFER_TOKENS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, USER_MESSAGE_TRUNCATION_MARKER, type WorkspaceEnvironmentContext, agentsErrorRunState, appendGenesisTitleDirective, appendSessionInstructions, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionPromptInput, buildCompactionReplacementHistory, buildDeterministicFallbackCompactionHistory, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, clampCompactionThresholdRatio, clientCompactionThresholdTokens, composeAgentInstructions, computerUse, configureOpenAI, configureRuntimeMetricsHooks, contextRobustnessFilterForSettings, coreInstructions, createProductionAgentRuntime, decideClientCompaction, elideStaleScreenshotImages, enforceInputBudget, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findCompactionNeededError, findKeepBoundary, isCompactionSummary, isUserMessage, lazySkillSourceWithPackSkills, materializeSandboxFileDownloads, maxTurnsExceededRunState, mcpToolErrorOutput, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, prefixedMcpToolName, prepareAgentTools, prepareRunInput, renderCompactionPromptInputForChat, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runRepositoryCloneHook, runToolspaceTokenSeedHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, toolspaceTokenSeedCommand, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, workspaceEnvironmentInstructions };
+export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_PROMPT, COMPACTION_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, type ClientCompactionDecision, CodexSubscriptionUnavailableError, type CompactionItem, CompactionNeededError, ComputerActionError, ComputerReadOnlyError, type ComputerToolMode, ComputerUnavailableError, type ComputerUseArgs, ComputerUseCapability, type ContextRobustnessFilterOptions, DEFAULT_COMPACTION_THRESHOLD_RATIO, type ElideStaleScreenshotsOptions, type ElideStaleScreenshotsResult, GENESIS_TITLE_DIRECTIVE, type HistoryItem, MAX_COMPACTION_THRESHOLD_RATIO, MIN_COMPACTION_THRESHOLD_RATIO, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type ResolveConnectionCredentialInput, type ResolveConnectionCredentialResult, type RunAgentStreamOptions, RuntimeMetricsHooks, SCREENSHOT_OMITTED_PLACEHOLDER, SUMMARY_BUFFER_TOKENS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, TOOLSPACE_PROGRAMMATIC_DIRECTIVE, USER_MESSAGE_TRUNCATION_MARKER, type WorkspaceEnvironmentContext, agentsErrorRunState, appendGenesisTitleDirective, appendSessionInstructions, appendToolspaceInstructions, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionPromptInput, buildCompactionReplacementHistory, buildDeterministicFallbackCompactionHistory, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, clampCompactionThresholdRatio, clientCompactionThresholdTokens, composeAgentInstructions, computerUse, configureOpenAI, configureRuntimeMetricsHooks, contextRobustnessFilterForSettings, coreInstructions, createProductionAgentRuntime, decideClientCompaction, elideStaleScreenshotImages, enforceInputBudget, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findCompactionNeededError, findKeepBoundary, isCompactionSummary, isUserMessage, lazySkillSourceWithPackSkills, materializeSandboxFileDownloads, maxTurnsExceededRunState, mcpToolErrorOutput, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, prefixedMcpToolName, prepareAgentTools, prepareRunInput, renderCompactionPromptInputForChat, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runRepositoryCloneHook, runToolspaceTokenSeedHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, toolspaceTokenSeedCommand, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, workspaceEnvironmentInstructions };

package/dist/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";
 
 // src/index.ts
 import { AGENT_INSTRUCTIONS_CORE_PLACEHOLDER, collectSandboxEnvironment as collectSandboxEnvironment2, contextInputBudgetTokens, contextServerCompactThreshold, firstPartyMcpBaseUrl, resolveContextCompactionMode, resolveModelProvider, sandboxLifecycleHookIds } from "@opengeni/config";
@@ -2150,6 +2151,9 @@ function appendSessionInstructions(composed, sessionInstructions) {
   const trimmed = sessionInstructions?.trim();
   return trimmed ? `${composed} ${trimmed}` : composed;
 }
+function appendToolspaceInstructions(composed, toolspaceAvailable) {
+  return toolspaceAvailable ? `${composed} ${TOOLSPACE_PROGRAMMATIC_DIRECTIVE}` : composed;
+}
 function appendGenesisTitleDirective(instructions, genesisTitleHint) {
   return genesisTitleHint ? `${instructions} ${GENESIS_TITLE_DIRECTIVE}` : instructions;
 }
@@ -2183,14 +2187,21 @@ function buildOpenGeniAgent(settings, resources, options = {}) {
     // 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
@@ -2894,6 +2905,7 @@ async function prepareRunInput(agent, input, options = {}) {
   return { input: state };
 }
 var 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.";
+var 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 \u2014 called programmatically they return a typed error.";
 var stripProviderItemIdsFilter = ({ modelData }) => ({
   ...modelData,
   input: modelData.input.map((item) => {
@@ -3007,6 +3019,11 @@ async function runAgentStream(agent, input, settings, overrides = {}) {
           ...runAs2 ? { runAs: runAs2 } : {}
         });
       }
+    } else {
+      const toolspaceHooks = sandboxToolspaceTokenHooksForAgent(agent);
+      if (toolspaceHooks.length > 0) {
+        await runBeforeAgentStartHooks(setupSession, toolspaceHooks, ownedHookContext);
+      }
     }
     const decoratedClient = withSandboxLifecycleHooks(resourceClient2, ownedHooks, ownedHookContext);
     const ownedFilter = composeCallModelInputFilters(
@@ -4348,6 +4365,7 @@ export {
   StreamTokenPayload,
   TERMINAL_SERVER_TIMEOUT_MS,
   TERMINAL_STREAM_PORT,
+  TOOLSPACE_PROGRAMMATIC_DIRECTIVE,
   TerminalServerError,
   TerminalServerUnsupportedError,
   USER_MESSAGE_TRUNCATION_MARKER,
@@ -4355,6 +4373,7 @@ export {
   agentsErrorRunState,
   appendGenesisTitleDirective,
   appendSessionInstructions,
+  appendToolspaceInstructions,
   applyMissingManifestEntries,
   assertDescriptorRegistryInvariants,
   assertProviderRegistryInvariants,
@@ -4399,6 +4418,7 @@ export {
   elideStaleScreenshotImages,
   enforceInputBudget,
   ensureDisplayStack,
+  ensureModalRegistryImage,
   ensureReadableStreamFrom,
   ensureTerminalServer,
   establishSandboxSessionFromEnvelope,