@opengeni/runtime 0.6.1 → 0.7.1

package/src/sandbox/selfhosted/session.ts

@@ -18,6 +18,7 @@
 import {
   ControlRequest,
   ControlResponse,
+  ErrorCode,
   FsEntryKind,
   StreamKind,
   type DesktopInputRequest,
@@ -36,9 +37,22 @@ import { Manifest } from "@openai/agents/sandbox";
 import type { ExposedPortEndpoint } from "../stream-port";
 import {
   agentErrorToControlError,
+  drainingExhaustedError,
+  execDeadlineHint,
+  SelfhostedControlError,
   subjectFor,
   type ControlRpc,
 } from "./control-rpc";
+import {
+  decideSelfhostedRetry,
+  defaultSelfhostedRetryClock,
+  type SelfhostedRetryClock,
+} from "./retry-policy";
+import type { SelfhostedOpObservation, SelfhostedOpObserver } from "./op-observer";
+import { selfhostedFaultClass } from "./fault-rendering";
+import { nextDurableOpId } from "../op-correlation";
+import { OpStreamExecClient, type OpStreamJournal } from "./op-stream";
+import { OpStreamUnavailableError, type OpStreamTransport } from "./op-transport";
 
 const decoder = new TextDecoder();
 const encoder = new TextEncoder();
@@ -116,7 +130,11 @@ function toMachinePath(p: string | undefined, workingDir: string): string {
  *  runtime barrel (`packages/runtime/src/index.ts`, which DOES import that root)
  *  injects it via `setSelfhostedApplyDiff` at module load. Until injected,
  *  `createEditor()` surfaces a clear error rather than a silent wrong-edit. */
-export type SelfhostedApplyDiff = (input: string, diff: string, mode?: "default" | "create") => string;
+export type SelfhostedApplyDiff = (
+  input: string,
+  diff: string,
+  mode?: "default" | "create",
+) => string;
 let injectedApplyDiff: SelfhostedApplyDiff | undefined;
 
 /** Register the SDK's `applyDiff` so `SelfhostedSession.createEditor()` can apply
@@ -128,8 +146,14 @@ export function setSelfhostedApplyDiff(fn: SelfhostedApplyDiff): void {
 /** The structural Editor surface the SDK's filesystem capability consumes (the
  *  three apply_patch operations). Mirrors `@openai/agents-core`'s `Editor`. */
 export interface SelfhostedEditor {
-  createFile(operation: { path: string; diff: string }, context?: unknown): Promise<{ output?: string } | void>;
-  updateFile(operation: { path: string; diff: string; moveTo?: string }, context?: unknown): Promise<{ output?: string } | void>;
+  createFile(
+    operation: { path: string; diff: string },
+    context?: unknown,
+  ): Promise<{ output?: string } | void>;
+  updateFile(
+    operation: { path: string; diff: string; moveTo?: string },
+    context?: unknown,
+  ): Promise<{ output?: string } | void>;
   deleteFile(operation: { path: string }, context?: unknown): Promise<{ output?: string } | void>;
 }
 
@@ -143,6 +167,13 @@ export interface SelfhostedImageOutput {
 /** Default control-op timeout. A transient miss surfaces as `agent_reconnecting`
  *  (the turn pauses + retries); it is NOT a hard failure. */
 export const SELFHOSTED_DEFAULT_TIMEOUT_MS = 30_000;
+/** Reply grace after an agent-side exec deadline. The child is terminated at
+ *  `ExecRequest.timeoutMs`; this outer window lets the typed `timedOut` response
+ *  cross NATS before request/reply gives up. */
+const SELFHOSTED_EXEC_REPLY_GRACE_MS = 5_000;
+/** nats.js ultimately schedules a JS timer; stay inside the signed 32-bit timer
+ *  range while also fitting the reply grace. */
+const SELFHOSTED_MAX_EXEC_TIMEOUT_MS = 2_147_483_647 - SELFHOSTED_EXEC_REPLY_GRACE_MS;
 
 /**
  * The ONLY manifest-environment keys exported into a selfhosted machine's exec
@@ -153,7 +184,10 @@ export const SELFHOSTED_DEFAULT_TIMEOUT_MS = 30_000;
  * 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;
+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> = {};
@@ -184,17 +218,55 @@ export interface SelfhostedRelayConfig {
 /** The relay's default wss dial path (the `opengeni-relay` server route). */
 export const SELFHOSTED_RELAY_STREAM_PATH = "/stream";
 
+/**
+ * The op-stream injection (op-stream protocol v1.1 — see op-stream.ts). PRESENT
+ * = the streaming exec transport is enabled for this session (the worker
+ * injects it only when the runner advertised `Capabilities.op_stream` AND the
+ * server flag is on — the leaf carries no flag logic). ABSENT = the legacy
+ * monolithic exec, byte-identical to before. The timing knobs exist for tests.
+ */
+export interface SelfhostedOpStreamDeps {
+  transport: OpStreamTransport;
+  /** The durable-resume journal (attach generation + settled-frontier persist).
+   *  Absent (tests, non-activity callers) ⇒ generation "1", no persistence. */
+  journal?: OpStreamJournal;
+  windowBytes?: number;
+  ackIntervalMs?: number;
+  silenceTimeoutMs?: number;
+  reconnectHoldMs?: number;
+}
+
 export interface SelfhostedSessionDeps {
   workspaceId: string;
   agentId: string;
   controlRpc: ControlRpc;
   relay: SelfhostedRelayConfig;
+  /** Op-stream exec transport (present = enabled; see SelfhostedOpStreamDeps). */
+  opStream?: SelfhostedOpStreamDeps;
   /** The lease/active epoch this session is fenced under (echoed on every
    *  ControlRequest so the agent can reject a stale op with ERROR_CODE_FENCED).
    *  Defaults to 0 (no fence) for the negotiation-only / test path. */
   epoch?: number;
-  /** Override the control-op timeout (tests). */
+  /** The CONTROL-op timeout (ping/fs/desktop/pty and the exec wire fallback). The
+   *  agent's own control liveness must stay responsive, so this is short (the 30s
+   *  default). Override for tests or per-deployment tuning. */
   timeoutMs?: number;
+  /**
+   * The EXEC process deadline — distinct from `timeoutMs`. A real command
+   * (compile, test run, install) routinely outlives the short control timeout, so
+   * exec gets its own, much larger budget: the agent kills the child at this wall,
+   * and the wire waits `execTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS`. Omitted ⇒
+   * falls back to `timeoutMs` (byte-identical to before this split), so any caller
+   * that does not opt in keeps today's behavior.
+   */
+  execTimeoutMs?: number;
+  /** The clock the bounded control-op retry loop drives (sleep + jitter). Injected
+   *  so tests are deterministic; defaults to a real timer + `Math.random()`. */
+  retryClock?: SelfhostedRetryClock;
+  /** A fire-and-forget observer invoked once per completed control op (out-of-band
+   *  telemetry — metrics + `machine.*` events). The worker/api wire it to the sinks;
+   *  the leaf only invokes it (guarded so it can never break an op). Omitted ⇒ no-op. */
+  onOp?: SelfhostedOpObserver;
   /**
    * The run's declared sandbox environment — the SAME `Record<string,string>` the
    * worker turn passes to `runtime.buildAgent`'s `sandboxEnvironment` (and that the
@@ -226,6 +298,10 @@ export interface SelfhostedExecResult {
   stdout: string;
   stderr: string;
   exitCode: number | null;
+  /** True when the agent killed the child at the exec deadline. Additive to the
+   *  Channel-A superset (consumers that don't read it are unaffected); `execCommand`
+   *  reads it to surface the deadline hint on the stdout-only SDK path. */
+  timedOut?: boolean;
 }
 
 /** The `exec` args the structural surface accepts (mirrors ChannelAExecArgs). */
@@ -260,7 +336,14 @@ export class SelfhostedSession {
   private readonly relay: SelfhostedRelayConfig;
   private readonly epoch: number;
   private readonly timeoutMs: number;
+  /** The exec process deadline (falls back to `timeoutMs` when unset). */
+  private readonly execTimeoutMs: number | undefined;
+  private readonly retryClock: SelfhostedRetryClock;
+  private readonly onOp: SelfhostedOpObserver | undefined;
   private readonly subject: string;
+  /** The op-stream exec client — constructed iff `deps.opStream` was injected
+   *  (= the streaming transport is enabled for this session). */
+  private readonly opStreamClient: OpStreamExecClient | undefined;
   /** The session working directory — the path/cwd base every op is rooted under
    *  (see `toMachinePath`). "" by default ⇒ today's workspace_root behavior. */
   private readonly workingDir: string;
@@ -292,7 +375,12 @@ export class SelfhostedSession {
    * selfhosted (resume re-addresses the machine by agentId via the lease pointer,
    * never from this SDK envelope), so its only job is to not crash the serialize.
    */
-  readonly state: { agentId: string; instanceId: string; manifest: Manifest; environment: Record<string, string> };
+  readonly state: {
+    agentId: string;
+    instanceId: string;
+    manifest: Manifest;
+    environment: Record<string, string>;
+  };
 
   constructor(deps: SelfhostedSessionDeps) {
     this.workspaceId = deps.workspaceId;
@@ -301,8 +389,36 @@ export class SelfhostedSession {
     this.relay = deps.relay;
     this.epoch = deps.epoch ?? 0;
     this.timeoutMs = deps.timeoutMs ?? SELFHOSTED_DEFAULT_TIMEOUT_MS;
+    this.execTimeoutMs = deps.execTimeoutMs;
+    this.retryClock = deps.retryClock ?? defaultSelfhostedRetryClock;
+    this.onOp = deps.onOp;
     this.subject = subjectFor(deps.workspaceId, deps.agentId);
     this.workingDir = deps.workingDir ?? "";
+    this.opStreamClient = deps.opStream
+      ? new OpStreamExecClient({
+          workspaceId: deps.workspaceId,
+          agentId: deps.agentId,
+          epoch: this.epoch,
+          controlRpc: deps.controlRpc,
+          rpcSubject: this.subject,
+          transport: deps.opStream.transport,
+          controlTimeoutMs: this.timeoutMs,
+          retryClock: this.retryClock,
+          ...(deps.opStream.journal !== undefined ? { journal: deps.opStream.journal } : {}),
+          ...(deps.opStream.windowBytes !== undefined
+            ? { windowBytes: deps.opStream.windowBytes }
+            : {}),
+          ...(deps.opStream.ackIntervalMs !== undefined
+            ? { ackIntervalMs: deps.opStream.ackIntervalMs }
+            : {}),
+          ...(deps.opStream.silenceTimeoutMs !== undefined
+            ? { silenceTimeoutMs: deps.opStream.silenceTimeoutMs }
+            : {}),
+          ...(deps.opStream.reconnectHoldMs !== undefined
+            ? { reconnectHoldMs: deps.opStream.reconnectHoldMs }
+            : {}),
+        })
+      : undefined;
     // A valid Manifest mirroring the Modal create-manifest shape (sandbox/index.ts
     // `createManifest`: `new Manifest({ root: "/workspace", environment })`). `root`
     // is "/workspace" to match `buildManifest`'s declared root (the root-delta guard
@@ -320,7 +436,11 @@ export class SelfhostedSession {
     this.state = {
       agentId: deps.agentId,
       instanceId: deps.agentId,
-      manifest: new Manifest({ root: "/workspace", entries: {}, environment: deps.environment ?? {} }),
+      manifest: new Manifest({
+        root: "/workspace",
+        entries: {},
+        environment: deps.environment ?? {},
+      }),
       // The SDK `SandboxSessionState.environment` — the run's threaded env (or `{}`).
       // The group client's end-of-turn serialize reads `state.environment` directly
       // (Object.entries), so it must be a defined object, not absent.
@@ -328,32 +448,145 @@ export class SelfhostedSession {
     };
   }
 
-  /** Issue a control op, decoding the agent's reply or throwing the mapped
-   *  `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
-   *  timeout error from the transport). */
-  private async call(op: NonNullable<ControlRequest["op"]>): Promise<NonNullable<ControlResponse["result"]>> {
-    const req: ControlRequest = {
-      requestId: crypto.randomUUID(),
-      epoch: this.epoch,
-      op,
-    };
-    const res = await this.controlRpc.request(this.subject, req, { timeoutMs: this.timeoutMs });
-    if (res.error) {
-      throw agentErrorToControlError(res.error);
+  /** Invoke the injected per-op observer, guarded: a telemetry tap must NEVER break
+   *  an op (a throwing sink is swallowed). No-op when no observer is wired. */
+  private emitOp(observation: SelfhostedOpObservation): void {
+    if (!this.onOp) {
+      return;
+    }
+    try {
+      this.onOp(observation);
+    } catch {
+      // A telemetry sink must never surface into the op path.
     }
-    if (!res.result) {
-      throw agentErrorToControlError({
-        code: 7, // ERROR_CODE_PROTOCOL — an empty result is a protocol violation
-        message: "agent returned an empty control response",
-        retryable: false,
-        detail: {},
+  }
+
+  /**
+   * Issue a control op, decoding the agent's reply or throwing the mapped
+   * `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
+   * timeout error from the transport).
+   *
+   * Two failure modes are retried in-place (the decision is the pure
+   * `decideSelfhostedRetry` policy):
+   *   - DRAINING — a pre-admission host-work backpressure rejection; the op never
+   *     started, so it is safe to re-issue for ANY op kind (bounded).
+   *   - a TIMEOUT / `agent_reconnecting` blip — re-issued ONCE, and ONLY for a
+   *     read-only idempotent-safe op. A timed-out MUTATION is NEVER re-issued: it
+   *     may already have executed on the machine (at-least-once), which would
+   *     duplicate the write/command. FENCED is intentionally NOT retried here — the
+   *     routing proxy retries it against a re-resolved backend under a fresh epoch.
+   * Each attempt carries a FRESH `requestId` (a retry is a distinct request).
+   */
+  private async call(
+    op: NonNullable<ControlRequest["op"]>,
+    timeoutMs = this.timeoutMs,
+  ): Promise<NonNullable<ControlResponse["result"]>> {
+    const opKind = op.$case;
+    const startedAt = Date.now();
+    let drainingRetries = 0;
+    let timeoutRetries = 0;
+    let neverSentRetries = 0;
+    for (;;) {
+      const req: ControlRequest = {
+        requestId: crypto.randomUUID(),
+        epoch: this.epoch,
+        op,
+      };
+      const res = await this.controlRpc.request(this.subject, req, { timeoutMs });
+      if (!res.error && res.result) {
+        const retries = drainingRetries + timeoutRetries + neverSentRetries;
+        this.emitOp({
+          op: opKind,
+          outcome: "ok",
+          healed: retries > 0,
+          retries,
+          durationMs: Date.now() - startedAt,
+          machineId: this.agentId,
+          // A healed op's class is whichever retry budget it recovered from.
+          ...(retries > 0
+            ? {
+                faultClass:
+                  neverSentRetries > 0
+                    ? "offline"
+                    : drainingRetries > 0
+                      ? "draining"
+                      : "reconnecting",
+              }
+            : {}),
+        });
+        return res.result;
+      }
+      const error = res.error
+        ? agentErrorToControlError(res.error)
+        : agentErrorToControlError({
+            code: 7, // ERROR_CODE_PROTOCOL — an empty result is a protocol violation
+            message: "agent returned an empty control response",
+            retryable: false,
+            detail: {},
+          });
+      const decision = decideSelfhostedRetry({
+        opKind,
+        error,
+        drainingRetries,
+        timeoutRetries,
+        neverSentRetries,
+        jitter: this.retryClock.jitter(),
       });
+      if (decision.action === "fail") {
+        const retries = drainingRetries + timeoutRetries + neverSentRetries;
+        const encoded = Number(error.detail.encoded_bytes);
+        this.emitOp({
+          op: opKind,
+          outcome: "failed",
+          healed: false,
+          retries,
+          durationMs: Date.now() - startedAt,
+          code: error.code,
+          reason: error.reason,
+          neverSent: error.neverSent,
+          machineId: this.agentId,
+          faultClass: selfhostedFaultClass(error),
+          // Known only on a PAYLOAD_TOO_LARGE fault (the agent's encoded_bytes detail).
+          ...(Number.isFinite(encoded) ? { replyBytes: encoded } : {}),
+        });
+        // Fold the retry count into the DRAINING copy when we actually retried, so
+        // the surfaced message reads "…retried N times first…".
+        if (error.draining && drainingRetries > 0) {
+          throw drainingExhaustedError(error, drainingRetries);
+        }
+        throw error;
+      }
+      await this.retryClock.sleep(decision.delayMs);
+      // Advance the counter for the class that was retried (separate budgets).
+      if (error.neverSent) {
+        neverSentRetries += 1;
+      } else if (error.draining) {
+        drainingRetries += 1;
+      } else {
+        timeoutRetries += 1;
+      }
     }
-    return res.result;
+  }
+
+  /** The clamped exec process deadline (ms): the exec-specific budget when threaded,
+   *  else the control timeout. Shared by `exec()` (the wire deadline) and
+   *  `execCommand()` (the timed-out hint's "N-second limit"), so the two never drift. */
+  private execDeadlineMs(): number {
+    // exec gets its OWN (much larger) deadline distinct from the short control
+    // timeout — a real command routinely outlives 30s. Falls back to `timeoutMs`
+    // when no exec deadline is threaded (unchanged for those callers).
+    return Math.max(
+      1,
+      Math.min(Math.trunc(this.execTimeoutMs ?? this.timeoutMs), SELFHOSTED_MAX_EXEC_TIMEOUT_MS),
+    );
   }
 
   /** Channel-A `exec`: run a command on the machine and return its output. */
   async exec(args: SelfhostedExecArgs): Promise<SelfhostedExecResult> {
+    // Keep the process deadline inside the request/reply deadline. Previously the
+    // wire carried timeoutMs=0 (unbounded) while the caller stopped waiting after
+    // ~30s, leaving accepted work invisible and able to starve control liveness.
+    const executionTimeoutMs = this.execDeadlineMs();
     const execReq: ExecRequest = {
       // The agent does NOT shell-interpret unless `shell` — Channel-A passes a
       // single shell command string, so run it through the platform shell.
@@ -370,13 +603,116 @@ export class SelfhostedSession {
       // seed hook can find the tool surface. See SELFHOSTED_EXEC_ENV_ALLOWLIST.
       env: selfhostedExecEnv(this.state.environment),
       stdin: new Uint8Array(0),
-      timeoutMs: 0,
+      timeoutMs: executionTimeoutMs,
     };
-    const result = await this.call({ $case: "exec", exec: execReq });
+    if (this.opStreamClient) {
+      try {
+        return await this.execViaOpStream(this.opStreamClient, execReq, executionTimeoutMs);
+      } catch (error) {
+        // The transport had no live connection, or the runner refused the START
+        // itself (capability/downgrade race) — the op provably never ran, so
+        // the legacy monolithic exec (the permanent fallback wire form) is safe.
+        if (!(error instanceof OpStreamUnavailableError)) {
+          throw error;
+        }
+      }
+    }
+    return this.execLegacy(execReq, executionTimeoutMs);
+  }
+
+  /** The legacy monolithic exec request/reply — the permanent fallback wire
+   *  form (and the only form for runners without `op_stream`). */
+  private async execLegacy(
+    execReq: ExecRequest,
+    executionTimeoutMs: number,
+  ): Promise<SelfhostedExecResult> {
+    const result = await this.call(
+      { $case: "exec", exec: execReq },
+      executionTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS,
+    );
     if (result.$case !== "exec") {
       throw new Error(`selfhosted exec: unexpected result ${result.$case}`);
     }
-    return execResultToChannelA(result.exec);
+    return execResultToChannelA(result.exec, executionTimeoutMs);
+  }
+
+  /**
+   * The op-stream exec path: the SAME `ExecRequest`, streamed (see
+   * op-stream.ts). The durable op id comes from the tool-call correlation
+   * context (`{callId}:{ordinal}` — B1) when this exec runs inside an SDK tool
+   * invocation; a non-tool caller falls back to a random unique id (never
+   * collides, merely not stable across a turn re-dispatch). Emits the SAME
+   * per-op observation the legacy path does, with `replyBytes` filled from the
+   * reassembled stream (the field the framed transport was designed to own).
+   */
+  private async execViaOpStream(
+    client: OpStreamExecClient,
+    execReq: ExecRequest,
+    executionTimeoutMs: number,
+  ): Promise<SelfhostedExecResult> {
+    const startedAt = Date.now();
+    const opId = nextDurableOpId() ?? `anon_${crypto.randomUUID()}`;
+    try {
+      const outcome = await client.exec(
+        opId,
+        execReq,
+        executionTimeoutMs,
+        executionTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS,
+      );
+      const retries = outcome.heals + outcome.startRetries;
+      this.emitOp({
+        op: "exec",
+        outcome: "ok",
+        healed: retries > 0,
+        retries,
+        durationMs: Date.now() - startedAt,
+        machineId: this.agentId,
+        replyBytes: outcome.replyBytes,
+        // A healed op's class: attach heals are link blips (reconnecting);
+        // start retries without heals were admission backpressure (draining).
+        ...(retries > 0 ? { faultClass: outcome.heals > 0 ? "reconnecting" : "draining" } : {}),
+      });
+      return execResultToChannelA(outcome.response, executionTimeoutMs);
+    } catch (error) {
+      if (error instanceof OpStreamUnavailableError) {
+        // Not a fault: the caller falls back to the legacy exec, which emits
+        // its own observation.
+        throw error;
+      }
+      const controlError =
+        error instanceof SelfhostedControlError
+          ? error
+          : new SelfhostedControlError({
+              message: error instanceof Error ? error.message : String(error),
+              code: ErrorCode.ERROR_CODE_PROTOCOL,
+              reason: null,
+              retryable: false,
+            });
+      this.emitOp({
+        op: "exec",
+        outcome: "failed",
+        healed: false,
+        retries: 0,
+        durationMs: Date.now() - startedAt,
+        code: controlError.code,
+        reason: controlError.reason,
+        neverSent: controlError.neverSent,
+        machineId: this.agentId,
+        faultClass: selfhostedFaultClass(controlError),
+      });
+      throw controlError;
+    }
+  }
+
+  /**
+   * The turn-end op-stream durability hook: persists each settled op's frontier
+   * to the journal, then final-acks it on the wire (licensing the runner to GC
+   * its retained frames). The WORKER calls this after the turn's results are
+   * durably recorded — never mid-turn (the durable-before-wire-ack ordering).
+   * A no-op for sessions without the op-stream transport.
+   */
+  async finalizeOpStreamOps(): Promise<void> {
+    await this.opStreamClient?.finalizeSettledOps();
   }
 
   // ── The agent-turn provided-session contract (over the SAME NATS primitives) ──
@@ -386,9 +722,22 @@ export class SelfhostedSession {
 
   /** SDK shell capability `execCommand`: run a command and return its stdout (the
    *  `exec_command` tool). Selfhosted exec is non-interactive (no PTY) — `tty` is
-   *  ignored; `supportsPty()` is false so the SDK never offers a stdin session. */
+   *  ignored; `supportsPty()` is false so the SDK never offers a stdin session.
+   *
+   *  On a DEADLINE timeout the SDK path is stdout-only (the model sees `result.output`
+   *  and nothing else), so the deadline hint that `exec()` puts on stderr would be
+   *  invisible — a >deadline command would return `{"output":""}` and the model would
+   *  conclude "no output" with no idea it was killed. So when the result timed out we
+   *  surface the hint HERE, on stdout: the hint alone when stdout is empty, or appended
+   *  after a newline when there is partial output (a timed-out result is already not
+   *  cleanly parseable — silence is worse than an explanatory suffix). The structured
+   *  `exec()` result is left untouched for the Channel-A parsers. */
   async execCommand(args: { cmd: string; workdir?: string; runAs?: string }): Promise<string> {
     const result = await this.exec({ cmd: args.cmd, workdir: args.workdir, runAs: args.runAs });
+    if (result.timedOut) {
+      const hint = execDeadlineHint(Math.round(this.execDeadlineMs() / 1000));
+      return result.output ? `${result.output}\n${hint}` : hint;
+    }
     return result.output;
   }
 
@@ -403,7 +752,10 @@ export class SelfhostedSession {
    *  and wrap them in the tool-output image shape (magic-byte sniff + path fallback,
    *  mirroring the SDK's `imageOutputFromBytes`). */
   async viewImage(args: { path: string; runAs?: string }): Promise<SelfhostedImageOutput> {
-    const bytes = await this.readFile({ path: args.path, ...(args.runAs ? { runAs: args.runAs } : {}) });
+    const bytes = await this.readFile({
+      path: args.path,
+      ...(args.runAs ? { runAs: args.runAs } : {}),
+    });
     const mediaType = sniffImageMediaType(bytes, args.path);
     if (!mediaType) {
       throw new Error(`selfhosted view_image: unsupported image format for ${args.path}`);
@@ -418,7 +770,10 @@ export class SelfhostedSession {
   }
 
   /** SDK skills `listDir`: list a directory as `{name, path, type}[]`. */
-  async listDir(args: { path: string; runAs?: string }): Promise<Array<{ name: string; path: string; type: "file" | "dir" | "other" }>> {
+  async listDir(args: {
+    path: string;
+    runAs?: string;
+  }): Promise<Array<{ name: string; path: string; type: "file" | "dir" | "other" }>> {
     const result = await this.listFiles({ path: args.path });
     return result.fsList.entries.map((entry) => ({
       name: entry.name,
@@ -468,7 +823,10 @@ export class SelfhostedSession {
       // EMPTY base) — prefixing workingDir here too would DOUBLE it (the cwd is
       // already workingDir). A non-virtual absolute path passes through and rm
       // uses it as-is; an empty workingDir is byte-identical to before.
-      await this.exec({ cmd: `rm -rf -- ${shellQuote(toMachinePath(path, ""))}`, ...(runAs ? { runAs } : {}) });
+      await this.exec({
+        cmd: `rm -rf -- ${shellQuote(toMachinePath(path, ""))}`,
+        ...(runAs ? { runAs } : {}),
+      });
     };
     return {
       async createFile(operation) {
@@ -512,7 +870,12 @@ export class SelfhostedSession {
   }
 
   /** Write a file onto the machine (the fs surface the descriptor advertises). */
-  async writeFile(args: { path: string; content: string | Uint8Array; createParents?: boolean; append?: boolean }): Promise<number> {
+  async writeFile(args: {
+    path: string;
+    content: string | Uint8Array;
+    createParents?: boolean;
+    append?: boolean;
+  }): Promise<number> {
     const content = typeof args.content === "string" ? encoder.encode(args.content) : args.content;
     const result = await this.call({
       $case: "fsWrite",
@@ -531,10 +894,16 @@ export class SelfhostedSession {
   }
 
   /** List a directory on the machine. */
-  async listFiles(args: { path: string; recursive?: boolean }): Promise<NonNullable<ControlResponse["result"]> & { $case: "fsList" }> {
+  async listFiles(args: {
+    path: string;
+    recursive?: boolean;
+  }): Promise<NonNullable<ControlResponse["result"]> & { $case: "fsList" }> {
     const result = await this.call({
       $case: "fsList",
-      fsList: { path: toMachinePath(args.path, this.workingDir), recursive: args.recursive ?? false },
+      fsList: {
+        path: toMachinePath(args.path, this.workingDir),
+        recursive: args.recursive ?? false,
+      },
     });
     if (result.$case !== "fsList") {
       throw new Error(`selfhosted listFiles: unexpected result ${result.$case}`);
@@ -544,7 +913,10 @@ export class SelfhostedSession {
 
   /** Stat a path on the machine. */
   async statFile(args: { path: string }): Promise<{ exists: boolean }> {
-    const result = await this.call({ $case: "fsStat", fsStat: { path: toMachinePath(args.path, this.workingDir) } });
+    const result = await this.call({
+      $case: "fsStat",
+      fsStat: { path: toMachinePath(args.path, this.workingDir) },
+    });
     if (result.$case !== "fsStat") {
       throw new Error(`selfhosted statFile: unexpected result ${result.$case}`);
     }
@@ -648,7 +1020,9 @@ export class SelfhostedSession {
         desktopEnsure: { width: 0, height: 0 },
       });
       if (result.$case !== "desktopEnsure") {
-        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+        throw new Error(
+          `selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`,
+        );
       }
       channel = result.desktopEnsure.channel;
     } else {
@@ -660,10 +1034,19 @@ export class SelfhostedSession {
         // Open the terminal in the session workingDir (default "" ⇒ the agent's
         // workspace_root, byte-identical to before). A relative workingDir resolves
         // under workspace_root; an absolute one is used as-is by the agent.
-        ptyOpen: { command: [], cwd: this.workingDir, env: {}, cols: 0, rows: 0, term: "xterm-256color" },
+        ptyOpen: {
+          command: [],
+          cwd: this.workingDir,
+          env: {},
+          cols: 0,
+          rows: 0,
+          term: "xterm-256color",
+        },
       });
       if (result.$case !== "ptyOpen") {
-        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+        throw new Error(
+          `selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`,
+        );
       }
       channel = result.ptyOpen.channel;
     }
@@ -716,8 +1099,11 @@ export class SelfhostedSandboxClient {
   private readonly defaultAgentId: string | undefined;
   private readonly epoch: number | undefined;
   private readonly timeoutMs: number | undefined;
+  private readonly execTimeoutMs: number | undefined;
   private readonly environment: Record<string, string> | undefined;
   private readonly workingDir: string | undefined;
+  private readonly onOp: SelfhostedOpObserver | undefined;
+  private readonly opStream: SelfhostedOpStreamDeps | undefined;
   private controlRpcMemo: ControlRpc | undefined;
 
   constructor(opts: {
@@ -729,7 +1115,11 @@ export class SelfhostedSandboxClient {
      *  resume path supplies it via deserializeSessionState. */
     agentId?: string;
     epoch?: number;
+    /** The control-op timeout threaded into every bound session. */
     timeoutMs?: number;
+    /** The exec process deadline threaded into every bound session (distinct from
+     *  `timeoutMs`; falls back to it when unset). See SelfhostedSessionDeps.execTimeoutMs. */
+    execTimeoutMs?: number;
     /** The run's declared sandbox environment, threaded into every bound session's
      *  `state.manifest.environment` so the SDK's per-turn manifest-env delta is
      *  empty (validateNoEnvironmentDelta). See SelfhostedSessionDeps.environment.
@@ -739,6 +1129,11 @@ export class SelfhostedSandboxClient {
      *  cwd base; see SelfhostedSessionDeps.workingDir). Omitted/empty ⇒ the default
      *  workspace_root behavior. */
     workingDir?: string;
+    /** The per-op observer threaded into every bound session (out-of-band telemetry). */
+    onOp?: SelfhostedOpObserver;
+    /** The op-stream exec transport threaded into every bound session (present
+     *  = enabled; see SelfhostedOpStreamDeps). */
+    opStream?: SelfhostedOpStreamDeps;
   }) {
     this.workspaceId = opts.workspaceId;
     this.relay = opts.relay;
@@ -746,8 +1141,11 @@ export class SelfhostedSandboxClient {
     this.defaultAgentId = opts.agentId;
     this.epoch = opts.epoch;
     this.timeoutMs = opts.timeoutMs;
+    this.execTimeoutMs = opts.execTimeoutMs;
     this.environment = opts.environment;
     this.workingDir = opts.workingDir;
+    this.onOp = opts.onOp;
+    this.opStream = opts.opStream;
   }
 
   private controlRpc(): ControlRpc {
@@ -765,8 +1163,11 @@ export class SelfhostedSandboxClient {
       relay: this.relay,
       ...(this.epoch !== undefined ? { epoch: this.epoch } : {}),
       ...(this.timeoutMs !== undefined ? { timeoutMs: this.timeoutMs } : {}),
+      ...(this.execTimeoutMs !== undefined ? { execTimeoutMs: this.execTimeoutMs } : {}),
       ...(this.environment !== undefined ? { environment: this.environment } : {}),
       ...(this.workingDir !== undefined ? { workingDir: this.workingDir } : {}),
+      ...(this.onOp !== undefined ? { onOp: this.onOp } : {}),
+      ...(this.opStream !== undefined ? { opStream: this.opStream } : {}),
     });
   }
 
@@ -777,13 +1178,18 @@ export class SelfhostedSandboxClient {
   }
 
   /** Resume = re-address the subject. Identical to create — no provider state. */
-  async resume(state: SelfhostedSessionState | Record<string, unknown>, _options?: unknown): Promise<SelfhostedSession> {
+  async resume(
+    state: SelfhostedSessionState | Record<string, unknown>,
+    _options?: unknown,
+  ): Promise<SelfhostedSession> {
     const agentId = readAgentId(state) ?? this.requireAgentId();
     return this.bind(agentId);
   }
 
   /** Serialize a live session's state → `{agentId}` ONLY. */
-  async serializeSessionState(state: SelfhostedSessionState | { agentId?: string } | unknown): Promise<SelfhostedSessionState> {
+  async serializeSessionState(
+    state: SelfhostedSessionState | { agentId?: string } | unknown,
+  ): Promise<SelfhostedSessionState> {
     const agentId = readAgentId(state) ?? this.requireAgentId();
     return { agentId };
   }
@@ -802,7 +1208,9 @@ export class SelfhostedSandboxClient {
 
   private requireAgentId(): string {
     if (!this.defaultAgentId) {
-      throw new Error("selfhosted sandbox client: no agentId bound (create()/resume() need a session state carrying agentId)");
+      throw new Error(
+        "selfhosted sandbox client: no agentId bound (create()/resume() need a session state carrying agentId)",
+      );
     }
     return this.defaultAgentId;
   }
@@ -832,8 +1240,17 @@ export interface SelfhostedSessionBuild {
   environment?: Record<string, string>;
   /** The session working directory (the path/cwd base). Null/absent ⇒ workspace_root. */
   workingDir?: string | null;
-  /** Override the control-op timeout (tests). */
+  /** The control-op timeout (ping/fs/desktop/pty). Absent ⇒ the 30s default. */
   timeoutMs?: number;
+  /** The exec process deadline, distinct from `timeoutMs`. Absent ⇒ falls back to
+   *  `timeoutMs` (a real turn threads the long exec budget here). */
+  execTimeoutMs?: number;
+  /** The per-op observer (out-of-band telemetry). Absent ⇒ no-op. */
+  onOp?: SelfhostedOpObserver;
+  /** The op-stream exec transport (present = enabled for the session; the
+   *  worker injects it only when the runner advertised the capability AND the
+   *  server flag is on). Absent ⇒ the legacy exec, byte-identical to before. */
+  opStream?: SelfhostedOpStreamDeps;
 }
 
 /**
@@ -861,8 +1278,11 @@ export async function buildSelfhostedBackendSession(
     agentId: deps.agentId,
     epoch: deps.epoch,
     ...(deps.timeoutMs !== undefined ? { timeoutMs: deps.timeoutMs } : {}),
+    ...(deps.execTimeoutMs !== undefined ? { execTimeoutMs: deps.execTimeoutMs } : {}),
+    ...(deps.onOp !== undefined ? { onOp: deps.onOp } : {}),
     ...(deps.environment !== undefined ? { environment: deps.environment } : {}),
     ...(deps.workingDir ? { workingDir: deps.workingDir } : {}),
+    ...(deps.opStream !== undefined ? { opStream: deps.opStream } : {}),
   });
   const session = await client.resume({ agentId: deps.agentId });
   return { client, session };
@@ -870,8 +1290,9 @@ export async function buildSelfhostedBackendSession(
 
 function readAgentId(state: unknown): string | undefined {
   if (state && typeof state === "object") {
-    const candidate = (state as { agentId?: unknown }).agentId
-      ?? ((state as { providerState?: { agentId?: unknown } }).providerState?.agentId);
+    const candidate =
+      (state as { agentId?: unknown }).agentId ??
+      (state as { providerState?: { agentId?: unknown } }).providerState?.agentId;
     if (typeof candidate === "string" && candidate.length > 0) {
       return candidate;
     }
@@ -879,14 +1300,23 @@ function readAgentId(state: unknown): string | undefined {
   return undefined;
 }
 
-function execResultToChannelA(res: ExecResponse): SelfhostedExecResult {
+function execResultToChannelA(res: ExecResponse, execDeadlineMs: number): SelfhostedExecResult {
   const stdout = decoder.decode(res.stdout);
-  const stderr = decoder.decode(res.stderr);
+  let stderr = decoder.decode(res.stderr);
+  if (res.timedOut) {
+    // The agent killed the child at the exec deadline. Surface an actionable hint
+    // on STDERR ONLY — stdout is left byte-exact because the structural Channel-A
+    // surface parses command stdout (find/stat/git listings); a hint injected there
+    // would corrupt those parsers.
+    const hint = execDeadlineHint(Math.round(execDeadlineMs / 1000));
+    stderr = stderr ? `${stderr}\n${hint}` : hint;
+  }
   return {
     output: stdout,
     stdout,
     stderr,
     exitCode: res.exitCode,
+    timedOut: res.timedOut,
   };
 }
 
@@ -904,24 +1334,37 @@ function shellQuote(value: string): string {
  *  mirroring @openai/agents-core's `sniffImageMediaType` so `viewImage` returns the
  *  SAME media types the SDK would. Returns undefined for an unrecognized format. */
 function sniffImageMediaType(bytes: Uint8Array, path: string): string | undefined {
-  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+    return "image/png";
   if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
-  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) return "image/gif";
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38)
+    return "image/gif";
   if (
-    bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
-    bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50
-  ) return "image/webp";
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  )
+    return "image/webp";
   if (bytes[0] === 0x42 && bytes[1] === 0x4d) return "image/bmp";
   if (
     (bytes[0] === 0x49 && bytes[1] === 0x49 && bytes[2] === 0x2a && bytes[3] === 0x00) ||
     (bytes[0] === 0x4d && bytes[1] === 0x4d && bytes[2] === 0x00 && bytes[3] === 0x2a)
-  ) return "image/tiff";
+  )
+    return "image/tiff";
   if (looksLikeSvg(bytes)) return "image/svg+xml";
   return mediaTypeFromPath(path);
 }
 
 function looksLikeSvg(bytes: Uint8Array): boolean {
-  const prefix = decoder.decode(bytes.subarray(0, Math.min(bytes.byteLength, 512))).trimStart().toLowerCase();
+  const prefix = decoder
+    .decode(bytes.subarray(0, Math.min(bytes.byteLength, 512)))
+    .trimStart()
+    .toLowerCase();
   return prefix.startsWith("<svg") || /^<\?xml[\s\S]*<svg/u.test(prefix);
 }