@opengeni/api-router 2.6.4 → 2.10.0-canary.0

package/src/workspace-artifact-content.ts

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+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: string;
+  sizeBytes: number;
+  sourceKey: string;
+  sourceSha256: string;
+  sourceSizeBytes: number;
+  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 = WorkspaceArtifactSourceBundle.parse(input.source ?? sourceBundleFromHtml(html));
+  const requestedTools =
+    input.requestedTools === undefined
+      ? undefined
+      : WorkspaceArtifactRequestedTools.parse(input.requestedTools);
+  const contentBytes = encoder.encode(html);
+  const sourceBytes = encoder.encode(JSON.stringify(source));
+  const contentSha256 = sha256(contentBytes);
+  const sourceSha256 = sha256(sourceBytes);
+  const storageGroupId = crypto.randomUUID();
+  const contentKey = `workspaces/${workspaceId}/workspace-artifacts/blobs/${storageGroupId}-${contentSha256}.html`;
+  const sourceKey = `workspaces/${workspaceId}/workspace-artifacts/sources/${storageGroupId}-${sourceSha256}.json`;
+  const discardContent = async (): Promise<void> => {
+    await Promise.allSettled([
+      objectStorage.deleteObject(contentKey),
+      objectStorage.deleteObject(sourceKey),
+    ]);
+  };
+  return {
+    contentKey,
+    contentSha256,
+    sizeBytes: contentBytes.byteLength,
+    sourceKey,
+    sourceSha256,
+    sourceSizeBytes: sourceBytes.byteLength,
+    ...(requestedTools === undefined ? {} : { requestedTools }),
+    discardContent,
+    persistContent: async () => {
+      const writes = await Promise.allSettled([
+        objectStorage.putObject({
+          key: contentKey,
+          contentType: "text/html; charset=utf-8",
+          body: contentBytes,
+          sha256: contentSha256,
+        }),
+        objectStorage.putObject({
+          key: sourceKey,
+          contentType: "application/json; charset=utf-8",
+          body: sourceBytes,
+          sha256: sourceSha256,
+        }),
+      ]);
+      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");
+  if (
+    sha256(contentObject.bytes) !== input.version.contentSha256 ||
+    contentObject.bytes.byteLength !== input.version.sizeBytes
+  ) {
+    throw new Error("Artifact content failed integrity verification");
+  }
+  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");
+    if (
+      !input.version.sourceSha256 ||
+      input.version.sourceSizeBytes === null ||
+      sha256(sourceObject.bytes) !== input.version.sourceSha256 ||
+      sourceObject.bytes.byteLength !== input.version.sourceSizeBytes
+    ) {
+      throw new Error("Artifact source failed integrity verification");
+    }
+    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 sha256(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+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-deletion.ts

@@ -0,0 +1,64 @@
+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" });
+    }
+    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,
+  );
+}

package/src/workspace-tool-gateway-observability.ts

@@ -0,0 +1,100 @@
+import type { ToolGatewayCatalogEntry } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+
+export type WorkspaceToolGatewayAdapter = "http" | "mcp";
+export type WorkspaceToolGatewayOperation = "approval" | "call";
+export type WorkspaceToolGatewayOutcome =
+  | "ok"
+  | "tool_error"
+  | "approval_required"
+  | "catalog_stale"
+  | "invalid_input"
+  | "not_found"
+  | "rate_limited"
+  | "failed";
+
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
+
+/**
+ * Low-cardinality gateway telemetry shared by HTTP/SDK/Site and aggregate MCP
+ * adapters. Tool names, workspace/subject ids, arguments, results, credentials,
+ * and approval tokens are excluded by construction.
+ */
+export function startWorkspaceToolGatewayObservation(
+  observability: Observability | null | undefined,
+  input: {
+    adapter: WorkspaceToolGatewayAdapter;
+    operation: WorkspaceToolGatewayOperation;
+    source: ToolGatewayCatalogEntry["source"] | "aggregate";
+  },
+): { end: (outcome: WorkspaceToolGatewayOutcome) => void } {
+  const startedAt = performance.now();
+  let span: ReturnType<Observability["startSpan"]> | undefined;
+  try {
+    span = observability?.startSpan("opengeni.tool_gateway.operation", {
+      surface: "workspace_tool_gateway",
+      op: `${input.adapter}.${input.operation}`,
+      provider: input.source,
+    });
+  } catch {
+    // Telemetry must never change gateway execution truth.
+  }
+  let ended = false;
+  return {
+    end: (outcome) => {
+      if (ended) return;
+      ended = true;
+      const durationMs = Math.max(0, performance.now() - startedAt);
+      try {
+        observability?.incrementCounter({
+          name: "opengeni_tool_gateway_operations_total",
+          help: "Workspace tool gateway operations by bounded adapter, operation, source, and outcome.",
+          labels: {
+            adapter: input.adapter,
+            operation: input.operation,
+            source: input.source,
+            outcome,
+          },
+        });
+        observability?.observeHistogram({
+          name: "opengeni_tool_gateway_operation_duration_seconds",
+          help: "Workspace tool gateway operation duration in seconds.",
+          labels: {
+            adapter: input.adapter,
+            operation: input.operation,
+            source: input.source,
+          },
+          buckets: DURATION_BUCKETS,
+          value: durationMs / 1_000,
+        });
+        observability?.info("Workspace tool gateway operation completed", {
+          surface: "workspace_tool_gateway",
+          op: `${input.adapter}.${input.operation}`,
+          provider: input.source,
+          outcome,
+          durationMs: Math.round(durationMs),
+        });
+      } catch {
+        try {
+          observability?.incrementCounter({
+            name: "opengeni_observability_observer_errors_total",
+            help: "Observability observer failures isolated from product execution.",
+            labels: { observer: "workspace_tool_gateway" },
+          });
+        } catch {
+          // Telemetry must never change gateway execution truth.
+        }
+      }
+      try {
+        span?.end({
+          attributes: {
+            outcome,
+            "opengeni.duration_ms": Math.round(durationMs),
+          },
+        });
+      } catch {
+        // Telemetry must never change gateway execution truth.
+      }
+    },
+  };
+}