@opengeni/core 3.0.1 → 3.1.2

package/src/sandbox/fleet.ts

@@ -11,15 +11,22 @@
 // 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 type { SandboxBackend } from "@opengeni/contracts";
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import {
+  agentCapabilityEnabled,
+  type SandboxBackend,
+  type SecretResolver,
+} from "@opengeni/contracts";
 import {
   authorizePersonalMachineForAttempt,
   getEnrollment,
+  getSession,
   getLiveEnrollmentConnection,
   getSandbox,
   listEnrollments,
   listSandboxes,
+  nestedPostgresSqlState,
   readActiveSandbox,
   readLease,
   resolvePersonalMachineConnectionForAttempt,
@@ -30,9 +37,14 @@ import {
   type SandboxRecord,
 } from "@opengeni/db";
 import type { EventBus } from "@opengeni/events";
+import { HTTPException } from "hono/http-exception";
 import {
   NatsControlRpc,
   NatsOpStreamTransport,
+  prepareSecretExec,
+  resolveSecretLiteralText,
+  runWithSecretCarry,
+  type SecretExecCarry,
   selfhostedLiveness,
   SelfhostedSession,
   resolveConnectedMachineWorkspaceRoot,
@@ -46,7 +58,8 @@ import {
   type SelfhostedOperationResourcePolicy,
 } from "@opengeni/runtime/sandbox";
 import { relayConfigFromSettings } from "./routing";
-import { managedSessionGroupBackend } from "./runtime-settings";
+import { createSecretResolver } from "../domain/vaults/secret-resolver";
+import { managedSessionGroupBackend, sessionGroupMachinePresentation } from "./runtime-settings";
 
 export type FleetServices = {
   db: Database;
@@ -130,7 +143,7 @@ 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" | "opensandbox";
+  kind: Exclude<SandboxBackend, "none">;
   name: string;
   liveness: FleetLiveness;
   /** True for the session's currently-active sandbox (the routing target). */
@@ -192,11 +205,82 @@ export type FleetSwapResult = {
     | BackendUnresolvableCode
     | "invalid_working_directory"
     | "concurrent_swap"
+    | PersonalMachineRefusalCode
     | "recovery_in_progress"
     | "recovery_degraded"
     | "recovery_unrecoverable";
 };
 
+export type PersonalMachineRefusalCode =
+  | "personal_machine_permission_required"
+  | "personal_machine_not_permitted";
+
+/**
+ * Plain refusal for a personal ("Only me") Connected Machine that the database
+ * admission (`authorize_session_attempt_personal_machine`) turned down. The
+ * function raises SQLSTATE 42501 for policy refusals and P0002 when a required
+ * owner, authority or enrollment row is not current. Only failures of that
+ * admission statement are mapped; anything else is a real failure and stays an
+ * error. The raw database error is never shown.
+ */
+export function personalMachineRefusal(
+  error: unknown,
+): { code: PersonalMachineRefusalCode; reason: string } | null {
+  const sqlState = nestedPostgresSqlState(error);
+  if (sqlState !== "42501" && sqlState !== "P0002") return null;
+  const messages: string[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth < 8 && current instanceof Error; depth += 1) {
+    messages.push(current.message);
+    current = current.cause;
+  }
+  const text = messages.join("\n");
+  if (!text.includes("authorize_session_attempt_personal_machine")) return null;
+  if (sqlState === "42501" && text.includes("requires explicit grant")) {
+    return {
+      code: "personal_machine_permission_required",
+      reason:
+        "This is a personal (Only me) machine, and its owner has not allowed this chat to use it. " +
+        "The owner can allow it from this chat: choose the machine with Use in this chat, then allow it once, for this chat, or always.",
+    };
+  }
+  if (
+    text.includes("only the personal machine owner may use it") ||
+    text.includes("not the frozen initiating human")
+  ) {
+    return {
+      code: "personal_machine_not_permitted",
+      reason:
+        "This is a personal (Only me) machine. Only its owner can use it, in turns the owner started.",
+    };
+  }
+  if (text.includes("lacks target workspace access")) {
+    return {
+      code: "personal_machine_not_permitted",
+      reason:
+        "This is a personal (Only me) machine, and its owner does not have access to this workspace.",
+    };
+  }
+  if (text.includes("requires exact current attempt authority")) {
+    return {
+      code: "personal_machine_not_permitted",
+      reason:
+        "This turn is no longer the chat's current turn, so it cannot use the personal machine.",
+    };
+  }
+  if (sqlState === "P0002") {
+    return {
+      code: "personal_machine_not_permitted",
+      reason:
+        "This personal machine's connection or its owner's access is no longer current. The owner can reconnect it.",
+    };
+  }
+  return {
+    code: "personal_machine_not_permitted",
+    reason: "This personal (Only me) machine cannot be used from this chat.",
+  };
+}
+
 const PROBE_TIMEOUT_MS = 5_000;
 
 function controlRpc(bus: EventBus | undefined): ControlRpc {
@@ -325,10 +409,11 @@ export async function listFleet(
         : groupRecovering
           ? "recovering"
           : "wakeable";
+    const presentation = sessionGroupMachinePresentation(groupBackend);
     entries.push({
       id: ctx.sessionGroupId,
-      kind: groupBackend === "opensandbox" ? "opensandbox" : "modal",
-      name: "session sandbox",
+      kind: presentation.kind,
+      name: presentation.name,
       liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
       active: groupActive,
       isSessionGroup: true,
@@ -667,6 +752,9 @@ export async function swapActiveSandbox(
     try {
       readinessHold = await services.ensureSessionGroupReady(ctx);
     } catch (error) {
+      // An explicit refusal (e.g. the session's Sandbox Environment is not
+      // available to this caller) is not a recovery state; surface it as is.
+      if (error instanceof HTTPException && error.status === 403) throw error;
       const lease = await readLease(services.db, ctx.workspaceId, ctx.sessionGroupId);
       const restore = lease?.recovery.restore.status;
       const code =
@@ -724,20 +812,34 @@ export async function swapActiveSandbox(
       // Even a same-target attach advances active_epoch. It is a repair/fence
       // request, not a no-op acknowledgment: any cached stale route is invalidated
       // only after target readiness has been proved above.
-      const result = await setActiveSandbox(services.db, {
-        accountId: ctx.accountId,
-        workspaceId: ctx.workspaceId,
-        sessionId: ctx.sessionId,
-        targetSandboxId: resolved.targetSandboxId,
-        expectedEpoch: pointer.activeEpoch,
-        ...(ctx.subjectId ? { subjectId: ctx.subjectId } : {}),
-        ...(ctx.attemptAuthority ? { personalMachineAttempt: ctx.attemptAuthority } : {}),
-        ...(resolved.workspaceRoot !== undefined
-          ? { workingDir: effectiveWorkingDir ?? resolved.workspaceRoot }
-          : workingDir !== undefined
-            ? { workingDir }
-            : {}),
-      });
+      let result: Awaited<ReturnType<typeof setActiveSandbox>>;
+      try {
+        result = await setActiveSandbox(services.db, {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          sessionId: ctx.sessionId,
+          targetSandboxId: resolved.targetSandboxId,
+          expectedEpoch: pointer.activeEpoch,
+          ...(ctx.subjectId ? { subjectId: ctx.subjectId } : {}),
+          ...(ctx.attemptAuthority ? { personalMachineAttempt: ctx.attemptAuthority } : {}),
+          ...(resolved.workspaceRoot !== undefined
+            ? { workingDir: effectiveWorkingDir ?? resolved.workspaceRoot }
+            : workingDir !== undefined
+              ? { workingDir }
+              : {}),
+        });
+      } catch (error) {
+        // The admission refusal rolled the whole CAS transaction back, so the
+        // pointer read above is still current.
+        const refusal = personalMachineRefusal(error);
+        if (!refusal) throw error;
+        return {
+          swapped: false,
+          activeSandboxId: pointer.activeSandboxId,
+          activeEpoch: pointer.activeEpoch,
+          ...refusal,
+        };
+      }
       if (result.swapped && result.pointer) {
         return {
           swapped: true,
@@ -815,14 +917,52 @@ export type RunOnSelfhostedMachine = {
    * the active attempt that owns the one-off operation.
    */
   transientExecEnvironment?: Readonly<Record<string, string>>;
+  /**
+   * The calling attempt's secret resolver (W1, DL-9). exec splices
+   * `{{secret:…}}` / `{{secretfile:…}}` in the machine's dialect and delivers
+   * values in ExecRequest.env; write resolves its content; read resolves
+   * nothing. Absent: references pass through literally.
+   */
+  secretResolver?: SecretResolver | null;
 };
 
+/**
+ * The secret resolver for a `run_on` call made by an exact agent attempt (the
+ * MCP claims). Gated by the session's `secrets` capability (default on).
+ */
+export async function createRunOnSecretResolver(
+  services: Pick<FleetServices, "db" | "settings">,
+  attempt: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+  },
+  /** Connected vaults (1Password, host) for the attempt's acting human. */
+  providersForSubject?: (subjectId: string | null) => VaultProviderRegistry,
+): Promise<SecretResolver> {
+  const session = await getSession(services.db, attempt.workspaceId, attempt.sessionId);
+  return createSecretResolver(
+    { db: services.db, encryptionKey: environmentsEncryptionKeyBytes(services.settings) ?? null },
+    { kind: "attempt", ...attempt },
+    {
+      capabilityEnabled: session?.agent
+        ? agentCapabilityEnabled(session.agent.capabilities, "secrets")
+        : true,
+      ...(providersForSubject ? { providersForSubject } : {}),
+    },
+  );
+}
+
 export type RunOnOptions = {
   transientExecEnvironment?: Readonly<Record<string, string>>;
+  secretResolver?: SecretResolver | null;
 };
 
 function runOnOperationAdmission(
-  services: FleetServices,
+  services: Pick<FleetServices, "settings" | "bus">,
   enrollment: EnrollmentRecord | null,
 ): SelfhostedOperationAdmission | null {
   if (!enrollment?.connectionInstanceId || !enrollment.workspaceRoot) return null;
@@ -844,9 +984,16 @@ function runOnOperationAdmission(
     operationResourcePolicy: enrollment.operationPolicy,
     operationResourcePolicySupported: enrollment.agentCapabilities.operationResourcePolicy === true,
     operationCpuQuotaSupported: enrollment.agentCapabilities.operationCpuQuota === true,
+    transactionalFsWriteSupported: enrollment.agentCapabilities.transactionalFsWrite === true,
   };
 }
 
+function hasSecretFileReference(carry: SecretExecCarry): boolean {
+  return carry.tokens.some(
+    (token) => token.type === "reference" && token.reference.kind === "secretfile",
+  );
+}
+
 /**
  * Execute the one-off machine operation once the workspace/enrollment lookup has
  * succeeded. Kept separate from {@link runOnSandbox} so the command/deadline
@@ -887,13 +1034,35 @@ export async function executeRunOnSelfhostedMachine(
     ...(machine.opStream !== undefined ? { opStream: machine.opStream } : {}),
   });
 
+  const secretUse = { surface: "run_on" as const, toolName: "run_on" };
   try {
     if (op.kind === "exec") {
       const deadlineMs = session.effectiveExecDeadlineMs;
-      const res = await session.exec({
-        cmd: op.cmd,
-        ...(op.workdir ? { workdir: op.workdir } : {}),
+      // Resolve before dispatch (all-or-nothing); the machine adapter splices
+      // in its own dialect from the in-memory carry. `op.cmd` keeps references.
+      const prepared = await prepareSecretExec(op.cmd, {
+        resolver: machine.secretResolver,
+        dialect: null,
+        use: secretUse,
       });
+      let res: Awaited<ReturnType<typeof session.exec>>;
+      try {
+        res = await runWithSecretCarry(
+          prepared?.carry ?? null,
+          async () =>
+            await session.exec({
+              cmd: prepared?.text ?? op.cmd,
+              ...(op.workdir ? { workdir: op.workdir } : {}),
+            }),
+        );
+      } finally {
+        // A one-off has no attempt-end cleanup on this machine: remove the
+        // `secretfile` scope it wrote (SEC-4) with the filesystem op, which
+        // works on every host OS and skips command admission. Best effort.
+        if (prepared?.carry && hasSecretFileReference(prepared.carry)) {
+          await session.clearSecretFilesForAttempt().catch(() => undefined);
+        }
+      }
       const timedOut = res.timedOut === true;
       const hasTerminalExit = res.exitCode !== null;
       return {
@@ -928,7 +1097,10 @@ export async function executeRunOnSelfhostedMachine(
     }
     const bytesWritten = await session.writeFile({
       path: op.path,
-      content: op.content,
+      content: await resolveSecretLiteralText(op.content, {
+        resolver: machine.secretResolver,
+        use: { ...secretUse, surface: "file_write" },
+      }),
     });
     return { target, kind: "write", ok: true, bytesWritten };
   } catch (error) {
@@ -950,6 +1122,56 @@ export async function executeRunOnSelfhostedMachine(
   }
 }
 
+/**
+ * Run one short command on a specific enrolled machine for an action a person
+ * or agent took outside a session's routing (opening a macOS settings pane).
+ * The caller has already authorized the actor for this enrollment; `access` is
+ * the same scope the caller used to read it. `execTimeoutMs` bounds the command.
+ */
+export async function runOnEnrollmentDirect(
+  services: Pick<FleetServices, "db" | "settings" | "bus">,
+  input: {
+    access: string | { accountId: string; workspaceId: string; subjectId: string };
+    enrollmentId: string;
+    /** Display label for results (machine name or sandbox id). */
+    target: string;
+    cmd: string;
+    execTimeoutMs: number;
+  },
+): Promise<RunOnResult> {
+  const live = await getLiveEnrollmentConnection(services.db, input.access, input.enrollmentId);
+  if (!live || live.status !== "active" || !live.connectionInstanceId || !live.workspaceRoot) {
+    return { target: input.target, kind: "exec", ok: false, reason: "machine is not connected" };
+  }
+  return await executeRunOnSelfhostedMachine(
+    {
+      workspaceId: live.workspaceId,
+      agentId: input.enrollmentId,
+      connectionInstanceId: live.connectionInstanceId,
+      workspaceRoot: live.workspaceRoot,
+      controlRpc: controlRpc(services.bus),
+      relay: relayConfigFromSettings(services.settings),
+      controlTimeoutMs: services.settings.sandboxSelfhostedControlTimeoutMs,
+      execTimeoutMs: input.execTimeoutMs,
+      operationResourcePolicy: live.operationPolicy,
+      operationResourcePolicySupported: live.agentCapabilities.operationResourcePolicy === true,
+      operationCpuQuotaSupported: live.agentCapabilities.operationCpuQuota === true,
+      resolveOperationAdmission: async () => {
+        try {
+          return runOnOperationAdmission(
+            services,
+            await getLiveEnrollmentConnection(services.db, input.access, input.enrollmentId),
+          );
+        } catch {
+          return null;
+        }
+      },
+    },
+    input.target,
+    { kind: "exec", cmd: input.cmd },
+  );
+}
+
 /**
  * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
  * (the design `run_on`). Only selfhosted targets are routable as a one-off here
@@ -1025,13 +1247,15 @@ export async function runOnSandbox(
           reason: "personal Connected Machine authority was not admitted for this attempt",
         };
       }
-    } catch {
+    } catch (error) {
       return {
         target,
         targetName: sandbox.name,
         kind: op.kind,
         ok: false,
-        reason: "personal Connected Machine authority is not live for this attempt",
+        reason:
+          personalMachineRefusal(error)?.reason ??
+          "personal Connected Machine authority is not live for this attempt",
       };
     }
   }
@@ -1114,6 +1338,7 @@ export async function runOnSandbox(
       ...(options.transientExecEnvironment !== undefined
         ? { transientExecEnvironment: options.transientExecEnvironment }
         : {}),
+      ...(options.secretResolver ? { secretResolver: options.secretResolver } : {}),
       ...(services.settings.agentOpStreamEnabled === true &&
       enrollment.opStream === true &&
       services.bus?.getOpStreamConnection
@@ -1164,7 +1389,7 @@ export async function provisionSandbox(
     return {
       kind: "selfhosted",
       instructions:
-        "Share one of these deployment-specific commands with a human operator. It installs the OpenGeni agent and starts `opengeni-agent connect` for this exact deployment and workspace; do not run a second bare `connect`. 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. Existing connections to other OpenGeni workspaces or deployments are preserved.",
+        "Share one of these deployment-specific commands with a human operator. It installs the Opengeni agent and starts `opengeni-agent connect` for this exact deployment and workspace; do not run a second bare `connect`. 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. Existing connections to other Opengeni workspaces or deployments are preserved.",
       // 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