@opengeni/api-router 4.4.1 → 4.5.0

package/dist/http/session-list-hints.d.ts

@@ -5,13 +5,23 @@ export type SessionListHint = {
     available: boolean;
     /** null means reconcile all loaded scopes, including formerly visible rows. */
     sessionIds: string[] | null;
+    /**
+     * The viewer's changed Site conversations, which ordinary lists omit. Only
+     * a surface that shows them (the rail's Site rows) needs to act on these.
+     */
+    siteSessionIds?: string[];
+};
+/** Authorized hint IDs; a plain array has no Site conversations. */
+export type SessionListHintIds = string[] | {
+    sessionIds: string[];
+    siteSessionIds: string[];
 };
 /** Transient commit hints; only the subsequent authorized list read is truth. */
 export declare function subscribeSessionListHints(options: {
     source: SessionListChangeSource;
     workspaceId: string;
     subjectId: string;
-    authorizeIds: (ids: string[]) => Promise<string[]>;
+    authorizeIds: (ids: string[]) => Promise<SessionListHintIds>;
     write: (hint: SessionListHint) => Promise<unknown>;
     fail: (error: unknown) => void;
     intervalMs: number;

package/dist/http/sse.d.ts

@@ -2,6 +2,7 @@ import { type SessionEvent } from "@opengeni/contracts";
 import { type Database, type SessionListChangeSource } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
+import { type SessionListHintIds } from "./session-list-hints.js";
 export declare const SSE_QUEUED_FRAME_MAX_COUNT = 1;
 export declare const SSE_WRITE_STALL_TIMEOUT_MS = 30000;
 export declare const SSE_HEARTBEAT_INTERVAL_MS = 15000;
@@ -78,7 +79,7 @@ export type WorkspaceInteractionSseOptions = SseDeliveryOptions & {
     sessionLists?: {
         source: SessionListChangeSource;
         subjectId: string;
-        authorizeIds: (ids: string[]) => Promise<string[]>;
+        authorizeIds: (ids: string[]) => Promise<SessionListHintIds>;
     } | undefined;
 };
 /**

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump,
   withAccessGrantSessionRlsContext
-} from "./chunk-3KRHXJPM.js";
+} from "./chunk-LXUAR3HS.js";
 import "./chunk-OGQDXVXY.js";
 
 // src/index.ts

package/dist/routes/client-errors.d.ts

@@ -121,6 +121,7 @@ export declare const ClientSignalReport: z.ZodDiscriminatedUnion<[z.ZodObject<{
         settings: "settings";
         "setup-account": "setup-account";
         "site-auth": "site-auth";
+        sites: "sites";
         state: "state";
         "variable-sets": "variable-sets";
     }>;

package/dist/routes/sessions.d.ts

@@ -19,6 +19,7 @@ export declare function sessionTenancyHttpError(error: unknown): Error;
 export declare function sessionListQuery(query: Record<string, string>, allowCursor?: boolean): {
     originSiteId: string | undefined;
     siteAccessId: string | undefined;
+    siteConversations: "include" | "group" | undefined;
     limit: string | undefined;
     parentSessionId: string | null | undefined;
     cursor: ReturnType<typeof decodeSessionListCursor> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Opengeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,29 +45,29 @@
     "@keeper-security/secrets-manager-core": "17.6.0",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "4.4.1",
-    "@opengeni/artifact-tool": "4.4.1",
-    "@opengeni/capabilities": "4.4.1",
-    "@opengeni/codemode": "4.4.1",
-    "@opengeni/codex": "4.4.1",
-    "@opengeni/config": "4.4.1",
-    "@opengeni/contracts": "4.4.1",
-    "@opengeni/core": "4.4.1",
-    "@opengeni/db": "4.4.1",
-    "@opengeni/documents": "4.4.1",
-    "@opengeni/events": "4.4.1",
-    "@opengeni/github": "4.4.1",
-    "@opengeni/interaction": "4.4.1",
-    "@opengeni/network": "4.4.1",
-    "@opengeni/observability": "4.4.1",
-    "@opengeni/runtime": "4.4.1",
-    "@opengeni/storage": "4.4.1",
-    "@opengeni/tool-gateway": "4.4.1",
-    "@opengeni/vaults": "4.4.1",
-    "@opengeni/vaults-keeper": "4.4.1",
-    "@opengeni/vaults-onepassword": "4.4.1",
-    "@opengeni/vaults-protonpass": "4.4.1",
-    "@opengeni/xai-subscription": "4.4.1",
+    "@opengeni/agent-proto": "4.5.0",
+    "@opengeni/artifact-tool": "4.5.0",
+    "@opengeni/capabilities": "4.5.0",
+    "@opengeni/codemode": "4.5.0",
+    "@opengeni/codex": "4.5.0",
+    "@opengeni/config": "4.5.0",
+    "@opengeni/contracts": "4.5.0",
+    "@opengeni/core": "4.5.0",
+    "@opengeni/db": "4.5.0",
+    "@opengeni/documents": "4.5.0",
+    "@opengeni/events": "4.5.0",
+    "@opengeni/github": "4.5.0",
+    "@opengeni/interaction": "4.5.0",
+    "@opengeni/network": "4.5.0",
+    "@opengeni/observability": "4.5.0",
+    "@opengeni/runtime": "4.5.0",
+    "@opengeni/storage": "4.5.0",
+    "@opengeni/tool-gateway": "4.5.0",
+    "@opengeni/vaults": "4.5.0",
+    "@opengeni/vaults-keeper": "4.5.0",
+    "@opengeni/vaults-onepassword": "4.5.0",
+    "@opengeni/vaults-protonpass": "4.5.0",
+    "@opengeni/xai-subscription": "4.5.0",
     "@temporalio/client": "^1.17.0",
     "ajv": "^8.20.0",
     "better-auth": "^1.6.14",

package/src/app.ts

@@ -193,6 +193,7 @@ import {
   registerProductUsageMetricBaselines,
   stampPersonalApiKeyRequest,
   verifiedDelegatedHumanAuthorizationForRequest,
+  browserExtension,
 } from "@opengeni/core";
 import { createManagedAuthNewSignupsGate } from "./auth/new-signups-gate";
 import {
@@ -1516,6 +1517,7 @@ export function createAppComposition(deps: AppDependencies): {
         deploymentRevision: deps.settings.deploymentRevision,
         claudeSubscriptionEnabled: deps.settings.claudeSubscriptionEnabled,
         connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+        browserExtension: browserExtension(deps.settings),
         apiContractRevision: OPENGENI_API_CONTRACT_REVISION,
         ...(deps.settings.serverVersion ? { serverVersion: deps.settings.serverVersion } : {}),
         defaultModel,

package/src/http/session-list-hints.ts

@@ -6,14 +6,22 @@ export type SessionListHint = {
   available: boolean;
   /** null means reconcile all loaded scopes, including formerly visible rows. */
   sessionIds: string[] | null;
+  /**
+   * The viewer's changed Site conversations, which ordinary lists omit. Only
+   * a surface that shows them (the rail's Site rows) needs to act on these.
+   */
+  siteSessionIds?: string[];
 };
 
+/** Authorized hint IDs; a plain array has no Site conversations. */
+export type SessionListHintIds = string[] | { sessionIds: string[]; siteSessionIds: string[] };
+
 /** Transient commit hints; only the subsequent authorized list read is truth. */
 export function subscribeSessionListHints(options: {
   source: SessionListChangeSource;
   workspaceId: string;
   subjectId: string;
-  authorizeIds: (ids: string[]) => Promise<string[]>;
+  authorizeIds: (ids: string[]) => Promise<SessionListHintIds>;
   write: (hint: SessionListHint) => Promise<unknown>;
   fail: (error: unknown) => void;
   intervalMs: number;
@@ -24,12 +32,13 @@ export function subscribeSessionListHints(options: {
   let all = false;
   const ids = new Set<string>();
   let tail = Promise.resolve();
-  const emit = (available: boolean, sessionIds: string[] | null) =>
+  const emit = (available: boolean, sessionIds: string[] | null, siteSessionIds: string[] = []) =>
     options.write({
       type: "workspace.sessions.changed",
       workspaceId: options.workspaceId,
       available,
       sessionIds,
+      ...(siteSessionIds.length ? { siteSessionIds } : {}),
     });
   const enqueue = (action: () => Promise<unknown>) => {
     tail = tail
@@ -73,10 +82,14 @@ export function subscribeSessionListHints(options: {
     ids.clear();
     enqueue(async () => {
       if (observedGeneration !== generation || !connected) return;
-      const visibleIds = reconcileAll ? null : await options.authorizeIds(pendingIds);
+      const authorized = reconcileAll ? null : await options.authorizeIds(pendingIds);
       if (observedGeneration !== generation || !connected) return;
-      if (visibleIds !== null && !visibleIds.length) return;
-      await emit(true, visibleIds);
+      if (authorized === null) return await emit(true, null);
+      const visible = Array.isArray(authorized)
+        ? { sessionIds: authorized, siteSessionIds: [] }
+        : authorized;
+      if (!visible.sessionIds.length && !visible.siteSessionIds.length) return;
+      await emit(true, visible.sessionIds, visible.siteSessionIds);
     });
   }, options.intervalMs);
   return () => {

package/src/http/sse.ts

@@ -22,7 +22,7 @@ import {
 } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
 import { MANAGED_AUTH_ACTOR_EPOCH_HEADER } from "@opengeni/core/managed-auth-session-sets";
-import { subscribeSessionListHints } from "./session-list-hints";
+import { subscribeSessionListHints, type SessionListHintIds } from "./session-list-hints";
 
 const SESSION_REPLAY_PAGE_SIZE = 100;
 const SESSION_REPLAY_PAGE_MAX_BYTES = 8 * 1024 * 1024;
@@ -744,7 +744,7 @@ export type WorkspaceInteractionSseOptions = SseDeliveryOptions & {
     | {
         source: SessionListChangeSource;
         subjectId: string;
-        authorizeIds: (ids: string[]) => Promise<string[]>;
+        authorizeIds: (ids: string[]) => Promise<SessionListHintIds>;
       }
     | undefined;
 };

package/src/mcp/action-catalog.gen.ts

@@ -6407,6 +6407,15 @@ export const ACTION_CATALOG: readonly ActionCatalogEntry[] = [
       "PersonalGitHubOAuthStartResponse"
     ]
   },
+  {
+    "id": "recordSiteOpened",
+    "method": "POST",
+    "path": "/v1/workspaces/:workspaceId/published-artifacts/:artifactId/opened",
+    "request": [],
+    "response": [
+      "SiteOpenedResponse"
+    ]
+  },
   {
     "id": "recoverSandbox",
     "method": "POST",

package/src/mcp/server.ts

@@ -210,9 +210,9 @@ import {
   buildCapabilityCatalog,
   CONNECTED_MACHINE_CAPABILITY_ID,
   EXCEL_ADDIN_CAPABILITY_ID,
+  browserExtension,
   nativeConnectionCapabilityRecommendations,
   userSetupCardPayload,
-  OPENGENI_BROWSER_EXTENSION_URL,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
@@ -2297,7 +2297,7 @@ function registerSandboxFileArtifactTool(
     "sandbox_file_publish",
     {
       description:
-        "Publish one exact file from this session's /workspace into durable workspace storage. Use this before presenting a video, ZIP, CSV, JSON, Markdown, HTML, PDF, Office file, or other sandbox output as downloadable. Present the returned artifact.artifactId as [Open file](artifact:<artifactId>), or ![Preview](artifact:<artifactId>) for inline image/video/audio/PDF previews. Replace <artifactId> with the exact returned ID and use a descriptive label. Never expose a sandbox: URL as the durable result. The artifactId is also the file's workspace File ID, so tools that take workspace file IDs, such as a browser upload action, accept it. A new file gets this chat's visibility (Only me in an Only me chat, otherwise the workspace) unless you pass visibility; to change an existing file, such as a generated image, pass its artifactId and visibility instead of path. Check the result's access.whoCanOpen before sharing a link with anyone.",
+        "Publish one file from this session's workspace so the person can open it. Use it for every file you hand over: document, spreadsheet, PDF, image, video, archive or data. Link the result as [Descriptive label](artifact:<artifactId>), or ![Descriptive label](artifact:<artifactId>) to preview an image, video, audio or PDF inline; never give a sandbox: link instead. The artifactId is also the file's workspace file ID, which tools such as a browser upload accept. A new file gets this chat's visibility unless you pass visibility. To change who can open an existing file, such as a generated image, pass its artifactId and visibility instead of path. Check access.whoCanOpen in the result before sharing the link with anyone else.",
       inputSchema: {
         path: z4.string().min(1).max(4_096).optional(),
         artifactId: z4.string().uuid().optional(),
@@ -4471,9 +4471,10 @@ function registerFleetTools(
         // Same live-attempt authority the other fleet tools resolve, without
         // requiring a session box: a chat with no sandbox can still connect one.
         await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
-        const item = nativeConnectionCapabilityRecommendations({ connectedMachines: true }).find(
-          (candidate) => candidate.id === CONNECTED_MACHINE_CAPABILITY_ID,
-        )!;
+        const item = nativeConnectionCapabilityRecommendations({
+          connectedMachines: true,
+          browserExtension: browserExtension(deps.settings),
+        }).find((candidate) => candidate.id === CONNECTED_MACHINE_CAPABILITY_ID)!;
         const setup = await capabilitySetupProjection(
           deps,
           grant.workspaceId,
@@ -4501,7 +4502,7 @@ function registerFleetTools(
             setup.status === "ready"
               ? `${setup.detail} The Connected Machine card lists them, so the person can choose one for this chat or connect another.`
               : "The Connected Machine card was posted. It shows the person what to do, so do not describe its buttons or steps; nothing is connected yet."
-          } Check sandboxes_list after they confirm. Chrome needs the browser extension (${OPENGENI_BROWSER_EXTENSION_URL}) on the connected machine.`,
+          } Check sandboxes_list after they confirm. Chrome needs the browser extension (${browserExtension(deps.settings).installUrl}) on the connected machine.`,
         });
       }
       return json(
@@ -4531,7 +4532,7 @@ function registerConnectedMachineTools(
     {
       description:
         "Create a single-use Connected Machine enrollment token for this workspace (expires in one hour) using existing enrollments:manage authority. Returns the token, expiry and Unix/PowerShell install commands. Use it when you can run commands on the target machine yourself (run_on, SSH, a VM you control): run the matching command there, then verify the machine with sandboxes_list. One token connects one machine; mint another for each additional machine (the same machine may rerun its command). When the person must run it on their own computer, post the Connected Machine card instead (capability_authorization_request with api:connected-machine), which mints the command in their browser; do not paste a token into the chat. Screen control is optional and defaults off; to turn it on for a machine that is already connected, use connected_machine_enable_screen_control instead of reconnecting. The token grants whole-machine access on enrollment; do not put it in public code or unrelated logs. Existing machine connections are preserved. For Chrome, the person installs the Opengeni Browser extension (" +
-        OPENGENI_BROWSER_EXTENSION_URL +
+        browserExtension(deps.settings).installUrl +
         ") after the machine is connected.",
       inputSchema: { allowScreenControl: z4.boolean().optional() },
     },
@@ -4563,7 +4564,7 @@ function registerConnectedMachineTools(
     {
       description:
         "Turn screen control on for a machine that is already connected, in place, so agents can see and use its screen (computer and attached-Chrome tools). `target` is a sandboxes_list id or an enrollment id. Needs no human click, token, terminal or reconnect: the platform records the consent on that machine and its agent refreshes its own credentials over the live connection. status=active means it is on now. status=pending means it is allowed and turns on by itself: reason=offline when the machine next connects; reason=agent_update_required after its agent is updated (update it with the machine update action, POST /v1/workspaces/{workspaceId}/machines/{enrollmentId}/update); reason=renewal_failed: call again shortly; reason=reconnect_required: the machine's connection predates in-place changes, so rerun the connect command on it (connected_machine_enroll_token with allowScreenControl=true). On a Mac the OS must also allow Screen Recording, Accessibility and Input Monitoring for the app that runs the agent (the name macOS lists in those panes): open each pane on the Mac with run_on exec `open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'` (Privacy_Accessibility, Privacy_ListenEvent; also the privacy-settings machine action) and ask the person to switch that app on there, choosing Quit & Reopen if macOS asks; the machine list reports runtime.macPermissions. Chrome additionally needs the Opengeni Browser extension (" +
-        OPENGENI_BROWSER_EXTENSION_URL +
+        browserExtension(deps.settings).installUrl +
         ") on that machine.",
       inputSchema: { target: z4.string().min(1) },
     },
@@ -6720,6 +6721,7 @@ function registerCapabilityDiscoveryTools(
         ...current.items,
         ...nativeConnectionCapabilityRecommendations({
           connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+          browserExtension: browserExtension(deps.settings),
         }),
       ];
       const ranked = searchCapabilityCatalogItems(candidates, query, limit ?? 8);
@@ -6793,6 +6795,7 @@ function registerCapabilityDiscoveryTools(
         ...current.items,
         ...nativeConnectionCapabilityRecommendations({
           connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+          browserExtension: browserExtension(deps.settings),
         }),
       ].find((candidate) => candidate.id === capabilityId);
       if (!item || !capabilityCatalogItemIsTrustedForExposure(item)) {
@@ -6832,7 +6835,7 @@ function registerCapabilityDiscoveryTools(
           capabilityId: item.id,
           status: "ready",
           eventId,
-          message: `${setup.detail} The Connected Machine card is in this chat: the person can choose a machine for this chat or connect another. Chrome needs the browser extension (${OPENGENI_BROWSER_EXTENSION_URL}) on a connected machine.`,
+          message: `${setup.detail} The Connected Machine card is in this chat: the person can choose a machine for this chat or connect another. Chrome needs the browser extension (${browserExtension(deps.settings).installUrl}) on a connected machine.`,
         });
       }
       if (githubCardWhenReady) {

package/src/routes/browser-sessions.ts

@@ -6126,6 +6126,26 @@ export function parseBrowserScreenshotOptions(
 export function browserTabDiagnosisError(error: unknown): unknown {
   if (!(error instanceof BrowserControlRequestError)) return error;
   const code = error.error.code;
+  // A controller that says a resource is gone for good (for example, the
+  // person's Chrome profile reconnected and this session no longer controls
+  // it) answers 503 but not retryable. As a 503 it would reach the agent as
+  // "temporarily unavailable, retry", and every retry fails the same way, so
+  // keep the controller's guidance and present it as the conflict it is.
+  if (
+    code === "resource_unavailable" &&
+    error.status >= 500 &&
+    !error.retryable &&
+    !legacyInteractionCapacityFailure(error, "browser")
+  ) {
+    const failure = new ApiHttpError(409, {
+      code: "conflict",
+      message: error.error.message,
+      retryable: false,
+      outcomeUnknown: false,
+    });
+    failure.cause = error;
+    return failure;
+  }
   if (code !== "tab_not_responding" && code !== "tab_crashed") return error;
   const failure = new ApiHttpError(409, {
     code,

package/src/routes/interaction-resources.ts

@@ -40,7 +40,7 @@ import {
   listInteractionInterventions,
   listNetworkRoutes,
   listSiteAuthConnections,
-  listVisibleSessionInvalidationIds,
+  listVisibleSessionInvalidationHints,
   sessionListChangesFor,
   resolveInteractionIntervention,
   updateNetworkRoute,
@@ -113,7 +113,7 @@ export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps)
                   freshGrant,
                   "http",
                 );
-                return await listVisibleSessionInvalidationIds(deps.db, workspaceId, ids, {
+                return await listVisibleSessionInvalidationHints(deps.db, workspaceId, ids, {
                   subjectId: freshGrant.subjectId,
                   ...(authorizationScope ? { authorizationScope } : {}),
                   personalWorkspaceOwnerException:

package/src/routes/sessions.ts

@@ -1042,6 +1042,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           ...(query.channelId !== undefined ? { channelId: query.channelId } : {}),
           ...(query.originSiteId ? { originSiteId: query.originSiteId } : {}),
           ...(query.siteAccessId ? { siteAccessId: query.siteAccessId } : {}),
+          ...(query.siteConversations ? { siteConversations: query.siteConversations } : {}),
           ...(query.createdBy ? { createdBy: query.createdBy } : {}),
           ...(query.updatedFrom ? { updatedFrom: query.updatedFrom } : {}),
           ...(query.updatedBefore ? { updatedBefore: query.updatedBefore } : {}),
@@ -5891,6 +5892,7 @@ export function sessionListQuery(
 ): {
   originSiteId: string | undefined;
   siteAccessId: string | undefined;
+  siteConversations: "include" | "group" | undefined;
   limit: string | undefined;
   parentSessionId: string | null | undefined;
   cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
@@ -5925,6 +5927,33 @@ export function sessionListQuery(
     });
   if (originSiteId !== undefined && !z.string().uuid().safeParse(originSiteId).success)
     throw new HTTPException(400, { message: "originSiteId must be a Site id" });
+  const siteConversations = query.siteConversations;
+  if (siteConversations !== undefined) {
+    if (siteConversations !== "include" && siteConversations !== "group")
+      throw new HTTPException(400, { message: 'siteConversations must be "include" or "group"' });
+    if (!allowCursor)
+      throw new HTTPException(400, { message: 'siteConversations requires view="page"' });
+    // A Site's own history is already explicit; Site frames never reach this.
+    if (originSiteId !== undefined || siteAccessId !== undefined)
+      throw new HTTPException(400, {
+        message: "siteConversations cannot be combined with a Site filter",
+      });
+    if (
+      siteConversations === "group" &&
+      (query.parentSessionId !== "null" || query.pinsOnly === "true")
+    )
+      throw new HTTPException(400, {
+        message: 'siteConversations="group" requires a root page (parentSessionId=null)',
+      });
+    // Archived is a flat list: its Site conversations are ordinary rows.
+    if (
+      siteConversations === "group" &&
+      (query.archiveStatus === "archived" || query.archivedOnly === "true")
+    )
+      throw new HTTPException(400, {
+        message: 'siteConversations="group" cannot list archived sessions; use "include"',
+      });
+  }
   // "null" = roots only; a uuid = children of that session; anything else is
   // a client error (an unvalidated value would surface as a Postgres uuid cast
   // failure -> 500 rather than an honest 400).
@@ -6092,6 +6121,7 @@ export function sessionListQuery(
     limit: query.limit,
     originSiteId,
     siteAccessId,
+    siteConversations,
     parentSessionId:
       parentSessionId === undefined
         ? undefined

package/src/routes/workspace-artifacts.ts

@@ -5,6 +5,7 @@ import {
   PublishWorkspaceArtifactVersionRequest,
   RollbackWorkspaceArtifactRequest,
   SetWorkspaceArtifactStatusRequest,
+  SiteOpenedResponse,
   UpdateWorkspaceArtifactVisibilityRequest,
   UpdateWorkspaceArtifactVisibilityResponse,
   WORKSPACE_ARTIFACT_TITLE_MAX_CHARS,
@@ -24,6 +25,7 @@ import {
   resolveSiteAudienceChange,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  currentSiteSessionOrigin,
   siteViewerForGrant,
   type ApiRouteDeps,
 } from "@opengeni/core";
@@ -33,6 +35,7 @@ import {
   getWorkspaceArtifact,
   getWorkspaceArtifactContentRef,
   listWorkspaceArtifacts,
+  recordSiteOpened,
   nestedPostgresSqlState,
   publishWorkspaceArtifactVersion,
   rollbackWorkspaceArtifact,
@@ -232,6 +235,33 @@ export function registerWorkspaceArtifactRoutes(app: Hono, deps: ApiRouteDeps):
     }
   });
 
+  // Opening a Site counts as this person's activity on its sidebar row. It is
+  // personal, needs only read access, and a Site page cannot record it.
+  app.post(`${base}/:artifactId/opened`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
+    if (currentSiteSessionOrigin())
+      throw new HTTPException(403, { message: "A Site page cannot record opening a Site" });
+    const siteId = artifactId(context);
+    const viewer = await siteViewerForGrant(deps.db, grant);
+    if (!viewer.subjectId)
+      throw new HTTPException(403, { message: "A signed-in person is required" });
+    try {
+      return context.json(
+        SiteOpenedResponse.parse(
+          await recordSiteOpened(deps.db, {
+            workspaceId,
+            subjectId: viewer.subjectId,
+            viewer,
+            siteId,
+          }),
+        ),
+      );
+    } catch (error) {
+      return workspaceArtifactErrorResponse(context, error);
+    }
+  });
+
   app.get(base, async (context) => {
     const workspaceId = context.req.param("workspaceId");
     const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:read");