@opengeni/api-router 0.5.3 → 0.5.5

package/src/routes/social.ts

@@ -1,7 +1,4 @@
-import {
-  CreateSocialConnectionRequest,
-  CreateSocialPostRequest,
-} from "@opengeni/contracts";
+import { CreateSocialConnectionRequest, CreateSocialPostRequest } from "@opengeni/contracts";
 import {
   createSocialConnection,
   createSocialPost,
@@ -29,19 +26,22 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const payload = CreateSocialConnectionRequest.parse(await c.req.json());
     try {
-      return c.json(await createSocialConnection(db, {
-        accountId: grant.accountId,
-        workspaceId,
-        provider: payload.provider,
-        accountHandle: payload.accountHandle,
-        accountName: payload.accountName ?? null,
-        externalAccountId: payload.externalAccountId ?? null,
-        status: payload.status,
-        scopes: payload.scopes,
-        credentialRef: payload.credentialRef ?? null,
-        tokenMetadata: payload.tokenMetadata,
-        metadata: payload.metadata,
-      }), 201);
+      return c.json(
+        await createSocialConnection(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          provider: payload.provider,
+          accountHandle: payload.accountHandle,
+          accountName: payload.accountName ?? null,
+          externalAccountId: payload.externalAccountId ?? null,
+          status: payload.status,
+          scopes: payload.scopes,
+          credentialRef: payload.credentialRef ?? null,
+          tokenMetadata: payload.tokenMetadata,
+          metadata: payload.metadata,
+        }),
+        201,
+      );
     } catch (error) {
       throw socialHttpException(error);
     }
@@ -51,13 +51,17 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
     const since = parseSince(c.req.query("since"));
-    const connectionIds = parseConnectionIds(c.req.query("connectionIds") ?? c.req.query("connectionId"));
-    return c.json(await listSocialPosts(db, {
-      workspaceId,
-      ...(connectionIds?.length ? { connectionIds } : {}),
-      ...(since ? { since } : {}),
-      limit: boundedLimit(c.req.query("limit")),
-    }));
+    const connectionIds = parseConnectionIds(
+      c.req.query("connectionIds") ?? c.req.query("connectionId"),
+    );
+    return c.json(
+      await listSocialPosts(db, {
+        workspaceId,
+        ...(connectionIds?.length ? { connectionIds } : {}),
+        ...(since ? { since } : {}),
+        limit: boundedLimit(c.req.query("limit")),
+      }),
+    );
   });
 
   app.post("/v1/workspaces/:workspaceId/social/posts", async (c) => {
@@ -65,18 +69,21 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const payload = CreateSocialPostRequest.parse(await c.req.json());
     try {
-      return c.json(await createSocialPost(db, {
-        accountId: grant.accountId,
-        workspaceId,
-        connectionId: payload.connectionId,
-        externalPostId: payload.externalPostId ?? null,
-        url: payload.url ?? null,
-        authorHandle: payload.authorHandle ?? null,
-        text: payload.text,
-        publishedAt: new Date(payload.publishedAt),
-        metrics: payload.metrics,
-        raw: payload.raw,
-      }), 201);
+      return c.json(
+        await createSocialPost(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          connectionId: payload.connectionId,
+          externalPostId: payload.externalPostId ?? null,
+          url: payload.url ?? null,
+          authorHandle: payload.authorHandle ?? null,
+          text: payload.text,
+          publishedAt: new Date(payload.publishedAt),
+          metrics: payload.metrics,
+          raw: payload.raw,
+        }),
+        201,
+      );
     } catch (error) {
       throw socialHttpException(error);
     }
@@ -98,10 +105,15 @@ function parseConnectionIds(raw: string | undefined): string[] | undefined {
   if (!raw) {
     return undefined;
   }
-  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+  const values = raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
   const parsed = z.array(z.string().uuid()).safeParse(values);
   if (!parsed.success) {
-    throw new HTTPException(422, { message: "connectionIds must be a comma-separated list of UUIDs" });
+    throw new HTTPException(422, {
+      message: "connectionIds must be a comma-separated list of UUIDs",
+    });
   }
   const ids = parsed.data;
   return [...new Set(ids)];

package/src/routes/workspace-capture.ts

@@ -0,0 +1,238 @@
+// Workbench v2 — capture READ serving (dossier §10.3).
+//
+// The two GET capture routes in `sessions.ts` are thin: grant-first (files:read),
+// load the row (DB, RLS-scoped), then delegate the response SHAPING to the two
+// pure functions here. Keeping the shaping decoupled from Hono + the DB lets the
+// hermetic route tests exercise every branch ({available:false}, inline-vs-signed
+// manifest, file resolve/marker/404) with in-memory fakes — no live stack.
+//
+// These functions NEVER touch a live sandbox box: a capture is served entirely
+// from the durable `workspace_captures` row + its object-storage blobs. That is
+// the whole point — the <200ms cold paint must not depend on a warm machine.
+
+import {
+  GetWorkspaceCaptureFileResponse,
+  GetWorkspaceCaptureResponse,
+  WorkspaceCaptureDegradedReason,
+  WorkspaceCaptureManifest,
+  WorkspaceCaptureStats,
+} from "@opengeni/contracts";
+import type { WorkspaceCaptureRow } from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+// Serve the manifest inline below this size (the overwhelmingly common case —
+// the one API round-trip requirement); above it, a signed GET URL to the blob.
+export const CAPTURE_INLINE_MANIFEST_MAX_BYTES = 2 * 1024 * 1024;
+// Serve a single after-image inline below this size; above it, a signed GET URL.
+export const CAPTURE_INLINE_FILE_MAX_BYTES = 256 * 1024;
+// Short-lived — the client fetches immediately after the metadata response.
+export const CAPTURE_SIGNED_URL_TTL_SECONDS = 300;
+
+// The slice of ObjectStorage the serving path needs. Structural so the tests can
+// inject an in-memory map without standing up S3/minio.
+export type CaptureStoragePort = {
+  getObjectBytes: (key: string) => Promise<{ bytes: Uint8Array } | null>;
+  createGetUrl: (args: {
+    key: string;
+    expiresInSeconds?: number;
+  }) => Promise<{ url: string; expiresAt: Date }>;
+};
+
+function signedUrl(signed: { url: string; expiresAt: Date }): { url: string; expiresAt: string } {
+  return { url: signed.url, expiresAt: signed.expiresAt.toISOString() };
+}
+
+// Fetch + validate the manifest blob for a row. Returns null when the row has no
+// manifest key, the blob is gone (GC'd), or the bytes fail to parse/validate — a
+// malformed capture is treated as "no capture available" (the list route degrades
+// to {available:false}, the file route to 404). Capture reads must NEVER be worse
+// than the status-quo live/wake fallback (dossier §10.10), so a poison row can
+// never 500 the workbench; it degrades and logs.
+async function loadManifest(
+  row: WorkspaceCaptureRow,
+  storage: CaptureStoragePort,
+): Promise<{ manifest: WorkspaceCaptureManifest; byteLength: number } | null> {
+  if (!row.manifestKey) return null;
+  const blob = await storage.getObjectBytes(row.manifestKey);
+  if (!blob) return null;
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(blob.bytes));
+  } catch {
+    console.warn(
+      `workspace capture read — manifest blob is not valid JSON (session=${row.sessionId} rev=${row.revision})`,
+    );
+    return null;
+  }
+  const parsed = WorkspaceCaptureManifest.safeParse(json);
+  if (!parsed.success) {
+    console.warn(
+      `workspace capture read — manifest failed schema validation (session=${row.sessionId} rev=${row.revision})`,
+    );
+    return null;
+  }
+  return { manifest: parsed.data, byteLength: blob.bytes.byteLength };
+}
+
+/**
+ * Shape the GET …/workspace/capture response from a loaded row. `{available:false}`
+ * when there is no capture yet, the row is not in the `available` state, or its
+ * manifest blob has been GC'd (all graceful cold-fallback states — never errors).
+ * Inline manifest for ≤2MB, signed URL above.
+ */
+export async function serveWorkspaceCapture(
+  row: WorkspaceCaptureRow | null,
+  storage: CaptureStoragePort,
+): Promise<GetWorkspaceCaptureResponse> {
+  if (!row) {
+    return { available: false };
+  }
+  if (row.state === "failed") {
+    const reason = WorkspaceCaptureDegradedReason.safeParse(row.stats.degradedReason);
+    if (!reason.success) {
+      // `failed` was reserved before repository-discovery markers existed. Do
+      // not invent a cause for an older or malformed row; plain unavailable is
+      // the only truthful backwards-compatible response.
+      return { available: false };
+    }
+    return GetWorkspaceCaptureResponse.parse({
+      available: false,
+      degradedReason: reason.data,
+      revision: row.revision,
+      capturedAt: row.capturedAt,
+      turnId: row.turnId,
+      leaseEpoch: row.leaseEpoch,
+    });
+  }
+  if (row.state !== "available" || !row.manifestKey) return { available: false };
+  const stats = WorkspaceCaptureStats.safeParse(row.stats);
+  if (!stats.success) {
+    // A row with malformed stats (or a synthetic/partial row) degrades to the
+    // cold-fallback state rather than 500.
+    console.warn(
+      `workspace capture read — row stats failed schema validation (session=${row.sessionId} rev=${row.revision})`,
+    );
+    return { available: false };
+  }
+  const meta = {
+    available: true as const,
+    revision: row.revision,
+    capturedAt: row.capturedAt,
+    turnId: row.turnId,
+    leaseEpoch: row.leaseEpoch,
+    sizeBytes: row.sizeBytes ?? 0,
+    stats: stats.data,
+  };
+  const blob = await storage.getObjectBytes(row.manifestKey);
+  if (!blob) {
+    // Manifest raced GC between the row read and the blob fetch — degrade to the
+    // cold-fallback state rather than 500.
+    return { available: false };
+  }
+  if (blob.bytes.byteLength <= CAPTURE_INLINE_MANIFEST_MAX_BYTES) {
+    let json: unknown;
+    try {
+      json = JSON.parse(new TextDecoder().decode(blob.bytes));
+    } catch {
+      console.warn(
+        `workspace capture read — manifest blob is not valid JSON (session=${row.sessionId} rev=${row.revision})`,
+      );
+      return { available: false };
+    }
+    const manifest = WorkspaceCaptureManifest.safeParse(json);
+    if (!manifest.success) {
+      console.warn(
+        `workspace capture read — manifest failed schema validation (session=${row.sessionId} rev=${row.revision})`,
+      );
+      return { available: false };
+    }
+    return GetWorkspaceCaptureResponse.parse({
+      ...meta,
+      manifest: manifest.data,
+      manifestUrl: null,
+    });
+  }
+  const signed = await storage.createGetUrl({
+    key: row.manifestKey,
+    expiresInSeconds: CAPTURE_SIGNED_URL_TTL_SECONDS,
+  });
+  return GetWorkspaceCaptureResponse.parse({
+    ...meta,
+    manifest: null,
+    manifestUrl: signedUrl(signed),
+  });
+}
+
+/**
+ * Shape the GET …/workspace/capture/file response from a loaded row (the row
+ * already resolved to the requested revision, or the latest). Throws
+ * HTTPException(404) when there is no capture, the path is not in the manifest,
+ * or the file was deleted. Returns a metadata-only marker for a tooLarge file (or
+ * a captured file whose after-image blob is missing). Inline content for ≤256KB,
+ * signed URL above.
+ */
+export async function serveWorkspaceCaptureFile(
+  row: WorkspaceCaptureRow | null,
+  path: string,
+  storage: CaptureStoragePort,
+): Promise<GetWorkspaceCaptureFileResponse> {
+  const loaded = row ? await loadManifest(row, storage) : null;
+  if (!loaded) {
+    throw new HTTPException(404, { message: "capture not found" });
+  }
+  const { manifest } = loaded;
+  const file = manifest.files.find((f) => f.path === path);
+  if (!file) {
+    throw new HTTPException(404, { message: "path not in capture" });
+  }
+  if (file.deleted) {
+    // Parity with fs/read on a deleted path.
+    throw new HTTPException(404, { message: "file was deleted" });
+  }
+  const base = {
+    path: file.path,
+    revision: manifest.revision,
+    status: file.status,
+    hash: file.hash,
+    baseHash: file.baseHash,
+    sizeBytes: file.sizeBytes,
+    isBinary: file.isBinary,
+    tooLarge: file.tooLarge,
+  };
+  if (file.tooLarge || !file.contentRef) {
+    // Marker: content was not captured (guard tripped) or the blob is unavailable.
+    return GetWorkspaceCaptureFileResponse.parse({
+      ...base,
+      encoding: null,
+      content: null,
+      contentUrl: null,
+    });
+  }
+  if (file.sizeBytes <= CAPTURE_INLINE_FILE_MAX_BYTES) {
+    const blob = await storage.getObjectBytes(file.contentRef);
+    if (!blob) {
+      // After-image GC'd out from under us → return the marker (client opens live).
+      return GetWorkspaceCaptureFileResponse.parse({
+        ...base,
+        encoding: null,
+        content: null,
+        contentUrl: null,
+      });
+    }
+    const encoding = file.isBinary ? "base64" : "utf8";
+    const content = file.isBinary
+      ? Buffer.from(blob.bytes).toString("base64")
+      : new TextDecoder().decode(blob.bytes);
+    return GetWorkspaceCaptureFileResponse.parse({ ...base, encoding, content, contentUrl: null });
+  }
+  const signed = await storage.createGetUrl({
+    key: file.contentRef,
+    expiresInSeconds: CAPTURE_SIGNED_URL_TTL_SECONDS,
+  });
+  return GetWorkspaceCaptureFileResponse.parse({
+    ...base,
+    encoding: null,
+    content: null,
+    contentUrl: signedUrl(signed),
+  });
+}

package/src/routes/workspaces.ts

@@ -2,8 +2,12 @@ import {
   AddWorkspaceMemberRequest,
   CreateWorkspaceRequest,
   ListWorkspaceMembersResponse,
+  SetWorkspaceDefaultRigRequest,
   UpdateWorkspaceMemberRequest,
+  UpdateWorkspaceModelPolicyRequest,
   UpdateWorkspaceRequest,
+  UpdateWorkspaceSettingsRequest,
+  WorkspaceInferenceControlRequest,
   Workspace,
   WorkspaceMember,
   type AccessContext,
@@ -16,20 +20,33 @@ import {
   createWorkspace,
   deleteWorkspace,
   getManagedUserByEmail,
+  getWorkspaceModelPolicy,
   grantWorkspaceAccess,
   listScheduledTasks,
   listWorkspaceMembers,
+  listWorkspaceControlEvents,
   listWorkspacesForSubject,
   removeWorkspaceMember,
   requireWorkspace,
+  getRig,
+  setWorkspaceDefaultRig,
   updateWorkspace,
+  updateWorkspaceSettings,
+  upsertWorkspaceModelPolicy,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { hasPermission, requireAccessContext, requireAccessGrant } from "@opengeni/core";
 import { requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { assertWorkspaceDeletable, assertWorkspaceMemberRemovable, resolveMemberSubjectId } from "@opengeni/core";
+import {
+  assertWorkspaceDeletable,
+  assertWorkspaceMemberRemovable,
+  controlHumanWorkspace,
+  resolveMemberSubjectId,
+} from "@opengeni/core";
+import { boundedLimit } from "../http/common";
+import { sseWorkspaceControlStream } from "../http/sse";
 
 export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/access/me", async (c) => {
@@ -38,14 +55,24 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces", async (c) => {
     const context = await requireAccessContext(c, deps);
-    const readableWorkspaceIds = [...new Set(context.workspaceGrants
-      .filter((grant) => hasPermission(grant.permissions, "workspace:read"))
-      .map((grant) => grant.workspaceId))];
+    const readableWorkspaceIds = [
+      ...new Set(
+        context.workspaceGrants
+          .filter((grant) => hasPermission(grant.permissions, "workspace:read"))
+          .map((grant) => grant.workspaceId),
+      ),
+    ];
     if (readableWorkspaceIds.length > 0) {
-      const workspaces = await Promise.all(readableWorkspaceIds.map((workspaceId) => requireWorkspace(deps.db, workspaceId)));
+      const workspaces = await Promise.all(
+        readableWorkspaceIds.map((workspaceId) => requireWorkspace(deps.db, workspaceId)),
+      );
       return c.json(workspaces.map((workspace) => Workspace.parse(workspace)));
     }
-    return c.json((await listWorkspacesForSubject(deps.db, context.subjectId)).map((workspace) => Workspace.parse(workspace)));
+    return c.json(
+      (await listWorkspacesForSubject(deps.db, context.subjectId)).map((workspace) =>
+        Workspace.parse(workspace),
+      ),
+    );
   });
 
   app.post("/v1/workspaces", async (c) => {
@@ -63,7 +90,9 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
       slug: payload.slug?.trim() || null,
       externalSource: payload.externalSource ?? null,
       externalId: payload.externalId ?? null,
-      ...(payload.agentInstructions !== undefined ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) } : {}),
+      ...(payload.agentInstructions !== undefined
+        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
+        : {}),
     });
     await grantWorkspaceAccess(deps.db, {
       accountId,
@@ -89,8 +118,101 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspace = await updateWorkspace(deps.db, workspaceId, {
       ...(payload.name !== undefined ? { name: payload.name.trim() } : {}),
       ...(payload.slug !== undefined ? { slug: payload.slug?.trim() || null } : {}),
-      ...(payload.agentInstructions !== undefined ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) } : {}),
+      ...(payload.agentInstructions !== undefined
+        ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) }
+        : {}),
+    });
+    return c.json(Workspace.parse(workspace));
+  });
+
+  // Read is via GET /v1/workspaces/:workspaceId (Workspace.settings). This PATCH
+  // deep-merges (top-level) a settings patch, preserving unknown/future keys.
+  app.patch("/v1/workspaces/:workspaceId/settings", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const parsed = UpdateWorkspaceSettingsRequest.safeParse(await c.req.json());
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid workspace settings patch" });
+    }
+    const workspace = await updateWorkspaceSettings(deps.db, workspaceId, parsed.data);
+    return c.json(Workspace.parse(workspace));
+  });
+
+  // Per-workspace model/provider availability policy (the HARD blocker over
+  // which providers/models may serve a turn at all). Absent row reads as
+  // unrestricted {null, null}.
+  app.get("/v1/workspaces/:workspaceId/model-policy", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const policy = await getWorkspaceModelPolicy(deps.db, workspaceId);
+    return c.json({
+      allowedProviders: policy?.allowedProviders ?? null,
+      allowedModels: policy?.allowedModels ?? null,
+    });
+  });
+
+  // Full replace (PUT, not merge): null/omitted = unrestricted for that
+  // dimension; an empty array is a valid explicit total block. Admin access —
+  // this decides whether turns can reach paid providers, so it is the same
+  // trust level as billing-affecting workspace settings.
+  app.put("/v1/workspaces/:workspaceId/model-policy", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = UpdateWorkspaceModelPolicyRequest.parse(await c.req.json());
+    const policy = await upsertWorkspaceModelPolicy(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      allowedProviders: payload.allowedProviders ?? null,
+      allowedModels: payload.allowedModels ?? null,
     });
+    return c.json(policy);
+  });
+
+  app.post("/v1/workspaces/:workspaceId/inference-control", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = WorkspaceInferenceControlRequest.parse(await c.req.json());
+    return c.json(
+      await controlHumanWorkspace(
+        { db: deps.db, bus: deps.bus, workflowClient: deps.workflowClient },
+        { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+        payload,
+      ),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/control-events", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const after = Math.max(0, Number.parseInt(c.req.query("after") ?? "0", 10) || 0);
+    return c.json(
+      await listWorkspaceControlEvents(
+        deps.db,
+        workspaceId,
+        after,
+        boundedLimit(c.req.query("limit")),
+      ),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/control-events/stream", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const after = Math.max(0, Number.parseInt(c.req.query("after") ?? "0", 10) || 0);
+    return await sseWorkspaceControlStream(deps.db, deps.bus, workspaceId, after, c.req.raw.signal);
+  });
+
+  app.put("/v1/workspaces/:workspaceId/default-rig", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "rigs:manage");
+    const payload = SetWorkspaceDefaultRigRequest.parse(await c.req.json());
+    if (payload.rigId) {
+      const rig = await getRig(deps.db, workspaceId, payload.rigId);
+      if (!rig) {
+        throw new HTTPException(422, { message: `unknown rigId: ${payload.rigId}` });
+      }
+    }
+    const workspace = await setWorkspaceDefaultRig(deps.db, workspaceId, payload.rigId);
     return c.json(Workspace.parse(workspace));
   });
 
@@ -109,9 +231,13 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     // Clean external Temporal state the FK cascade can't reach: every scheduled
     // task's schedule (best-effort, mirroring the scheduled-task delete path).
     const tasks = await listScheduledTasks(deps.db, workspaceId, 1000);
-    await Promise.all(tasks.map((task) =>
-      deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId: task.temporalScheduleId }).catch(() => undefined),
-    ));
+    await Promise.all(
+      tasks.map((task) =>
+        deps.workflowClient
+          .deleteScheduledTaskSchedule({ temporalScheduleId: task.temporalScheduleId })
+          .catch(() => undefined),
+      ),
+    );
     await deleteWorkspace(deps.db, workspaceId);
     return c.body(null, 204);
   });
@@ -198,9 +324,16 @@ function normalizeAgentInstructions(value: string | null): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-function requireAccountPermission(context: AccessContext, accountId: string, permission: Permission): void {
+function requireAccountPermission(
+  context: AccessContext,
+  accountId: string,
+  permission: Permission,
+): void {
   const grant = context.accountGrants.find((candidate) => candidate.accountId === accountId);
-  if (!grant || (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))) {
+  if (
+    !grant ||
+    (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))
+  ) {
     throw new HTTPException(403, { message: `missing permission: ${permission}` });
   }
 }

package/src/sandbox/access.ts

@@ -34,7 +34,10 @@ import type {
 } from "@opengeni/core";
 
 export class SandboxResumeError extends Error {
-  constructor(message: string, readonly cause?: unknown) {
+  constructor(
+    message: string,
+    readonly cause?: unknown,
+  ) {
     super(message);
     this.name = "SandboxResumeError";
   }
@@ -57,7 +60,9 @@ export function createApiSandboxClient(settings: Settings): ApiSandboxClient | u
  * a live session for one in-process op. The caller drives exec/readFile and then
  * drops the handle (resume → use → drop); it does NOT own the box.
  */
-export function makeResumeBoxById(client: ApiSandboxClient | undefined): (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession> {
+export function makeResumeBoxById(
+  client: ApiSandboxClient | undefined,
+): (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession> {
   return async ({ backend, resumeState }: ResumeBoxByIdInput): Promise<ResumedSandboxSession> => {
     if (!client) {
       throw new SandboxResumeError(
@@ -77,7 +82,10 @@ export function makeResumeBoxById(client: ApiSandboxClient | undefined): (input:
     let session: ApiSandboxSession;
     try {
       const state = await client.deserializeSessionState(resumeState);
-      session = await client.resume(state);
+      // API-direct access borrows the live box. The lease remains its sole
+      // lifecycle owner, even when the serialized founding handle was owned.
+      // Clone instead of mutating the canonical resume envelope.
+      session = await client.resume({ ...state, ownsSandbox: false });
     } catch (error) {
       throw new SandboxResumeError(
         `Failed to resume sandbox box by id on backend "${backend}": ${error instanceof Error ? error.message : String(error)}`,

package/src/sandbox/auth-callout.ts

@@ -28,7 +28,11 @@
 // on its callout timeout). The bearer's `exp` caps the minted credential's life so a
 // revoked/expired enrollment cannot outlive its bearer.
 
-import { resolveEnrollmentSigningSecret, type NatsCalloutConfig, type Settings } from "@opengeni/config";
+import {
+  resolveEnrollmentSigningSecret,
+  type NatsCalloutConfig,
+  type Settings,
+} from "@opengeni/config";
 import { verifyEnrollmentBearer } from "@opengeni/contracts";
 import { getEnrollment, type Database } from "@opengeni/db";
 import {