@opengeni/runtime 0.7.0 → 0.11.0

package/src/sandbox/select.ts

@@ -3,7 +3,7 @@
 // negotiateCapabilities() turns a static CapabilityDescriptor + runtime context
 // (the selected OS, the lease liveness/epoch, and the deployment's desktop
 // policy) into a coherent SessionCapabilities document. The load-bearing rule
-// (master-spine Part D): a capability cell is ALWAYS present — when unavailable
+// (sandbox contract Part D): a capability cell is ALWAYS present — when unavailable
 // it is `available:false` + a typed `reason`, NEVER absent. Degradation is a
 // value, not a silent drop.
 
@@ -45,7 +45,7 @@ export interface NegotiationContext {
    *  (settings.computerUseReadOnly). v1 default false (the agent clicks/types). */
   computerUseReadOnly?: boolean;
   /**
-   * Whether a scoped-stream-token secret is resolvable (I8/OD-8). When desktop
+   * Whether a scoped-stream-token secret is resolvable (stream-token availability contract). When desktop
    * is enabled but this is false (no streamTokenSecret AND no delegationSecret),
    * the desktop plane GRACEFULLY DEGRADES to transport:null — the deployment
    * boots, but the pixel plane cannot mint scoped tokens. Defaults to true so a
@@ -279,7 +279,7 @@ export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilit
       available = false;
       reason = "disabled_by_policy";
     } else if (ctx.streamTokenSecretAvailable === false) {
-      // Graceful degrade (I8/OD-8): desktop is enabled + backend-capable, but no
+      // Graceful degrade (stream-token availability contract): desktop is enabled + backend-capable, but no
       // stream-token secret is resolvable, so no scoped token can be minted. The
       // deployment boots; the desktop cell reports transport:null + a typed
       // reason rather than crashing the API.

package/src/sandbox/selfhosted/capabilities.ts

@@ -1,4 +1,4 @@
-// Selfhosted capability negotiation (M3, dossier §10.2 item 4).
+// Selfhosted capability negotiation (M3, item 4).
 //
 // `negotiateSelfhostedCapabilities` resolves the selfhosted-specific cells from
 //   (a) the M2 enrollment row (consent / display / status / lastSeenAt), and

package/src/sandbox/selfhosted/op-stream.ts

@@ -168,6 +168,37 @@ export class OpStreamExecClient {
     return this.deps.journal?.attachGeneration() ?? "1";
   }
 
+  /**
+   * Cancel an exec by its durable op id. OpCancel is idempotent and also acts
+   * as a cancel-before-start tombstone, so calling this while OpStart is still
+   * racing is safe: the runner either kills the accepted process tree or
+   * refuses the later start without spawning it.
+   */
+  async cancel(opId: string): Promise<void> {
+    const response = await this.deps.controlRpc.request(
+      this.deps.rpcSubject,
+      {
+        requestId: crypto.randomUUID(),
+        epoch: this.deps.epoch,
+        op: { $case: "opCancel", opCancel: { opId } },
+      },
+      { timeoutMs: this.deps.controlTimeoutMs },
+    );
+    if (response.error || !response.result) {
+      throw agentErrorToControlError(
+        response.error ?? {
+          code: ErrorCode.ERROR_CODE_PROTOCOL,
+          message: "op-stream cancel returned an empty result",
+          retryable: false,
+          detail: {},
+        },
+      );
+    }
+    if (response.result.$case !== "opStatus") {
+      throw protocolError(`op-stream cancel: unexpected result ${response.result.$case}`);
+    }
+  }
+
   /**
    * Run one exec over the op stream. `opId` is the durable id (B1) — a re-issue
    * with the same id attaches instead of re-running. `deadlineMs` is the exec
@@ -429,6 +460,15 @@ class OpConsumer {
   }
 
   private refusedStart(status: OpStatus | undefined): SelfhostedControlError {
+    if (status?.exit?.cancelled) {
+      return new SelfhostedControlError({
+        message: "The command was cancelled before the machine admitted it.",
+        code: ErrorCode.ERROR_CODE_TIMEOUT,
+        reason: null,
+        retryable: false,
+        detail: { cancelled: "true" },
+      });
+    }
     if (status?.state === OpState.OP_STATE_LOST) {
       return lostToControlError(status);
     }

package/src/sandbox/selfhosted/op-testing.ts

@@ -110,6 +110,8 @@ export interface FakeOpScript {
    *  live emission; later attaches replay from retention unfiltered. Default
    *  false = the op is COMPLETE at start (pure collection). */
   live?: boolean;
+  /** Keep a live op RUNNING with no frames until OpCancel is received. */
+  holdUntilCancel?: boolean;
   /** Seqs whose LIVE emission is dropped (retention keeps them). */
   dropLiveSeqs?: ReadonlySet<number>;
   /** Seqs whose LIVE emission is duplicated (delivered twice back-to-back). */
@@ -155,6 +157,7 @@ export class FakeOpRunner implements ControlRpc {
   /** Op ids that answer LOST (evicted) on query/attach — bounded-retention
    *  collateral. */
   readonly lostOps = new Set<string>();
+  private readonly cancelledBeforeStart = new Set<string>();
 
   constructor(opts: {
     transport: InMemoryOpStreamTransport;
@@ -219,6 +222,8 @@ export class FakeOpRunner implements ControlRpc {
         );
       case "opQuery":
         return this.handleQuery(req.requestId, op.opQuery.opId);
+      case "opCancel":
+        return this.handleCancel(req.requestId, op.opCancel.opId);
       default: {
         if (this.fallback) {
           return this.fallback.request(subject, req, opts);
@@ -233,6 +238,9 @@ export class FakeOpRunner implements ControlRpc {
   }
 
   private handleStart(opId: string): ControlResponse {
+    if (this.cancelledBeforeStart.has(opId)) {
+      return startResponse(opId, cancelledStatus(opId), false);
+    }
     const existing = this.runs.get(opId);
     if (existing) {
       // IDEMPOTENT BY OP ID: a known op answers its current status and NEVER
@@ -294,7 +302,7 @@ export class FakeOpRunner implements ControlRpc {
     if (run.script.live && !run.liveEmitted) {
       // First attach on a live op: nothing retained yet worth replaying — the
       // child "runs now" and the (faulty) live flow begins.
-      this.emitLive(opId, run, subject);
+      if (!run.script.holdUntilCancel) this.emitLive(opId, run, subject);
       return statusOnly(requestId, this.statusOf(opId, run));
     }
     // A heal (or completed-op collection): replay from RETENTION — every frame
@@ -320,6 +328,26 @@ export class FakeOpRunner implements ControlRpc {
     return statusOnly(requestId, this.statusOf(opId, run));
   }
 
+  private handleCancel(requestId: string, opId: string): ControlResponse {
+    const run = this.runs.get(opId);
+    if (!run) {
+      this.cancelledBeforeStart.add(opId);
+      return statusOnly(requestId, cancelledStatus(opId));
+    }
+    if (!run.liveEmitted && run.script.holdUntilCancel) {
+      run.exit.exitCode = -1;
+      run.exit.cancelled = true;
+      run.liveEmitted = true;
+      const subject = opFrameSubject(this.workspaceId, this.agentId, opId);
+      queueMicrotask(() => {
+        for (const frame of run.frames) {
+          this.transport.deliver(subject, OpFrame.encode(frame).finish());
+        }
+      });
+    }
+    return statusOnly(requestId, this.statusOf(opId, run));
+  }
+
   /** The LIVE flow: fault filters applied (drops, duplicates, adjacent
    *  reordering); retention still holds every frame for the heal replay. */
   private emitLive(opId: string, run: FakeOpRun, subject: string): void {
@@ -441,11 +469,11 @@ function errorResponse(requestId: string, code: ErrorCode, message: string): Con
   };
 }
 
-function startResponse(requestId: string, status: OpStatus): ControlResponse {
+function startResponse(requestId: string, status: OpStatus, accepted = true): ControlResponse {
   return {
     requestId,
     error: undefined,
-    result: { $case: "opStart", opStart: { accepted: true, status } },
+    result: { $case: "opStart", opStart: { accepted, status } },
   };
 }
 
@@ -466,3 +494,22 @@ function lostStatus(opId: string): OpStatus {
     lostReason: OpLostReason.OP_LOST_REASON_EVICTED,
   };
 }
+
+function cancelledStatus(opId: string): OpStatus {
+  return {
+    opId,
+    state: OpState.OP_STATE_COMPLETE,
+    nextSeq: "1",
+    exit: {
+      exitCode: -1,
+      timedOut: false,
+      cancelled: true,
+      durationMs: "0",
+      digests: {},
+      totals: {},
+      failureCode: "",
+      failureDetail: {},
+    },
+    lostReason: OpLostReason.OP_LOST_REASON_UNSPECIFIED,
+  };
+}

package/src/sandbox/selfhosted/session.ts

@@ -1,7 +1,7 @@
 // `SelfhostedSession` + `SelfhostedSandboxClient` — the NATS-backed structural
 // sandbox surface for the `selfhosted` backend (bring-your-own-compute).
 //
-// The insight (dossier §7): every existing seam (Channel-A exec/fs/git, the
+// The insight: every existing seam (Channel-A exec/fs/git, the
 // viewer's `resolveExposedPort`, computer-use) consumes a provider session
 // STRUCTURALLY — `session.exec ?? session.execCommand`, `session.readFile`,
 // `session.resolveExposedPort`, `session.serializeSessionState`. If the
@@ -64,7 +64,7 @@ const encoder = new TextEncoder();
  * provided-session root-delta guard (`validateProvidedSessionManifestUpdate`).
  *
  * On a bring-your-own machine this path DOES NOT EXIST: the machine's real root
- * is the agent's `workspace_root` (reported in Hello, e.g. "/home/jorge/repo").
+ * is the agent's `workspace_root` (reported in Hello, e.g. "/home/user/repo").
  * The Rust agent's `resolve_cwd` maps an EMPTY cwd / a RELATIVE path onto its
  * `workspace_root`, but takes an ABSOLUTE path AS-IS. So a virtual-root-anchored
  * path the SDK hands us ("/workspace" or "/workspace/sub", e.g. an exec workdir
@@ -187,6 +187,7 @@ const SELFHOSTED_MAX_EXEC_TIMEOUT_MS = 2_147_483_647 - SELFHOSTED_EXEC_REPLY_GRA
 const SELFHOSTED_EXEC_ENV_ALLOWLIST = [
   "OPENGENI_TOOLSPACE_URL",
   "OPENGENI_TOOLSPACE_TOKEN_FILE",
+  "OPENGENI_OGTOOL_PACKAGE_SPEC",
 ] as const;
 
 function selfhostedExecEnv(environment: Record<string, string>): Record<string, string> {
@@ -741,6 +742,18 @@ export class SelfhostedSession {
     return result.output;
   }
 
+  /**
+   * Physical turn-cancellation seam used by the runtime tool fence. Only the
+   * op-stream transport has a process-tree cancellation protocol; a legacy
+   * runner returns false and the caller remains fail-closed until its exec
+   * deadline rather than claiming the machine is quiescent.
+   */
+  async cancelExecCommand(opId: string): Promise<boolean> {
+    if (!this.opStreamClient) return false;
+    await this.opStreamClient.cancel(opId);
+    return true;
+  }
+
   /** SDK shell capability never calls this (gated on `supportsPty()` which is
    *  false), but the surface advertises it. Selfhosted exec has no interactive PTY
    *  session over the structured RPC, so a stdin write is unsupported. */
@@ -994,7 +1007,7 @@ export class SelfhostedSession {
    * after asking the agent to ensure a stream channel for the port. M8b wires the
    * real relay tier (the byte pump) behind THIS seam.
    *
-   * THE CHANNEL-KEY QUERY (the M8b relay-dial contract, dossier §10.5): the relay
+   * THE CHANNEL-KEY QUERY (the M8b relay-dial contract): the relay
    * routes by `{workspaceId, agentId, port}` — the EXACT `ChannelKey::query` the
    * agent's relay client (`opengeni-agent-stream`) appends when it registers the
    * producer side: `ws=<workspaceId>&agent=<agentId>&port=<port>`. We append the
@@ -1400,7 +1413,7 @@ function kindToProtocol(kind: StreamKind | undefined): string {
 
 /**
  * The selfhosted NotFound discriminator — THE load-bearing safety property
- * (dossier §10.2/§19): for selfhosted, `agent-offline` (no responder) is NEVER a
+ *: for selfhosted, `agent-offline` (no responder) is NEVER a
  * provider NotFound. A user's real machine is not recreatable; if the lease saw
  * agent-offline as NotFound it would cold-create a RIVAL box (a Modal box) for
  * the user's machine. So this ALWAYS returns FALSE for selfhosted — there is no

package/src/sandbox/selfhosted/testing.ts

@@ -7,7 +7,7 @@
 //
 // It is shipped from the runtime package (a testing util, not test-only-private)
 // because the API/worker integration suites (M4+) reuse it to drive
-// `withChannelA`/viewer/swap end-to-end without a real machine (dossier §16).
+// `withChannelA`/viewer/swap end-to-end without a real machine.
 
 import {
   AgentError,

package/src/sandbox/stream-port.ts

@@ -15,7 +15,7 @@
 // (Modal raw-TLS host:port, Daytona signed preview, Blaxel preview-token query)
 // carries the reach-the-port boundary; the OpenGeni stream token is RECORDED
 // against the viewer holder and is the in-box websockify edge boundary (P3/P5).
-// Per the master-spine ruling, exposeStreamPort returns the token alongside the
+// Per the sandbox contract ruling, exposeStreamPort returns the token alongside the
 // URL so the caller records it; it does NOT append it to `url`.
 
 import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";

package/src/sandbox/stream-token.ts

@@ -1,7 +1,7 @@
 // @opengeni/runtime/sandbox — scoped stream-token mint/verify (P3.1).
 //
 // The agent-loop-free home for the scoped data-plane stream token used by the
-// desktop pixel plane (Channel B, master-spine §C.3 / crosscut PART 1.3). It is
+// desktop pixel plane (Channel B, sandbox contract §C.3 / crosscut PART 1.3). It is
 // a THIN wrapper over the contracts HMAC envelope (signStreamToken /
 // verifyStreamToken) — NOT a second crypto: it REUSES the exact base64Url +
 // hmacSha256 construction that backs signDelegatedAccessToken, with the distinct

package/src/sandbox/terminal-server.ts

@@ -110,7 +110,11 @@ export type EnsureTerminalServerResult = {
  *
  * Exported (pure, side-effect-free) so the ensureTerminalServer unit test can
  * assert the exact command sequence without a live box. Mirrors
- * buildDisplayStackScript.
+ * buildDisplayStackScript. A ttyd process is sandbox-group-global, not
+ * OpenGeni-session-specific, so it must never inherit the box-global legacy
+ * Toolspace pointer. Session-scoped interactive exec/PTY uses Channel A; the
+ * shared ttyd shell fails closed for Toolspace until that stream plane itself is
+ * session-isolated.
  */
 export function buildTerminalServerScript(options: EnsureTerminalServerOptions = {}): string {
   const port = options.port ?? TERMINAL_STREAM_PORT;
@@ -120,7 +124,7 @@ export function buildTerminalServerScript(options: EnsureTerminalServerOptions =
   return (
     `mkdir -p /tmp/opengeni-terminal && ` +
     `flock -w 30 /tmp/opengeni-terminal/up.outer.lock ` +
-    `env TERMINAL_PORT=${port} opengeni-terminal-up`
+    `env TERMINAL_PORT=${port} OPENGENI_TOOLSPACE_TOKEN_FILE=/dev/null opengeni-terminal-up`
   );
 }
 

package/src/sandbox/toolspace-token.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { posix as posixPath } from "node:path";
+
+import type {
+  ExecCommandArgs,
+  SandboxClient,
+  SandboxSessionLike,
+  SandboxSessionState,
+} from "@openai/agents/sandbox";
+
+const MAX_TOOLSPACE_SESSION_ID_BYTES = 512;
+
+export class ToolspaceTokenPathError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolspaceTokenPathError";
+  }
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function assertToolspaceSessionId(sessionId: string): string {
+  if (
+    !sessionId ||
+    sessionId.trim() !== sessionId ||
+    new TextEncoder().encode(sessionId).byteLength > MAX_TOOLSPACE_SESSION_ID_BYTES ||
+    sessionId.includes("\0")
+  ) {
+    throw new ToolspaceTokenPathError("Toolspace session id is invalid");
+  }
+  return sessionId;
+}
+
+/**
+ * Derive the per-session token file beside the legacy manifest pointer.
+ *
+ * The manifest pointer stays box-global so an already-warm shared sandbox does
+ * not receive an illegal environment delta. Every OpenGeni command overrides
+ * that pointer with this deterministic path. The hash is path hygiene and
+ * avoids disclosing host/session ids in filenames; filesystem paths are not an
+ * authorization boundary. The delegated bearer's session claim remains the
+ * authority boundary for Toolspace calls.
+ */
+export function toolspaceTokenFileForSession(manifestTokenFile: string, sessionId: string): string {
+  if (
+    !manifestTokenFile ||
+    manifestTokenFile.includes("\0") ||
+    !posixPath.isAbsolute(manifestTokenFile)
+  ) {
+    throw new ToolspaceTokenPathError("Toolspace manifest token file must be absolute");
+  }
+  const normalizedManifestFile = posixPath.normalize(manifestTokenFile);
+  const digest = createHash("sha256").update(assertToolspaceSessionId(sessionId)).digest("hex");
+  return posixPath.join(posixPath.dirname(normalizedManifestFile), "toolspace-tokens", digest);
+}
+
+export function toolspaceTokenFileFromEnvironment(
+  environment: Readonly<Record<string, string>>,
+  sessionId: string,
+): string {
+  const manifestTokenFile =
+    environment.OPENGENI_TOOLSPACE_TOKEN_FILE ??
+    `${environment.HOME ?? "/workspace"}/.opengeni/toolspace-token`;
+  return toolspaceTokenFileForSession(manifestTokenFile, sessionId);
+}
+
+/** Prefix one sandbox command with its session-specific Toolspace pointer. */
+export function withToolspaceTokenEnvironment(cmd: string, tokenFile: string): string {
+  if (!tokenFile || tokenFile.includes("\0") || !posixPath.isAbsolute(tokenFile)) {
+    throw new ToolspaceTokenPathError("Toolspace token file must be absolute");
+  }
+  return [`export OPENGENI_TOOLSPACE_TOKEN_FILE=${shellQuote(tokenFile)}`, cmd].join("\n");
+}
+
+/** Preserve provider identity/capabilities while decorating command creation. */
+export function withToolspaceTokenSession<T extends object>(session: T, tokenFile: string): T {
+  return new Proxy(session, {
+    get(target, property, receiver) {
+      if (property === "exec" || property === "execCommand") {
+        const command = Reflect.get(target, property, target) as
+          | ((args: ExecCommandArgs) => Promise<unknown>)
+          | undefined;
+        if (!command) return undefined;
+        return async (args: ExecCommandArgs) =>
+          await command.call(target, {
+            ...args,
+            cmd: withToolspaceTokenEnvironment(args.cmd, tokenFile),
+          });
+      }
+      const value = Reflect.get(target, property, receiver) as unknown;
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+/** Decorate every client-created/resumed session with one session pointer. */
+export function withToolspaceTokenClient(client: SandboxClient, tokenFile: string): SandboxClient {
+  const decorated = new WeakMap<object, SandboxSessionLike>();
+  const wrap = <T extends SandboxSessionLike>(session: T): T => {
+    const existing = decorated.get(session);
+    if (existing) return existing as T;
+    const wrapped = withToolspaceTokenSession(session, tokenFile);
+    decorated.set(session, wrapped);
+    return wrapped;
+  };
+  return {
+    backendId: client.backendId,
+    ...(client.supportsDefaultOptions !== undefined
+      ? { supportsDefaultOptions: client.supportsDefaultOptions }
+      : {}),
+    ...(client.create
+      ? { create: async (...args: any[]) => wrap(await (client.create as any)(...args)) }
+      : {}),
+    ...(client.resume
+      ? { resume: async (...args: any[]) => wrap(await (client.resume as any)(...args)) }
+      : {}),
+    ...(client.delete
+      ? { delete: async (state: SandboxSessionState) => await client.delete!(state) }
+      : {}),
+    ...(client.serializeSessionState
+      ? {
+          serializeSessionState: async (state: SandboxSessionState, options) =>
+            await client.serializeSessionState!(state, options),
+        }
+      : {}),
+    ...(client.canPersistOwnedSessionState
+      ? {
+          canPersistOwnedSessionState: async (state: SandboxSessionState) =>
+            await client.canPersistOwnedSessionState!(state),
+        }
+      : {}),
+    ...(client.canReusePreservedOwnedSession
+      ? {
+          canReusePreservedOwnedSession: async (state: SandboxSessionState) =>
+            await client.canReusePreservedOwnedSession!(state),
+        }
+      : {}),
+    ...(client.deserializeSessionState
+      ? {
+          deserializeSessionState: async (state: Record<string, unknown>) =>
+            await client.deserializeSessionState!(state),
+        }
+      : {}),
+  } as SandboxClient;
+}