@opengeni/runtime 0.2.2 → 0.3.0

package/dist/sandbox/index.d.ts

@@ -3,6 +3,7 @@ export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
 import { SandboxBackend, CapabilityDescriptor, SandboxOs, SessionCapabilities, StreamTokenPayload, SessionEventType, SessionStructuredCapabilities, FsListRequest, FsListResponse, FsReadRequest, FsReadResponse, FsWriteRequest, FsWriteResponse, FsDeleteRequest, FsDeleteResponse, FsMoveRequest, FsMoveResponse, FsMkdirRequest, FsMkdirResponse, GitStatusRequest, GitStatusResponse, GitDiffRequest, GitDiffResponse, GitLogRequest, GitLogResponse, GitShowRequest, GitShowResponse, TerminalExecRequest, TerminalExecResponse, PtyOpenRequest, PtyOpenResponse, PtyWriteRequest, PtyResizeRequest, PtyCloseRequest, GitChangedPayload, GitDiffHunk, GitFileStatusCode, CapabilityUnavailableReason } from '@opengeni/contracts';
 export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
 import { Manifest, SandboxClient, SandboxSessionState } from '@openai/agents/sandbox';
+import * as modal from 'modal';
 import { ControlRequest, ControlResponse, ErrorCode, AgentError, DesktopInputRequest, ExecRequest, ExecResponse } from '@opengeni/agent-proto';
 
 /**
@@ -61,6 +62,38 @@ declare const PROVIDER_REGISTRY: Record<SandboxBackend, ProviderRegistration>;
  */
 declare function assertProviderRegistryInvariants(): void;
 
+type ModalSandboxAttribution = {
+    leaseId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+};
+type LiveModalSandboxLeaseAttribution = ModalSandboxAttribution & {
+    instanceId: string | null;
+    liveness?: string;
+};
+type ModalOrphanSweepTermination = {
+    sandboxId: string;
+    reason: "stale_attribution" | "unattributed";
+    tags: Record<string, string>;
+};
+type ModalOrphanSweepResult = {
+    examined: number;
+    terminated: ModalOrphanSweepTermination[];
+    skipped: number;
+};
+declare function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string>;
+declare function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string>;
+type ModalModule = typeof modal;
+type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
+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?: {
+    now?: Date;
+    maxTerminations?: number;
+    unattributedGraceMs?: number;
+    client?: ModalClientLike;
+}): Promise<ModalOrphanSweepResult>;
+
 interface NegotiationContext {
     sessionId: string;
     backend: SandboxBackend;
@@ -220,7 +253,7 @@ declare function mintStreamToken(secret: string, input: MintStreamTokenInput): P
 declare function verifyStreamToken(secret: string, token: string, nowSeconds?: number): Promise<StreamTokenPayload | null>;
 
 declare const STREAM_PORT = 6080;
-declare const DISPLAY_STACK_TIMEOUT_MS = 60000;
+declare const DISPLAY_STACK_TIMEOUT_MS = 90000;
 /** Desktop geometry for the framebuffer. v1 has no live RANDR: a resolution
  *  change is a full down -> up restart (a separate op). */
 type DesktopGeometry = {
@@ -230,11 +263,13 @@ type DesktopGeometry = {
 };
 declare const DEFAULT_DESKTOP_GEOMETRY: DesktopGeometry;
 /** Thrown when a stage of the launch script failed. exitCode 11/12/13 map to
- *  Xvfb / x11vnc / websockify respectively (the stage that died). Degradation is
- *  surfaced as a value to viewers by the caller; this error is for diagnostics. */
+ *  Xvfb / x11vnc / websockify respectively (the stage that died); 14 is the
+ *  PAINTABLE-FRAME gate (ports listening but scrot still yields an empty frame —
+ *  the display is up but not actually painting). Degradation is surfaced as a
+ *  value to viewers by the caller; this error is for diagnostics. */
 declare class DisplayStackError extends Error {
     readonly exitCode: number;
-    readonly stage: "xvfb" | "x11vnc" | "websockify" | "unknown";
+    readonly stage: "xvfb" | "x11vnc" | "websockify" | "paint" | "unknown";
     constructor(exitCode: number, output: string);
 }
 /** Thrown when the provider session cannot run commands (a headless-only
@@ -1049,11 +1084,18 @@ declare class SelfhostedSession {
     /** Computer-use VIEW op: capture a single PNG screenshot of the machine's desktop
      *  plus its geometry (via ScreenCaptureKit / x11). NOT consent-gated (a view op —
      *  the view/control decoupling), so it works with a display but no screen-control
-     *  consent. Returns the raw encoded bytes + width/height. */
+     *  consent. Returns the raw encoded bytes + the ENCODED width/height, plus the
+     *  NATIVE (pre-downscale) geometry: when the agent had to downscale the PNG to fit
+     *  the transport's max payload, `nativeWidth`/`nativeHeight` carry the original
+     *  capture size so the computer-use layer can scale model clicks (in encoded-pixel
+     *  space) back to native pixels. An older agent leaves them 0 → read as "same as
+     *  width/height" (no downscale). */
     screenshot(): Promise<{
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
     /** A cheap liveness probe — request a Ping on the subject; returns true iff a
      *  responder answered (no AgentError). Used by `negotiateSelfhostedCapabilities`.
@@ -1373,6 +1415,8 @@ interface RoutableBackendSession {
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
 }
 /** The resolved active backend for an epoch: the live session + the sandbox id it
@@ -1455,6 +1499,8 @@ declare class RoutingSandboxSession implements RoutableBackendSession {
         png: Uint8Array;
         width: number;
         height: number;
+        nativeWidth: number;
+        nativeHeight: number;
     }>;
     constructor(deps: RoutingSandboxSessionDeps);
     /**
@@ -1687,6 +1733,7 @@ type EstablishedSandboxSession = {
     instanceId: string;
     backendId: string;
 };
+type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
 /**
  * Per-provider NotFound discriminator. The @openai/agents-extensions
  * `isProviderSandboxNotFoundError` / `assertResumeRecreateAllowed` helpers live
@@ -1720,6 +1767,7 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
     sessionId: string;
     backendOverride?: SandboxBackend;
     environment?: Record<string, string>;
+    onSandboxCreated?: SandboxCreatedCallback;
 }): Promise<EstablishedSandboxSession>;
 /**
  * Fold a freshly-established (or resumed) sandbox session into the persistable
@@ -1735,4 +1783,4 @@ declare function establishSandboxSessionFromEnvelope(settings: Settings, envelop
  */
 declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
 
-export { type ActiveBackendResolverDeps, ActiveBackendUnresolvableError, type ActivePointer, ChannelAConflictError, type ChannelAEmitter, type ChannelAExecArgs, type ChannelAExecResult, ChannelANotFoundError, type ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, type ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, type DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, type EnsureDisplayStackOptions, type EnsureDisplayStackResult, type EnsureTerminalServerOptions, type EnsureTerminalServerResult, type EstablishedSandboxSession, type ExposeStreamPortInput, type ExposeStreamPortResult, type ExposedPortEndpoint, type FinalizeRecordingResult, type MintStreamTokenInput, MockAgentResponder, type MockAgentResponderOptions, type MockExecHandler, NatsControlRpc, type NatsRequestConnection, type NegotiationContext, type NumstatEntry, PROVIDER_REGISTRY, type ProviderConstructionContext, type ProviderRegistration, type RecordingCodec, type RecordingContentType, RecordingError, type RecordingProcess, RecordingUnavailableError, type ResolvedActiveBackend, type RoutableBackendSession, type RoutableSandbox, RoutingSandboxSession, type RoutingSandboxSessionDeps, type RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, type SandboxChannelAServiceOptions, SandboxConfigError, SandboxProviderUnavailableError, type SelfhostedApplyDiff, SelfhostedControlError, type SelfhostedEditor, type SelfhostedEnrollment, type SelfhostedExecArgs, type SelfhostedExecResult, type SelfhostedImageOutput, type SelfhostedLivenessState, type SelfhostedNegotiationInput, type SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, type SelfhostedSessionBuild, type SelfhostedSessionDeps, type SelfhostedSessionState, type SelfhostedUnavailableReason, type StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, tearDownDisplayStack, tearDownTerminalServer, timeoutAgentError, timeoutControlResponse, verifyStreamToken };
+export { type ActiveBackendResolverDeps, ActiveBackendUnresolvableError, type ActivePointer, ChannelAConflictError, type ChannelAEmitter, type ChannelAExecArgs, type ChannelAExecResult, ChannelANotFoundError, type ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, type ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, type DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, type EnsureDisplayStackOptions, type EnsureDisplayStackResult, type EnsureTerminalServerOptions, type EnsureTerminalServerResult, type EstablishedSandboxSession, type ExposeStreamPortInput, type ExposeStreamPortResult, type ExposedPortEndpoint, type FinalizeRecordingResult, type LiveModalSandboxLeaseAttribution, type MintStreamTokenInput, MockAgentResponder, type MockAgentResponderOptions, type MockExecHandler, type ModalOrphanSweepResult, type ModalSandboxAttribution, NatsControlRpc, type NatsRequestConnection, type NegotiationContext, type NumstatEntry, PROVIDER_REGISTRY, type ProviderConstructionContext, type ProviderRegistration, type RecordingCodec, type RecordingContentType, RecordingError, type RecordingProcess, RecordingUnavailableError, type ResolvedActiveBackend, type RoutableBackendSession, type RoutableSandbox, RoutingSandboxSession, type RoutingSandboxSessionDeps, type RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, type SandboxChannelAServiceOptions, SandboxConfigError, type SandboxCreatedCallback, SandboxProviderUnavailableError, type SelfhostedApplyDiff, SelfhostedControlError, type SelfhostedEditor, type SelfhostedEnrollment, type SelfhostedExecArgs, type SelfhostedExecResult, type SelfhostedImageOutput, type SelfhostedLivenessState, type SelfhostedNegotiationInput, type SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, type SelfhostedSessionBuild, type SelfhostedSessionDeps, type SelfhostedSessionState, type SelfhostedUnavailableReason, type StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, modalSandboxAttributionEnvironment, modalSandboxAttributionTags, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, sweepModalOrphanSandboxes, tagModalSandbox, tearDownDisplayStack, tearDownTerminalServer, terminateModalSandboxById, timeoutAgentError, timeoutControlResponse, verifyStreamToken };

package/dist/sandbox/index.js

@@ -63,6 +63,8 @@ import {
   isWorkspaceEscapeError,
   makeActiveBackendResolver,
   mintStreamToken,
+  modalSandboxAttributionEnvironment,
+  modalSandboxAttributionTags,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
   offlineAgentError,
@@ -85,12 +87,15 @@ import {
   stopRecording,
   stripExecBanner,
   subjectFor,
+  sweepModalOrphanSandboxes,
+  tagModalSandbox,
   tearDownDisplayStack,
   tearDownTerminalServer,
+  terminateModalSandboxById,
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken
-} from "../chunk-2PO56VAL.js";
+} from "../chunk-D5KU3QUC.js";
 export {
   ActiveBackendUnresolvableError,
   CAPABILITY_DESCRIPTORS,
@@ -156,6 +161,8 @@ export {
   isWorkspaceEscapeError,
   makeActiveBackendResolver,
   mintStreamToken,
+  modalSandboxAttributionEnvironment,
+  modalSandboxAttributionTags,
   negotiateCapabilities,
   negotiateSelfhostedCapabilities,
   offlineAgentError,
@@ -178,8 +185,11 @@ export {
   stopRecording,
   stripExecBanner,
   subjectFor,
+  sweepModalOrphanSandboxes,
+  tagModalSandbox,
   tearDownDisplayStack,
   tearDownTerminalServer,
+  terminateModalSandboxById,
   timeoutAgentError,
   timeoutControlResponse,
   verifyStreamToken

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@opengeni/agent-proto": "^0.2.1",
-    "@opengeni/config": "^0.2.2",
-    "@opengeni/contracts": "^0.4.0",
+    "@opengeni/config": "^0.2.4",
+    "@opengeni/contracts": "^0.6.0",
     "@openai/agents": "^0.11.6",
     "@openai/agents-extensions": "^0.11.6",
     "modal": "^0.7.4",