@open-everywhere/adapters 0.1.0

package/agent/oe-oauth/user-auth-flow.ts

@@ -0,0 +1,76 @@
+// The own-rolled OAuth USER-AUTH-FLOW adapter — core's vendor-neutral port over our own client and token
+// vault. The callback completer shares ONE vault instance, so the single-flight lock covers both paths.
+
+import type { TokenResult } from "eve/connections";
+import type { UserAuthFlowProvider, UserAuthSubject, UserTokenMintParams, OeOauthCallbackCompleter, CredentialPurgeHook } from "@open-everywhere/core/agent/adapter-api.js";
+import type { OeOauthProviderConfig } from "./config.js";
+import { makeOeOauthTokenVault, type OeOauthVaultDeps, type OeOauthSubject } from "./token-vault.js";
+import { isUserAuthRequiredError } from "./errors.js";
+
+/** Normalise the port's UserAuthSubject into the vault's subject shape. */
+function toVaultSubject(subject: UserAuthSubject): OeOauthSubject {
+  return subject.type === "app" ? { type: "app" } : { type: "user", id: subject.id };
+}
+
+/** Build the own-rolled provider plus the callback completer, sharing one token vault. `deps` is the DI seam. */
+export function makeOeOauth(
+  providers: ReadonlyMap<string, OeOauthProviderConfig>,
+  deps: OeOauthVaultDeps = {},
+): { readonly flow: UserAuthFlowProvider; readonly completer: OeOauthCallbackCompleter; readonly purge: CredentialPurgeHook } {
+  const vault = makeOeOauthTokenVault(providers, deps);
+
+  const flow: UserAuthFlowProvider = {
+    async mintServiceToken(providerRef: string, _getTokenOptions: unknown): Promise<TokenResult> {
+      return { token: await vault.accessTokenFor(providerRef, { type: "app" }) };
+    },
+    async mintUserToken(providerRef: string, params: UserTokenMintParams): Promise<TokenResult> {
+      return { token: await vault.accessTokenFor(providerRef, { type: "user", id: params.subject.id }) };
+    },
+    async startAuthorization(providerRef, params, options): Promise<{ url: string }> {
+      // `consent` (OPE-1619) rides through UNREAD — it is core's opaque record of the request this
+      // detour interrupted, and the vault stores it beside the pending row and returns it at the
+      // callback. This adapter never inspects it.
+      return vault.startAuthorization(providerRef, toVaultSubject(params.subject), {
+        ...(options.expiresInMs ? { expiresInMs: options.expiresInMs } : {}),
+        ...(options.consent ? { consent: options.consent } : {}),
+      });
+    },
+    isUserAuthRequired(e: unknown): boolean {
+      return isUserAuthRequiredError(e);
+    },
+    async environmentClaim(): Promise<string> {
+      return "self";
+    },
+    async hasFreshGrant(providerRef: string, subject: UserAuthSubject): Promise<boolean> {
+      // (OPE-93) Existence check of the user's token vault row — the mid-turn self-heal signal (the real
+      // mint refreshes an expired token, so ROW EXISTENCE is what matters). Fail-soft: a vault-read
+      // failure reports `false`, never throws, so a probe error leaves the memo's short-circuit standing.
+      try {
+        return await vault.hasToken(providerRef, toVaultSubject(subject));
+      } catch {
+        return false;
+      }
+    },
+  };
+
+  const completer: OeOauthCallbackCompleter = async ({ state, code }) => {
+    try {
+      // `subject` and `rebound` ride out UNREAD by this adapter: core's callback route audits them as
+      // `connector.credential_bound` (OPE-1937). No token material is on this path, by construction.
+      const { providerRef, subject, rebound, consent } = await vault.completeAuthorization(state, code);
+      return { ok: true, connectionName: providerRef, subject, rebound, ...(consent ? { consent } : {}) };
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+  };
+
+  // The credential-purge hook, sharing the mint methods' vault: whatever this adapter can MINT for a subject it
+  // can also DESTROY. There is no app-subject purge — the service identity is not a person.
+  const purge: CredentialPurgeHook = {
+    async purgeSubject(subjectId: string): Promise<number> {
+      return vault.forgetAll({ type: "user", id: subjectId });
+    },
+  };
+
+  return { flow, completer, purge };
+}

package/agent/postgres/neon.ts

@@ -0,0 +1,108 @@
+// Neon (serverless Postgres) adapter — where the driver is constructed and handed to core's register seams,
+// so core stays vendor-SDK-free. LIVE-ONLY: it needs a real DATABASE_URL, and the driver imports dynamically.
+
+import {
+  registerPostgres,
+  registerOperationalPostgres,
+  initPostgresSchema,
+  type PgClient,
+  initOperationalSchema,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+/**
+ * Construct a Neon serverless client, initialise the schema, and register it as both the memory and the
+ * operational Postgres backend. Call once at startup, before the first session.
+ */
+export async function registerNeon(connectionString = process.env.DATABASE_URL): Promise<PgClient> {
+  if (!connectionString) {
+    throw new Error("registerNeon: no connection string (set DATABASE_URL)");
+  }
+  // 🔴 This specifier is DELIBERATELY statically analyzable: hosted functions ship no node_modules, so the
+  // driver must be inlined by static resolution. A dynamic form killed every prod request (2026-08-11).
+  const mod = (await import("@neondatabase/serverless")) as {
+    Pool: new (cfg: { connectionString: string }) => unknown;
+    neonConfig: NeonConfig;
+  };
+  // Local dev only: the serverless driver speaks WebSockets/HTTPS, not raw TCP, so a plain Postgres
+  // (the docker-compose postgres:16 sidecar) is reached through a `wsproxy` in front of it. OFF unless
+  // OE_NEON_WS_PROXY is set ⇒ the hosted Neon path is byte-identical. See docker-compose.yml.
+  configureLocalWsProxy(mod.neonConfig);
+  const { Pool } = mod;
+  const pool = new Pool({ connectionString }) as {
+    query(text: string, params?: readonly unknown[]): Promise<{ rows: unknown[] }>;
+    connect(): Promise<PooledConnection>;
+    on?(event: "error", listener: (err: unknown) => void): unknown;
+  };
+  attachPoolErrorHandler(pool);
+  const client: PgClient = {
+    query: (text, params) => pool.query(text, params),
+    // The connection-pinning seam (OPE-1636). The audit chain's append needs `BEGIN … COMMIT`
+    // plus a transaction-scoped advisory lock on ONE connection; without this the hosted
+    // runtime's separate functions fork the chain. Every exit path releases, so a throwing
+    // callback can never leak a connection out of the pool.
+    withConnection: async (fn) => {
+      const conn = await pool.connect();
+      try {
+        const result = await fn({ query: (text, params) => conn.query(text, params) });
+        conn.release();
+        return result;
+      } catch (err) {
+        // 🔴 `release(err)` DESTROYS the connection; a bare `release()` returns it to the pool
+        // whatever state it is in. A failed append can leave an open transaction holding the
+        // org's advisory lock, and that connection would then block every other appender for
+        // that org until it happened to be reused.
+        conn.release(err);
+        throw err;
+      }
+    },
+  };
+
+  await initPostgresSchema(client);
+  await initOperationalSchema(client);
+  registerPostgres(client);
+  registerOperationalPostgres(client);
+  return client;
+}
+
+/** One connection checked out of the pool: queries like the pool itself, plus the `release()`
+ *  that hands it back. */
+interface PooledConnection {
+  query(text: string, params?: readonly unknown[]): Promise<{ rows: unknown[] }>;
+  release(err?: unknown): void;
+}
+
+/** The subset of @neondatabase/serverless's `neonConfig` we touch for the local-wsproxy recipe.
+ *  `wsProxy` maps a target (host, port) to the proxy's `<host:port>/v1?address=…` URL. */
+interface NeonConfig {
+  wsProxy?: (host: string, port: number) => string;
+  useSecureWebSocket?: boolean;
+  pipelineTLS?: boolean;
+  pipelineConnect?: boolean | "password";
+  webSocketConstructor?: unknown;
+}
+
+/**
+ * Point the driver at a local `wsproxy` so it reaches a plain Postgres over the compose network. NO-OP unless
+ * OE_NEON_WS_PROXY is set. Insecure WS is correct for a same-network local proxy ONLY, never a remote one.
+ */
+export function configureLocalWsProxy(neonConfig: NeonConfig): void {
+  const proxy = process.env.OE_NEON_WS_PROXY?.trim();
+  if (!proxy) return;
+  neonConfig.wsProxy = (host, port) => `${proxy}/v1?address=${host}:${port}`;
+  neonConfig.useSecureWebSocket = false;
+  neonConfig.pipelineTLS = false;
+  neonConfig.pipelineConnect = false;
+  if (!neonConfig.webSocketConstructor && typeof (globalThis as { WebSocket?: unknown }).WebSocket !== "undefined") {
+    neonConfig.webSocketConstructor = (globalThis as { WebSocket: unknown }).WebSocket;
+  }
+}
+
+/**
+ * The Pool is a long-lived EventEmitter, and an idle connection's socket can error during teardown. With no
+ * 'error' listener Node kills the process, even after the request returned 200 — this listener is the fix.
+ */
+export function attachPoolErrorHandler(pool: { on?(event: "error", listener: (err: unknown) => void): unknown }): void {
+  pool.on?.("error", (err) => {
+    console.warn(`[open-everywhere:neon] pool error on an idle connection (ignored, no query affected): ${err instanceof Error ? err.message : String(err)}`);
+  });
+}

package/agent/sandbox/backend-stop.ts

@@ -0,0 +1,259 @@
+// WHO OWNS THE TURN-END SANDBOX STOP — one implementation per sandbox backend. Each is a ZERO-SIDE-EFFECT
+// peek first: eve's own `stop()` provisions, and a turn-end hook must never create a sandbox to stop one.
+
+import { Sandbox } from "@vercel/sandbox";
+import { execFile } from "node:child_process";
+import { onVercel, resolveSelfHostBackendKind } from "@open-everywhere/core/agent/adapter-api.js";
+import { getRecordedSandboxName } from "./created-sandbox-registry.js";
+
+/** One sandbox as its backend reports it — `createdAt` (epoch ms) is the one honestly-observable
+ *  timing reference (see vercel-lifecycle.ts's file-level comment on delta billing). */
+export interface SandboxListing {
+  readonly name: string;
+  readonly status: string;
+  readonly createdAt: number;
+}
+
+/**
+ * The backend-specific half of the turn-end stop. One implementation per sandbox backend OE can
+ * select; `resolveSandboxStopper()` picks the one matching the running deployment.
+ *
+ * Injected into `stopSessionSandboxes` so the decision logic is testable without credentials, a
+ * docker daemon, or a platform.
+ */
+export interface SandboxStopper {
+  /** Backend id, matching `OE_SANDBOX_BACKEND` / eve's backend name. For logs and tests. */
+  readonly backend: string;
+  /** Does this backend bill sandbox runtime by wall clock? Only then is a stop priced. */
+  readonly metered: boolean;
+  /** One line naming who owns the stop on this deployment, logged once per process. */
+  readonly ownership: string;
+  /** Sandboxes already tagged to this session. MUST NOT provision — an empty list is the
+   *  correct answer for a backend that cannot look without creating. */
+  list(sessionId: string): Promise<SandboxListing[]>;
+  /** Stop the compute, preserving whatever the backend needs to reopen the session. */
+  stop(name: string): Promise<void>;
+  /**
+   * Re-tag an existing sandbox onto `sessionId`. Returns `true` when the backend re-tagged, and
+   * `false` when this backend never re-tags on attach — in which case there is nothing to undo
+   * and the caller must not treat the `false` as a failure. See the OPE-447 note on the Vercel
+   * implementation for why this exists at all.
+   */
+  retag(name: string, sessionId: string): Promise<boolean>;
+}
+
+/** Only a booted (or booting) sandbox is worth stopping; stopped/snapshotting are already done.
+ *  Vercel's status vocabulary is the shared one — every other stopper normalises onto it. */
+export function shouldStop(status: string): boolean {
+  return status === "running" || status === "pending";
+}
+
+// ── Vercel ────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `Sandbox.list({tags})` is the zero-side-effect peek this hook depends on, and `resume: false` keeps a
+ * stopped sandbox stopped. RETAG: `update` REPLACES the tag map, so the restore merges and overrides one key.
+ */
+
+/**
+ * The raw Vercel SDK surface `createVercelList` needs — injectable so the OPE-722 augmentation
+ * below (falling back to a direct `Sandbox.get` for a name THIS process recorded opening) is
+ * unit-testable without live credentials. `defaultVercelListSdk` is the real `@vercel/sandbox`
+ * calls; tests inject a fake to prove the merge deterministically.
+ */
+export interface VercelListSdk {
+  /** The tag-index query. OPE-722 reported this returning empty immediately after
+   *  `Sandbox.create`, attributed to eventual consistency in the tag index; see the OPE-722
+   *  doc comment on `createVercelList` below for what a later re-probe actually found. */
+  listByTag(sessionId: string): Promise<SandboxListing[]>;
+  /** A primary-key lookup by name. `undefined` when the sandbox genuinely does not exist (or the
+   *  lookup failed) — the caller treats that exactly like "not found by the tag index either". */
+  getByName(name: string): Promise<SandboxListing | undefined>;
+}
+
+const defaultVercelListSdk: VercelListSdk = {
+  async listByTag(sessionId) {
+    const result = await Sandbox.list({ tags: { sessionId } });
+    const out: SandboxListing[] = [];
+    for await (const s of result) out.push({ name: s.name, status: s.status, createdAt: s.createdAt });
+    return out;
+  },
+  async getByName(name) {
+    try {
+      const s = await Sandbox.get({ name, resume: false });
+      // Sandbox.get()'s `.createdAt` is a Date; Sandbox.list()'s iterated items report a number
+      // (epoch ms) for the same field — normalise onto the number SandboxListing already uses.
+      return { name: s.name, status: s.status, createdAt: s.createdAt.getTime() };
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+/**
+ * Augment the tag-index result with a direct `Sandbox.get` for any name THIS process recorded this turn
+ * (created-sandbox-registry.ts) — a primary-key read, so the stop never depends on tag-index freshness.
+ */
+export function createVercelList(sdk: VercelListSdk = defaultVercelListSdk): SandboxStopper["list"] {
+  return async (sessionId) => {
+    const out = await sdk.listByTag(sessionId);
+    const recordedName = getRecordedSandboxName(sessionId);
+    if (recordedName !== undefined && !out.some((s) => s.name === recordedName)) {
+      const direct = await sdk.getByName(recordedName);
+      if (direct !== undefined) out.push(direct);
+    }
+    return out;
+  };
+}
+
+export const vercelStopper: SandboxStopper = {
+  backend: "vercel",
+  metered: true,
+  ownership:
+    "stop owner = vercel — @vercel/sandbox stops the session VM at turn end, and its runtime seconds are priced into the spend ledger",
+  list: createVercelList(),
+  async stop(name) {
+    await (await Sandbox.get({ name, resume: false })).stop();
+  },
+  async retag(name, sessionId) {
+    const sandbox = await Sandbox.get({ name, resume: false });
+    await sandbox.update({ tags: { ...(sandbox.tags ?? {}), sessionId } });
+    return true;
+  },
+};
+
+// ── docker ────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * eve labels every session container it CREATES with its diagnostic tags, prefixed
+ * `eve.sandbox.tag.` (its docker binding's `startDockerContainer`). That label is the only
+ * zero-side-effect handle on a running session container, so `docker ps` by label is the peek.
+ *
+ * The container is long-lived by construction: eve starts it with a `sleep 2147483647` keepalive
+ * and only ever stops it on `handle.stop()` or server shutdown. Without a turn-end stop a
+ * self-hosted box therefore accumulates one running container per conversation, indefinitely.
+ * `docker stop` (never `rm`) is the right verb: eve's `create` restarts a stopped container by
+ * name and the filesystem survives, which is the same stop/resume shape Vercel snapshots give.
+ */
+export const DOCKER_SESSION_LABEL = "eve.sandbox.tag.sessionId";
+
+/** The docker CLI as this module needs it. Injected in tests; the default shells out exactly as
+ *  eve does, honouring `EVE_DOCKER_PATH` so a Podman-shimmed deployment keeps working. */
+export interface DockerRunner {
+  (args: readonly string[]): Promise<string>;
+}
+
+const defaultDockerRunner: DockerRunner = async (args) =>
+  await new Promise<string>((resolve, reject) => {
+    const bin = process.env.EVE_DOCKER_PATH?.trim() || "docker";
+    execFile(bin, [...args], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+
+/** Docker's own state vocabulary, mapped onto the shared one `shouldStop` reads. Anything else
+ *  (exited, dead, removing, paused) passes through unchanged and is left alone. */
+export function dockerStatusToSandboxStatus(state: string): string {
+  if (state === "running") return "running";
+  if (state === "created" || state === "restarting") return "pending";
+  return state;
+}
+
+/** `docker inspect` reports `0001-01-01T00:00:00Z` for a container that never started. Anything
+ *  before this floor is not a real start time — report "now" so the window is 0, never a
+ *  two-thousand-year one. */
+const DOCKER_START_TIME_FLOOR_MS = Date.UTC(2000, 0, 1);
+
+export function createDockerStopper(run: DockerRunner = defaultDockerRunner): SandboxStopper {
+  return {
+    backend: "docker",
+    metered: false,
+    ownership:
+      "stop owner = docker — eve's session containers are stopped through the docker CLI at turn end. Runtime is NOT metered per second on this backend, so no spend-ledger row is written for it",
+    async list(sessionId) {
+      const names = (await run(["ps", "-a", "--no-trunc", "--filter", `label=${DOCKER_SESSION_LABEL}=${sessionId}`, "--format", "{{.Names}}"]))
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+      if (names.length === 0) return [];
+      // One inspect for all of them; `{{.Name}}` carries a leading slash, so the name is read back
+      // rather than zipped by position. `docker inspect` FAILS THE WHOLE CALL if any one name has
+      // gone away since the peek, so a vanished container must not blind the sweep to its
+      // siblings: fall back to treating every listed name as running now. `docker stop` on a name
+      // that no longer exists then fails soft, per sandbox, in stopSessionSandboxes.
+      let inspected: string;
+      try {
+        inspected = await run(["inspect", "--format", "{{.Name}}\t{{.State.Status}}\t{{.State.StartedAt}}", ...names]);
+      } catch {
+        const now = Date.now();
+        return names.map((name) => ({ name, status: "running", createdAt: now }));
+      }
+      const out: SandboxListing[] = [];
+      for (const line of inspected.split("\n")) {
+        const [rawName, state, startedAt] = line.trim().split("\t");
+        if (rawName === undefined || state === undefined) continue;
+        const name = rawName.replace(/^\//, "");
+        if (name.length === 0) continue;
+        const parsed = startedAt === undefined ? Number.NaN : Date.parse(startedAt);
+        const createdAt = Number.isFinite(parsed) && parsed >= DOCKER_START_TIME_FLOOR_MS ? parsed : Date.now();
+        out.push({ name, status: dockerStatusToSandboxStatus(state), createdAt });
+      }
+      return out;
+    },
+    async stop(name) {
+      await run(["stop", "-t", "0", name]);
+    },
+    async retag() {
+      // eve's docker binding applies labels ONLY on `docker run`, i.e. when it creates the
+      // container. A reattach (`container inspect` then `docker start`) never re-labels, and a
+      // running container's labels are immutable anyway. So the OPE-447 re-tag hazard does not
+      // exist on this backend and there is nothing to hand back.
+      return false;
+    },
+  };
+}
+
+// ── just-bash ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The just-bash backend is an in-process interpreter — no VM, no container, no metered runtime — so this
+ * stopper is deliberately inert. It names itself in the log rather than swallowing an error.
+ */
+export const justBashStopper: SandboxStopper = {
+  backend: "just-bash",
+  metered: false,
+  ownership:
+    "stop owner = NONE — the just-bash backend runs inside this app process. There is no VM or container to stop and no metered runtime, so the turn-end sweep is inert by design. Set OE_SANDBOX_BACKEND=docker for a backend whose compute is stopped at turn end",
+  async list() {
+    return [];
+  },
+  async stop() {
+    // Unreachable: list() never yields a name.
+  },
+  async retag() {
+    return false;
+  },
+};
+
+// ── selection ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The ONE "who stops the sandbox on this deployment" decision. It reads the SAME two switches the
+ * app reads to BUILD the backend — `onVercel()` and `resolveSelfHostBackendKind()` — so the
+ * backend that runs and the backend that stops can never disagree. An unknown
+ * `OE_SANDBOX_BACKEND` throws here exactly as it throws at boot; the hook's fail-soft catch logs
+ * it rather than failing the turn.
+ */
+export function resolveSandboxStopper(): SandboxStopper {
+  if (forcedStopper !== undefined) return forcedStopper;
+  if (onVercel()) return vercelStopper;
+  return resolveSelfHostBackendKind() === "justbash" ? justBashStopper : createDockerStopper();
+}
+
+/** Test seam: force the resolved stopper so the hook's own branching can be driven without a
+ *  platform, credentials or a docker daemon. Pass `undefined` to restore real selection. */
+let forcedStopper: SandboxStopper | undefined;
+export function setSandboxStopperForTest(stopper: SandboxStopper | undefined): void {
+  forcedStopper = stopper;
+}

package/agent/sandbox/created-sandbox-registry.ts

@@ -0,0 +1,27 @@
+// Record the sandbox name THIS process opened, so the stop hook can reach it with a primary-key
+// `Sandbox.get` instead of the tag index. It NARROWS the create-then-stop race, and never replaces `list()`.
+const recordedSandboxNames = new Map<string, string>();
+
+/**
+ * Record the vendor sandbox name eve just opened for `sessionId`, in THIS process. Called from
+ * `agent/sandbox/sandbox.ts`'s `onSession` hook. Never throws — a caller that races this against
+ * a torn-down process loses nothing beyond falling back to the pre-fix `Sandbox.list` behaviour.
+ */
+export function recordCreatedSandbox(sessionId: string, name: string): void {
+  if (sessionId.length === 0 || name.length === 0) return;
+  recordedSandboxNames.set(sessionId, name);
+}
+
+/**
+ * The vendor sandbox name recorded for `sessionId` in THIS process, if any. `undefined` means
+ * either no sandbox was opened here this invocation, or it was opened by a different process —
+ * both cases fall back to the vendor's tag index, exactly as before this fix.
+ */
+export function getRecordedSandboxName(sessionId: string): string | undefined {
+  return recordedSandboxNames.get(sessionId);
+}
+
+/** Test seam: reset between assertions so one test's recording can't leak into the next. */
+export function clearRecordedSandboxesForTest(): void {
+  recordedSandboxNames.clear();
+}

package/agent/sandbox/extend-workspace-time.ts

@@ -0,0 +1,77 @@
+// `extend_workspace_time` — lengthen the sandbox session's FIXED fuse before a long command. It extends
+// BLIND (no remaining-time reading exists), is capped and audited, and plan ceilings still apply upstream.
+
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { Sandbox } from "@vercel/sandbox";
+import { auditToolAction, getSettings } from "@open-everywhere/core/agent/adapter-api.js";
+import { shouldStop } from "./vercel-lifecycle.js";
+import { vercelStopper } from "./backend-stop.js";
+
+/** Per-call cap on the extension, in minutes — the `sandbox.extendMaxMinutes` setting
+ *  (OPE-371), with `sandbox.extendMaxMinutes` as its declared ops override. */
+export function maxExtendMinutes(): number {
+  return getSettings().sandbox.extendMaxMinutes;
+}
+
+/** Injected SDK surface, so the logic is testable without Vercel credentials. */
+export interface ExtendDeps {
+  list(sessionId: string): Promise<Array<{ name: string; status: string }>>;
+  extend(name: string, ms: number): Promise<void>;
+}
+
+// The list is `vercelStopper.list` — the same tag-index-plus-id-record lookup the stop hook uses — rather
+// than a second, independent `Sandbox.list({tags})` call.
+const sdkDeps: ExtendDeps = {
+  list: vercelStopper.list,
+  async extend(name, ms) {
+    await (await Sandbox.get({ name })).extendTimeout(ms);
+  },
+};
+
+/**
+ * Extend every RUNNING sandbox tagged with this session by `minutes` (clamped to the
+ * cap). A stopped/absent sandbox needs no extension — its next boot gets a full fresh
+ * window — so that case reports rather than errors.
+ */
+export async function extendSessionSandboxes(
+  sessionId: string,
+  minutes: number,
+  deps: ExtendDeps = sdkDeps,
+): Promise<{ extended: string[]; clampedTo: number }> {
+  const clampedTo = Math.min(Math.max(1, Math.floor(minutes)), maxExtendMinutes());
+  const extended: string[] = [];
+  for (const s of await deps.list(sessionId)) {
+    if (!shouldStop(s.status)) continue; // same "is the VM up" predicate as the stop hook
+    await deps.extend(s.name, clampedTo * 60_000);
+    extended.push(s.name);
+  }
+  return { extended, clampedTo };
+}
+
+export default defineTool({
+  description:
+    "Extend your workspace VM's lifetime by N minutes. Call this BEFORE starting a long-running command " +
+    "(a big install, build, or a test run you expect to take more than ~10 minutes): the workspace has a " +
+    "fixed time window and a command still running when it expires is killed. There is no visible countdown, " +
+    "so extend by roughly the time the upcoming work needs. If no VM is currently running, nothing needs " +
+    "extending — your next command boots a fresh one with a full window.",
+  inputSchema: z.object({
+    minutes: z.number().int().min(1).describe("How many extra minutes the upcoming work needs."),
+    reason: z.string().optional().describe("What the time is for (goes to the audit log)."),
+  }),
+  async execute(input, ctx) {
+    const { extended, clampedTo } = await extendSessionSandboxes(ctx.session.id, input.minutes);
+    await auditToolAction(ctx, "sandbox.extend", {
+      minutes: clampedTo,
+      requested: input.minutes,
+      extended,
+      ...(input.reason ? { reason: input.reason } : {}),
+    });
+    if (extended.length === 0) {
+      return "No workspace VM is currently running — nothing to extend. Your next command boots a fresh session with a full time window, so just proceed.";
+    }
+    const clampNote = clampedTo !== input.minutes ? ` (requested ${input.minutes}, capped at ${clampedTo} by sandbox.extendMaxMinutes)` : "";
+    return `Extended the workspace lifetime by ${clampedTo} minutes${clampNote}. Start the long-running work now.`;
+  },
+});