@opengeni/core 0.28.1 → 1.0.0

package/src/product-usage-metrics.ts

@@ -0,0 +1,101 @@
+import { SESSION_TURN_SURFACES, type SessionTurnSurface } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+
+/**
+ * Live, content-free product usage counters recorded where work is accepted.
+ * Every label is a closed set: the product surface (or `unknown` when no
+ * surface was captured), who created a session (`subject` or `service`), and
+ * whether the session is a root. No workspace, user, model or text value ever
+ * becomes a label.
+ */
+export type ProductUsageMetricsSink = Pick<Observability, "incrementCounter">;
+
+export const PRODUCT_USAGE_SURFACE_LABELS = [...SESSION_TURN_SURFACES, "unknown"] as const;
+export type ProductUsageSurfaceLabel = (typeof PRODUCT_USAGE_SURFACE_LABELS)[number];
+export const SESSION_CREATED_BY_KINDS = ["subject", "service"] as const;
+export type SessionCreatedByKind = (typeof SESSION_CREATED_BY_KINDS)[number];
+
+const SESSIONS_CREATED_METRIC = {
+  name: "opengeni_sessions_created_total",
+  help: "Sessions created by product surface, creator kind, and whether they are root sessions.",
+} as const;
+const USER_MESSAGES_METRIC = {
+  name: "opengeni_user_messages_total",
+  help: "Accepted user messages and scheduled prompts by product surface.",
+} as const;
+
+export function productUsageSurfaceLabel(
+  surface: SessionTurnSurface | null | undefined,
+): ProductUsageSurfaceLabel {
+  return surface && (SESSION_TURN_SURFACES as readonly string[]).includes(surface)
+    ? surface
+    : "unknown";
+}
+
+function sessionCreatedByKind(kind: string | null | undefined): SessionCreatedByKind {
+  return kind === "subject" ? "subject" : "service";
+}
+
+/** Count one newly created session. Never throws; replays must not call it. */
+export function recordSessionCreated(
+  sink: ProductUsageMetricsSink | null | undefined,
+  input: {
+    surface: SessionTurnSurface | null | undefined;
+    createdByKind: string | null | undefined;
+    parentSessionId: string | null | undefined;
+  },
+): void {
+  try {
+    sink?.incrementCounter({
+      ...SESSIONS_CREATED_METRIC,
+      labels: {
+        surface: productUsageSurfaceLabel(input.surface),
+        created_by_kind: sessionCreatedByKind(input.createdByKind),
+        root: input.parentSessionId ? "false" : "true",
+      },
+    });
+  } catch {
+    // Telemetry must never change the create outcome.
+  }
+}
+
+/** Count one newly accepted user message. Never throws; replays must not call it. */
+export function recordUserMessageAccepted(
+  sink: ProductUsageMetricsSink | null | undefined,
+  input: { surface: SessionTurnSurface | null | undefined },
+): void {
+  try {
+    sink?.incrementCounter({
+      ...USER_MESSAGES_METRIC,
+      labels: { surface: productUsageSurfaceLabel(input.surface) },
+    });
+  } catch {
+    // Telemetry must never change the send outcome.
+  }
+}
+
+/**
+ * Publish every closed series at zero so dashboards can tell a quiet surface
+ * from missing instrumentation. Never throws.
+ */
+export function registerProductUsageMetricBaselines(
+  sink: ProductUsageMetricsSink | null | undefined,
+): void {
+  if (!sink) return;
+  try {
+    for (const surface of PRODUCT_USAGE_SURFACE_LABELS) {
+      sink.incrementCounter({ ...USER_MESSAGES_METRIC, labels: { surface }, amount: 0 });
+      for (const createdByKind of SESSION_CREATED_BY_KINDS) {
+        for (const root of ["true", "false"]) {
+          sink.incrementCounter({
+            ...SESSIONS_CREATED_METRIC,
+            labels: { surface, created_by_kind: createdByKind, root },
+            amount: 0,
+          });
+        }
+      }
+    }
+  } catch {
+    // Telemetry only; series appear on their first real increment.
+  }
+}

package/src/rigs/index.ts

@@ -11,6 +11,7 @@ import type {
   ProposeRigChangeRequest,
   Rig,
   RigChange,
+  ResourceAuthorityScope,
   RigVersion,
   UpdateRigRequest,
 } from "@opengeni/contracts";
@@ -21,7 +22,6 @@ import {
   createRigChange,
   createRigVersion,
   createRigVersionForChangePromotion,
-  deleteRigIfNoActiveSessions,
   getRig,
   getRigByName,
   getRigChange,
@@ -30,12 +30,15 @@ import {
   listRigChanges,
   listRigVersions,
   recordAuditEvent,
+  revokeScopedRig,
   RigActiveVersionChangedError,
   RigChangeTransitionError,
-  updateRig,
+  updateScopedRig,
   type Database,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
+import { boundedParallelMap } from "@opengeni/runtime/mcp-network";
+import { requirePermission } from "../access";
 import { rigProviderImagesFromVerification } from "./provider-images";
 
 export * from "./provider-images";
@@ -44,6 +47,34 @@ export const MAX_RIGS_PER_WORKSPACE = 50;
 export const MAX_CHECKS_PER_RIG = 100;
 export const MAX_CREDENTIAL_HOOKS_PER_RIG = 50;
 export const MAX_DEFAULT_VARIABLE_SETS_PER_RIG = 25;
+export const RIG_DEFAULT_VARIABLE_SET_LOAD_CONCURRENCY = 4;
+
+type VariableSetEnvironment = { values: Record<string, string> } | null;
+
+/** Load complete rig defaults concurrently while preserving listed precedence. */
+export async function loadRigDefaultVariableSetEnvironment(
+  variableSetIds: readonly string[],
+  load: (variableSetId: string) => Promise<VariableSetEnvironment>,
+): Promise<Record<string, string>> {
+  const variableSets = await boundedParallelMap(
+    variableSetIds,
+    RIG_DEFAULT_VARIABLE_SET_LOAD_CONCURRENCY,
+    load,
+  );
+  const values: Record<string, string> = {};
+  for (const variableSet of variableSets) {
+    Object.assign(values, variableSet?.values ?? {});
+  }
+  return values;
+}
+
+/** Rig defaults layer below the session's explicitly selected variable set. */
+export function mergeRigDefaultVariableSetEnvironment(
+  rigDefaultValues: Record<string, string>,
+  sessionValues: Record<string, string>,
+): Record<string, string> {
+  return { ...rigDefaultValues, ...sessionValues };
+}
 
 export type RigServices = {
   db: Database;
@@ -92,12 +123,12 @@ export function rigActorForGrant(grant: AccessGrant): string {
 
 export async function requireRigForApi(
   db: Database,
-  workspaceId: string,
+  grant: AccessGrant,
   rigId: string,
 ): Promise<Rig> {
-  const rig = await getRig(db, workspaceId, rigId);
+  const rig = await getRig(db, grant, rigId);
   if (!rig) {
-    throw new HTTPException(404, { message: "rig not found" });
+    throw new HTTPException(404, { message: "sandbox environment not found" });
   }
   return rig;
 }
@@ -112,7 +143,7 @@ export async function requireRigChangeForApi(
   // RLS + the workspace clause make a cross-workspace id indistinguishable from
   // missing; the rigId clause keeps the change addressable only under its rig.
   if (!change || change.rigId !== rigId) {
-    throw new HTTPException(404, { message: "rig change not found" });
+    throw new HTTPException(404, { message: "sandbox environment change not found" });
   }
   return change;
 }
@@ -120,7 +151,7 @@ export async function requireRigChangeForApi(
 function trimmedRigName(name: string): string {
   const trimmed = name.trim();
   if (!trimmed) {
-    throw new HTTPException(422, { message: "rig name is required" });
+    throw new HTTPException(422, { message: "sandbox environment name is required" });
   }
   return trimmed;
 }
@@ -133,7 +164,9 @@ function assertUniqueCheckNames(checks: ReadonlyArray<{ name: string }> | undefi
   const seen = new Set<string>();
   for (const check of checks) {
     if (seen.has(check.name)) {
-      throw new HTTPException(422, { message: `duplicate rig check name: ${check.name}` });
+      throw new HTTPException(422, {
+        message: `duplicate sandbox environment check name: ${check.name}`,
+      });
     }
     seen.add(check.name);
   }
@@ -143,47 +176,83 @@ function assertUniqueCheckNames(checks: ReadonlyArray<{ name: string }> | undefi
 // cross-workspace id indistinguishable from a missing one, so both map to 422.
 async function assertVariableSetsExist(
   db: Database,
-  workspaceId: string,
+  access: AccessGrant,
+  rigScope: ResourceAuthorityScope,
   ids: ReadonlyArray<string> | undefined,
 ): Promise<void> {
-  if (!ids || ids.length === 0) {
+  if (ids === undefined) {
+    return;
+  }
+  requirePermission(access, "variable-sets:attach");
+  if (ids.length === 0) {
     return;
   }
+  requirePermission(access, "variable-sets:use");
   const unique = [...new Set(ids)];
   for (const id of unique) {
-    const variableSet = await getVariableSet(db, workspaceId, id);
+    const variableSet = await getVariableSet(db, access, id);
     if (!variableSet) {
-      throw new HTTPException(422, { message: `unknown defaultVariableSetId: ${id}` });
+      throw new HTTPException(422, {
+        message: `unknown defaultVariableSetId: ${id}`,
+      });
+    }
+    if (!variableSetScopeAllowedForRig(rigScope, variableSet.scope)) {
+      throw new HTTPException(422, {
+        message: `${rigScope}-scoped sandbox environments cannot use ${variableSet.scope}-scoped variable sets`,
+      });
     }
   }
 }
 
+/** A resource may depend only on Variable Sets whose audience is no narrower
+ * than its own. User-owned rigs may use anything visible to their owner. */
+export function variableSetScopeAllowedForRig(
+  rigScope: ResourceAuthorityScope,
+  variableSetScope: ResourceAuthorityScope,
+): boolean {
+  return (
+    rigScope === "user" ||
+    variableSetScope === "organization" ||
+    (rigScope === "workspace" && variableSetScope === "workspace")
+  );
+}
+
 export async function createRigForApi(
   deps: RigServices,
   grant: AccessGrant,
   payload: CreateRigRequest,
+  options: { allowOrganization?: boolean } = {},
 ): Promise<Rig> {
-  const workspaceId = grant.workspaceId;
   const name = trimmedRigName(payload.name);
   assertUniqueCheckNames(payload.checks);
-  await assertVariableSetsExist(deps.db, workspaceId, payload.defaultVariableSetIds);
-  if ((await countRigs(deps.db, workspaceId)) >= MAX_RIGS_PER_WORKSPACE) {
+  await assertVariableSetsExist(
+    deps.db,
+    grant,
+    payload.scope,
+    payload.defaultVariableSetIds.length > 0 ? payload.defaultVariableSetIds : undefined,
+  );
+  if ((await countRigs(deps.db, grant, payload.scope)) >= MAX_RIGS_PER_WORKSPACE) {
     throw new HTTPException(422, {
-      message: `a workspace supports at most ${MAX_RIGS_PER_WORKSPACE} rigs`,
+      message: `a workspace supports at most ${MAX_RIGS_PER_WORKSPACE} sandbox environments`,
     });
   }
-  if (await getRigByName(deps.db, workspaceId, name)) {
-    throw new HTTPException(409, { message: `rig name is already in use: ${name}` });
+  if (await getRigByName(deps.db, grant, name, payload.scope)) {
+    throw new HTTPException(409, {
+      message: `sandbox environment name is already in use: ${name}`,
+    });
   }
   const createdBy = rigActorForGrant(grant);
   const rig = await createRig(deps.db, {
     accountId: grant.accountId,
-    workspaceId,
+    workspaceId: grant.workspaceId,
+    scope: payload.scope,
+    subjectId: grant.subjectId,
+    allowOrganization: options.allowOrganization === true,
     name,
     description: payload.description ?? null,
     createdBy,
     initialVersion: {
-      image: payload.image ?? null,
+      image: null,
       setupScript: payload.setupScript ?? null,
       checks: payload.checks,
       credentialHooks: payload.credentialHooks,
@@ -192,7 +261,11 @@ export async function createRigForApi(
       createdBy,
     },
   });
-  await recordRigAuditEvent(deps.db, { grant, action: "rig.created", rigId: rig.id });
+  await recordRigAuditEvent(deps.db, {
+    grant,
+    action: "rig.created",
+    rigId: rig.id,
+  });
   return rig;
 }
 
@@ -201,20 +274,27 @@ export async function updateRigForApi(
   grant: AccessGrant,
   rig: Rig,
   payload: UpdateRigRequest,
+  options: { allowOrganization?: boolean } = {},
 ): Promise<Rig> {
-  const workspaceId = grant.workspaceId;
   const name = payload.name !== undefined ? trimmedRigName(payload.name) : undefined;
   if (name !== undefined && name !== rig.name) {
-    const existing = await getRigByName(deps.db, workspaceId, name);
+    const existing = await getRigByName(deps.db, grant, name, rig.scope);
     if (existing && existing.id !== rig.id) {
-      throw new HTTPException(409, { message: `rig name is already in use: ${name}` });
+      throw new HTTPException(409, {
+        message: `sandbox environment name is already in use: ${name}`,
+      });
     }
   }
-  const updated = await updateRig(deps.db, workspaceId, rig.id, {
+  const updated = await updateScopedRig(deps.db, grant, rig.id, {
     ...(name !== undefined ? { name } : {}),
     ...(payload.description !== undefined ? { description: payload.description } : {}),
+    allowOrganization: options.allowOrganization === true,
+  });
+  await recordRigAuditEvent(deps.db, {
+    grant,
+    action: "rig.updated",
+    rigId: rig.id,
   });
-  await recordRigAuditEvent(deps.db, { grant, action: "rig.updated", rigId: rig.id });
   return updated;
 }
 
@@ -222,18 +302,27 @@ export async function deleteRigForApi(
   deps: RigServices,
   grant: AccessGrant,
   rig: Rig,
+  options: { allowOrganization?: boolean } = {},
 ): Promise<void> {
-  const workspaceId = grant.workspaceId;
-  const deleted = await deleteRigIfNoActiveSessions(deps.db, workspaceId, rig.id);
-  if (deleted.activeSessionCount > 0) {
-    throw new HTTPException(409, {
-      message: `rig is referenced by ${deleted.activeSessionCount} active session(s); it cannot be deleted`,
+  try {
+    await revokeScopedRig(deps.db, grant, rig.id, {
+      allowOrganization: options.allowOrganization === true,
     });
+  } catch (error) {
+    let current: unknown = error;
+    while (current instanceof Error) {
+      if (current.message.includes("active sessions")) {
+        throw new HTTPException(409, { message: current.message });
+      }
+      current = current.cause;
+    }
+    throw error;
   }
-  if (!deleted.deleted) {
-    throw new HTTPException(404, { message: "rig not found" });
-  }
-  await recordRigAuditEvent(deps.db, { grant, action: "rig.deleted", rigId: rig.id });
+  await recordRigAuditEvent(deps.db, {
+    grant,
+    action: "rig.deleted",
+    rigId: rig.id,
+  });
 }
 
 // Records a proposed change against the rig's CURRENT active version (the base
@@ -247,15 +336,18 @@ export async function proposeRigChangeForApi(
   request: ProposeRigChangeRequest,
   options: { proposedBy?: string } = {},
 ): Promise<RigChange> {
-  const workspaceId = grant.workspaceId;
+  const workspaceId = rig.workspaceId;
   if (!rig.activeVersion) {
-    throw new HTTPException(422, { message: "rig has no active version to base a change on" });
+    throw new HTTPException(422, {
+      message: "sandbox environment has no active version to base a change on",
+    });
   }
   if (request.kind === "definition_edit") {
     assertUniqueCheckNames(request.payload.checks);
     await assertVariableSetsExist(
       deps.db,
-      workspaceId,
+      grant,
+      rig.scope,
       request.payload.defaultVariableSetIds ?? undefined,
     );
   }
@@ -320,7 +412,7 @@ async function promoteChangeWithActiveCas(
   } catch (error) {
     if (error instanceof RigActiveVersionChangedError) {
       throw new HTTPException(409, {
-        message: `rig moved since this change was verified (base ${error.expectedVersionId}, now ${error.actualVersionId ?? "none"}); re-verify before promoting`,
+        message: `sandbox environment moved since this change was verified (base ${error.expectedVersionId}, now ${error.actualVersionId ?? "none"}); re-verify before promoting`,
       });
     }
     if (error instanceof RigChangeTransitionError) {
@@ -342,21 +434,25 @@ export async function promoteSetupAppendChange(
     });
   }
   if (change.status !== "proposed" && change.status !== "verifying") {
-    throw new HTTPException(409, { message: `rig change is ${change.status}; cannot promote` });
+    throw new HTTPException(409, {
+      message: `sandbox environment change is ${change.status}; cannot promote`,
+    });
   }
   if (!change.baseVersionId) {
-    throw new HTTPException(422, { message: "rig change has no base version" });
+    throw new HTTPException(422, { message: "sandbox environment change has no base version" });
   }
-  const base = await getRigVersion(deps.db, grant.workspaceId, rig.id, change.baseVersionId);
+  const base = await getRigVersion(deps.db, rig.workspaceId, rig.id, change.baseVersionId);
   if (!base) {
-    throw new HTTPException(404, { message: "base rig version not found" });
+    throw new HTTPException(404, { message: "base sandbox environment version not found" });
   }
   const payload = change.payload as { command?: unknown; note?: unknown };
   if (typeof payload.command !== "string" || !payload.command.trim()) {
-    throw new HTTPException(422, { message: "setup_append change is missing command" });
+    throw new HTTPException(422, {
+      message: "setup_append change is missing command",
+    });
   }
   const nextDefinition = {
-    image: base.image,
+    image: null,
     setupScript: appendRigSetupCommand(base.setupScript, payload.command),
     checks: base.checks,
     credentialHooks: base.credentialHooks,
@@ -364,7 +460,7 @@ export async function promoteSetupAppendChange(
   };
   const { version, change: updated } = await promoteChangeWithActiveCas(
     deps,
-    grant.workspaceId,
+    rig.workspaceId,
     rig.id,
     change.id,
     {
@@ -382,13 +478,21 @@ export async function promoteSetupAppendChange(
     grant,
     action: "rig.change.merged",
     rigId: rig.id,
-    metadata: { changeId: change.id, versionId: version.id, version: version.version },
+    metadata: {
+      changeId: change.id,
+      versionId: version.id,
+      version: version.version,
+    },
   });
   await recordRigAuditEvent(deps.db, {
     grant,
     action: "rig.version.promoted",
     rigId: rig.id,
-    metadata: { changeId: change.id, versionId: version.id, version: version.version },
+    metadata: {
+      changeId: change.id,
+      versionId: version.id,
+      version: version.version,
+    },
   });
   return { change: updated, version };
 }
@@ -400,10 +504,14 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
   change: RigChange,
 ): Promise<{ change: RigChange; version: RigVersion }> {
   if (change.kind !== "definition_edit") {
-    throw new HTTPException(422, { message: "only definition_edit changes use explicit promote" });
+    throw new HTTPException(422, {
+      message: "only definition_edit changes use explicit promote",
+    });
   }
   if (change.status !== "proposed") {
-    throw new HTTPException(409, { message: `rig change is ${change.status}; cannot promote` });
+    throw new HTTPException(409, {
+      message: `sandbox environment change is ${change.status}; cannot promote`,
+    });
   }
   if (change.verification?.passed !== true) {
     throw new HTTPException(422, {
@@ -411,14 +519,13 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
     });
   }
   if (!change.baseVersionId) {
-    throw new HTTPException(422, { message: "rig change has no base version" });
+    throw new HTTPException(422, { message: "sandbox environment change has no base version" });
   }
-  const base = await getRigVersion(deps.db, grant.workspaceId, rig.id, change.baseVersionId);
+  const base = await getRigVersion(deps.db, rig.workspaceId, rig.id, change.baseVersionId);
   if (!base) {
-    throw new HTTPException(404, { message: "base rig version not found" });
+    throw new HTTPException(404, { message: "base sandbox environment version not found" });
   }
   const payload = change.payload as {
-    image?: unknown;
     setupScript?: unknown;
     checks?: unknown;
     credentialHooks?: unknown;
@@ -426,7 +533,7 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
     changelog?: unknown;
   };
   const nextDefinition = {
-    image: payload.image === undefined ? base.image : (payload.image as string | null),
+    image: null,
     setupScript:
       payload.setupScript === undefined ? base.setupScript : (payload.setupScript as string | null),
     checks: Array.isArray(payload.checks) ? (payload.checks as RigVersion["checks"]) : base.checks,
@@ -439,7 +546,7 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
   };
   const { version, change: updated } = await promoteChangeWithActiveCas(
     deps,
-    grant.workspaceId,
+    rig.workspaceId,
     rig.id,
     change.id,
     {
@@ -457,13 +564,21 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
     grant,
     action: "rig.change.merged",
     rigId: rig.id,
-    metadata: { changeId: change.id, versionId: version.id, version: version.version },
+    metadata: {
+      changeId: change.id,
+      versionId: version.id,
+      version: version.version,
+    },
   });
   await recordRigAuditEvent(deps.db, {
     grant,
     action: "rig.version.promoted",
     rigId: rig.id,
-    metadata: { changeId: change.id, versionId: version.id, version: version.version },
+    metadata: {
+      changeId: change.id,
+      versionId: version.id,
+      version: version.version,
+    },
   });
   return { change: updated, version };
 }
@@ -475,21 +590,22 @@ export async function createRigVersionForApi(
   payload: RigDefinitionEditPayload,
 ): Promise<RigVersion> {
   if (!rig.activeVersion) {
-    throw new HTTPException(422, { message: "rig has no active version" });
+    throw new HTTPException(422, { message: "sandbox environment has no active version" });
   }
   assertUniqueCheckNames(payload.checks);
   await assertVariableSetsExist(
     deps.db,
-    grant.workspaceId,
+    grant,
+    rig.scope,
     payload.defaultVariableSetIds ?? undefined,
   );
   const base = rig.activeVersion;
   const version = await createRigVersion(
     deps.db,
-    grant.workspaceId,
+    rig.workspaceId,
     rig.id,
     {
-      image: payload.image === undefined ? base.image : payload.image,
+      image: null,
       setupScript: payload.setupScript === undefined ? base.setupScript : payload.setupScript,
       checks: payload.checks ?? base.checks,
       credentialHooks: payload.credentialHooks ?? base.credentialHooks,
@@ -516,7 +632,7 @@ export async function activateRigVersionForApi(
   rig: Rig,
   versionId: string,
 ): Promise<RigVersion> {
-  const workspaceId = grant.workspaceId;
+  const workspaceId = rig.workspaceId;
   const version = await activateRigVersion(deps.db, workspaceId, rig.id, versionId);
   await recordRigAuditEvent(deps.db, {
     grant,

package/src/rigs/provider-images.ts

@@ -11,7 +11,7 @@ import {
 
 export type RigProviderImageDefinition = Pick<
   RigVersion,
-  "image" | "setupScript" | "checks" | "credentialHooks" | "defaultVariableSetIds"
+  "setupScript" | "checks" | "credentialHooks" | "defaultVariableSetIds"
 >;
 
 function sha256(value: string): string {
@@ -42,10 +42,9 @@ export function rigProviderImageContentHash(input: {
 }): string {
   return sha256(
     stableJson({
-      version: 1,
+      version: 2,
       backend: input.backend,
       sourceImage: input.sourceImage,
-      image: input.definition.image,
       setupScript: input.definition.setupScript,
       checks: input.definition.checks,
       credentialHooks: input.definition.credentialHooks,