@opengeni/api-router 3.0.1 → 3.1.2

package/src/interaction-agent-access.ts

@@ -1,31 +1,56 @@
 import type { AccessGrant } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
 import {
-  grantHasAgentAttemptAuthority,
   requireSessionAuthorization,
   SessionAuthorizationDeniedError,
   type ApiRouteDeps,
 } from "@opengeni/core";
 
 type AssociatedInteractionSession = {
-  associations: ReadonlyArray<{ sessionId: string }>;
+  associations: ReadonlyArray<{ sessionId: string; relationship: string }>;
 };
 
+const InteractionSessionListQuery = z
+  .object({
+    associatedSessionId: z.string().uuid().optional(),
+    includeTerminal: z.enum(["true", "false"]).optional(),
+  })
+  .strict();
+
+/**
+ * Optional narrowing filters for BrowserSession/ComputerSession inventories,
+ * applied in SQL before per-source authorization. They narrow, never grant:
+ * every returned row still passes filterInteractionSessionsForGrant.
+ */
+export function parseInteractionSessionListQuery(query: Record<string, string>): {
+  associatedSessionId?: string;
+  includeTerminal?: boolean;
+} {
+  const parsed = InteractionSessionListQuery.safeParse(query);
+  if (!parsed.success) {
+    throw new HTTPException(400, { message: "Invalid interaction session list query" });
+  }
+  return {
+    ...(parsed.data.associatedSessionId
+      ? { associatedSessionId: parsed.data.associatedSessionId.toLowerCase() }
+      : {}),
+    ...(parsed.data.includeTerminal
+      ? { includeTerminal: parsed.data.includeTerminal === "true" }
+      : {}),
+  };
+}
+
 /**
- * Narrow a workspace-wide BrowserSession/ComputerSession inventory to the
- * entries a live agent attempt may reach. Every attach-by-id route already
- * authorizes the exact source session through the core seam; the list is the
- * discovery surface behind `interaction_discover scope=workspace`, so it must
- * apply the same seam (private sessions, Slack ownership, and the 0426
- * agent-access scope) to each associated session instead of exposing every
- * peer's identity. Humans, API keys, and service principals keep the complete
- * workspace inventory exactly as before.
+ * Apply the same source-chat authorization as get/control routes, for every
+ * caller. A later using/observing/related association never transfers ownership
+ * or makes a private interaction discoverable through another chat.
  */
 export async function filterInteractionSessionsForGrant<T extends AssociatedInteractionSession>(
   deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">,
   grant: AccessGrant,
   sessions: readonly T[],
 ): Promise<T[]> {
-  if (!grantHasAgentAttemptAuthority(grant)) return [...sessions];
   const decisions = new Map<string, Promise<boolean>>();
   const authorized = (sessionId: string): Promise<boolean> => {
     let decision = decisions.get(sessionId);
@@ -46,15 +71,10 @@ export async function filterInteractionSessionsForGrant<T extends AssociatedInte
   };
   const kept: T[] = [];
   for (const session of sessions) {
-    const associated = [...new Set(session.associations.map((entry) => entry.sessionId))];
-    let visible = false;
-    for (const sessionId of associated) {
-      if (await authorized(sessionId)) {
-        visible = true;
-        break;
-      }
-    }
-    if (visible) kept.push(session);
+    const sources = session.associations.filter((entry) => entry.relationship === "created");
+    // Control-record resolution also requires exactly one creation association.
+    // Incomplete or ambiguous records cannot establish a discoverable owner.
+    if (sources.length === 1 && (await authorized(sources[0]!.sessionId))) kept.push(session);
   }
   return kept;
 }

package/src/interaction-agent-version.ts

@@ -0,0 +1,85 @@
+/**
+ * Saved-secret typing needs a controller that understands the private
+ * `secretValues` side map. Server-managed controllers always do; a Connected
+ * Machine or attached browser runs whatever agent its owner installed, and an
+ * agent built before the field existed rejects the whole command as malformed.
+ * Refuse before anything is resolved or dispatched, and say how to fix it.
+ */
+import type { AccessGrant, InteractionPlacement } from "@opengeni/contracts";
+import {
+  type Database,
+  getAttachedBrowserDevice,
+  getLiveEnrollmentConnection,
+  getSandbox,
+} from "@opengeni/db";
+import { attachedBrowserViewer } from "./attached-browser-viewer";
+import { ApiHttpError } from "./http/api-error";
+import { compareAgentVersions } from "./sandbox/machines";
+
+/** The first agent release whose controller accepts `secretValues`. */
+export const MINIMUM_AGENT_VERSION_FOR_SECRET_VALUES = "0.1.56";
+
+/** True only when the installed version is known and predates secret values.
+ * An unknown or unparsable version is not refused on a guess. */
+export function agentVersionRejectsSecretValues(agentVersion: string | null): boolean {
+  if (!agentVersion) return false;
+  const order = compareAgentVersions(agentVersion, MINIMUM_AGENT_VERSION_FOR_SECRET_VALUES);
+  return order !== null && order < 0;
+}
+
+export function agentUpdateRequiredForSecretsError(agentVersion: string): ApiHttpError {
+  return new ApiHttpError(422, {
+    code: "validation_failed",
+    message:
+      `This machine runs Opengeni agent ${agentVersion}, which cannot type saved secrets. ` +
+      `Update the machine's agent to ${MINIMUM_AGENT_VERSION_FOR_SECRET_VALUES} or newer ` +
+      `(Machines, Update now), then retry. Nothing was typed.`,
+    retryable: false,
+    outcomeUnknown: false,
+    details: {
+      reason: "agent_update_required",
+      agentVersion,
+      minimumAgentVersion: MINIMUM_AGENT_VERSION_FOR_SECRET_VALUES,
+    },
+  });
+}
+
+/** The installed agent version behind a device placement; null for
+ * server-managed placements or when the machine is not live. */
+export async function placementAgentVersion(
+  db: Database,
+  grant: AccessGrant,
+  workspaceId: string,
+  placement: InteractionPlacement | null,
+): Promise<string | null> {
+  if (placement?.kind === "connected_machine") {
+    const sandbox = await getSandbox(db, grant, placement.sandboxId);
+    if (sandbox?.kind !== "selfhosted" || !sandbox.enrollmentId) return null;
+    const enrollment = await getLiveEnrollmentConnection(db, grant, sandbox.enrollmentId);
+    return enrollment?.agentVersion ?? null;
+  }
+  if (placement?.kind === "attached_device") {
+    const device = await getAttachedBrowserDevice(db, {
+      ...(await attachedBrowserViewer({ db }, grant, workspaceId)),
+      deviceId: placement.deviceId,
+    });
+    const enrollment = await getLiveEnrollmentConnection(db, workspaceId, device.enrollmentId);
+    return enrollment?.agentVersion ?? null;
+  }
+  return null;
+}
+
+/** A `beforeResolve` hook for `resolveInteractionSecretValues`. */
+export function requirePlacementAcceptsSecretValues(
+  db: Database,
+  grant: AccessGrant,
+  workspaceId: string,
+  placement: InteractionPlacement | null,
+): () => Promise<void> {
+  return async () => {
+    const agentVersion = await placementAgentVersion(db, grant, workspaceId, placement);
+    if (agentVersion !== null && agentVersionRejectsSecretValues(agentVersion)) {
+      throw agentUpdateRequiredForSecretsError(agentVersion);
+    }
+  };
+}

package/src/interaction-holder-heartbeat.ts

@@ -1,5 +1,9 @@
 import type { AccessGrant } from "@opengeni/contracts";
-import { touchInteractionOperation, touchLeaseHolder } from "@opengeni/db";
+import {
+  touchExpiredBrowserSessionResume,
+  touchInteractionOperation,
+  touchLeaseHolder,
+} from "@opengeni/db";
 import type { ApiRouteDeps } from "@opengeni/core";
 
 const MAX_HEARTBEAT_INTERVAL_MS = 10_000;
@@ -20,6 +24,11 @@ export async function withInteractionHolderHeartbeat<T>(
     operationId: string;
     resourceId: string;
     controllerGeneration: string;
+    /** Continuing an expired browser resume on its retained generation: its
+     * operation is recorded only once the controller adopts the working copy,
+     * so the expired resume itself (still lost, still bound to this
+     * generation) is the authority until then. */
+    continuesExpiredBrowserResume?: true;
   },
   run: () => Promise<T>,
 ): Promise<T> {
@@ -38,13 +47,20 @@ export async function withInteractionHolderHeartbeat<T>(
   const pulse = async (): Promise<void> => {
     try {
       const [operationAlive, holderAlive] = await Promise.all([
-        touchInteractionOperation(deps.db, {
-          accountId: input.grant.accountId,
-          workspaceId: input.workspaceId,
-          operationId: input.operationId,
-          resourceId: input.resourceId,
-          controllerGeneration: input.controllerGeneration,
-        }),
+        input.continuesExpiredBrowserResume
+          ? touchExpiredBrowserSessionResume(deps.db, {
+              accountId: input.grant.accountId,
+              workspaceId: input.workspaceId,
+              browserSessionId: input.resourceId,
+              controllerGeneration: input.controllerGeneration,
+            })
+          : touchInteractionOperation(deps.db, {
+              accountId: input.grant.accountId,
+              workspaceId: input.workspaceId,
+              operationId: input.operationId,
+              resourceId: input.resourceId,
+              controllerGeneration: input.controllerGeneration,
+            }),
         input.sandboxGroupId
           ? touchLeaseHolder(deps.db, {
               accountId: input.grant.accountId,

package/src/interaction-metrics.ts

@@ -8,7 +8,6 @@ import type {
   ComputerActionRequest,
   ComputerSessionMutationResponse,
   InteractionInterventionMutationResponse,
-  ProtectedAuthFillResponse,
 } from "@opengeni/contracts";
 import {
   interactionAuthMetricObserver,
@@ -22,7 +21,7 @@ type InteractionActionReceipt = BrowserActionReceipt | ComputerActionReceipt;
 type InteractionLifecycleMutation =
   | BrowserSessionMutationResponse
   | ComputerSessionMutationResponse;
-type AuthMutation = AuthRunMutationResponse | ProtectedAuthFillResponse;
+type AuthMutation = AuthRunMutationResponse;
 
 const STALE_INTERACTION_ERROR_CODES = new Set([
   "controller_stale",
@@ -52,6 +51,7 @@ export function observeBrowserActionResult(
     operation: "act",
     mode: browserActionMode(request.action),
     outcome: actionReceiptOutcome(receipt),
+    reason: actionReceiptReason(receipt),
     durationMs: elapsedMs(startedAtMs),
   });
 }
@@ -67,6 +67,7 @@ export function observeComputerActionResult(
     operation: "act",
     mode: computerActionMode(request.action.type),
     outcome: actionReceiptOutcome(receipt),
+    reason: actionReceiptReason(receipt),
     durationMs: elapsedMs(startedAtMs),
   });
 }
@@ -102,6 +103,7 @@ export function observeLifecycleResult(
     operation: response.operation.kind,
     mode: "lifecycle",
     outcome: actionReceiptOutcome(response.operation),
+    reason: actionReceiptReason(response.operation),
     durationMs: elapsedMs(startedAtMs),
     replayed: response.operation.replayed,
   });
@@ -184,6 +186,166 @@ function actionReceiptOutcome(receipt: Pick<InteractionActionReceipt, "state" |
   return receipt.state;
 }
 
+function actionReceiptReason(receipt: Pick<InteractionActionReceipt, "state" | "error">): string {
+  if (receipt.state !== "failed") return "none";
+  const code = receipt.error?.code;
+  return code && INTERACTION_ERROR_REASONS.has(code) ? code : "action_failed";
+}
+
 function elapsedMs(startedAtMs: number): number {
   return Math.max(0, performance.now() - startedAtMs);
 }
+
+type InteractionRouteOperation = {
+  resource: "browser" | "computer";
+  operation: string;
+  mode: string;
+  /** The handler already records its successful outcome from the receipt. */
+  successObservedByHandler: boolean;
+};
+
+const BROWSER = "/v1/workspaces/:workspaceId/browser-sessions";
+const COMPUTER = "/v1/workspaces/:workspaceId/computer-sessions";
+const B = `${BROWSER}/:browserSessionId`;
+const C = `${COMPUTER}/:computerSessionId`;
+
+/**
+ * Every Browser/Computer control route the product depends on, keyed by
+ * `METHOD route-label`. Read-only listing/detail routes are deliberately
+ * absent: they are not user-visible operations and stay in the generic HTTP
+ * metrics.
+ */
+const INTERACTION_ROUTE_OPERATIONS = new Map<string, InteractionRouteOperation>(
+  (
+    [
+      ["POST", BROWSER, "browser", "create", "lifecycle", true],
+      ["GET", `${B}/targets`, "browser", "observe", "semantic", false],
+      ["POST", `${B}/targets`, "browser", "open_target", "lifecycle", false],
+      ["POST", `${B}/targets/:targetId/select`, "browser", "select_target", "lifecycle", false],
+      ["DELETE", `${B}/targets/:targetId`, "browser", "close_target", "lifecycle", false],
+      ["GET", `${B}/targets/:targetId/observation`, "browser", "observe", "semantic", false],
+      ["GET", `${B}/targets/:targetId/state`, "browser", "observe", "semantic", false],
+      ["POST", `${B}/targets/:targetId/dom-read`, "browser", "observe", "semantic", false],
+      ["GET", `${B}/targets/:targetId/screenshot`, "browser", "observe", "media", false],
+      ["POST", `${B}/actions`, "browser", "act", "semantic", true],
+      ["POST", `${B}/auth-runs`, "browser", "auth_start", "auth", true],
+      ["POST", `${B}/auth-runs/:authRunId/report`, "browser", "auth_report", "auth", true],
+      ["POST", `${B}/auth-runs/:authRunId/external-auth`, "browser", "auth_start", "auth", true],
+      [
+        "POST",
+        `${B}/auth-runs/:authRunId/external-auth/interactive`,
+        "browser",
+        "auth_start",
+        "auth",
+        true,
+      ],
+      ["POST", `${B}/auth-runs/:authRunId/verify`, "browser", "auth_verify", "auth", true],
+      ["POST", `${B}/attachments`, "browser", "attach", "human", false],
+      ["POST", `${B}/revisions`, "browser", "publish", "lifecycle", true],
+      ["POST", `${B}/suspend`, "browser", "suspend", "lifecycle", true],
+      ["POST", `${B}/resume`, "browser", "resume", "lifecycle", true],
+      ["POST", `${B}/end`, "browser", "end", "lifecycle", true],
+      ["POST", COMPUTER, "computer", "create", "lifecycle", true],
+      ["GET", `${C}/targets`, "computer", "observe", "semantic", false],
+      ["GET", `${C}/targets/:targetId/observation`, "computer", "observe", "semantic", false],
+      ["GET", `${C}/targets/:targetId/screenshot`, "computer", "observe", "media", false],
+      ["POST", `${C}/actions`, "computer", "act", "semantic", true],
+      ["POST", `${C}/attachments`, "computer", "attach", "human", false],
+      ["POST", `${C}/end`, "computer", "end", "lifecycle", true],
+    ] as const
+  ).map(([method, route, resource, operation, mode, successObservedByHandler]) => [
+    `${method} ${route}`,
+    { resource, operation, mode, successObservedByHandler },
+  ]),
+);
+
+export function interactionRouteOperation(
+  method: string,
+  route: string,
+): InteractionRouteOperation | null {
+  return INTERACTION_ROUTE_OPERATIONS.get(`${method} ${route}`) ?? null;
+}
+
+const INTERACTION_ERROR_REASONS = new Set([
+  "resource_not_found",
+  "resource_unavailable",
+  "controller_stale",
+  "target_not_found",
+  "target_stale",
+  "observation_stale",
+  "document_stale",
+  "frame_stale",
+  "locator_not_found",
+  "locator_ambiguous",
+  "unsupported",
+  "permission_denied",
+  "machine_locked",
+  "attempt_stale",
+  "operation_conflict",
+  "outcome_unknown",
+  "invalid_action",
+  "timeout",
+  "controller_lost",
+  "driver_failed",
+]);
+
+/**
+ * Bounded failure reason for a refused or failed interaction route, derived
+ * only from the HTTP status and the content-free rejection classification.
+ */
+export function interactionRouteFailureReason(
+  status: number,
+  rejectionReason: string | undefined,
+): string {
+  if (rejectionReason?.startsWith("permission:")) return "permission_denied";
+  if (rejectionReason?.startsWith("control:")) return rejectionReason.replace(":", "_");
+  if (rejectionReason && INTERACTION_ERROR_REASONS.has(rejectionReason)) return rejectionReason;
+  if (rejectionReason && STALE_INTERACTION_ERROR_CODES.has(rejectionReason)) return "stale";
+  if (status === 401) return "unauthenticated";
+  if (status === 403) return "access_denied";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 400 || status === 422) return "invalid_request";
+  if (status === 429) return "rate_limited";
+  if (status === 504) return "timeout";
+  if (status === 502 || status === 503) return "unavailable";
+  return status >= 500 ? "internal" : "rejected";
+}
+
+/**
+ * Observe the HTTP-level outcome of an interaction route. Routes whose handler
+ * already records success from its receipt are counted here only on failure,
+ * so every attempt is counted exactly once.
+ */
+export function observeInteractionRouteOutcome(
+  observability: Observability | null | undefined,
+  input: {
+    method: string;
+    route: string;
+    status: number;
+    durationMs: number;
+    rejectionReason?: string | undefined;
+  },
+): void {
+  const operation = interactionRouteOperation(input.method, input.route);
+  if (!operation) return;
+  const failed = input.status >= 400;
+  if (!failed && operation.successObservedByHandler) return;
+  const reason = failed
+    ? interactionRouteFailureReason(input.status, input.rejectionReason)
+    : "none";
+  interactionOperationMetricObserver(observability)({
+    resource: operation.resource,
+    operation: operation.operation,
+    mode: operation.mode,
+    outcome: !failed
+      ? "completed"
+      : reason === "stale" || STALE_INTERACTION_ERROR_CODES.has(reason)
+        ? "stale"
+        : input.status === 401 || input.status === 403
+          ? "denied"
+          : "failed",
+    reason,
+    durationMs: input.durationMs,
+  });
+}

package/src/interaction-route-stages.ts

@@ -0,0 +1,94 @@
+import type { Observability } from "@opengeni/observability";
+import type { Context } from "hono";
+
+/** Fixed stage names, so the histogram label stays bounded. */
+export type InteractionRouteStage =
+  | "auth"
+  | "record"
+  | "authorize"
+  | "source_session"
+  | "control"
+  | "placement_cache"
+  | "placement_resolve"
+  | "placement_cache_write"
+  | "placement"
+  | "fences"
+  | "passkey_pre"
+  | "secrets"
+  | "dispatch"
+  | "passkey_post"
+  // Browser creation (open) stages.
+  | "replay_check"
+  | "prepare"
+  | "restore"
+  | "network_route"
+  | "holder"
+  | "generation"
+  | "provision"
+  | "display"
+  | "launch"
+  | "activate";
+
+export type InteractionRouteStageOperation = "act" | "observe" | "target_state" | "create";
+
+/**
+ * Wall-clock split of one browser control request into its sequential stages.
+ * `mark(stage)` closes the stage that ran since the previous mark. Stages that
+ * run more than once (a recovery retry) accumulate. The split is reported as a
+ * content-free `Server-Timing` header and a per-stage histogram, so harness
+ * overhead around the controller's own work stays visible.
+ */
+export class InteractionRouteStages {
+  private last: number;
+  private readonly durations = new Map<InteractionRouteStage, number>();
+
+  constructor(
+    readonly operation: InteractionRouteStageOperation,
+    private readonly now: () => number = () => performance.now(),
+  ) {
+    this.last = now();
+  }
+
+  mark(stage: InteractionRouteStage): void {
+    const at = this.now();
+    this.durations.set(stage, (this.durations.get(stage) ?? 0) + Math.max(0, at - this.last));
+    this.last = at;
+  }
+
+  entries(): Array<[InteractionRouteStage, number]> {
+    return [...this.durations.entries()];
+  }
+
+  serverTiming(): string {
+    return this.entries()
+      .map(([stage, ms]) => `browser-${stage.replaceAll("_", "-")};dur=${ms.toFixed(1)}`)
+      .join(", ");
+  }
+
+  observe(observability: Observability | null | undefined): void {
+    if (!observability) return;
+    try {
+      for (const [stage, ms] of this.entries()) {
+        observability.observeHistogram({
+          name: "opengeni_interaction_route_stage_seconds",
+          help: "Browser control request wall time by sequential stage, around the controller's own work.",
+          labels: { resource: "browser", operation: this.operation, stage },
+          value: ms / 1_000,
+        });
+      }
+    } catch {
+      // Timing never changes a control request's outcome.
+    }
+  }
+}
+
+/** Attach the stage split to the response and the stage histogram. */
+export function reportInteractionRouteStages(
+  context: Context,
+  observability: Observability | null | undefined,
+  stages: InteractionRouteStages,
+): void {
+  const timing = stages.serverTiming();
+  if (timing) context.header("server-timing", timing, { append: true });
+  stages.observe(observability);
+}