@opengeni/core 0.2.0

package/src/domain/workspace-members.ts

@@ -0,0 +1,80 @@
+// Pure, HTTP-shaped guard helpers for the workspace member + workspace delete
+// routes. Kept out of the route bodies so the don't-orphan rules (never remove
+// the last admin, never delete an account's last workspace or one with a live
+// session) are unit-testable without a database.
+import type { Permission, WorkspaceMember } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+
+/** The membership permission that grants member-management (admin is the wildcard). */
+const MEMBER_ADMIN_PERMISSIONS: Permission[] = ["workspace:admin", "members:manage"];
+
+/** A member can manage other members (directly or via the admin wildcard). */
+export function memberCanAdminister(member: Pick<WorkspaceMember, "permissions">): boolean {
+  return member.permissions.some((permission) => MEMBER_ADMIN_PERMISSIONS.includes(permission));
+}
+
+/** Only `user:` subjects are people; `api_key:` subjects belong to API keys. */
+export function isUserMember(member: Pick<WorkspaceMember, "subjectId">): boolean {
+  return member.subjectId.startsWith("user:");
+}
+
+/**
+ * Turn an email lookup result into the membership subject id. A null id means
+ * no registered user matched the email — email invites for not-yet-registered
+ * users are deferred, so that is a 404 (not a 400) at the API surface.
+ */
+export function resolveMemberSubjectId(userId: string | null): string {
+  if (!userId) {
+    throw new HTTPException(404, { message: "user is not registered" });
+  }
+  return `user:${userId}`;
+}
+
+/**
+ * Guard the member-remove path. Refuses (409) to remove the caller's own
+ * membership and refuses to remove the last member that still holds an admin
+ * permission, so a workspace can never be orphaned with no one able to manage
+ * it. `members` is the full roster (every subject, including api_key ones —
+ * an api_key with workspace:admin still counts as an administering subject).
+ */
+export function assertWorkspaceMemberRemovable(input: {
+  members: WorkspaceMember[];
+  subjectId: string;
+  callerSubjectId: string;
+}): void {
+  const { members, subjectId, callerSubjectId } = input;
+  if (subjectId === callerSubjectId) {
+    throw new HTTPException(409, { message: "you cannot remove your own membership" });
+  }
+  const target = members.find((member) => member.subjectId === subjectId);
+  if (!target) {
+    throw new HTTPException(404, { message: "member not found" });
+  }
+  if (memberCanAdminister(target)) {
+    const remainingAdmins = members.filter((member) => member.subjectId !== subjectId && memberCanAdminister(member));
+    if (remainingAdmins.length === 0) {
+      throw new HTTPException(409, { message: "cannot remove the last member who can manage this workspace" });
+    }
+  }
+}
+
+/**
+ * Guard the workspace-delete path before any external/DB mutation. Refuses
+ * (409) to delete the account's last workspace, and refuses while any session
+ * could still be running in Temporal (there is no clean per-session terminate
+ * to call first, so we will not orphan a workflow — the operator must stop the
+ * sessions first).
+ */
+export function assertWorkspaceDeletable(input: {
+  workspaceCountForAccount: number;
+  activeSessionCount: number;
+}): void {
+  if (input.workspaceCountForAccount <= 1) {
+    throw new HTTPException(409, { message: "cannot delete the account's only workspace" });
+  }
+  if (input.activeSessionCount > 0) {
+    throw new HTTPException(409, {
+      message: "stop the workspace's running sessions before deleting it",
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// @opengeni/core — the framework-agnostic OpenGeni core.
+//
+// WHAT THIS PACKAGE IS: the OpenGeni domain, access, and billing layers carved
+// out of `apps/api` into an importable library, so a host (e.g. cloudgeni) can
+// call the OpenGeni core DIRECTLY, off-HTTP — e.g. `createSessionForRequest(
+// deps, grant, workspaceId, input)` — without standing up the Hono router.
+// `apps/api` (@opengeni/api-router) and `apps/worker` (@opengeni/worker-bundle)
+// remain the STANDALONE RUNNERS that consume this library; nothing about the
+// standalone served API or the worker boot changed.
+//
+// BEHAVIOR-PRESERVING MOVE PASS (Chunk 3): this extraction is a pure file-move +
+// import-rewrite with ZERO behavior change. The domain keeps throwing Hono
+// `HTTPException` exactly as before — so `hono` is a real runtime dependency of
+// @opengeni/core for now. The typed-errors carve-out (transport-neutral error
+// hierarchy + HTTP adapter in the router) is DEFERRED to a later pass; there is
+// no `errors.ts` here yet.
+//
+// DEPENDENCY DISCIPLINE: the moved closure references the engine-internal
+// sandbox client (`@opengeni/runtime/sandbox`, via the fleet/routing service it
+// needs for `swapActiveSandbox`) and the type slots
+// `@opengeni/storage`/`documents`/`observability` (in `dependencies.ts`). The
+// storage/documents/observability references are TYPE-ONLY (erased at build),
+// so they are devDependencies. `@opengeni/runtime` and `@opengeni/codex` are
+// real runtime deps (fleet routing + the codex model-id prefix constant). The
+// Better Auth `Auth` type (`managed-auth-type.ts`) is a type-only devDependency.
+
+// The central dependency type surface (AppDependencies, ApiRouteDeps,
+// SessionWorkflowClient, DocumentIndexClient, ObjectStorageDependency).
+export * from "./dependencies";
+
+// Boundary type slots referenced by dependencies.ts. The IMPLEMENTATIONS that
+// construct these (the real sandbox client / Better Auth instance) stay in
+// apps/api because they pull engine-internal / driver packages; only the
+// structural TYPES live here.
+export * from "./sandbox-types";
+export * from "./managed-auth-type";
+
+// Sandbox fleet/routing service — the closure of `domain/sessions.ts`
+// (`swapActiveSandbox` + `FleetContext`). apps/api re-imports these for its MCP
+// fleet tools, the machines REST route, and the rest of the sandbox layer.
+export * from "./sandbox/fleet";
+export * from "./sandbox/routing";
+
+// Access layer (transport-neutral grant resolution + permission checks).
+export * from "./access";
+
+// Billing / usage-limit admission (checkLimit / requireLimit / recordWorkspaceUsage).
+export * from "./billing/limits";
+
+// Domain layer — the off-HTTP V2 surface (createSessionForRequest,
+// postUserMessageTurn, createAndStartSession, capability/pack/environment/
+// scheduled-task/workspace-member logic, …).
+export * from "./domain/capabilities";
+export * from "./domain/environments";
+export * from "./domain/packs";
+export * from "./domain/resources";
+export * from "./domain/scheduled-tasks";
+export * from "./domain/sessions";
+export * from "./domain/workspace-members";

package/src/managed-auth-type.ts

@@ -0,0 +1,20 @@
+// @opengeni/core ManagedAuth TYPE alias.
+//
+// WHY THIS MODULE LIVES IN CORE: `dependencies.ts` carries a `managedAuth?:
+// ManagedAuth | null` passthrough slot and the access layer calls
+// `managedAuth.api.getSession({ headers })`. Both are framework-agnostic, so
+// they belong in @opengeni/core. The CONSTRUCTION of a real Better Auth
+// instance — `createManagedAuth`, which opens its own `pg.Pool` and wires
+// Resend — stays in `apps/api/src/auth/managed-auth.ts` (it pulls the `pg`
+// driver, which must NEVER enter @opengeni/core).
+//
+// This is a TYPE-ONLY import of Better Auth's `Auth` generic: it is fully
+// erased at build time (tsup `dts`/transpile drop it), so it adds NO runtime
+// dependency and NO driver import to the published @opengeni/core tarball —
+// `better-auth` is a devDependency for typecheck only. Keeping the alias as the
+// exact `Auth<any>` shape (not a hand-narrowed structural type) means
+// `apps/api/src/app.ts` — which uses `managedAuth.handler(...)` AND the
+// passthrough `deps.managedAuth` — stays byte-identically typed.
+import type { Auth } from "better-auth";
+
+export type ManagedAuth = Auth<any>;

package/src/sandbox/fleet.ts

@@ -0,0 +1,460 @@
+// apps/api/src/sandbox/fleet.ts — the FLEET service backing the fleet MCP tools
+// (M7): list / attach / swap / run_on / provision over the heterogeneous fleet
+// (the session's Modal group box + the workspace's enrolled selfhosted machines).
+//
+// Each operation is workspace-scoped (the caller's grant) and, for the
+// session-pointer mutations (attach/swap), session-scoped (the worker-signed
+// sessionId claim). The swap is the epoch-fenced CAS `setActiveSandbox`: it bumps
+// active_epoch + repoints active_sandbox_id, which the routing proxy reads on the
+// NEXT tool call. Liveness for a selfhosted target is a real ControlRpc ping over
+// the events bus (the subject IS the registry); a Modal box is "live" while its
+// session group exists. `run_on` builds a one-off backend session and runs a
+// single op WITHOUT touching the active pointer.
+
+import type { Settings } from "@opengeni/config";
+import {
+  getEnrollment,
+  getSandbox,
+  listEnrollments,
+  listSandboxes,
+  readActiveSandbox,
+  requireSession,
+  setActiveSandbox,
+  type Database,
+  type EnrollmentRecord,
+  type SandboxRecord,
+} from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import {
+  NatsControlRpc,
+  selfhostedLiveness,
+  SelfhostedSession,
+  type ControlRpc,
+  type NatsRequestConnection,
+} from "@opengeni/runtime/sandbox";
+import { HTTPException } from "hono/http-exception";
+import { relayConfigFromSettings } from "./routing";
+
+export type FleetServices = {
+  db: Database;
+  settings: Settings;
+  bus?: EventBus;
+};
+
+export type FleetContext = {
+  accountId: string;
+  workspaceId: string;
+  /** The calling session (the pointer the attach/swap mutates + whose group box
+   *  is the default fleet member). */
+  sessionId: string;
+  /** The session's own group sandbox backend (modal/selfhosted/…). */
+  sessionBackend: string;
+  /** The session's own group sandbox id (the lease group). */
+  sessionGroupId: string;
+};
+
+/**
+ * Build a session-scoped {@link FleetContext}: load the session (workspace-
+ * scoped), reject a session with no box (backend:none — the fleet is only
+ * meaningful for a sandboxed session), and project its group backend/id. Shared
+ * by the worker-signed MCP fleet tools and the user-authenticated swap REST
+ * route so both resolve the SAME context (no drift). The `accountId`/`workspaceId`/
+ * `sessionId` come from the trusted grant/route; the backend + group id come from
+ * the session row.
+ */
+export async function buildFleetContextForSession(
+  deps: { db: Database },
+  ctx: { accountId: string; workspaceId: string; sessionId: string },
+): Promise<FleetContext> {
+  const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
+  if (session.sandboxBackend === "none") {
+    throw new HTTPException(422, {
+      message: "this session has no sandbox (backend: none); the fleet is unavailable",
+    });
+  }
+  return {
+    accountId: ctx.accountId,
+    workspaceId: ctx.workspaceId,
+    sessionId: ctx.sessionId,
+    sessionBackend: session.sandboxBackend,
+    sessionGroupId: session.sandboxGroupId,
+  };
+}
+
+/** The dominant liveness of a fleet member, surfaced to the dock + the agent. */
+export type FleetLiveness = "online" | "reconnecting" | "offline";
+
+/**
+ * A fleet member as the agent + the dock see it (the M8b/M9 UI seam — the
+ * `sandboxes_list` response entry the dock renders). STABLE shape: the dock keys
+ * on `id`, renders `name`/`kind`/`liveness`, and marks `active`. The session's own
+ * Modal group box is a synthetic entry with `id: groupId`, `kind: "modal"`, and a
+ * null `enrollmentId`; an enrolled machine carries its sandbox + enrollment ids.
+ */
+export type FleetSandboxEntry = {
+  /** The sandbox id used as the attach/swap/run_on `target`. For the session's
+   *  own group box this is the group id (a null active pointer == this box). */
+  id: string;
+  kind: "modal" | "selfhosted";
+  name: string;
+  liveness: FleetLiveness;
+  /** True for the session's currently-active sandbox (the routing target). */
+  active: boolean;
+  /** True for the session's own group box (the default/home sandbox). */
+  isSessionGroup: boolean;
+  enrollmentId: string | null;
+  /** Whether this target can be attached/swapped to right now (live + addressable). */
+  attachable: boolean;
+  /** Selfhosted only: whether whole-machine + screen-control consent is acked. */
+  consented?: boolean;
+  /** Selfhosted only: whether a display (real/Xvfb) is present. */
+  hasDisplay?: boolean;
+  lastSeenAt?: string | null;
+};
+
+export type FleetListResult = {
+  /** The session's currently-active sandbox id, or null == the group box. */
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  sandboxes: FleetSandboxEntry[];
+};
+
+/** A swap/attach outcome the tool returns. */
+export type FleetSwapResult = {
+  swapped: boolean;
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  reason?: string;
+};
+
+const PROBE_TIMEOUT_MS = 5_000;
+
+function controlRpc(bus: EventBus | undefined): ControlRpc {
+  return new NatsControlRpc(async (): Promise<NatsRequestConnection | null> => {
+    if (!bus) {
+      return null;
+    }
+    return bus.getRequestConnection();
+  });
+}
+
+/** Probe an enrolled machine's liveness: a real ControlRpc ping (the subject IS
+ *  the registry), mapped through `selfhostedLiveness` (the enrollment row's
+ *  status/consent/display + lastSeenAt disambiguate a probe-miss into
+ *  reconnecting vs offline). A revoked/never-seen enrollment is offline without a
+ *  probe. */
+async function probeEnrollment(
+  services: FleetServices,
+  workspaceId: string,
+  enrollment: EnrollmentRecord,
+): Promise<{ liveness: FleetLiveness; consented: boolean; hasDisplay: boolean }> {
+  const { settings, bus } = services;
+  let probeResponded = false;
+  if (enrollment.status === "active") {
+    const session = new SelfhostedSession({
+      workspaceId,
+      agentId: enrollment.id,
+      controlRpc: controlRpc(bus),
+      relay: relayConfigFromSettings(settings),
+      timeoutMs: PROBE_TIMEOUT_MS,
+    });
+    try {
+      probeResponded = await session.ping();
+    } catch {
+      probeResponded = false;
+    }
+  }
+  const state = selfhostedLiveness({
+    enrollment: {
+      status: enrollment.status,
+      exposure: enrollment.exposure,
+      allowScreenControl: enrollment.allowScreenControl,
+      hasDisplay: enrollment.hasDisplay,
+      lastSeenAt: enrollment.lastSeenAt,
+    },
+    probeResponded,
+  });
+  return { liveness: state.state, consented: state.consented, hasDisplay: state.hasDisplay };
+}
+
+/**
+ * List the fleet: the session's own Modal group box (a synthetic entry) + the
+ * workspace's first-class selfhosted sandboxes (each probed for liveness), each
+ * with an `active` marker derived from the session's active pointer.
+ */
+export async function listFleet(services: FleetServices, ctx: FleetContext): Promise<FleetListResult> {
+  const { db } = services;
+  const pointer = (await readActiveSandbox(db, ctx.workspaceId, ctx.sessionId)) ?? {
+    activeSandboxId: null,
+    activeEpoch: 0,
+  };
+
+  const entries: FleetSandboxEntry[] = [];
+
+  // The session's own group box (the default/home sandbox; null active pointer ==
+  // this box). It is live by virtue of being the session's resumable group.
+  const groupActive = pointer.activeSandboxId === null;
+  entries.push({
+    id: ctx.sessionGroupId,
+    kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
+    name: "session sandbox",
+    liveness: "online",
+    active: groupActive,
+    isSessionGroup: true,
+    enrollmentId: null,
+    attachable: true,
+  });
+
+  // The workspace's first-class selfhosted sandboxes (enrolled machines). Probe
+  // each for liveness; a missing enrollment is offline.
+  const sandboxes = await listSandboxes(db, ctx.workspaceId);
+  for (const sandbox of sandboxes) {
+    if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
+      continue;
+    }
+    const enrollment = await getEnrollment(db, ctx.workspaceId, sandbox.enrollmentId);
+    const probe = enrollment
+      ? await probeEnrollment(services, ctx.workspaceId, enrollment)
+      : { liveness: "offline" as FleetLiveness, consented: false, hasDisplay: false };
+    entries.push({
+      id: sandbox.id,
+      kind: "selfhosted",
+      name: sandbox.name,
+      liveness: probe.liveness,
+      active: pointer.activeSandboxId === sandbox.id,
+      isSessionGroup: false,
+      enrollmentId: sandbox.enrollmentId,
+      attachable: probe.liveness === "online",
+      consented: probe.consented,
+      hasDisplay: probe.hasDisplay,
+      lastSeenAt: enrollment?.lastSeenAt ?? null,
+    });
+  }
+
+  return { activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch, sandboxes: entries };
+}
+
+/** Resolve a swap target id → the value `setActiveSandbox` writes. The session's
+ *  own group id maps to NULL (the default pointer); a first-class sandbox id is
+ *  validated (workspace ownership + liveness) and written verbatim. */
+async function resolveTarget(
+  services: FleetServices,
+  ctx: FleetContext,
+  target: string,
+): Promise<{ ok: true; targetSandboxId: string | null } | { ok: false; reason: string }> {
+  // The session's own group box → the default pointer (null).
+  if (target === ctx.sessionGroupId || target === "session" || target === "default") {
+    return { ok: true, targetSandboxId: null };
+  }
+  const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
+  if (!sandbox) {
+    return { ok: false, reason: `sandbox ${target} not found in this workspace` };
+  }
+  if (sandbox.kind === "selfhosted") {
+    if (!sandbox.enrollmentId) {
+      return { ok: false, reason: `selfhosted sandbox ${target} has no enrollment` };
+    }
+    const enrollment = await getEnrollment(services.db, ctx.workspaceId, sandbox.enrollmentId);
+    if (!enrollment) {
+      return { ok: false, reason: `enrollment for sandbox ${target} not found` };
+    }
+    const probe = await probeEnrollment(services, ctx.workspaceId, enrollment);
+    if (probe.liveness !== "online") {
+      return { ok: false, reason: `sandbox ${target} is ${probe.liveness}; cannot attach to a non-online machine` };
+    }
+  }
+  return { ok: true, targetSandboxId: sandbox.id };
+}
+
+/**
+ * THE SWAP (and attach — identical mechanic). Validate the target's ownership +
+ * liveness, then repoint the session via the epoch-fenced CAS `setActiveSandbox`:
+ * read the current epoch, then CAS on it. A concurrent double-swap lets exactly
+ * one win; the loser re-reads + may retry. The bumped epoch fences any in-flight
+ * op cached against the old pointer, which then retries against the new active
+ * sandbox (the routing proxy's fenced-retry role).
+ */
+export async function swapActiveSandbox(
+  services: FleetServices,
+  ctx: FleetContext,
+  target: string,
+  // The session's working directory to seed alongside the pointer (create-time
+  // machine targeting). OMITTED ⇒ the column is left unchanged (a live swap/attach
+  // never touches it); threaded straight into the epoch-fenced setActiveSandbox CAS.
+  workingDir?: string | null,
+): Promise<FleetSwapResult> {
+  const resolved = await resolveTarget(services, ctx, target);
+  if (!resolved.ok) {
+    const pointer = (await readActiveSandbox(services.db, ctx.workspaceId, ctx.sessionId)) ?? {
+      activeSandboxId: null,
+      activeEpoch: 0,
+    };
+    return { swapped: false, activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch, reason: resolved.reason };
+  }
+
+  // Read the current epoch, then CAS on it (the fence). One retry on a lost race
+  // (a concurrent swap bumped the epoch between read and write).
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const pointer = (await readActiveSandbox(services.db, ctx.workspaceId, ctx.sessionId)) ?? {
+      activeSandboxId: null,
+      activeEpoch: 0,
+    };
+    // No-op swap (already pointed there) is a success without an epoch bump churn.
+    if (pointer.activeSandboxId === resolved.targetSandboxId) {
+      return { swapped: true, activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch };
+    }
+    const result = await setActiveSandbox(services.db, {
+      accountId: ctx.accountId,
+      workspaceId: ctx.workspaceId,
+      sessionId: ctx.sessionId,
+      targetSandboxId: resolved.targetSandboxId,
+      expectedEpoch: pointer.activeEpoch,
+      ...(workingDir !== undefined ? { workingDir } : {}),
+    });
+    if (result.swapped && result.pointer) {
+      return { swapped: true, activeSandboxId: result.pointer.activeSandboxId, activeEpoch: result.pointer.activeEpoch };
+    }
+    // CAS lost (a concurrent swap won) — re-read + retry once.
+  }
+  const pointer = (await readActiveSandbox(services.db, ctx.workspaceId, ctx.sessionId)) ?? {
+    activeSandboxId: null,
+    activeEpoch: 0,
+  };
+  return {
+    swapped: false,
+    activeSandboxId: pointer.activeSandboxId,
+    activeEpoch: pointer.activeEpoch,
+    reason: "a concurrent swap won the epoch fence; re-read and retry",
+  };
+}
+
+export type RunOnOp =
+  | { kind: "exec"; cmd: string; workdir?: string }
+  | { kind: "read"; path: string }
+  | { kind: "write"; path: string; content: string };
+
+export type RunOnResult = {
+  target: string;
+  kind: string;
+  ok: boolean;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  content?: string;
+  bytesWritten?: number;
+  reason?: string;
+};
+
+/**
+ * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
+ * (the dossier `run_on`). Only selfhosted targets are routable as a one-off here
+ * (a Modal target is the session's group box, reached via the normal Channel-A /
+ * turn path — `run_on` is for reaching a NON-active enrolled machine without
+ * swapping). The op is fenced under the target's enrollment, addressed to its
+ * agent subject; an offline machine surfaces a clear reason, never a wrong-box
+ * landing.
+ */
+export async function runOnSandbox(
+  services: FleetServices,
+  ctx: FleetContext,
+  target: string,
+  op: RunOnOp,
+): Promise<RunOnResult> {
+  const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
+  if (!sandbox) {
+    return { target, kind: op.kind, ok: false, reason: `sandbox ${target} not found in this workspace` };
+  }
+  if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
+    return {
+      target,
+      kind: op.kind,
+      ok: false,
+      reason: `run_on routes one-off ops to enrolled selfhosted machines; ${sandbox.kind} targets are reached via the active sandbox (swap to it first)`,
+    };
+  }
+  const enrollment = await getEnrollment(services.db, ctx.workspaceId, sandbox.enrollmentId);
+  if (!enrollment || enrollment.status !== "active") {
+    return { target, kind: op.kind, ok: false, reason: `sandbox ${target} is not enrolled/active` };
+  }
+
+  const session = new SelfhostedSession({
+    workspaceId: ctx.workspaceId,
+    agentId: sandbox.enrollmentId,
+    controlRpc: controlRpc(services.bus),
+    relay: relayConfigFromSettings(services.settings),
+  });
+
+  try {
+    if (op.kind === "exec") {
+      const res = await session.exec({ cmd: op.cmd, ...(op.workdir ? { workdir: op.workdir } : {}) });
+      return { target, kind: "exec", ok: true, stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode };
+    }
+    if (op.kind === "read") {
+      const bytes = await session.readFile({ path: op.path });
+      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
+    }
+    // write
+    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
+    return { target, kind: "write", ok: true, bytesWritten };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { target, kind: op.kind, ok: false, reason };
+  }
+}
+
+export type ProvisionResult =
+  | {
+      kind: "selfhosted";
+      instructions: string;
+      installCommandUnix: string;
+      installCommandWindows: string;
+      verificationUri: string;
+      note: string;
+    }
+  | { kind: "modal"; sandbox: SandboxRecord; note: string };
+
+/**
+ * Provision a new fleet member.
+ *   - selfhosted → return the device-flow enrollment instructions (the agent
+ *     surfaces them to a HUMAN, who installs the agent + enrolls — the agent
+ *     cannot click the loud whole-machine consent itself).
+ *   - modal → create a first-class named modal `sandboxes` record (a swap target).
+ *     NOTE: the Modal BOX is materialized lazily when first swapped-to (Modal
+ *     lifecycle is owned by the lease — unchanged per dossier §21).
+ */
+export async function provisionSandbox(
+  services: FleetServices,
+  ctx: FleetContext,
+  input: { kind: "selfhosted" | "modal"; name?: string },
+): Promise<ProvisionResult> {
+  if (input.kind === "selfhosted") {
+    const base = (services.settings.publicBaseUrl ?? "https://get.opengeni.ai").replace(/\/+$/, "");
+    return {
+      kind: "selfhosted",
+      instructions:
+        "Share these instructions with a human operator. They install the OpenGeni agent on the machine, run `opengeni-agent enroll`, complete the device-flow at the verification URL (the loud whole-machine + screen-control consent), and the machine then appears here as an attachable selfhosted sandbox.",
+      // Install from THIS control plane's origin (not a hardcoded public CDN): the
+      // served install script is rewritten to pull the per-SHA agent baked into
+      // this exact deployment (see apps/api/src/routes/install.ts), so a deployed
+      // env is self-contained and a private/air-gapped one works with no public DNS.
+      installCommandUnix: `curl -fsSL ${base}/install.sh | sh`,
+      installCommandWindows: `irm ${base}/install.ps1 | iex`,
+      verificationUri: `${base}/device`,
+      note: "Whole-machine access requires explicit human consent in the device-flow web page; the agent cannot self-consent.",
+    };
+  }
+  // modal: create a first-class named modal sandbox record (a swap target). The
+  // box is materialized lazily on first swap (Modal lifecycle unchanged).
+  const { createSandbox } = await import("@opengeni/db");
+  const sandbox = await createSandbox(services.db, {
+    accountId: ctx.accountId,
+    workspaceId: ctx.workspaceId,
+    kind: "modal",
+    name: input.name?.trim() || "modal-box",
+  });
+  return {
+    kind: "modal",
+    sandbox,
+    note: "A named Modal sandbox record was created. Its box is materialized when first swapped-to; the session's own group box remains the default until then.",
+  };
+}