@opengeni/api-router 0.30.3 → 1.0.0

package/src/work-discovery-observability.ts

@@ -0,0 +1,121 @@
+import type { WorkDiscoveryMatchClass } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+
+export type WorkDiscoverySurface = "first_party_mcp" | "agent_topology";
+export type WorkDiscoveryMode = "browse" | "query" | "subject";
+export type WorkDiscoveryOutcome = "ok" | "empty" | "disabled" | "error";
+export type WorkDiscoveryAuthorizationScope = "workspace" | "scoped";
+
+export type WorkDiscoveryObservation = {
+  surface: WorkDiscoverySurface;
+  mode: WorkDiscoveryMode;
+  outcome: WorkDiscoveryOutcome;
+  authorizationScope: WorkDiscoveryAuthorizationScope;
+  durationMs: number;
+  responseBytes: number;
+  resultCount: number;
+  overlapCount: number;
+  matchCounts: Partial<Record<WorkDiscoveryMatchClass, number>>;
+};
+
+type WorkDiscoveryObservedRow = {
+  relatedWork?: {
+    match: { class: WorkDiscoveryMatchClass } | null;
+    possibleOverlap: boolean;
+  };
+};
+
+const RESULT_BUCKETS = [0, 1, 2, 4, 8, 16, 32, 64, 100];
+const RESPONSE_BYTE_BUCKETS = [512, 1_024, 4_096, 16_384, 65_536, 128_000, 262_144];
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5];
+
+export function summarizeWorkDiscoveryRows(
+  rows: readonly WorkDiscoveryObservedRow[],
+): Pick<WorkDiscoveryObservation, "resultCount" | "overlapCount" | "matchCounts"> {
+  const matchCounts: WorkDiscoveryObservation["matchCounts"] = {};
+  let overlapCount = 0;
+  for (const row of rows) {
+    if (row.relatedWork?.possibleOverlap) overlapCount += 1;
+    const matchClass = row.relatedWork?.match?.class;
+    if (matchClass) matchCounts[matchClass] = (matchCounts[matchClass] ?? 0) + 1;
+  }
+  return { resultCount: rows.length, overlapCount, matchCounts };
+}
+
+/**
+ * Low-cardinality work-discovery telemetry. Identifiers, search text, subject
+ * keys, titles, goals, claim labels, versions, and provenance are excluded by
+ * construction. An observability failure never changes product behavior.
+ */
+export function observeWorkDiscovery(
+  observability: Observability | null | undefined,
+  observation: WorkDiscoveryObservation,
+): void {
+  if (!observability) return;
+  const labels = {
+    surface: observation.surface,
+    mode: observation.mode,
+    outcome: observation.outcome,
+    authorization_scope: observation.authorizationScope,
+  };
+  try {
+    observability.incrementCounter({
+      name: "opengeni_work_discovery_requests_total",
+      help: "Advisory work-discovery requests by bounded surface, mode, outcome, and authorization scope.",
+      labels,
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_duration_seconds",
+      help: "Advisory work-discovery request duration in seconds.",
+      labels,
+      buckets: DURATION_BUCKETS,
+      value: Math.max(0, observation.durationMs) / 1_000,
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_results",
+      help: "Bounded advisory work-discovery result rows per request.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESULT_BUCKETS,
+      value: Math.max(0, Math.floor(observation.resultCount)),
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_response_bytes",
+      help: "Serialized advisory work-discovery response bytes.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESPONSE_BYTE_BUCKETS,
+      value: Math.max(0, Math.floor(observation.responseBytes)),
+    });
+    if (observation.overlapCount > 0) {
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_overlap_results_total",
+        help: "Advisory discovery rows carrying a possible-overlap explanation.",
+        labels: { surface: observation.surface, mode: observation.mode },
+        amount: Math.floor(observation.overlapCount),
+      });
+    }
+    for (const matchClass of ["exact_subject", "title", "goal", "fuzzy"] as const) {
+      const amount = Math.floor(observation.matchCounts[matchClass] ?? 0);
+      if (amount < 1) continue;
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_matches_total",
+        help: "Advisory discovery matches by stable explanation class.",
+        labels: {
+          surface: observation.surface,
+          mode: observation.mode,
+          match_class: matchClass,
+        },
+        amount,
+      });
+    }
+  } catch {
+    try {
+      observability.incrementCounter({
+        name: "opengeni_observability_observer_errors_total",
+        help: "Observability observer failures isolated from product execution.",
+        labels: { observer: "work_discovery" },
+      });
+    } catch {
+      // The metrics registry itself is unhealthy. Discovery remains authoritative.
+    }
+  }
+}

package/src/workspace-artifact-content.ts

@@ -0,0 +1,144 @@
+import {
+  WorkspaceArtifactHtml,
+  WorkspaceArtifactRequestedTools,
+  WorkspaceArtifactSourceBundle,
+  type ToolGatewayIdentity,
+  type WorkspaceArtifactSourceBundle as WorkspaceArtifactSourceBundleValue,
+  type WorkspaceArtifactVersion,
+} from "@opengeni/contracts";
+import type { ObjectStorageDependency } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+export type PreparedWorkspaceArtifactContent = {
+  contentKey: string;
+  contentSha256: null;
+  sizeBytes: number;
+  sourceKey: string | null;
+  sourceSha256: null;
+  sourceSizeBytes: number | null;
+  requestedTools?: ToolGatewayIdentity[];
+  persistContent: () => Promise<void>;
+  discardContent: () => Promise<void>;
+};
+
+export function prepareWorkspaceArtifactContent(
+  objectStorage: NonNullable<ObjectStorageDependency>,
+  workspaceId: string,
+  input: {
+    html: string;
+    source?: WorkspaceArtifactSourceBundleValue;
+    requestedTools?: ToolGatewayIdentity[];
+  },
+): PreparedWorkspaceArtifactContent {
+  const html = WorkspaceArtifactHtml.parse(input.html);
+  const source = input.source ? WorkspaceArtifactSourceBundle.parse(input.source) : null;
+  const requestedTools =
+    input.requestedTools === undefined
+      ? undefined
+      : WorkspaceArtifactRequestedTools.parse(input.requestedTools);
+  const contentBytes = encoder.encode(html);
+  const sourceBytes = source ? encoder.encode(JSON.stringify(source)) : null;
+  const contentSha256 = null;
+  const sourceSha256 = null;
+  const storageGroupId = crypto.randomUUID();
+  const contentKey = `workspaces/${workspaceId}/workspace-artifacts/blobs/${storageGroupId}.html`;
+  const sourceKey = `workspaces/${workspaceId}/workspace-artifacts/sources/${storageGroupId}.json`;
+  const discardContent = async (): Promise<void> => {
+    await Promise.allSettled([
+      objectStorage.deleteObject(contentKey),
+      ...(source ? [objectStorage.deleteObject(sourceKey)] : []),
+    ]);
+  };
+  return {
+    contentKey,
+    contentSha256,
+    sizeBytes: contentBytes.byteLength,
+    sourceKey: source ? sourceKey : null,
+    sourceSha256,
+    sourceSizeBytes: sourceBytes?.byteLength ?? null,
+    ...(requestedTools === undefined ? {} : { requestedTools }),
+    discardContent,
+    persistContent: async () => {
+      const writes = await Promise.allSettled([
+        objectStorage.putObject({
+          key: contentKey,
+          contentType: "text/html; charset=utf-8",
+          body: contentBytes,
+        }),
+        sourceBytes
+          ? objectStorage.putObject({
+              key: sourceKey,
+              contentType: "application/json; charset=utf-8",
+              body: sourceBytes,
+            })
+          : Promise.resolve(),
+      ]);
+      const failed = writes.find((write) => write.status === "rejected");
+      if (!failed) return;
+      await Promise.allSettled(
+        writes.flatMap((write, index) =>
+          write.status === "fulfilled"
+            ? [objectStorage.deleteObject(index === 0 ? contentKey : sourceKey)]
+            : [],
+        ),
+      );
+      throw failed.reason;
+    },
+  };
+}
+
+export async function readWorkspaceArtifactContent(
+  objectStorage: NonNullable<ObjectStorageDependency>,
+  input: {
+    contentKey: string;
+    sourceKey: string | null;
+    version: WorkspaceArtifactVersion;
+  },
+): Promise<{
+  html: string;
+  source: WorkspaceArtifactSourceBundleValue;
+  requestedTools: ToolGatewayIdentity[];
+}> {
+  const [contentObject, sourceObject] = await Promise.all([
+    retryWhileMissing(async () => await objectStorage.getObjectBytes(input.contentKey)),
+    input.sourceKey
+      ? retryWhileMissing(async () => await objectStorage.getObjectBytes(input.sourceKey!))
+      : Promise.resolve(null),
+  ]);
+  if (!contentObject) throw new Error("Artifact content is unavailable");
+  const html = decode(contentObject.bytes, "Artifact content is not valid UTF-8");
+  let source = sourceBundleFromHtml(html);
+  if (input.sourceKey) {
+    if (!sourceObject) throw new Error("Artifact source is unavailable");
+    try {
+      source = WorkspaceArtifactSourceBundle.parse(
+        JSON.parse(decode(sourceObject.bytes, "Artifact source is not valid UTF-8")),
+      );
+    } catch (error) {
+      if (error instanceof Error && error.message === "Artifact source is not valid UTF-8") {
+        throw error;
+      }
+      throw new Error("Artifact source is invalid", { cause: error });
+    }
+  }
+  return {
+    html,
+    source,
+    requestedTools: WorkspaceArtifactRequestedTools.parse(input.version.requestedTools),
+  };
+}
+
+export function sourceBundleFromHtml(html: string): WorkspaceArtifactSourceBundleValue {
+  return { entrypoint: "index.html", files: [{ path: "index.html", content: html }] };
+}
+
+function decode(bytes: Uint8Array, message: string): string {
+  try {
+    return decoder.decode(bytes);
+  } catch (error) {
+    throw new Error(message, { cause: error });
+  }
+}

package/src/workspace-artifact-provenance.ts

@@ -0,0 +1,104 @@
+import type {
+  WorkspaceArtifactDetailResponse,
+  WorkspaceArtifactListResponse,
+  WorkspaceArtifactMutationResponse,
+  WorkspaceArtifactVersion,
+} from "@opengeni/contracts";
+
+type ArtifactProvenance = {
+  sourceSessionId: string | null;
+  sourceTurnId: string | null;
+  sourceAttemptId: string | null;
+  sourceExecutionGeneration: number | null;
+};
+
+type CanReadSession = (sessionId: string) => Promise<boolean>;
+
+function redactProvenance<Value extends ArtifactProvenance>(value: Value): Value {
+  return {
+    ...value,
+    sourceSessionId: null,
+    sourceTurnId: null,
+    sourceAttemptId: null,
+    sourceExecutionGeneration: null,
+  };
+}
+
+function artifactProvenanceProjector(canReadSession: CanReadSession) {
+  const decisions = new Map<string, Promise<boolean>>();
+  const canRead = (sessionId: string): Promise<boolean> => {
+    const existing = decisions.get(sessionId);
+    if (existing) return existing;
+    const decision = canReadSession(sessionId);
+    decisions.set(sessionId, decision);
+    return decision;
+  };
+  return async <Value extends ArtifactProvenance>(value: Value): Promise<Value> => {
+    if (!value.sourceSessionId || (await canRead(value.sourceSessionId))) return value;
+    return redactProvenance(value);
+  };
+}
+
+export function redactWorkspaceArtifactListProvenance(
+  response: WorkspaceArtifactListResponse,
+): WorkspaceArtifactListResponse {
+  return {
+    ...response,
+    artifacts: response.artifacts.map((artifact) => ({
+      ...artifact,
+      currentVersion: artifact.currentVersion ? redactProvenance(artifact.currentVersion) : null,
+    })),
+  };
+}
+
+export async function projectWorkspaceArtifactVersionProvenance(
+  version: WorkspaceArtifactVersion,
+  canReadSession: CanReadSession,
+): Promise<WorkspaceArtifactVersion> {
+  return await artifactProvenanceProjector(canReadSession)(version);
+}
+
+export async function projectWorkspaceArtifactDetailProvenance(
+  detail: WorkspaceArtifactDetailResponse,
+  canReadSession: CanReadSession,
+): Promise<WorkspaceArtifactDetailResponse> {
+  const project = artifactProvenanceProjector(canReadSession);
+  const [currentVersion, versions, events] = await Promise.all([
+    detail.artifact.currentVersion ? project(detail.artifact.currentVersion) : null,
+    Promise.all(detail.versions.map(project)),
+    Promise.all(detail.events.map(project)),
+  ]);
+  return {
+    ...detail,
+    artifact: { ...detail.artifact, currentVersion },
+    versions,
+    events,
+  };
+}
+
+export async function projectWorkspaceArtifactMutationProvenance(
+  response: WorkspaceArtifactMutationResponse,
+  canReadSession: CanReadSession,
+): Promise<WorkspaceArtifactMutationResponse> {
+  // The mutation is already durable before this response projection runs. A
+  // transient source-session lookup must fail closed to redaction rather than
+  // turn a committed, idempotent mutation into an ambiguous HTTP/tool error.
+  const project = artifactProvenanceProjector(async (sessionId) => {
+    try {
+      return await canReadSession(sessionId);
+    } catch {
+      return false;
+    }
+  });
+  const [currentVersion, version, event] = await Promise.all([
+    response.artifact.currentVersion ? project(response.artifact.currentVersion) : null,
+    project(response.version),
+    project(response.event),
+  ]);
+  return {
+    ...response,
+    artifact: { ...response.artifact, currentVersion },
+    version,
+    event,
+  };
+}

package/src/workspace-delete-observability.ts

@@ -0,0 +1,75 @@
+import type { WorkspaceDeleteObservation, WorkspaceDeleteObserver } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+
+const DURATION_BUCKETS = [
+  0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600, 1_200, 2_400,
+  3_600,
+];
+const INVENTORY_BUCKETS = [0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1_000, 5_000, 10_000];
+
+function recordWorkspaceDeleteObservation(
+  observability: Observability,
+  identity: { accountId: string; workspaceId: string },
+  observation: WorkspaceDeleteObservation,
+): void {
+  const labels = { phase: observation.phase, outcome: observation.outcome };
+  observability.observeHistogram({
+    name: "opengeni_workspace_delete_phase_seconds",
+    help: "Workspace deletion transaction and bounded internal phase duration in seconds.",
+    labels,
+    buckets: DURATION_BUCKETS,
+    value: Math.max(0, observation.durationSeconds),
+  });
+  if (observation.phase === "transaction") {
+    observability.incrementCounter({
+      name: "opengeni_workspace_delete_attempts_total",
+      help: "Workspace deletion attempts by terminal database outcome.",
+      labels: { outcome: observation.outcome },
+    });
+  }
+  for (const [kind, count] of Object.entries(observation.inventory ?? {})) {
+    observability.observeHistogram({
+      name: "opengeni_workspace_delete_inventory_rows",
+      help: "Rows or live owners observed by workspace deletion preflight inventory class.",
+      labels: { kind },
+      buckets: INVENTORY_BUCKETS,
+      value: Math.max(0, Math.floor(count ?? 0)),
+    });
+  }
+  observability.info("Workspace deletion phase", {
+    accountId: identity.accountId,
+    workspaceId: identity.workspaceId,
+    phase: observation.phase,
+    outcome: observation.outcome,
+    durationSeconds: observation.durationSeconds,
+    inventoryJson: JSON.stringify(observation.inventory ?? {}),
+  });
+}
+
+/**
+ * Retain exact workspace deletion timing and inventory without putting tenant
+ * identifiers in metric labels. Observer failures never change deletion truth.
+ */
+export function workspaceDeleteObserver(
+  observability: Observability | null | undefined,
+  identity: { accountId: string; workspaceId: string },
+): WorkspaceDeleteObserver | undefined {
+  if (!observability) return undefined;
+  return {
+    onPhase: (observation) => {
+      try {
+        recordWorkspaceDeleteObservation(observability, identity, observation);
+      } catch {
+        try {
+          observability.incrementCounter({
+            name: "opengeni_observability_observer_errors_total",
+            help: "Observability observer failures isolated from product execution.",
+            labels: { observer: "workspace_delete" },
+          });
+        } catch {
+          // The metrics registry itself is unhealthy. Deletion remains authoritative.
+        }
+      }
+    },
+  };
+}

package/src/workspace-deletion.ts

@@ -0,0 +1,73 @@
+import { deleteWorkspaceIfQuiescent, nestedPostgresSqlState } from "@opengeni/db";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { HTTPException } from "hono/http-exception";
+
+import { processTemporalScheduleCleanupClaims } from "./temporal-schedule-cleanup";
+import { workspaceDeleteObserver } from "./workspace-delete-observability";
+
+export async function deleteWorkspaceForRequest(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    organizationAdministratorSubjectId?: string;
+  },
+): Promise<void> {
+  const observer = workspaceDeleteObserver(deps.observability, input);
+  let deleted;
+  try {
+    deleted = await deleteWorkspaceIfQuiescent(deps.db, {
+      ...input,
+      ...(observer ? { observer } : {}),
+    });
+  } catch (error) {
+    const state = nestedPostgresSqlState(error);
+    if (state === "42501") {
+      throw new HTTPException(403, { message: "organization administration is not authorized" });
+    }
+    if (state === "P0002") {
+      throw new HTTPException(404, { message: "workspace not found" });
+    }
+    if (state === "23503") {
+      // Retention and linked-record FKs are intentional deletion boundaries.
+      // The failed transaction has rolled back: do not erase history, retry
+      // the cascade, or dispatch any external schedule cleanup.
+      throw new HTTPException(409, {
+        message:
+          "workspace deletion is blocked by retained or linked records; keep the workspace, revoke access, and disable scheduled work instead",
+      });
+    }
+    throw error;
+  }
+
+  if (deleted.status === "not_found") {
+    throw new HTTPException(404, { message: "workspace not found" });
+  }
+  const conflicts = {
+    only_workspace: "cannot delete the account's only workspace",
+    active_sessions: "stop the workspace's running sessions before deleting it",
+    active_video_generations:
+      "wait for the workspace's active video generations to finish before deleting it",
+    active_background_commands:
+      "pause or cancel the workspace's background commands before deleting it",
+    live_sandboxes:
+      "wait for the workspace's active sandboxes to finish draining before deleting it",
+  } as const;
+  if (deleted.status in conflicts) {
+    throw new HTTPException(409, { message: conflicts[deleted.status as keyof typeof conflicts] });
+  }
+  if (deleted.status !== "deleted") {
+    throw new Error(`Unhandled workspace deletion outcome: ${deleted.status}`);
+  }
+
+  await processTemporalScheduleCleanupClaims(
+    {
+      db: deps.db,
+      deleteSchedule: async (temporalScheduleId) => {
+        await deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId });
+      },
+      ...(deps.observability ? { observability: deps.observability } : {}),
+    },
+    deleted.temporalScheduleCleanups,
+  );
+}