@opengeni/api-router 4.3.3-canary.39786771332001 → 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-S5VJ3GVR.js";
+} from "./chunk-LXUAR3HS.js";
 import "./chunk-OGQDXVXY.js";
 
 // src/index.ts

package/dist/mcp/user-setup-card.d.ts

@@ -0,0 +1,21 @@
+import { type UserSetupBlocker } from "@opengeni/contracts";
+export { sessionChatUrl } from "@opengeni/contracts";
+type ToolRefusal = {
+    code?: string | undefined;
+    reason?: string | undefined;
+};
+export type UserSetupCardPost = (blocker: UserSetupBlocker) => Promise<{
+    eventId: string | null;
+    chatUrl: string | null;
+} | null>;
+/**
+ * Post the setup card when a tool was refused for something the person can fix
+ * themselves (USER_SETUP_BLOCKERS), and tell the agent it is posted. Every
+ * other result is returned unchanged. Posting is best effort: if it cannot be
+ * posted, the original refusal still stands.
+ */
+export declare function withUserSetupCard<T extends ToolRefusal>(result: T, post: UserSetupCardPost): Promise<T & {
+    card?: "shown";
+    cardEventId?: string | null;
+    chatUrl?: string;
+}>;

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.3.3-canary.39786771332001",
+  "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.3.3-canary.39786771332001",
-    "@opengeni/artifact-tool": "4.3.3-canary.39786771332001",
-    "@opengeni/capabilities": "4.3.3-canary.39786771332001",
-    "@opengeni/codemode": "4.3.3-canary.39786771332001",
-    "@opengeni/codex": "4.3.3-canary.39786771332001",
-    "@opengeni/config": "4.3.3-canary.39786771332001",
-    "@opengeni/contracts": "4.3.3-canary.39786771332001",
-    "@opengeni/core": "4.3.3-canary.39786771332001",
-    "@opengeni/db": "4.3.3-canary.39786771332001",
-    "@opengeni/documents": "4.3.3-canary.39786771332001",
-    "@opengeni/events": "4.3.3-canary.39786771332001",
-    "@opengeni/github": "4.3.3-canary.39786771332001",
-    "@opengeni/interaction": "4.3.3-canary.39786771332001",
-    "@opengeni/network": "4.3.3-canary.39786771332001",
-    "@opengeni/observability": "4.3.3-canary.39786771332001",
-    "@opengeni/runtime": "4.3.3-canary.39786771332001",
-    "@opengeni/storage": "4.3.3-canary.39786771332001",
-    "@opengeni/tool-gateway": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-keeper": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-onepassword": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-protonpass": "4.3.3-canary.39786771332001",
-    "@opengeni/xai-subscription": "4.3.3-canary.39786771332001",
+    "@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

@@ -18,11 +18,7 @@ import { enableMachineScreenControl, enrollmentAccess } from "../sandbox/screen-
 import { registerNotificationTools } from "./notification-tools";
 import { excelAddinSetup, registerExcelTools } from "./excel-tools";
 import { capabilityAccountReadiness } from "./capability-account-readiness";
-import {
-  sessionChatUrl,
-  withMachinePermissionCard,
-  type MachinePermissionCardPost,
-} from "./machine-permission-card";
+import { sessionChatUrl, withUserSetupCard, type UserSetupCardPost } from "./user-setup-card";
 import {
   prepareWorkspaceArtifactUpload,
   prepareWorkspaceArtifactPublication,
@@ -214,8 +210,9 @@ import {
   buildCapabilityCatalog,
   CONNECTED_MACHINE_CAPABILITY_ID,
   EXCEL_ADDIN_CAPABILITY_ID,
+  browserExtension,
   nativeConnectionCapabilityRecommendations,
-  OPENGENI_BROWSER_EXTENSION_URL,
+  userSetupCardPayload,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
@@ -2300,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(),
@@ -4323,23 +4320,23 @@ function registerFleetTools(
     };
   };
 
-  // A refusal that only the owner's permission can resolve posts the Connected
-  // Machine card right away, in the agent's own turn, so the person can allow
-  // the machine without the agent having to find and call the card tool. Only
-  // exact agent attempts post it. The card names the machine the agent asked
-  // for, so it can lead with allowing that machine. A repeated refusal for the
-  // same machine in the same turn reuses that turn's card; the lookup and
-  // append run atomically under the attempt fence so parallel refusals cannot
-  // stack copies. Cards for every other capability are never limited.
-  const machinePermissionCard =
-    (toolName: string, target: string): MachinePermissionCardPost =>
-    async () => {
+  // A refusal the person can fix themselves (USER_SETUP_BLOCKERS, for example
+  // the owner not having allowed this chat to use their machine yet) posts the
+  // setup card right away, in the agent's own turn, so the person sees the fix
+  // without the agent having to find and call the card tool. Only exact agent
+  // attempts post it. A machine card names the machine the agent asked for, so
+  // it can lead with allowing that machine. A repeated refusal for the same
+  // machine in the same turn reuses that turn's card; the lookup and append run
+  // atomically under the attempt fence so parallel refusals cannot stack
+  // copies. Cards for every other capability are never limited.
+  const userSetupCard =
+    (toolName: string, target: string): UserSetupCardPost =>
+    async (blocker) => {
       const requestedSandboxId = UUID_TARGET.test(target) ? target.toLowerCase() : null;
       if (!exactAgentAttemptClaims(grant)) return null;
       const claims = exactAgentCommandContext(grant, sessionId);
-      const item = nativeConnectionCapabilityRecommendations({ connectedMachines: true }).find(
-        (candidate) => candidate.id === CONNECTED_MACHINE_CAPABILITY_ID,
-      )!;
+      const payload = userSetupCardPayload(blocker, { toolName, requestedSandboxId });
+      if (!payload) return null;
       const appended = await appendTurnCapabilityCardOnce(
         deps.db,
         grant.workspaceId,
@@ -4347,23 +4344,13 @@ function registerFleetTools(
         claims.callerTurnId,
         claims.callerExecutionGeneration,
         claims.callerAttemptId,
-        item.id,
-        {
-          type: "tool.auth_needed",
-          payload: {
-            ...capabilityCardPayload(item, {
-              action: "connect",
-              rationale: "Allow this chat to use your computer.",
-              toolName,
-            }),
-            ...(requestedSandboxId ? { requestedSandboxId } : {}),
-          },
-        },
+        blocker.capabilityId,
+        { type: "tool.auth_needed", payload },
         requestedSandboxId,
       );
       await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, appended.events);
       if (!appended.accepted) {
-        throw new Error("The calling turn was replaced before the machine card committed.");
+        throw new Error("The calling turn was replaced before the setup card committed.");
       }
       return {
         eventId: appended.existingEventId ?? appended.events[0]?.id ?? null,
@@ -4398,9 +4385,9 @@ function registerFleetTools(
     },
     async ({ target }) =>
       json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await swapActiveSandbox(services, await fleetContext(), target),
-          machinePermissionCard("sandbox_attach", target),
+          userSetupCard("sandbox_attach", target),
         ),
       ),
   );
@@ -4414,9 +4401,9 @@ function registerFleetTools(
     },
     async ({ target }) =>
       json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await swapActiveSandbox(services, await fleetContext(), target),
-          machinePermissionCard("sandbox_swap", target),
+          userSetupCard("sandbox_swap", target),
         ),
       ),
   );
@@ -4458,12 +4445,12 @@ function registerFleetTools(
             )
           : null;
       return json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await runOnSandbox(services, await fleetContext(), target, typedOp, {
             ...(transientExecEnvironment ? { transientExecEnvironment } : {}),
             ...(secretResolver ? { secretResolver } : {}),
           }),
-          machinePermissionCard("run_on", target),
+          userSetupCard("run_on", target),
         ),
       );
     },
@@ -4484,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,
@@ -4514,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(
@@ -4544,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() },
     },
@@ -4576,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) },
     },
@@ -6733,6 +6721,7 @@ function registerCapabilityDiscoveryTools(
         ...current.items,
         ...nativeConnectionCapabilityRecommendations({
           connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+          browserExtension: browserExtension(deps.settings),
         }),
       ];
       const ranked = searchCapabilityCatalogItems(candidates, query, limit ?? 8);
@@ -6806,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)) {
@@ -6845,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/mcp/user-setup-card.ts

@@ -0,0 +1,42 @@
+import {
+  type UserSetupBlocker,
+  userSetupBlocker,
+  userSetupCardShownMessage,
+} from "@opengeni/contracts";
+
+export { sessionChatUrl } from "@opengeni/contracts";
+
+type ToolRefusal = { code?: string | undefined; reason?: string | undefined };
+
+export type UserSetupCardPost = (blocker: UserSetupBlocker) => Promise<{
+  eventId: string | null;
+  chatUrl: string | null;
+} | null>;
+
+/**
+ * Post the setup card when a tool was refused for something the person can fix
+ * themselves (USER_SETUP_BLOCKERS), and tell the agent it is posted. Every
+ * other result is returned unchanged. Posting is best effort: if it cannot be
+ * posted, the original refusal still stands.
+ */
+export async function withUserSetupCard<T extends ToolRefusal>(
+  result: T,
+  post: UserSetupCardPost,
+): Promise<T & { card?: "shown"; cardEventId?: string | null; chatUrl?: string }> {
+  const blocker = userSetupBlocker(result.code);
+  if (!blocker) return result;
+  let posted: Awaited<ReturnType<UserSetupCardPost>>;
+  try {
+    posted = await post(blocker);
+  } catch {
+    return result;
+  }
+  if (!posted) return result;
+  return {
+    ...result,
+    reason: userSetupCardShownMessage(blocker, posted.chatUrl),
+    card: "shown",
+    cardEventId: posted.eventId,
+    ...(posted.chatUrl ? { chatUrl: posted.chatUrl } : {}),
+  };
+}

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