@opengeni/api-router 0.4.1 → 0.5.0

package/src/routes/connections.ts

@@ -0,0 +1,179 @@
+import {
+  ConnectionResponse,
+  CreateConnectionRequest,
+  IntegrationClientMetadata,
+  ListConnectionsResponse,
+  OAuthStartRequest,
+  OAuthStartResponse,
+  UpdateConnectionRequest,
+} from "@opengeni/contracts";
+import { requireAccessGrant, requireEnvironmentEncryption } from "@opengeni/core";
+import {
+  createConnection,
+  encryptEnvironmentValue,
+  getConnectionMetadata,
+  listConnectionsMetadata,
+  revokeConnection,
+  updateConnection,
+} from "@opengeni/db";
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import {
+  completeMcpOAuthCallback,
+  integrationBaseUrl,
+  startMcpOAuth,
+} from "../integrations/oauth-client";
+
+export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { db, settings } = deps;
+
+  function assertIntegrationsEnabled(): void {
+    if (!settings.integrationsEnabled) {
+      throw new HTTPException(404, { message: "integrations are not enabled for this deployment" });
+    }
+  }
+
+  app.get("/v1/workspaces/:workspaceId/connections", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
+    return c.json(ListConnectionsResponse.parse({
+      connections: await listConnectionsMetadata(db, workspaceId, grant.subjectId),
+    }));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/connections", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const payload = CreateConnectionRequest.parse(await c.req.json());
+    const key = requireEnvironmentEncryption(settings);
+    const subjectId = writableSubjectId(payload.subjectId, grant.subjectId);
+    const connection = await createConnection(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId,
+      providerDomain: payload.providerDomain,
+      kind: payload.kind,
+      credentialEncrypted: encryptCredentialBundle(key, payload.credential),
+      grantedScopes: payload.grantedScopes,
+      expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null,
+      metadata: payload.metadata,
+      createdBySubjectId: grant.subjectId,
+    });
+    return c.json(ConnectionResponse.parse({ connection }), 201);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/connections/:connectionId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
+    const connection = await getConnectionMetadata(db, workspaceId, c.req.param("connectionId"), grant.subjectId);
+    if (!connection) {
+      throw new HTTPException(404, { message: "connection not found" });
+    }
+    return c.json(ConnectionResponse.parse({ connection }));
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/connections/:connectionId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const payload = UpdateConnectionRequest.parse(await c.req.json());
+    // Status is not a free-form field: revocation goes through DELETE, and the
+    // broker owns needs_reauth/error. Reactivating a connection is only
+    // meaningful together with a fresh credential bundle — otherwise a PATCH
+    // could clear the broker's re-auth signal while stale tokens stay in place.
+    if (payload.status !== undefined) {
+      if (payload.status !== "active") {
+        throw new HTTPException(400, { message: "status can only be set to \"active\"; use DELETE to revoke" });
+      }
+      if (payload.credential === undefined) {
+        throw new HTTPException(400, { message: "reactivating a connection requires a new credential" });
+      }
+    }
+    const key = payload.credential === undefined ? null : requireEnvironmentEncryption(settings);
+    const subjectId = payload.subjectId === undefined ? undefined : writableSubjectId(payload.subjectId, grant.subjectId);
+    const connection = await updateConnection(db, {
+      workspaceId,
+      connectionId: c.req.param("connectionId"),
+      visibleToSubjectId: grant.subjectId,
+      updatedBySubjectId: grant.subjectId,
+      ...(payload.providerDomain !== undefined ? { providerDomain: payload.providerDomain } : {}),
+      ...(subjectId !== undefined ? { subjectId } : {}),
+      ...(payload.kind !== undefined ? { kind: payload.kind } : {}),
+      ...(payload.status !== undefined ? { status: payload.status } : {}),
+      ...(payload.credential !== undefined && key ? { credentialEncrypted: encryptCredentialBundle(key, payload.credential) } : {}),
+      ...(payload.grantedScopes !== undefined ? { grantedScopes: payload.grantedScopes } : {}),
+      ...(payload.expiresAt !== undefined ? { expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : null } : {}),
+      ...(payload.metadata !== undefined ? { metadata: payload.metadata } : {}),
+    });
+    if (!connection) {
+      throw new HTTPException(404, { message: "connection not found" });
+    }
+    return c.json(ConnectionResponse.parse({ connection }));
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/connections/:connectionId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const connection = await revokeConnection(db, workspaceId, c.req.param("connectionId"), grant.subjectId);
+    if (!connection) {
+      throw new HTTPException(404, { message: "connection not found" });
+    }
+    return c.json(ConnectionResponse.parse({ connection }));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/connections/oauth/start", async (c) => {
+    assertIntegrationsEnabled();
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+    const parsed = OAuthStartRequest.safeParse(await c.req.json());
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: parsed.error.issues[0]?.message ?? "invalid OAuth start request" });
+    }
+    const payload = parsed.data;
+    const result = await startMcpOAuth({ db, settings }, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      requestUrl: c.req.url,
+      payload,
+    });
+    return c.json(OAuthStartResponse.parse(result));
+  });
+
+  app.get("/v1/integrations/oauth/callback", async (c) => {
+    assertIntegrationsEnabled();
+    const result = await completeMcpOAuthCallback({ db, settings }, {
+      code: c.req.query("code"),
+      state: c.req.query("state"),
+      requestUrl: c.req.url,
+    });
+    return c.redirect(result.redirectTo, 302);
+  });
+
+  app.get("/v1/integrations/oauth/client-metadata.json", (c) => {
+    const baseUrl = integrationBaseUrl(settings.publicBaseUrl, c.req.url);
+    const metadataUrl = `${baseUrl}/v1/integrations/oauth/client-metadata.json`;
+    return c.json(IntegrationClientMetadata.parse({
+      client_id: metadataUrl,
+      client_name: "OpenGeni",
+      redirect_uris: [`${baseUrl}/v1/integrations/oauth/callback`],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+    }));
+  });
+}
+
+function writableSubjectId(requested: string | null | undefined, grantSubjectId: string): string | null {
+  if (requested == null) {
+    return null;
+  }
+  if (requested !== grantSubjectId) {
+    throw new HTTPException(403, { message: "cannot write a connection for another subject" });
+  }
+  return requested;
+}
+
+function encryptCredentialBundle(key: Uint8Array, credential: Record<string, unknown>): string {
+  return encryptEnvironmentValue(key, JSON.stringify(credential));
+}

package/src/routes/documents.ts

@@ -1,10 +1,20 @@
 import {
   AddDocumentRequest,
+  CreateKnowledgeMemoryRequest,
   CreateDocumentBaseRequest,
   Document,
   DocumentBase,
   DocumentSearchRequest,
+  KnowledgeMemory,
+  KnowledgeMemorySearchRequest,
+  UpdateKnowledgeMemoryRequest,
 } from "@opengeni/contracts";
+import {
+  createKnowledgeMemory,
+  getKnowledgeMemory,
+  listKnowledgeMemories,
+  updateKnowledgeMemory,
+} from "@opengeni/db";
 import {
   addDocumentToBase,
   createDocumentBase,
@@ -59,7 +69,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireLimit(deps, { accountId: grant.accountId, workspaceId, action: "document:index", quantity: 0 });
     const payload = AddDocumentRequest.parse(await c.req.json());
     try {
-      const document = await addDocumentToBase(db, { accountId: grant.accountId, workspaceId, baseId: c.req.param("baseId"), fileId: payload.fileId });
+      const document = await addDocumentToBase(db, { ...payload, accountId: grant.accountId, workspaceId, baseId: c.req.param("baseId") });
       const wasCreated = document.status === "queued" && document.chunkCount === 0 && document.error === null;
       const indexed = document.status === "ready" ? document : (await documentIndexer.indexDocument({ accountId: grant.accountId, workspaceId, documentId: document.id }) ?? document);
       if (indexed.status === "ready") {
@@ -159,15 +169,89 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         baseIds: [base.id],
         query: payload.query,
         limit: payload.limit,
+        mode: payload.mode,
+        sourceKinds: payload.sourceKinds,
+        aclTags: payload.aclTags,
       }, getDocumentServices()),
     });
   });
 
-  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
+  app.post("/v1/workspaces/:workspaceId/knowledge/search", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    const payload = DocumentSearchRequest.parse(await c.req.json());
+    return c.json({
+      results: await searchDocuments(db, {
+        workspaceId,
+        query: payload.query,
+        baseIds: payload.baseIds,
+        limit: payload.limit,
+        mode: payload.mode,
+        sourceKinds: payload.sourceKinds,
+        aclTags: payload.aclTags,
+      }, getDocumentServices()),
+    });
+  });
+
+  app.get("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    const parsed = KnowledgeMemorySearchRequest.safeParse({
+      query: c.req.query("query") || undefined,
+      status: c.req.query("status") || undefined,
+      kind: c.req.query("kind") || undefined,
+      scope: c.req.query("scope") || undefined,
+      limit: c.req.query("limit") ? Number(c.req.query("limit")) : undefined,
+    });
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid knowledge memory query parameters" });
+    }
+    return c.json((await listKnowledgeMemories(db, workspaceId, parsed.data)).map((memory) => KnowledgeMemory.parse(memory)));
+  });
+
+  app.get("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    const memory = await getKnowledgeMemory(db, workspaceId, c.req.param("memoryId"));
+    if (!memory) {
+      throw new HTTPException(404, { message: "knowledge memory not found" });
+    }
+    return c.json(KnowledgeMemory.parse(memory));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+    const payload = CreateKnowledgeMemoryRequest.parse(await c.req.json());
+    return c.json(KnowledgeMemory.parse(await createKnowledgeMemory(db, {
+      ...payload,
+      accountId: grant.accountId,
+      workspaceId,
+    })), 201);
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+    const payload = UpdateKnowledgeMemoryRequest.parse(await c.req.json());
+    const reviewedBy = payload.reviewedBy
+      ?? (payload.status === "approved" || payload.status === "rejected" ? grant.subjectLabel ?? grant.subjectId : undefined);
+    try {
+      return c.json(KnowledgeMemory.parse(await updateKnowledgeMemory(db, workspaceId, c.req.param("memoryId"), {
+        ...payload,
+        ...(reviewedBy ? { reviewedBy } : {}),
+      })));
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    const sessionId = typeof grant.metadata?.sessionId === "string" ? grant.metadata.sessionId : undefined;
     const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
-    const server = buildDocumentsMcpServer(db, workspaceId, getDocumentServices());
+    const server = buildDocumentsMcpServer(db, grant.accountId, workspaceId, getDocumentServices(), { createdBySessionId: sessionId });
     await server.connect(transport);
     return await transport.handleRequest(c.req.raw);
   });

package/src/routes/enrollments.ts

@@ -286,6 +286,7 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         pubkey: row.pubkey,
         exposure: row.exposure,
         hasDisplay: row.hasDisplay,
+        desktopUnavailableReason: row.desktopUnavailableReason,
         allowScreenControl: row.allowScreenControl,
         status: row.status,
         os: row.os,

package/src/sandbox/channel-a.ts

@@ -140,7 +140,7 @@ export async function withChannelA<T>(
     const settingsForSession = session.sandboxBackend !== settings.sandboxBackend
       ? { ...settings, sandboxBackend: session.sandboxBackend }
       : settings;
-    const environment = stableSandboxEnvironmentForRun(settingsForSession, workspaceEnvironment?.values ?? {});
+    const environment = stableSandboxEnvironmentForRun(settingsForSession, workspaceEnvironment?.values ?? {}, { workspaceId });
     if (hasGitHubRepositorySelection(session.resources)) {
       applyGitAuthPointerEnvironment(environment, githubAppBotIdentity(settings));
     }

package/src/sandbox/machines.ts

@@ -199,6 +199,7 @@ export async function listMachines(
       os: "linux",
       arch: "x86_64",
       hasDisplay: false,
+      desktopUnavailableReason: null,
       allowScreenControl: false,
       sharedSessionCount: 1,
       lastSeenAt: null,
@@ -244,6 +245,7 @@ export async function listMachines(
       os: enrollment.os,
       arch: enrollment.arch,
       hasDisplay: enrollment.hasDisplay,
+      desktopUnavailableReason: enrollment.desktopUnavailableReason,
       allowScreenControl: enrollment.allowScreenControl,
       sharedSessionCount,
       lastSeenAt: enrollment.lastSeenAt,

package/src/sandbox/metrics-ingestion.ts

@@ -30,7 +30,7 @@
 import {
   getEnrollment,
   ingestMachineMetricsSample,
-  setEnrollmentHasDisplay,
+  setEnrollmentDisplayState,
   touchEnrollmentLastSeen,
   type Database,
   type MachineMetricsSample,
@@ -203,33 +203,63 @@ export function helloReportsDisplay(hello: Hello): boolean {
   if (!caps) {
     return false;
   }
+  // A CAPTURE-BLOCKED display is NOT a usable display: a Mac reports a display but
+  // withholds `desktop` and sets `desktopUnavailableReason` when Screen Recording
+  // (TCC) is not granted. Treating it as "has display" is exactly how the 0.1.3
+  // incident hid — the machine claimed a desktop it could not capture, so it was
+  // offered for computer-use and the model saw a blank. Gate it out here (the single
+  // source of truth for `has_display`, consumed by both the machine state and the
+  // capability negotiation). The `display`-present fallback is preserved for every
+  // other case (e.g. a relay-less agent that reports a display but not `desktop`).
+  if (caps.desktopUnavailableReason) {
+    return false;
+  }
   return caps.desktop === true || caps.display != null;
 }
 
 /**
- * Reconcile `enrollments.has_display` to the display presence a Hello reports.
- * Resolves the enrollment (the accountId is the RLS principal + the existence
- * check + the current value). A no-change Hello short-circuits BEFORE issuing any
- * write (and the DB writer is itself change-guarded as a backstop), so a steady
- * state never churns. An unknown/cross-workspace agentId is a no-op.
+ * The human, actionable reason a display is present but UNUSABLE (macOS Screen
+ * Recording / TCC not granted), or null when capture is permitted / the machine is
+ * headless. Normalizes the proto's non-optional "" empty string to null so the DB
+ * carries a clean tri-state (a real reason vs. no reason) — the Machines dashboard
+ * shows "display: capture not granted" only when this is non-null.
+ */
+export function helloDesktopUnavailableReason(hello: Hello): string | null {
+  const reason = hello.capabilities?.desktopUnavailableReason;
+  return reason ? reason : null;
+}
+
+/**
+ * Reconcile `enrollments.has_display` (+ the capture-blocked reason) to what a Hello
+ * reports. Resolves the enrollment (the accountId is the RLS principal + the
+ * existence check + the current values). A no-change Hello short-circuits BEFORE
+ * issuing any write (and the DB writer is itself change-guarded on BOTH fields as a
+ * backstop), so a steady state never churns. An unknown/cross-workspace agentId is a
+ * no-op.
  */
 export async function refreshEnrollmentDisplay(
   db: Database,
-  input: { workspaceId: string; agentId: string; hasDisplay: boolean },
+  input: { workspaceId: string; agentId: string; hasDisplay: boolean; desktopUnavailableReason?: string | null },
 ): Promise<{ updated: boolean }> {
+  const desktopUnavailableReason = input.desktopUnavailableReason ?? null;
   const enrollment = await getEnrollment(db, input.workspaceId, input.agentId);
   if (!enrollment) {
     return { updated: false };
   }
-  if (enrollment.hasDisplay === input.hasDisplay) {
-    // Unchanged — do not even issue the UPDATE (no churn on a steady-state Hello).
+  if (
+    enrollment.hasDisplay === input.hasDisplay &&
+    (enrollment.desktopUnavailableReason ?? null) === desktopUnavailableReason
+  ) {
+    // Both fields unchanged — do not even issue the UPDATE (no churn on a
+    // steady-state Hello).
     return { updated: false };
   }
-  return await setEnrollmentHasDisplay(db, {
+  return await setEnrollmentDisplayState(db, {
     accountId: enrollment.accountId,
     workspaceId: input.workspaceId,
     enrollmentId: input.agentId,
     hasDisplay: input.hasDisplay,
+    desktopUnavailableReason,
   });
 }
 
@@ -263,6 +293,7 @@ export async function handleHelloPayload(
       workspaceId: ids.workspaceId,
       agentId: ids.agentId,
       hasDisplay: helloReportsDisplay(hello),
+      desktopUnavailableReason: helloDesktopUnavailableReason(hello),
     });
   } catch (error) {
     observability?.warn?.("Failed to refresh an enrollment's display from a Hello", {

package/src/sandbox/viewer.ts

@@ -136,7 +136,7 @@ export async function sessionAttachEnvironment(
   const settingsForSession = session.sandboxBackend !== services.settings.sandboxBackend
     ? { ...services.settings, sandboxBackend: session.sandboxBackend }
     : services.settings;
-  const environment = stableSandboxEnvironmentForRun(settingsForSession, workspaceEnvironment?.values ?? {});
+  const environment = stableSandboxEnvironmentForRun(settingsForSession, workspaceEnvironment?.values ?? {}, { workspaceId });
   if (hasGitHubRepositorySelection(session.resources)) {
     applyGitAuthPointerEnvironment(environment, githubAppBotIdentity(services.settings));
   }