@opengeni/api-router 4.1.0 → 4.1.2

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   createOpenGeniSlackBotInteractionClient,
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump
-} from "./chunk-24C5LPNE.js";
+} from "./chunk-2SSU5KWV.js";
 
 // src/index.ts
 import { scheduledTaskKnowledgeSource } from "@opengeni/contracts";

package/dist/integrations/github-lens-connect.d.ts

@@ -46,7 +46,7 @@ export declare function requireGitHubLensConnect(deps: ApiRouteDeps): Promise<{
                 eager?: boolean | undefined;
                 optional?: boolean | undefined;
             }[];
-            firstPartyMcpTools: ("artifacts_archive" | "artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_prepare_upload" | "artifacts_publish" | "artifacts_restore" | "artifacts_rollback" | "atlassian_get" | "atlassian_search" | "atlassian_sources_list" | "browser_act" | "browser_auth" | "browser_clipboard" | "browser_debug" | "browser_identity" | "browser_lifecycle" | "browser_observe" | "browser_open" | "browser_publish" | "browser_tabs" | "capability_authorization_request" | "capability_catalog_search" | "command_read" | "command_wait" | "company_profile_confirm" | "company_profile_propose" | "computer_act" | "computer_clipboard" | "computer_lifecycle" | "computer_observe" | "computer_open" | "computer_targets" | "connected_machine_enroll_token" | "connected_machine_remove" | "editable_artifact_apply" | "editable_artifact_create" | "editable_artifact_export" | "editable_artifact_export_status" | "editable_artifact_get" | "editable_artifact_import" | "editable_artifact_inspect" | "editable_artifact_list" | "environment_list" | "environment_set_variable" | "fiken_bank_accounts_list" | "fiken_companies_list" | "fiken_contact_create" | "fiken_contacts_list" | "fiken_invoice_draft_create" | "fiken_invoice_get" | "fiken_invoices_list" | "fiken_products_list" | "fiken_purchases_list" | "fiken_sales_list" | "github_connect_link" | "github_repositories_list" | "goal_complete" | "goal_pause" | "goal_progress" | "goal_resume" | "goal_set" | "goal_update" | "instruction_policy_get" | "instruction_policy_propose" | "instruction_policy_save" | "interaction_discover" | "interaction_request_human" | "knowledge_archive" | "knowledge_browse" | "knowledge_correct" | "knowledge_get" | "knowledge_prepare_save" | "knowledge_propose" | "knowledge_retain_file" | "knowledge_retain_message" | "knowledge_save" | "knowledge_search" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "project_create" | "project_delete" | "project_get" | "project_list" | "project_reorder" | "project_update" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "remember" | "remember_confirm" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_file_publish" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_pause" | "session_resume" | "session_send_message" | "session_set_project" | "session_steer" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_search" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "task_note_archive" | "task_note_promote_instruction_policy" | "task_note_promote_knowledge" | "task_note_promote_preference" | "task_note_replace" | "task_note_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "wait_for_input" | "work_claim_release" | "work_claim_upsert" | "x_accounts_list" | "x_mentions_live" | "x_post_reply" | "x_posts_sync" | "x_search_live" | "x_thread_fetch")[];
+            firstPartyMcpTools: ("artifacts_archive" | "artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_prepare_upload" | "artifacts_publish" | "artifacts_restore" | "artifacts_rollback" | "atlassian_get" | "atlassian_search" | "atlassian_sources_list" | "browser_act" | "browser_auth" | "browser_clipboard" | "browser_debug" | "browser_identity" | "browser_lifecycle" | "browser_observe" | "browser_open" | "browser_publish" | "browser_read" | "browser_screenshot" | "browser_tabs" | "capability_authorization_request" | "capability_catalog_search" | "command_read" | "command_wait" | "company_profile_confirm" | "company_profile_propose" | "computer_act" | "computer_clipboard" | "computer_lifecycle" | "computer_observe" | "computer_open" | "computer_targets" | "connected_machine_enroll_token" | "connected_machine_remove" | "editable_artifact_apply" | "editable_artifact_create" | "editable_artifact_export" | "editable_artifact_export_status" | "editable_artifact_get" | "editable_artifact_import" | "editable_artifact_inspect" | "editable_artifact_list" | "environment_list" | "environment_set_variable" | "fiken_bank_accounts_list" | "fiken_companies_list" | "fiken_contact_create" | "fiken_contacts_list" | "fiken_invoice_draft_create" | "fiken_invoice_get" | "fiken_invoices_list" | "fiken_products_list" | "fiken_purchases_list" | "fiken_sales_list" | "github_connect_link" | "github_repositories_list" | "goal_complete" | "goal_pause" | "goal_progress" | "goal_resume" | "goal_set" | "goal_update" | "instruction_policy_get" | "instruction_policy_propose" | "instruction_policy_save" | "interaction_discover" | "interaction_request_human" | "knowledge_archive" | "knowledge_browse" | "knowledge_correct" | "knowledge_get" | "knowledge_prepare_save" | "knowledge_propose" | "knowledge_retain_file" | "knowledge_retain_message" | "knowledge_save" | "knowledge_search" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "project_create" | "project_delete" | "project_get" | "project_list" | "project_reorder" | "project_update" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "remember" | "remember_confirm" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_file_publish" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_pause" | "session_resume" | "session_send_message" | "session_set_project" | "session_steer" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_search" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "task_note_archive" | "task_note_promote_instruction_policy" | "task_note_promote_knowledge" | "task_note_promote_preference" | "task_note_replace" | "task_note_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "wait_for_input" | "work_claim_release" | "work_claim_upsert" | "x_accounts_list" | "x_mentions_live" | "x_post_reply" | "x_posts_sync" | "x_search_live" | "x_thread_fetch")[];
             firstPartyMcpPermissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
             model: string | null;
             reasoningEffort: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | null;

package/dist/integrations/slack-interactions.d.ts

@@ -19,7 +19,7 @@ export declare const SLACK_SESSION_INSTRUCTIONS: string;
  * selection at session creation while keeping Slack mutations out of the model
  * surface; interaction delivery remains owned by the durable delivery pump.
  */
-export declare const SLACK_TASK_FIRST_PARTY_MCP_TOOLS: ("artifacts_archive" | "artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_prepare_upload" | "artifacts_publish" | "artifacts_restore" | "artifacts_rollback" | "atlassian_get" | "atlassian_search" | "atlassian_sources_list" | "browser_act" | "browser_auth" | "browser_clipboard" | "browser_debug" | "browser_identity" | "browser_lifecycle" | "browser_observe" | "browser_open" | "browser_publish" | "browser_tabs" | "capability_authorization_request" | "capability_catalog_search" | "command_read" | "command_wait" | "company_profile_confirm" | "company_profile_propose" | "computer_act" | "computer_clipboard" | "computer_lifecycle" | "computer_observe" | "computer_open" | "computer_targets" | "connected_machine_enroll_token" | "connected_machine_remove" | "editable_artifact_apply" | "editable_artifact_create" | "editable_artifact_export" | "editable_artifact_export_status" | "editable_artifact_get" | "editable_artifact_import" | "editable_artifact_inspect" | "editable_artifact_list" | "environment_list" | "environment_set_variable" | "fiken_bank_accounts_list" | "fiken_companies_list" | "fiken_contact_create" | "fiken_contacts_list" | "fiken_invoice_draft_create" | "fiken_invoice_get" | "fiken_invoices_list" | "fiken_products_list" | "fiken_purchases_list" | "fiken_sales_list" | "github_connect_link" | "github_repositories_list" | "goal_complete" | "goal_pause" | "goal_progress" | "goal_resume" | "goal_set" | "goal_update" | "instruction_policy_get" | "instruction_policy_propose" | "instruction_policy_save" | "interaction_discover" | "interaction_request_human" | "knowledge_archive" | "knowledge_browse" | "knowledge_correct" | "knowledge_get" | "knowledge_prepare_save" | "knowledge_propose" | "knowledge_retain_file" | "knowledge_retain_message" | "knowledge_save" | "knowledge_search" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "project_create" | "project_delete" | "project_get" | "project_list" | "project_reorder" | "project_update" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "remember" | "remember_confirm" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_file_publish" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_pause" | "session_resume" | "session_send_message" | "session_set_project" | "session_steer" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_search" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "task_note_archive" | "task_note_promote_instruction_policy" | "task_note_promote_knowledge" | "task_note_promote_preference" | "task_note_replace" | "task_note_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "wait_for_input" | "work_claim_release" | "work_claim_upsert" | "x_accounts_list" | "x_mentions_live" | "x_post_reply" | "x_posts_sync" | "x_search_live" | "x_thread_fetch")[];
+export declare const SLACK_TASK_FIRST_PARTY_MCP_TOOLS: ("artifacts_archive" | "artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_prepare_upload" | "artifacts_publish" | "artifacts_restore" | "artifacts_rollback" | "atlassian_get" | "atlassian_search" | "atlassian_sources_list" | "browser_act" | "browser_auth" | "browser_clipboard" | "browser_debug" | "browser_identity" | "browser_lifecycle" | "browser_observe" | "browser_open" | "browser_publish" | "browser_read" | "browser_screenshot" | "browser_tabs" | "capability_authorization_request" | "capability_catalog_search" | "command_read" | "command_wait" | "company_profile_confirm" | "company_profile_propose" | "computer_act" | "computer_clipboard" | "computer_lifecycle" | "computer_observe" | "computer_open" | "computer_targets" | "connected_machine_enroll_token" | "connected_machine_remove" | "editable_artifact_apply" | "editable_artifact_create" | "editable_artifact_export" | "editable_artifact_export_status" | "editable_artifact_get" | "editable_artifact_import" | "editable_artifact_inspect" | "editable_artifact_list" | "environment_list" | "environment_set_variable" | "fiken_bank_accounts_list" | "fiken_companies_list" | "fiken_contact_create" | "fiken_contacts_list" | "fiken_invoice_draft_create" | "fiken_invoice_get" | "fiken_invoices_list" | "fiken_products_list" | "fiken_purchases_list" | "fiken_sales_list" | "github_connect_link" | "github_repositories_list" | "goal_complete" | "goal_pause" | "goal_progress" | "goal_resume" | "goal_set" | "goal_update" | "instruction_policy_get" | "instruction_policy_propose" | "instruction_policy_save" | "interaction_discover" | "interaction_request_human" | "knowledge_archive" | "knowledge_browse" | "knowledge_correct" | "knowledge_get" | "knowledge_prepare_save" | "knowledge_propose" | "knowledge_retain_file" | "knowledge_retain_message" | "knowledge_save" | "knowledge_search" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "project_create" | "project_delete" | "project_get" | "project_list" | "project_reorder" | "project_update" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "remember" | "remember_confirm" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_file_publish" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_pause" | "session_resume" | "session_send_message" | "session_set_project" | "session_steer" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_search" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "task_note_archive" | "task_note_promote_instruction_policy" | "task_note_promote_knowledge" | "task_note_promote_preference" | "task_note_replace" | "task_note_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "wait_for_input" | "work_claim_release" | "work_claim_upsert" | "x_accounts_list" | "x_mentions_live" | "x_post_reply" | "x_posts_sync" | "x_search_live" | "x_thread_fetch")[];
 export type NormalizedSlackInteraction = {
     providerEventId: string;
     providerMessageId: string;

package/dist/mcp/documents.d.ts

@@ -1,3 +1,4 @@
+import type { Settings } from "@opengeni/config";
 import type { DocumentServices } from "@opengeni/documents";
 import { type KnowledgeContext, type Database } from "@opengeni/db";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -5,4 +6,5 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * chunk/base retrieval is retired: it cannot bypass pending Knowledge review. */
 export declare function buildDocumentsMcpServer(db: Database, accountId: string, workspaceId: string, documentServices: DocumentServices, options: {
     knowledge: KnowledgeContext;
+    settings?: Settings;
 }): McpServer;

package/dist/mcp/first-party-tool-permissions.d.ts

@@ -271,6 +271,14 @@ export declare const FIRST_PARTY_TOOL_AUTHORIZATION: {
         sessionRequired: true;
         allOf: "sessions:read"[];
     };
+    browser_read: {
+        sessionRequired: true;
+        allOf: "sessions:read"[];
+    };
+    browser_screenshot: {
+        sessionRequired: true;
+        allOf: "sessions:read"[];
+    };
     browser_act: {
         sessionRequired: true;
         allOf: "sessions:control"[];

package/dist/routes/browser-sessions.d.ts

@@ -1,5 +1,6 @@
 import { InteractionActor, type AccessGrant, type FileAsset } from "@opengeni/contracts";
 import { type ApiRouteDeps, type ResolvedSessionAuthorization } from "@opengeni/core";
+import { type BrowserControlScreenshotOptions, type BrowserControlFrame } from "@opengeni/runtime/sandbox";
 import type { Hono } from "hono";
 export declare function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): void;
 export declare function browserNeedsStandaloneDisplayStack(input: {
@@ -7,6 +8,8 @@ export declare function browserNeedsStandaloneDisplayStack(input: {
     linkedComputer: boolean;
     nativeBrowserControl: boolean;
 }): boolean;
+export declare function parseBrowserScreenshotOptions(query: URLSearchParams): BrowserControlScreenshotOptions;
+export declare function browserScreenshotResponse(frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">): Response;
 export declare function interactionActorForGrant(grant: AccessGrant): ReturnType<typeof InteractionActor.parse>;
 /** Resolve Drive authority from the same immutable session authorization that
  * admitted the browser action. Agent-attempt subjects are technical worker

package/dist/routes/github-browser-pages.d.ts

@@ -0,0 +1,5 @@
+import type { GitHubInstallationBindingCandidate } from "@opengeni/contracts";
+export declare function githubInstallationChooserHtml(candidates: GitHubInstallationBindingCandidate[], state: string, workspaceId: string, baseUrl: string): string;
+export declare function githubSetupSuccessHtml(account: string, returnUrl: string): string;
+export declare function githubSetupPendingHtml(): string;
+export declare function githubSuccessHtml(envLines: string[]): string;

package/dist/routes/insights.d.ts

@@ -1,4 +1,30 @@
 import { type ApiRouteDeps, type WorkspaceInsightsFilterField } from "@opengeni/core";
 import type { Hono } from "hono";
 export declare function normalizeWorkspaceInsightsQueryFilter(value: string | null | undefined, field: WorkspaceInsightsFilterField): string | null;
+/**
+ * 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 declare function createInFlightCoalescer<T>(): {
+    run: (key: string, work: () => Promise<T>) => Promise<T>;
+    readonly size: number;
+};
+/**
+ * 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 declare function workspaceInsightsCoalesceKey(input: {
+    workspaceId: string;
+    range: string;
+    provider: string | null;
+    model: string | null;
+    rlsActor: string | null;
+}): string;
 export declare function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/sandbox-file-artifacts.d.ts

@@ -1,6 +1,7 @@
 import { SandboxFileArtifactReceipt, type AccessGrant, type Session } from "@opengeni/contracts";
 import { type ApiRouteDeps, type AccessGrantAuthorization } from "@opengeni/core";
 import { getFile } from "@opengeni/db";
+import { type SandboxChannelAService } from "@opengeni/runtime/sandbox";
 /** Original bytes inherit the already-authorized source session's ownership. */
 export declare function publishSandboxFileArtifact(deps: ApiRouteDeps, input: Parameters<typeof publishSandboxFileArtifactInScope>[1]): Promise<SandboxFileArtifactReceipt>;
 declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
@@ -10,7 +11,22 @@ declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
     path: string;
     signal?: AbortSignal | undefined;
 }): Promise<SandboxFileArtifactReceipt>;
-export declare function sandboxArtifactRelativePath(value: string): string;
+/** Use the root captured by the same fenced Channel-A service that reads bytes,
+ * not the session's placement-home label or a caller-supplied root. */
+export declare function readSandboxArtifactFile(service: Pick<SandboxChannelAService, "capabilities" | "fsRead">, value: string, maxBytes: number): Promise<{
+    path: string;
+    sandboxPath: string;
+    read: {
+        path: string;
+        encoding: "base64" | "utf8";
+        content: string;
+        sizeBytes: number;
+        truncated: boolean;
+        isBinary: boolean;
+        revision: number;
+    };
+}>;
+export declare function sandboxArtifactRelativePath(value: string, workspaceRoot?: string): string;
 export declare function sandboxArtifactSafeFilename(filename: string): string;
 export declare function sandboxFileContentType(filename: string): string;
 export declare function sandboxArtifactIdentity(input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "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": {
@@ -44,22 +44,22 @@
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.6.0",
-    "@opengeni/artifact-tool": "^0.3.31",
+    "@opengeni/artifact-tool": "^0.3.32",
     "@opengeni/capabilities": "^0.3.4",
-    "@opengeni/codemode": "^0.6.1",
-    "@opengeni/codex": "^0.2.25",
-    "@opengeni/config": "^2.1.0",
-    "@opengeni/contracts": "^5.1.0",
-    "@opengeni/core": "^4.0.1",
-    "@opengeni/db": "^6.0.1",
-    "@opengeni/documents": "^0.8.32",
-    "@opengeni/events": "^0.4.30",
-    "@opengeni/github": "^0.7.15",
+    "@opengeni/codemode": "^0.6.2",
+    "@opengeni/codex": "^0.2.26",
+    "@opengeni/config": "^2.1.1",
+    "@opengeni/contracts": "^5.1.1",
+    "@opengeni/core": "^4.0.3",
+    "@opengeni/db": "^6.0.3",
+    "@opengeni/documents": "^0.8.34",
+    "@opengeni/events": "^0.4.32",
+    "@opengeni/github": "^0.7.16",
     "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.31",
-    "@opengeni/runtime": "^4.0.1",
-    "@opengeni/storage": "^0.2.132",
-    "@opengeni/tool-gateway": "^0.1.12",
+    "@opengeni/observability": "^0.8.32",
+    "@opengeni/runtime": "^4.0.3",
+    "@opengeni/storage": "^0.2.133",
+    "@opengeni/tool-gateway": "^0.1.13",
     "@opengeni/xai-subscription": "^0.1.4",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",

package/src/mcp/documents.ts

@@ -1,4 +1,5 @@
 import { searchKnowledgeEntries } from "@opengeni/core";
+import type { Settings } from "@opengeni/config";
 import { KnowledgeEntryListRequest } from "@opengeni/contracts";
 import type { DocumentServices } from "@opengeni/documents";
 import {
@@ -17,7 +18,7 @@ export function buildDocumentsMcpServer(
   accountId: string,
   workspaceId: string,
   documentServices: DocumentServices,
-  options: { knowledge: KnowledgeContext },
+  options: { knowledge: KnowledgeContext; settings?: Settings },
 ): McpServer {
   const context = options.knowledge;
   if (context.accountId !== accountId || context.workspaceId !== workspaceId)
@@ -39,7 +40,13 @@ export function buildDocumentsMcpServer(
         {
           type: "text",
           text: JSON.stringify(
-            await searchKnowledgeEntries(db, context, input, () => documentServices.embedder),
+            await searchKnowledgeEntries(
+              db,
+              context,
+              input,
+              () => documentServices.embedder,
+              options.settings,
+            ),
           ),
         },
       ],

package/src/mcp/first-party-tool-permissions.ts

@@ -117,6 +117,8 @@ export const FIRST_PARTY_TOOL_AUTHORIZATION = {
   browser_open: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_tabs: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_observe: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_read: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_screenshot: { sessionRequired: true, allOf: ["sessions:read"] },
   browser_act: { sessionRequired: true, allOf: ["sessions:control"] },
   browser_clipboard: { sessionRequired: true, allOf: ["sessions:read"] },
   browser_debug: { sessionRequired: true, allOf: ["sessions:read"] },

package/src/mcp/knowledge-entries.ts

@@ -142,7 +142,14 @@ export function registerKnowledgeEntryTools(
     },
     (input) =>
       run((context) =>
-        prepareKnowledgeSave(deps.db, context, input, () => deps.getDocumentServices().embedder),
+        prepareKnowledgeSave(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          undefined,
+          deps.settings,
+        ),
       ),
   );
   server.registerTool(
@@ -159,7 +166,13 @@ export function registerKnowledgeEntryTools(
     },
     (input) =>
       run((context) =>
-        searchKnowledgeEntries(deps.db, context, input, () => deps.getDocumentServices().embedder),
+        searchKnowledgeEntries(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          deps.settings,
+        ),
       ),
   );
   server.registerTool(

package/src/mcp/server.ts

@@ -5854,9 +5854,14 @@ function registerCapabilityDiscoveryTools(
   // This is a readiness projection, never credential resolution or a new grant.
   const setupProjections = async (items: CapabilityCatalogItem[]) => {
     const availableServerIds = new Set<string>();
+    const availableFirstPartyTools = new Set<string>();
     const acceptedServerIds = new Set<string>();
     let accountSelectionKnown = false;
-    if (items.some((item) => item.enabled && item.connectionRef)) {
+    if (
+      items.some(
+        (item) => item.enabled && (item.connectionRef || item.surfaceType === "first_party_fiken"),
+      )
+    ) {
       const claims = exactAgentCommandContext(grant, sessionId);
       const attemptCatalog = await getAttemptToolCatalog(deps.db, {
         accountId: grant.accountId,
@@ -5868,7 +5873,11 @@ function registerCapabilityDiscoveryTools(
         attemptCatalog.turnId === claims.callerTurnId &&
         attemptCatalog.executionGeneration === claims.callerExecutionGeneration
       ) {
-        for (const entry of attemptCatalog.entries) availableServerIds.add(entry.identity.serverId);
+        for (const entry of attemptCatalog.entries) {
+          availableServerIds.add(entry.identity.serverId);
+          if (entry.identity.serverId === "opengeni")
+            availableFirstPartyTools.add(entry.identity.toolName);
+        }
         const bindings = await getSessionTurnMcpAccountBindings(
           deps.db,
           grant.workspaceId,
@@ -5890,6 +5899,8 @@ function registerCapabilityDiscoveryTools(
           availableServerIds,
           acceptedServerIds,
           accountSelectionKnown,
+          availableFirstPartyTools,
+          new Set((grant.metadata?.firstPartyMcpTools as string[] | undefined) ?? []),
         ),
       ),
     );
@@ -6024,7 +6035,45 @@ async function capabilitySetupProjection(
   availableServerIds: ReadonlySet<string>,
   acceptedServerIds: ReadonlySet<string>,
   accountSelectionKnown: boolean,
+  availableFirstPartyTools: ReadonlySet<string>,
+  selectedFirstPartyTools: ReadonlySet<string>,
 ): Promise<CapabilitySetupProjection> {
+  if (item.surfaceType === "first_party_fiken") {
+    if (!item.enabled || item.metadata.connectionStatus !== "active") {
+      return {
+        status: "authorization_required",
+        action: "connect",
+        detail:
+          item.metadata.connectionStatus === "needs_reauth"
+            ? "The workspace Fiken connection needs reconnection."
+            : "Connect Fiken through the protected setup form.",
+      };
+    }
+    const selected = FIRST_PARTY_MCP_TOOL_NAMES.filter(
+      (name) => name.startsWith("fiken_") && selectedFirstPartyTools.has(name),
+    );
+    if (selected.length === 0) {
+      return {
+        status: "authorization_required",
+        action: "enable",
+        detail:
+          "Fiken is connected, but its tools are not selected for this conversation. Ask the user to add its tools through the setup card, then send a new message.",
+      };
+    }
+    if (selected.some((name) => availableFirstPartyTools.has(name))) {
+      return {
+        status: "ready",
+        action: null,
+        detail: "Fiken is connected and has tools available in this turn.",
+      };
+    }
+    return {
+      status: "unavailable",
+      action: null,
+      detail:
+        "Fiken is connected, but its selected tools are unavailable in this execution. Check tool permissions and setup before retrying; reconnection is not required by this status.",
+    };
+  }
   if (item.id === "api:github-app" || item.surfaceType === "first_party_github") {
     const missing = githubAppMissingSettings(deps.settings);
     if (missing.length > 0) {

package/src/routes/browser-sessions.ts

@@ -3,6 +3,7 @@ import {
   environmentsEncryptionKeyBytes,
   resolveFirstPartyDelegationSecret,
   resolveStreamTokenSecret,
+  sandboxWarmRateMicrosPerSecond,
 } from "@opengeni/config";
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
@@ -20,6 +21,8 @@ import {
   BrowserDownloadSaveRequest,
   BrowserDownloadSaveResponse,
   BrowserDownloadListResponse,
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
   BrowserExternalAuthCommand,
   BrowserOpenTargetRequest,
   BrowserObservation,
@@ -31,6 +34,7 @@ import {
   BrowserSessionListResponse,
   BrowserSessionMutationResponse,
   BrowserTargetListResponse,
+  BrowserTargetState,
   CreateBrowserSessionRequest,
   ExternalAuthInteractiveRequest,
   ExternalAuthInteractiveResponse,
@@ -75,6 +79,7 @@ import {
   BrowserSessionNotFoundError,
   BrowserSessionOperationConflictError,
   BrowserSessionStateError,
+  SandboxPaidComputeAdmissionError,
   completeBrowserSessionEnd,
   completeExternalAuth,
   completeBrowserDownloadSave,
@@ -88,6 +93,7 @@ import {
   dispatchExternalAuth,
   dispatchProtectedAuthFill,
   failBrowserSessionOperation,
+  failPreparedBrowserSessionSuspend,
   failBrowserSessionResume,
   failBrowserSessionResumePreparation,
   failBrowserSessionSuspension,
@@ -169,6 +175,8 @@ import {
   provisionBrowserControlClient,
   renewSandboxProviderExpiration,
   type BrowserControlPlacementSession,
+  type BrowserControlScreenshotOptions,
+  type BrowserControlFrame,
   type PlacementBrowserStateCaptureReceipt,
   type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
@@ -952,6 +960,71 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
     },
   );
 
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/state",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.targetState(targetId),
+      );
+      return context.json(BrowserTargetState.parse(result));
+    },
+  );
+
+  app.post(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/dom-read",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const request = await parseJsonBody(context, BrowserDomReadRequest);
+      const result = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.readDom(targetId, request),
+      );
+      return context.json(BrowserDomReadResponse.parse(result));
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/targets/:targetId/screenshot",
+    async (context) => {
+      const { workspaceId, grant, browserSessionId } = await browserRoutePreamble(
+        context,
+        "sessions:read",
+      );
+      const targetId = requireOpaqueParam(context, "targetId");
+      const captureOptions = parseBrowserScreenshotOptions(new URL(context.req.url).searchParams);
+      const frame = await withActiveBrowserController(
+        context,
+        grant,
+        workspaceId,
+        browserSessionId,
+        "session.read",
+        "browser.read",
+        async ({ sessionClient }) => await sessionClient.capture(targetId, captureOptions),
+      );
+      return browserScreenshotResponse(frame);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/browser-sessions/:browserSessionId/actions",
     async (context) => {
@@ -2047,6 +2120,7 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
       const request = await parseJsonBody(context, BrowserSessionLifecycleRequest);
       const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings);
+      let preparedForDispatch = false;
       try {
         const before = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
@@ -2098,6 +2172,8 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
           return context.json(parsed, 200);
         }
 
+        preparedForDispatch = true;
+
         const record = await getBrowserSessionControlRecord(deps.db, {
           accountId: grant.accountId,
           workspaceId,
@@ -2259,6 +2335,15 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
         observeLifecycleResult(deps.observability, startedAtMs, parsed);
         return context.json(parsed, 200);
       } catch (error) {
+        if (preparedForDispatch) {
+          await failPreparedBrowserSessionSuspend(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            browserSessionId,
+            operationId: request.operationId,
+            error: interactionFailure(error),
+          });
+        }
         throw browserRouteError(error);
       }
     },
@@ -2792,6 +2877,12 @@ export function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): voi
             resolved.kind !== "selfhosted" ||
             resolved.sandboxId !== expectedPlacement.sandboxId
           ) {
+            if (operation === "browser.create") {
+              throw new HTTPException(422, {
+                message:
+                  "The requested Connected Machine is not this session's current placement. Move the session to that machine before creating an interaction resource.",
+              });
+            }
             return await throwBrowserSourcePlacementChanged(
               grant,
               sourceSession.id,
@@ -3748,6 +3839,10 @@ async function ensureInteractionHolder(
     holderId: interactionHolderId(browserSessionId),
     subjectId: sourceSession.id,
     backend: placement.lease.backend,
+    warmBilling: {
+      mode: deps.settings.sandboxWarmBillingMode,
+      rateMicrosPerSecond: sandboxWarmRateMicrosPerSecond(deps.settings, placement.lease.backend),
+    },
     os: placement.lease.os,
     image: sandboxRuntime.image,
     rigVersionId: sourceSession.rigVersionId,
@@ -4160,6 +4255,49 @@ function optionalBoundedInteger(
   return parsed;
 }
 
+export function parseBrowserScreenshotOptions(
+  query: URLSearchParams,
+): BrowserControlScreenshotOptions {
+  for (const key of ["fullPage", "format", "quality"]) {
+    if (query.getAll(key).length > 1) {
+      throw new HTTPException(400, { message: `duplicate browser screenshot ${key}` });
+    }
+  }
+  const fullPage = query.get("fullPage");
+  if (fullPage !== null && fullPage !== "true" && fullPage !== "false") {
+    throw new HTTPException(400, { message: "invalid browser screenshot fullPage" });
+  }
+  const format = query.get("format");
+  if (format !== null && format !== "jpeg" && format !== "png") {
+    throw new HTTPException(400, { message: "invalid browser screenshot format" });
+  }
+  const quality = query.get("quality");
+  const parsedQuality = quality === null ? null : optionalBoundedInteger(quality, 1, 100);
+  if (quality !== null && parsedQuality === null) {
+    throw new HTTPException(400, { message: "invalid browser screenshot quality" });
+  }
+  return {
+    ...(fullPage === null ? {} : { fullPage: fullPage === "true" }),
+    ...(format === null ? {} : { format }),
+    ...(parsedQuality === null ? {} : { quality: parsedQuality }),
+  };
+}
+
+export function browserScreenshotResponse(
+  frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">,
+): Response {
+  // Node Buffers can be views into a larger backing allocation. Copy exactly
+  // the image bytes before constructing the Response.
+  return new Response(Uint8Array.from(frame.data).buffer, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": frame.mediaType,
+      "x-opengeni-browser-frame": frame.metadataHeader,
+    },
+  });
+}
+
 function isUuid(value: unknown): value is string {
   return (
     typeof value === "string" &&
@@ -4716,6 +4854,8 @@ function browserRouteError(error: unknown): HTTPException {
   const connectedMachineError = interactionControlApiError(error, "browser");
   if (connectedMachineError) return connectedMachineError;
   if (error instanceof HTTPException) return error;
+  if (error instanceof SandboxPaidComputeAdmissionError)
+    return new HTTPException(402, { message: error.message, cause: error });
   if (error instanceof BrowserSessionNotFoundError) {
     return new HTTPException(404, { message: error.message, cause: error });
   }