@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/insights-usage.ts

@@ -0,0 +1,345 @@
+import {
+  InsightsCallsResponse,
+  InsightsUsageResponse,
+  OrganizationInsightsCallsQuery,
+  OrganizationInsightsUsageQuery,
+  WorkspaceInsightsCallsQuery,
+  WorkspaceInsightsUsageQuery,
+} from "@opengeni/contracts/insights-usage";
+import type { AccessContext } from "@opengeni/contracts";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  getInsightsUsage,
+  hasPermission,
+  listInsightsCalls,
+  requireAccessContext,
+  requireAccessGrant,
+  type ApiRouteDeps,
+  type InsightsQueryScope,
+} from "@opengeni/core";
+import {
+  currentSessionRlsActorIdentityKey,
+  InvalidInsightsCallsCursorError,
+  readInsightsResponseCacheFence,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { createHash } from "node:crypto";
+import { HTTPException } from "hono/http-exception";
+import { requireSelectedAccount, withBillingUsageActor } from "./billing";
+import { createInFlightCoalescer } from "./insights";
+import {
+  createInsightsCredentialPartition,
+  createInsightsResponseCache,
+  insightsWithFriendlyTimeout,
+} from "./insights-response-cache";
+
+/** Keep repeated filters, but reject repeated scalar options in the strict schema. */
+export function insightsQueryParameters(
+  query: Record<string, string[]>,
+): Record<string, string | string[]> {
+  return Object.fromEntries(
+    Object.entries(query).map(([key, values]) => [key, values.length === 1 ? values[0]! : values]),
+  );
+}
+
+/** Frozen interim capabilities: a newer additive contract must not silently widen a raw query. */
+export function insightsRawQuerySupported(
+  query: Record<string, unknown>,
+  organization: boolean,
+  calls: boolean,
+): boolean {
+  const keys = new Set([
+    "range",
+    "provider",
+    "model",
+    "payer",
+    "projectId",
+    "person",
+    "rootSessionId",
+    "scheduleId",
+    "limit",
+    ...(organization ? ["workspaceId"] : []),
+    ...(calls ? ["cursor"] : ["groupBy", "seriesGroups"]),
+  ]);
+  if (Object.keys(query).some((key) => !keys.has(key))) return false;
+  if (
+    query.range !== undefined &&
+    !new Set(["today", "week", "month", "30d", "90d", "ytd"]).has(String(query.range))
+  )
+    return false;
+  return (
+    query.groupBy === undefined ||
+    new Set([
+      "model",
+      "provider",
+      "payer",
+      "project",
+      "rootSession",
+      "person",
+      "schedule",
+      ...(organization ? ["workspace"] : []),
+    ]).has(String(query.groupBy))
+  );
+}
+
+function organizationCacheAuthority(context: AccessContext, accountId: string) {
+  const key = accountScopedApiKeyWorkspaceAuthority(context);
+  return [
+    context.subjectId,
+    context.accountGrants
+      .filter((g) => g.accountId === accountId)
+      .map((g) => [g.subjectId, g.role, [...g.permissions].sort()]),
+    context.workspaceGrants
+      .filter((g) => g.accountId === accountId)
+      .map((g) => [g.workspaceId, g.subjectId, g.permissionMode, [...g.permissions].sort()])
+      .sort(),
+    key
+      ? [key.accountId, key.permissionMode, [...key.permissions].sort(), key.workspaceScope]
+      : null,
+  ];
+}
+
+function rawUsageResponse(response: Awaited<ReturnType<typeof getInsightsUsage>>) {
+  const parsed = InsightsUsageResponse.parse(response);
+  // A newer contract can supply an additive default. Absence is a capability
+  // signal, so this raw implementation must not manufacture source support.
+  if (!Object.hasOwn(response.facets, "sources")) Reflect.deleteProperty(parsed.facets, "sources");
+  return parsed;
+}
+
+/** The actor and its canonical detail authority are part of every sharing key. */
+export function insightsUsageCoalesceKey(
+  scope: InsightsQueryScope,
+  query: unknown,
+  actor: string | null,
+): string {
+  return JSON.stringify([
+    scope.accountId,
+    scope.workspaceId,
+    [...(scope.detailsWorkspaceIds ?? [])].sort(),
+    scope.detailsSharedWorkspaces === true,
+    query,
+    actor,
+  ]);
+}
+
+/** Reuse canonical read grants, never infer session access from billing authority. */
+export function organizationInsightsScope(
+  context: AccessContext,
+  accountId: string,
+): InsightsQueryScope {
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  if (authority?.accountId === accountId) {
+    const readable = hasPermission(
+      authority.permissions,
+      "sessions:read",
+      authority.permissionMode,
+    );
+    return {
+      accountId,
+      workspaceId: null,
+      detailsWorkspaceIds:
+        readable && authority.workspaceScope.kind === "selected"
+          ? [...authority.workspaceScope.workspaceIds].sort()
+          : [],
+      detailsSharedWorkspaces: readable && authority.workspaceScope.kind === "all",
+    };
+  }
+  return {
+    accountId,
+    workspaceId: null,
+    detailsWorkspaceIds: [
+      ...new Set(
+        context.workspaceGrants
+          .filter(
+            (grant) =>
+              grant.accountId === accountId &&
+              grant.subjectId === context.subjectId &&
+              hasPermission(grant.permissions, "sessions:read", grant.permissionMode),
+          )
+          .map((grant) => grant.workspaceId),
+      ),
+    ].sort(),
+    detailsSharedWorkspaces: false,
+  };
+}
+
+async function callsWithValidation(
+  read: () => Promise<Awaited<ReturnType<typeof listInsightsCalls>>>,
+) {
+  try {
+    return await read();
+  } catch (error) {
+    if (error instanceof InvalidInsightsCallsCursorError)
+      throw new HTTPException(400, { message: "invalid Insights calls cursor" });
+    throw error;
+  }
+}
+
+export function registerInsightsUsageRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const usage = createInFlightCoalescer<InsightsUsageResponse>();
+  const calls = createInFlightCoalescer<InsightsCallsResponse>();
+  const cache = createInsightsResponseCache();
+  const credentialPartition = createInsightsCredentialPartition();
+  async function cached<T>(
+    c: Context,
+    kind: "usage" | "calls",
+    scope: InsightsQueryScope,
+    query: object,
+    authority: unknown,
+    coalescer: { run(key: string, work: () => Promise<T>): Promise<T> },
+    read: () => Promise<T>,
+  ): Promise<T> {
+    // This runs only after this request's normal authentication and scope checks.
+    const normalized = Object.fromEntries(
+      Object.entries(query)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, Array.isArray(value) ? [...new Set(value)].sort() : value]),
+    );
+    const key = createHash("sha256")
+      .update(
+        JSON.stringify([
+          kind,
+          authority,
+          insightsUsageCoalesceKey(scope, normalized, currentSessionRlsActorIdentityKey()),
+          credentialPartition(c.req.header("authorization"), c.req.header("cookie")),
+          new Date().toISOString().slice(0, 10),
+        ]),
+      )
+      .digest("hex");
+    const fence = await readInsightsResponseCacheFence(deps.db, scope);
+    if (fence !== null) {
+      const hit = cache.get<T>(key, fence);
+      if (hit !== null) return hit;
+    }
+    return await coalescer.run(`${key}:${fence ?? "uncached"}`, async () => {
+      const response = await insightsWithFriendlyTimeout(read);
+      // Store validated successes only, and only if metadata remained stable.
+      if (fence !== null && fence === (await readInsightsResponseCacheFence(deps.db, scope)))
+        cache.put(key, fence, response);
+      return response;
+    });
+  }
+
+  app.get("/v1/workspaces/:workspaceId/insights/usage", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, false, false))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = WorkspaceInsightsUsageQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights usage query" });
+    const scope = {
+      accountId: grant.accountId,
+      workspaceId,
+      detailsWorkspaceIds: hasPermission(grant.permissions, "sessions:read", grant.permissionMode)
+        ? [workspaceId]
+        : [],
+    };
+    // The API's workspace middleware already binds/revalidates this grant's RLS actor.
+    const response = await cached(
+      c,
+      "usage",
+      scope,
+      parsed.data,
+      [grant.subjectId, grant.permissionMode, [...grant.permissions].sort()],
+      usage,
+      async () =>
+        rawUsageResponse(await getInsightsUsage(deps.db, { ...scope, query: parsed.data })),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/insights/calls", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, false, true))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = WorkspaceInsightsCallsQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights calls query" });
+    const scope = {
+      accountId: grant.accountId,
+      workspaceId,
+      detailsWorkspaceIds: hasPermission(grant.permissions, "sessions:read", grant.permissionMode)
+        ? [workspaceId]
+        : [],
+    };
+    const response = await cached(
+      c,
+      "calls",
+      scope,
+      parsed.data,
+      [grant.subjectId, grant.permissionMode, [...grant.permissions].sort()],
+      calls,
+      async () =>
+        InsightsCallsResponse.parse(
+          await callsWithValidation(() =>
+            listInsightsCalls(deps.db, { ...scope, query: parsed.data }),
+          ),
+        ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/organizations/:accountId/insights/usage", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.param("accountId"), "billing:read");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, true, false))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = OrganizationInsightsUsageQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights usage query" });
+    const scope = organizationInsightsScope(context, accountId);
+    const response = await withBillingUsageActor(deps, context, accountId, () =>
+      cached(
+        c,
+        "usage",
+        scope,
+        parsed.data,
+        organizationCacheAuthority(context, accountId),
+        usage,
+        async () =>
+          rawUsageResponse(await getInsightsUsage(deps.db, { ...scope, query: parsed.data })),
+      ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/organizations/:accountId/insights/calls", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.param("accountId"), "billing:read");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, true, true))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = OrganizationInsightsCallsQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights calls query" });
+    const scope = organizationInsightsScope(context, accountId);
+    // Call readers intersect these canonical grants with current actor visibility.
+    const response = await withBillingUsageActor(deps, context, accountId, () =>
+      cached(
+        c,
+        "calls",
+        scope,
+        parsed.data,
+        organizationCacheAuthority(context, accountId),
+        calls,
+        async () =>
+          InsightsCallsResponse.parse(
+            await callsWithValidation(() =>
+              listInsightsCalls(deps.db, { ...scope, query: parsed.data }),
+            ),
+          ),
+      ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+}

package/src/routes/insights.ts

@@ -1,12 +1,17 @@
 import { InsightsRange, WorkspaceInsightsResponse } from "@opengeni/contracts";
 import {
   getWorkspaceInsights,
+  measureInsightsPhase,
+  workspaceInsightsPhaseMetricObserver,
   normalizeWorkspaceInsightsFilter,
+  normalizeWorkspaceInsightsSessionScope,
   requireAccessGrant,
+  scheduledTaskViewerForGrant,
   WorkspaceInsightsFilterValidationError,
   type ApiRouteDeps,
   type WorkspaceInsightsFilterField,
 } from "@opengeni/core";
+import { currentSessionRlsActorIdentityKey } from "@opengeni/db";
 import { workspaceInsightsMetricObserver } from "@opengeni/observability";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -16,7 +21,9 @@ export function normalizeWorkspaceInsightsQueryFilter(
   field: WorkspaceInsightsFilterField,
 ): string | null {
   try {
-    return normalizeWorkspaceInsightsFilter(value, field);
+    return field === "rootSessionId" || field === "sessionId"
+      ? normalizeWorkspaceInsightsSessionScope(value, field)
+      : normalizeWorkspaceInsightsFilter(value, field);
   } catch (error) {
     if (error instanceof WorkspaceInsightsFilterValidationError) {
       throw new HTTPException(400, { message: error.message });
@@ -25,20 +32,82 @@ export function normalizeWorkspaceInsightsQueryFilter(
   }
 }
 
+/**
+ * Share one in-flight computation between identical concurrent callers.
+ *
+ * A reload, a second tab, or a retried fetch joins the rollup already running
+ * instead of starting another multi-second aggregate on the database.
+ * Authorization and filter validation still run per request before a caller
+ * may join; the map only ever holds running work. The caller supplies the
+ * complete sharing key, which must identify everything the result depends on.
+ */
+export function createInFlightCoalescer<T>(): {
+  run: (key: string, work: () => Promise<T>) => Promise<T>;
+  readonly size: number;
+} {
+  const inFlight = new Map<string, Promise<T>>();
+  return {
+    run(key, work) {
+      const pending = inFlight.get(key);
+      if (pending) return pending;
+      const started: Promise<T> = work().finally(() => {
+        if (inFlight.get(key) === started) inFlight.delete(key);
+      });
+      inFlight.set(key, started);
+      return started;
+    },
+    get size() {
+      return inFlight.size;
+    },
+  };
+}
+
+/**
+ * Insights rows are filtered by the database RLS actor (private sessions are
+ * visible only to their owner), so two administrators of one workspace can
+ * legitimately receive different responses. The actor identity is part of
+ * the key; requests share work only when every visibility input is equal.
+ */
+export function workspaceInsightsCoalesceKey(input: {
+  workspaceId: string;
+  range: string;
+  provider: string | null;
+  model: string | null;
+  rootSessionId?: string | null;
+  sessionId?: string | null;
+  rlsActor: string | null;
+}): string {
+  return JSON.stringify([
+    input.workspaceId,
+    input.range,
+    input.provider,
+    input.model,
+    input.rootSessionId ?? null,
+    input.sessionId ?? null,
+    input.rlsActor,
+  ]);
+}
+
 export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
   const observeRequest = workspaceInsightsMetricObserver(deps.observability);
+  const observePhase = workspaceInsightsPhaseMetricObserver(deps.observability);
+  const coalesce = createInFlightCoalescer<Awaited<ReturnType<typeof getWorkspaceInsights>>>();
   app.get("/v1/workspaces/:workspaceId/insights", async (c) => {
     const startedAtMs = performance.now();
     const rangeRaw = c.req.query("range") ?? "week";
     const providerRaw = c.req.query("provider");
     const modelRaw = c.req.query("model");
+    const rootSessionIdRaw = c.req.query("rootSessionId");
+    const sessionIdRaw = c.req.query("sessionId");
     let provider: string | null = null;
     let model: string | null = null;
     let outcome = "failed";
 
     try {
       const workspaceId = c.req.param("workspaceId");
-      await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const grant = await measureInsightsPhase(observePhase, "auth", () =>
+        requireAccessGrant(c, deps, workspaceId, "workspace:admin"),
+      );
 
       const rangeParsed = InsightsRange.safeParse(rangeRaw);
       if (!rangeParsed.success) {
@@ -48,13 +117,39 @@ export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       provider = normalizeWorkspaceInsightsQueryFilter(providerRaw, "provider");
       model = normalizeWorkspaceInsightsQueryFilter(modelRaw, "model");
+      const rootSessionId = normalizeWorkspaceInsightsQueryFilter(
+        rootSessionIdRaw,
+        "rootSessionId",
+      );
+      const sessionId = normalizeWorkspaceInsightsQueryFilter(sessionIdRaw, "sessionId");
 
-      const response = await getWorkspaceInsights(deps.db, deps.settings, {
-        workspaceId,
-        range: rangeParsed.data,
-        provider,
-        model,
-      });
+      const response = await coalesce.run(
+        workspaceInsightsCoalesceKey({
+          workspaceId,
+          range: rangeParsed.data,
+          provider,
+          model,
+          rootSessionId,
+          sessionId,
+          rlsActor: currentSessionRlsActorIdentityKey(),
+        }),
+        () =>
+          getWorkspaceInsights(
+            deps.db,
+            deps.settings,
+            {
+              workspaceId,
+              range: rangeParsed.data,
+              provider,
+              model,
+              rootSessionId,
+              sessionId,
+              viewerSubjectId: async () =>
+                (await scheduledTaskViewerForGrant(deps.db, grant, deps.settings)).subjectId,
+            },
+            observePhase,
+          ),
+      );
       c.header("cache-control", "private, no-store");
       const result = c.json(WorkspaceInsightsResponse.parse(response));
       outcome = "completed";

package/src/routes/install.ts

@@ -158,18 +158,53 @@ function bakedContentType(asset: string): string {
 // BAKED_DIR is a fixed sibling, so the resolved path cannot escape the dir.
 async function readBaked(asset: string): Promise<ArrayBuffer | null> {
   const url = new URL(asset, BAKED_DIR);
-  try {
-    const info = await stat(url);
-    if (!info.isFile()) {
+  const runtime =
+    /^(?:opengeni-agent-browser|opengeni-computer-native|opengeni-browserd|opengeni-agent)-(.+?)(?:\.(?:sha256|minisig))?$/.exec(
+      asset,
+    );
+  if (runtime) {
+    const target = runtime[1]!;
+    const cohort = [
+      "opengeni-agent",
+      "opengeni-browserd",
+      "opengeni-agent-browser",
+      "opengeni-computer-native",
+    ].flatMap((component) =>
+      ["", ".sha256", ".minisig"].map((suffix) => `${component}-${target}${suffix}`),
+    );
+    const members = await Promise.all(
+      cohort.map(async (name) => {
+        try {
+          const info = await stat(new URL(name, BAKED_DIR));
+          return info.isFile() && info.size > 0 ? "complete" : "invalid";
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+          throw new HTTPException(503, { message: "baked interaction runtime is unavailable" });
+        }
+      }),
+    );
+    // A target is either wholly absent or wholly baked. A partial image cannot
+    // combine its agent with helpers or verification sidecars from an archive.
+    if (members.every((member) => member === "absent")) return null;
+    if (members.some((member) => member !== "complete")) {
+      throw new HTTPException(503, { message: "baked interaction runtime is incomplete" });
+    }
+  } else {
+    try {
+      const info = await stat(url);
+      if (!info.isFile()) return null;
+    } catch {
       return null;
     }
-  } catch {
-    return null;
   }
   // Return a standalone ArrayBuffer (a valid Response BodyInit). `readFile`'s
   // Buffer may be a view into a larger pooled allocation, so copy out the exact
   // byte range with `.slice` rather than handing over the backing store.
-  const buf = await readFile(url);
+  const buf = await readFile(url).catch(() => {
+    // Never redirect after selecting a baked cohort, even if a file becomes
+    // unreadable between the completeness check and the byte read.
+    throw new HTTPException(503, { message: "baked interaction runtime is unavailable" });
+  });
   return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
 
@@ -205,7 +240,11 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
   // otherwise 302 to the GitHub Release at `redirectUrl` (mac/windows + any
   // un-baked asset). The baked path makes the agent the API enrolls against
   // identical to the API that serves it — no version skew, no extra hop.
-  async function serveAsset(asset: string, redirectUrl: string): Promise<Response> {
+  async function serveAsset(
+    asset: string,
+    redirectUrl: string,
+    allowBaked: boolean,
+  ): Promise<Response> {
     const committed = COMMITTED_BINARY_ASSETS[asset];
     if (committed) {
       const buf = await readFile(new URL(committed.file, INSTALL_DIR));
@@ -218,7 +257,7 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
         },
       });
     }
-    const baked = await readBaked(asset);
+    const baked = allowBaked ? await readBaked(asset) : null;
     if (baked !== null) {
       return new Response(baked, {
         status: 200,
@@ -251,7 +290,7 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!ASSET_NAME.test(asset)) {
       throw new HTTPException(400, { message: "invalid asset name" });
     }
-    return serveAsset(asset, `${releasesBase}/download/${stableAgentTag}/${asset}`);
+    return serveAsset(asset, `${releasesBase}/download/${stableAgentTag}/${asset}`, true);
   });
 
   // Signed self-update channel manifests. Each deployment exposes its own
@@ -296,7 +335,9 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "invalid version or asset name",
       });
     }
-    return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`);
+    // A pinned release must never be substituted with this deployment's baked
+    // canary, even when its semver happens to match. The archive owns its bytes.
+    return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`, false);
   });
 }