@opengeni/api-router 3.0.1 → 3.1.2

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

@@ -1,25 +1,47 @@
-import { type FileResourceRef, type WorkspaceSlackReactionSummonSettings } from "@opengeni/contracts";
+import { type FileResourceRef, type FirstPartyMcpToolName, type WorkspaceSlackReactionSummonSettings } from "@opengeni/contracts";
+import { type ParsedSessionUsageLimitReachedRefusal } from "@opengeni/contracts/session-usage-limit-refusal";
+import { type Settings } from "@opengeni/config";
 import { type SlackInstallationRoute, type SlackInteraction, type SlackInteractionInboxEntry, type SlackInteractionTriggerKind } from "@opengeni/db";
 import { type ApiRouteDeps } from "@opengeni/core";
 import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import { type OpenGeniSlackBotClient, type SlackMessageBlock } from "./slack-bot.js";
 import { type ImportedSlackReactionImage } from "../slack-reaction-files.js";
 export declare const SLACK_INTERACTION_MAX_BODY_BYTES: number;
 export declare const SLACK_SIGNATURE_REPLAY_WINDOW_SECONDS = 300;
 export declare const SLACK_DELIVERY_EVENT_TYPES: readonly ["agent.message.completed", "session.humanInput.requested", "session.requiresAction", "turn.completed", "turn.failed", "turn.cancelled", "session.status.changed", "system.update.pending", "goal.paused"];
+/**
+ * The thread line when a task stops at its usage limit: the amounts when the
+ * stop marker carries them, what a person can do, and a link to the task.
+ * API-equivalent model usage, never credits, billing or a monthly reset.
+ */
+export declare function slackSessionUsageLimitStopText(input: {
+    mention: string;
+    refusal: Pick<ParsedSessionUsageLimitReachedRefusal, "limitMicros" | "usedMicros"> | null;
+    link: string | null;
+}): string;
 /**
  * Slack delivery restrictions are durable session-level authority, not
- * attacker-adjacent user-message context. Migration 0240 backfills this exact
- * policy onto every pre-cutover session reserved by a Slack interaction.
+ * attacker-adjacent user-message context. Migration 0240 backfilled the original
+ * policy onto pre-cutover Slack sessions. Changes here apply to new sessions;
+ * historical stored instructions require a separately reviewed migration.
  */
 export declare const SLACK_SESSION_INSTRUCTIONS: string;
 /**
  * Slack-originated tasks may retrieve the workspace bot's bounded read surface
- * on demand. Connector tools are explicit-only, so freeze that narrow context
- * selection at session creation while keeping Slack mutations out of the model
- * surface; interaction delivery remains owned by the durable delivery pump.
+ * and explicitly deliver a retained task file to their own thread. These tools
+ * are guaranteed on top of the defaults a Slack session follows; ordinary
+ * interaction messages remain owned by the durable delivery pump.
+ */
+export declare const SLACK_TASK_FIRST_PARTY_MCP_TOOLS: ("admin_action_call" | "admin_action_describe" | "admin_actions_search" | "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_download_save" | "browser_downloads" | "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_enable_screen_control" | "connected_machine_enroll_token" | "connected_machine_remove" | "custom_mcp_setup_request" | "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" | "inbox_tidy" | "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" | "notification_withdraw" | "notify_user" | "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" | "secret_delete" | "secret_get" | "secret_move" | "secret_save" | "secret_search" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_message_status" | "session_pause" | "session_resume" | "session_send_message" | "session_set_model" | "session_set_project" | "session_steer" | "session_target_get" | "session_target_set" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "site_data_define_collection" | "site_data_describe" | "site_data_export" | "site_data_import" | "site_data_query" | "site_data_reset" | "site_data_write" | "site_files_delete" | "site_files_list" | "site_files_upload" | "site_hostname_check" | "site_publication_apply_fix" | "site_publication_get" | "site_publication_update" | "site_sql_define_query" | "site_sql_enable" | "site_sql_execute" | "site_sql_export" | "site_sql_import" | "site_sql_inspect" | "site_sql_migrate" | "site_sql_query" | "site_sql_reset" | "site_sql_run" | "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_prepare_message" | "slack_bot_search" | "slack_bot_send_prepared_message" | "slack_bot_thread_replies" | "slack_bot_upload_file" | "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")[];
+/** The Slack task tools that are not already default built-in tools. */
+export declare const SLACK_TASK_ADDITIONAL_FIRST_PARTY_MCP_TOOLS: readonly FirstPartyMcpToolName[];
+/**
+ * The workspace's default first-party selection (or the deployment default)
+ * plus the bounded Slack task tools. These are added whatever the base is, then
+ * intersected with deployment policy; existing accepted selections stay frozen.
  */
-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_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_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 function slackTaskFirstPartyMcpTools(settings: Settings, workspaceSettings: unknown): FirstPartyMcpToolName[];
 export type NormalizedSlackInteraction = {
     providerEventId: string;
     providerMessageId: string;
@@ -84,14 +106,69 @@ export declare function withWorkspaceLine(label: string | null, text: string, bl
  * id on the label rather than on the release: a labelled interaction can only
  * have been created by an image that already renders the line, and every
  * pre-existing and unlabelled interaction keeps its exact ledger identity.
+ *
+ * A compact interaction (one with a frozen `startMessageLine`) names its
+ * workspace once, on its first message, and nowhere else. For a labelled one
+ * that is again different bytes from what an older image renders for the same
+ * message, so its ids move once more, to `:v3`. Unlabelled interactions render
+ * the same bytes in both formats and keep their ids.
+ */
+export declare function slackPostSeed(interaction: Pick<SlackInteraction, "routedWorkspaceLabel" | "startMessageLine">, seed: string): string;
+/**
+ * The acknowledgement seed for interactions that already carry a frozen
+ * "Using" line from before new acknowledgements stopped including it.
+ *
+ * The old line was written once at session bind and never changes, so a
+ * historical retry must keep the same ledger identity and bytes. New
+ * interactions bind no line and use the original acknowledgement seed.
+ */
+export declare function slackDefaultsLinePostSeed(interaction: Pick<SlackInteraction, "sessionDefaultsLine">, seed: string): string;
+/**
+ * The post operation of an interaction's first message.
+ *
+ * A compact first message shares no bytes with anything an older image renders
+ * for the same interaction, so it has its own seed: an older image repairing it
+ * during a rolling deploy posts a second message rather than wedging on a digest
+ * conflict. Every handle on the first message carries this id.
+ */
+export declare function slackAcknowledgementOperationId(interaction: Pick<SlackInteraction, "id" | "routedWorkspaceLabel" | "sessionDefaultsLine" | "startMessageLine">): string;
+/** Where a compact task's first message says the task came from. */
+export type SlackStartMessageOrigin = {
+    kind: "task";
+} | {
+    kind: "private_dm_message";
+} | {
+    kind: "private_conversation";
+} | {
+    kind: "reaction";
+    emoji: string;
+};
+/**
+ * The opening sentence of a new task's first Slack message.
+ *
+ * The sentence itself links to the session, and a routed workspace is named
+ * inline, here and on no other message. The private variants keep their privacy
+ * sentence, and the reaction variant keeps its how-to, because a reaction-started
+ * task has no button and never shows the one-time hint.
+ *
+ * Rendered once when the session binds and frozen as `startMessageLine`, so a
+ * later change to the web base URL or the workspace name cannot change the bytes
+ * of a message the post and update ledgers already hold.
  */
-export declare function slackPostSeed(interaction: Pick<SlackInteraction, "routedWorkspaceLabel">, seed: string): string;
+export declare function renderSlackStartMessageLine(input: {
+    sessionUrl: string;
+    routedWorkspaceLabel: string | null;
+    origin: SlackStartMessageOrigin;
+}): string;
 export type SlackInvocationMessageContext = {
     messages: Awaited<ReturnType<OpenGeniSlackBotClient["threadReplies"]>>["messages"];
     nextCursor: string | null;
     kind: "thread" | "channel";
+    unavailable?: "rate_limited" | "attachments_only";
 };
-export declare function slackInvocationModelContext(invocationTimestamp: string, context: SlackInvocationMessageContext): string;
+/** Context is optional; only Slack's explicit history throttling may be omitted. */
+export declare function loadSlackInvocationMessageContext(client: Pick<OpenGeniSlackBotClient, "threadReplies" | "channelHistory">, entry: Pick<SlackInteractionInboxEntry, "slackChannelId" | "slackThreadTs" | "slackMessageTs">, authorizeRead?: () => Promise<void>, exactMessageOnly?: boolean): Promise<SlackInvocationMessageContext>;
+export declare function slackInvocationModelContext(invocationTimestamp: string, context: SlackInvocationMessageContext, channelId?: string): string;
 type SlackReactionMessageContext = Awaited<ReturnType<OpenGeniSlackBotClient["reactionMessageContext"]>>;
 type PreparedSlackReactionTask = Readonly<{
     resources: FileResourceRef[];
@@ -99,9 +176,10 @@ type PreparedSlackReactionTask = Readonly<{
     omissionCodes: string[];
     omittedCount: number;
 }>;
-export declare function slackReactionTaskText(context: SlackReactionMessageContext, prepared?: PreparedSlackReactionTask): string;
+export declare function slackReactionTaskText(context: SlackReactionMessageContext, prepared?: PreparedSlackReactionTask, channelId?: string): string;
 export declare function slackDeliveryTextsCoalesce(left: string, right: string): boolean;
 export declare function normalizedBlockActionInteraction(payload: Record<string, unknown>): NormalizedSlackInteraction;
+export declare function slackSecretAnswerRefusalText(sessionUrl: string | null): string;
 export declare function isSlackInfoCommand(text: string): boolean;
 type SlackUserLinkToken = {
     workspaceId: string;
@@ -112,4 +190,5 @@ type SlackUserLinkToken = {
 };
 export declare function createSlackUserLinkToken(signingSecret: string, entry: Pick<SlackInteractionInboxEntry, "workspaceId" | "connectionId" | "slackTeamId" | "slackUserId">, nowMs?: number): string;
 export declare function verifySlackUserLinkToken(signingSecret: string, token: string, nowMs?: number): SlackUserLinkToken | null;
+export declare function slackAdmissionFailureText(error: HTTPException): string;
 export {};

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

@@ -0,0 +1,41 @@
+/**
+ * Markdown to Slack mrkdwn for model-authored text Opengeni posts to Slack.
+ *
+ * Agents write ordinary Markdown because the same reply renders as Markdown in
+ * the Opengeni console. Slack message text does not render Markdown headings,
+ * `**bold**`, or `[label](url)` links, so a reply that reads well in the
+ * console arrives in Slack full of literal syntax. This rewrites only that
+ * syntax, only for the bytes handed to Slack: stored session events, model
+ * history, and every other surface keep the model's exact text. It is
+ * formatting at a third-party sink, not content classification or redaction.
+ *
+ * Code is never rewritten: fenced code blocks keep every line between their
+ * fences, and inline code spans are copied as they are.
+ *
+ * The output is part of the Slack post and update ledgers' request digest, so a
+ * change to it changes the bytes an in-flight operation is bound to. Delivery
+ * (`deliverSlackModelText` in `slack-interactions.ts`) falls back only to the
+ * unformatted text; a later output change must keep the previous rendering
+ * reachable the same way, or operations started before the deploy conflict on
+ * every retry.
+ */
+/** Remove provider citation handles and any stray citation delimiters. */
+export declare function stripProviderCitationMarkers(text: string): string;
+/**
+ * Rewrite common Markdown as Slack mrkdwn.
+ *
+ * - `# Heading` (any level) becomes a bold line.
+ * - `**bold**` and `__bold__` become `*bold*`, `***both***` becomes `*_both_*`,
+ *   and `~~struck~~` becomes `~struck~`.
+ * - `[label](https://...)` becomes `<https://...|label>`.
+ * - `-`, `*`, and `+` bullets become Slack's `•` bullet, keeping indentation;
+ *   numbered lists and block quotes are already Slack syntax and stay as they are.
+ * - Fenced code blocks, at any indentation, keep their contents byte for byte.
+ *   The opening fence loses its language tag, which Slack would otherwise print
+ *   as the first code line, and an unclosed block is closed so Slack still
+ *   renders it as code.
+ * - Provider citation handles are removed.
+ *
+ * Text that uses none of this syntax comes back unchanged.
+ */
+export declare function slackMrkdwnFromMarkdown(markdown: string): string;

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

@@ -48,7 +48,7 @@ export declare function isSlackDirectMessageConversation(entry: Pick<SlackIntera
  * Split a leading bot mention off the message text.
  *
  * Slack delivers an `app_mention` with the mention still in the text
- * (`<@U123> do the thing`), and OpenGeni stores it verbatim. The workspace
+ * (`<@U123> do the thing`), and Opengeni stores it verbatim. The workspace
  * prefix is only an override when it is the first thing the person typed, so it
  * is parsed after the mention rather than at byte 0 of the raw text. Everything
  * split off here is put back, so the message the model sees is unchanged apart

package/dist/integrations/slack-session-defaults.d.ts

@@ -0,0 +1,58 @@
+import { type AccessGrant, type GitHubRepository, type RepositoryResourceRef } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+/**
+ * A Slack task starts with at most this many repositories. Each one is a
+ * shallow, blob-filtered fetch before the first command, so the set stays
+ * small: the person's own most recently used repositories, not a catalog.
+ */
+export declare const SLACK_SESSION_RECENT_REPOSITORY_LIMIT = 5;
+/** How far back the person's own sessions count as recent use. */
+export declare const SLACK_SESSION_RECENT_REPOSITORY_WINDOW_MS: number;
+/**
+ * Pick a Slack task's repositories: the person's recently used repositories,
+ * in recency order, that the workspace GitHub App catalog still offers them.
+ *
+ * `recent` is a usage signal only, and only repositories the person attached
+ * themselves count: an automatically attached (`optional`) one never does. A
+ * repository reaches the task only through its current catalog entry (the
+ * same catalog and `github:use` permission as the website picker), on its
+ * default branch, so a Slack task never reaches a repository the person could
+ * not attach on the website today. Archived and
+ * empty repositories are skipped when GitHub reported that, because a clone of
+ * an empty repository has nothing to check out. Every returned resource is
+ * best effort (`optional`): one failed clone warns instead of failing setup.
+ */
+export declare function selectRecentRepositoryResources(recent: readonly RepositoryResourceRef[], catalog: readonly GitHubRepository[], limit?: number): RepositoryResourceRef[];
+/**
+ * The repositories a new Slack task starts with: the person's own recently
+ * used repositories in this workspace (their own top-level sessions active in
+ * the last 30 days, most recent first, at most five), limited to what the
+ * workspace GitHub App catalog offers them now. None when they have none; the
+ * agent can still find and clone repositories through its GitHub tools.
+ *
+ * GitHub is asked only when there is something to look up. A GitHub outage or
+ * an unconfigured App starts the task without repositories instead of failing
+ * it, with a log line for diagnosis.
+ */
+export declare function slackRecentRepositoryResources(deps: ApiRouteDeps, grant: Pick<AccessGrant, "permissions" | "subjectId">, workspaceId: string, now?: Date): Promise<RepositoryResourceRef[]>;
+export type OtherDeploymentLink = {
+    url: string;
+    host: string;
+};
+/**
+ * Opengeni workspace or session links in `text` that point at a sibling
+ * deployment of this one (for example staging versus production).
+ *
+ * A sibling is a different host under the same parent domain as this
+ * deployment's web origin, carrying Opengeni's own route shape. Anything else
+ * is left alone: an unrelated product's URL must never be described as
+ * another Opengeni.
+ */
+export declare function otherDeploymentLinks(text: string, webBaseUrl: string | null | undefined): OtherDeploymentLink[];
+/**
+ * Model context for links to another Opengeni deployment. A session id from
+ * one deployment does not exist in another, so without this the agent reports
+ * "Session not found or access denied" and asks for access that no grant in
+ * this deployment can give.
+ */
+export declare function otherDeploymentLinkContext(text: string, webBaseUrl: string | null | undefined): string | null;

package/dist/integrations/slack-task-file-upload.d.ts

@@ -0,0 +1,36 @@
+import { type AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type SlackInteraction } from "@opengeni/db";
+export declare const SLACK_TASK_FILE_UPLOAD_MAX_BYTES: number;
+/** The source and destination are canonical authorities, never a URL or channel supplied by the model. */
+export declare function uploadSlackTaskFile(deps: ApiRouteDeps, input: {
+    grant: AccessGrant;
+    sessionId: string;
+    fileId: string;
+    operationId: string;
+    authorize: () => Promise<void>;
+}): Promise<{
+    slackFileId: string;
+    replayed: boolean;
+    status: "uploaded";
+    fileId: string;
+    channelId: string;
+    threadTimestamp: string;
+    receipt: {
+        credentialRole: "opengeni_slack_bot";
+        credentialLabel: "OpenGeni Slack bot";
+        connectionId: string;
+        slackTeamId: string;
+        operation: string;
+        operationId: string;
+    };
+}>;
+export declare function slackTaskRequesterCanReceiveFile(permissions: AccessGrant["permissions"]): boolean;
+/** Private shortcuts bind a runnable session before its bot-DM route commits. */
+export declare function assertSlackTaskUploadTarget(interaction: Pick<SlackInteraction, "visibility" | "slackChannelId" | "slackThreadTs" | "routeKey" | "ackSlackMessageTs">): void;
+export declare function assertSlackTaskUploadFile(file: {
+    status: string;
+    scope?: string | undefined;
+    sizeBytes: number;
+    sha256: string | null;
+}, visibility: string): void;

package/dist/integrations/slack-tool-review.d.ts

@@ -0,0 +1,5 @@
+import type { ToolActionReview } from "@opengeni/contracts";
+import type { SlackMessageBlock } from "./slack-bot.js";
+/** Shared review facts, projected only into a proven private bot conversation. */
+export declare function slackToolReviewCanDecide(review: ToolActionReview): boolean;
+export declare function slackToolReviewBlocks(review: ToolActionReview, privateAudience: boolean): SlackMessageBlock[];

package/dist/interaction-agent-access.d.ts

@@ -3,17 +3,22 @@ import { type ApiRouteDeps } from "@opengeni/core";
 type AssociatedInteractionSession = {
     associations: ReadonlyArray<{
         sessionId: string;
+        relationship: string;
     }>;
 };
 /**
- * Narrow a workspace-wide BrowserSession/ComputerSession inventory to the
- * entries a live agent attempt may reach. Every attach-by-id route already
- * authorizes the exact source session through the core seam; the list is the
- * discovery surface behind `interaction_discover scope=workspace`, so it must
- * apply the same seam (private sessions, Slack ownership, and the 0426
- * agent-access scope) to each associated session instead of exposing every
- * peer's identity. Humans, API keys, and service principals keep the complete
- * workspace inventory exactly as before.
+ * Optional narrowing filters for BrowserSession/ComputerSession inventories,
+ * applied in SQL before per-source authorization. They narrow, never grant:
+ * every returned row still passes filterInteractionSessionsForGrant.
+ */
+export declare function parseInteractionSessionListQuery(query: Record<string, string>): {
+    associatedSessionId?: string;
+    includeTerminal?: boolean;
+};
+/**
+ * Apply the same source-chat authorization as get/control routes, for every
+ * caller. A later using/observing/related association never transfers ownership
+ * or makes a private interaction discoverable through another chat.
  */
 export declare function filterInteractionSessionsForGrant<T extends AssociatedInteractionSession>(deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">, grant: AccessGrant, sessions: readonly T[]): Promise<T[]>;
 export {};

package/dist/interaction-agent-version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Saved-secret typing needs a controller that understands the private
+ * `secretValues` side map. Server-managed controllers always do; a Connected
+ * Machine or attached browser runs whatever agent its owner installed, and an
+ * agent built before the field existed rejects the whole command as malformed.
+ * Refuse before anything is resolved or dispatched, and say how to fix it.
+ */
+import type { AccessGrant, InteractionPlacement } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+import { ApiHttpError } from "./http/api-error.js";
+/** The first agent release whose controller accepts `secretValues`. */
+export declare const MINIMUM_AGENT_VERSION_FOR_SECRET_VALUES = "0.1.56";
+/** True only when the installed version is known and predates secret values.
+ * An unknown or unparsable version is not refused on a guess. */
+export declare function agentVersionRejectsSecretValues(agentVersion: string | null): boolean;
+export declare function agentUpdateRequiredForSecretsError(agentVersion: string): ApiHttpError;
+/** The installed agent version behind a device placement; null for
+ * server-managed placements or when the machine is not live. */
+export declare function placementAgentVersion(db: Database, grant: AccessGrant, workspaceId: string, placement: InteractionPlacement | null): Promise<string | null>;
+/** A `beforeResolve` hook for `resolveInteractionSecretValues`. */
+export declare function requirePlacementAcceptsSecretValues(db: Database, grant: AccessGrant, workspaceId: string, placement: InteractionPlacement | null): () => Promise<void>;

package/dist/interaction-holder-heartbeat.d.ts

@@ -14,4 +14,9 @@ export declare function withInteractionHolderHeartbeat<T>(deps: ApiRouteDeps, in
     operationId: string;
     resourceId: string;
     controllerGeneration: string;
+    /** Continuing an expired browser resume on its retained generation: its
+     * operation is recorded only once the controller adopts the working copy,
+     * so the expired resume itself (still lost, still bound to this
+     * generation) is the authority until then. */
+    continuesExpiredBrowserResume?: true;
 }, run: () => Promise<T>): Promise<T>;

package/dist/interaction-metrics.d.ts

@@ -1,8 +1,8 @@
-import type { AuthRunMutationResponse, BrowserActionReceipt, BrowserActionRequest, PublishBrowserRevisionResponse, BrowserSessionMutationResponse, ComputerActionReceipt, ComputerActionRequest, ComputerSessionMutationResponse, InteractionInterventionMutationResponse, ProtectedAuthFillResponse } from "@opengeni/contracts";
+import type { AuthRunMutationResponse, BrowserActionReceipt, BrowserActionRequest, PublishBrowserRevisionResponse, BrowserSessionMutationResponse, ComputerActionReceipt, ComputerActionRequest, ComputerSessionMutationResponse, InteractionInterventionMutationResponse } from "@opengeni/contracts";
 import { type Observability } from "@opengeni/observability";
 import type { ComputerFrameEvidenceMismatchReason } from "@opengeni/runtime/sandbox";
 type InteractionLifecycleMutation = BrowserSessionMutationResponse | ComputerSessionMutationResponse;
-type AuthMutation = AuthRunMutationResponse | ProtectedAuthFillResponse;
+type AuthMutation = AuthRunMutationResponse;
 export declare function observeBrowserActionResult(observability: Observability | null | undefined, startedAtMs: number, request: BrowserActionRequest, receipt: BrowserActionReceipt): void;
 export declare function observeComputerActionResult(observability: Observability | null | undefined, startedAtMs: number, request: ComputerActionRequest, receipt: ComputerActionReceipt): void;
 export declare function observeComputerFrameEvidenceMismatch(observability: Observability | null | undefined, reason: ComputerFrameEvidenceMismatchReason): void;
@@ -10,4 +10,29 @@ export declare function observeLifecycleResult(observability: Observability | nu
 export declare function observeBrowserRevisionPublication(observability: Observability | null | undefined, startedAtMs: number, response: PublishBrowserRevisionResponse): void;
 export declare function observeAuthMutation(observability: Observability | null | undefined, startedAtMs: number, response: AuthMutation): void;
 export declare function observeInterventionMutation(observability: Observability | null | undefined, response: InteractionInterventionMutationResponse): void;
+type InteractionRouteOperation = {
+    resource: "browser" | "computer";
+    operation: string;
+    mode: string;
+    /** The handler already records its successful outcome from the receipt. */
+    successObservedByHandler: boolean;
+};
+export declare function interactionRouteOperation(method: string, route: string): InteractionRouteOperation | null;
+/**
+ * Bounded failure reason for a refused or failed interaction route, derived
+ * only from the HTTP status and the content-free rejection classification.
+ */
+export declare function interactionRouteFailureReason(status: number, rejectionReason: string | undefined): string;
+/**
+ * Observe the HTTP-level outcome of an interaction route. Routes whose handler
+ * already records success from its receipt are counted here only on failure,
+ * so every attempt is counted exactly once.
+ */
+export declare function observeInteractionRouteOutcome(observability: Observability | null | undefined, input: {
+    method: string;
+    route: string;
+    status: number;
+    durationMs: number;
+    rejectionReason?: string | undefined;
+}): void;
 export {};

package/dist/interaction-route-stages.d.ts

@@ -0,0 +1,25 @@
+import type { Observability } from "@opengeni/observability";
+import type { Context } from "hono";
+/** Fixed stage names, so the histogram label stays bounded. */
+export type InteractionRouteStage = "auth" | "record" | "authorize" | "source_session" | "control" | "placement_cache" | "placement_resolve" | "placement_cache_write" | "placement" | "fences" | "passkey_pre" | "secrets" | "dispatch" | "passkey_post" | "replay_check" | "prepare" | "restore" | "network_route" | "holder" | "generation" | "provision" | "display" | "launch" | "activate";
+export type InteractionRouteStageOperation = "act" | "observe" | "target_state" | "create";
+/**
+ * Wall-clock split of one browser control request into its sequential stages.
+ * `mark(stage)` closes the stage that ran since the previous mark. Stages that
+ * run more than once (a recovery retry) accumulate. The split is reported as a
+ * content-free `Server-Timing` header and a per-stage histogram, so harness
+ * overhead around the controller's own work stays visible.
+ */
+export declare class InteractionRouteStages {
+    readonly operation: InteractionRouteStageOperation;
+    private readonly now;
+    private last;
+    private readonly durations;
+    constructor(operation: InteractionRouteStageOperation, now?: () => number);
+    mark(stage: InteractionRouteStage): void;
+    entries(): Array<[InteractionRouteStage, number]>;
+    serverTiming(): string;
+    observe(observability: Observability | null | undefined): void;
+}
+/** Attach the stage split to the response and the stage histogram. */
+export declare function reportInteractionRouteStages(context: Context, observability: Observability | null | undefined, stages: InteractionRouteStages): void;

package/dist/interaction-secrets-vault.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The vault-backed `InteractionSecretsPort` (design §10B.4, Q-32, D20): the
+ * real secret resolver for agent Browser and Computer actions, and passkey
+ * items for the session's virtual authenticators.
+ */
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+import { type BrowserPasskeyCredentialMaterial } from "@opengeni/contracts";
+import { type VaultService } from "@opengeni/core";
+import { type Database } from "@opengeni/db";
+import type { InteractionSecretsPort } from "./interaction-secrets.js";
+export declare function passkeyItemName(credential: BrowserPasskeyCredentialMaterial): string;
+export declare function createVaultInteractionSecretsPort(deps: {
+    db: Database;
+    /** The variable-set envelope key; null fails value reads like the vault API. */
+    encryptionKey: Uint8Array | null;
+    /** Defaults to a service over the same database and key. */
+    vaultService?: VaultService;
+    /** Connected vaults (1Password, host) for a workspace's acting subject. */
+    providersFor?: (workspaceId: string, subjectId: string | null) => VaultProviderRegistry;
+}): InteractionSecretsPort;

package/dist/interaction-secrets.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `{{secret:…}}` references in Browser and Computer actions (design §10B.4,
+ * BR-1..3). Only agent attempts resolve: the API resolves the references in
+ * the secret-bearing fields of an action right before dispatch and sends the
+ * plaintext to the controller in the private `secretValues` side map. Human
+ * and service callers' text is always typed literally. Agent-owned passkeys
+ * ride the same seam: around every agent browser action the API loads the
+ * principal's leased passkeys into browserd and pulls registration and
+ * assertion events back into the vault.
+ */
+import { type AccessGrant, type BrowserPasskeyCredential, type BrowserPasskeyCredentialMaterial, type BrowserPasskeySyncRequest, type BrowserPasskeySyncResponse, type InteractionSecretValues, type SecretClock, SecretReferenceError, type SecretPrincipal, type SecretResolver, type SecretUseContext } from "@opengeni/contracts";
+import { ApiHttpError } from "./http/api-error.js";
+export type AttemptSecretPrincipal = Extract<SecretPrincipal, {
+    kind: "attempt";
+}>;
+/** Vault storage for agent-owned passkeys (F2: `lease_vault_passkeys`,
+ * `update_passkey_sign_count`, `release_vault_passkey_leases`). */
+export interface InteractionPasskeyStore {
+    /** Lease every passkey item the principal may use and no other holder holds. */
+    lease(principal: AttemptSecretPrincipal, holder: string, ttlSeconds: number): Promise<BrowserPasskeyCredential[]>;
+    /** Save a passkey the agent just registered; returns the new item. */
+    saveRegistered(principal: AttemptSecretPrincipal, input: {
+        credential: BrowserPasskeyCredentialMaterial;
+        origin: string | null;
+    }): Promise<{
+        itemId: string;
+    }>;
+    /** Monotonic write-back (`greatest(existing, new)`). */
+    updateSignCount(principal: AttemptSecretPrincipal, itemId: string, signCount: number): Promise<void>;
+    release(holder: string): Promise<void>;
+}
+export interface InteractionSecretsPort {
+    /** The principal's resolver, or null when secrets are unavailable here.
+     * A resolver with `enabled: false` (capability off) also passes text through
+     * literally (Q-35). */
+    resolverFor(principal: AttemptSecretPrincipal): Promise<SecretResolver | null>;
+    passkeys: InteractionPasskeyStore | null;
+    clock?: SecretClock;
+}
+export type InteractionSecretsLog = (event: string, fields: Record<string, unknown>) => void;
+/** The attempt principal of an agent grant. Human, service and incomplete
+ * grants have none, so their text is never resolved (BR-1). */
+export declare function attemptSecretPrincipal(grant: AccessGrant): AttemptSecretPrincipal | null;
+/** The public failure: nothing was dispatched. `details.secretReference` is
+ * the model-facing `{error, failures, askCard, hint}` object; it never
+ * contains values. */
+export declare function secretReferenceHttpError(error: SecretReferenceError): ApiHttpError;
+/** Every string in a JSON-like value (native desktop call arguments). */
+export declare function collectStringsDeep(value: unknown, out?: string[], depth?: number): string[];
+/**
+ * Resolve the references in `texts` for an agent grant. Returns undefined
+ * when the text must be dispatched literally (non-agent caller, no marker,
+ * secrets unavailable or off). Returns a (possibly empty) side map otherwise;
+ * an empty map still tells the controller to remove `\{{secret:…}}` escapes.
+ * TOTP codes are computed last, at dispatch (Q-33). Throws ApiHttpError(422)
+ * before anything is dispatched when any reference fails (I2).
+ */
+export declare function resolveInteractionSecretValues(input: {
+    port: InteractionSecretsPort | null | undefined;
+    grant: AccessGrant;
+    texts: readonly string[];
+    use: SecretUseContext;
+    /** Runs once the text is known to carry references for an agent with
+     * secrets enabled, before anything resolves: a controller that cannot
+     * accept secret values refuses here, with nothing used or dispatched. */
+    beforeResolve?: () => Promise<void>;
+}): Promise<InteractionSecretValues | undefined>;
+export declare const PASSKEY_LEASE_TTL_SECONDS = 600;
+export declare function resetPasskeySessionCacheForTests(): void;
+/** One lease holder per BrowserSession: every target in it shares the set. */
+export declare function passkeyLeaseHolder(browserSessionId: string): string;
+export type PasskeySyncClient = {
+    passkeySync(request: BrowserPasskeySyncRequest): Promise<BrowserPasskeySyncResponse>;
+};
+/**
+ * Load the principal's passkeys into the BrowserSession and write back what
+ * happened since the last sync. Best effort: a failure is logged and never
+ * fails the surrounding action. Unacknowledged events stay in browserd and
+ * are retried on the next sync.
+ *
+ * Syncs for one BrowserSession run one at a time, in call order, so a caller
+ * may start the write-back after an action without awaiting it: the next
+ * action's sync waits for it instead of racing it on the same events.
+ */
+export declare function syncBrowserPasskeys(input: PasskeySyncInput): Promise<PasskeySyncResult>;
+type PasskeySyncResult = {
+    saved: number;
+    asserted: number;
+} | null;
+type PasskeySyncInput = {
+    port: InteractionSecretsPort | null | undefined;
+    grant: AccessGrant;
+    browserSessionId: string;
+    controllerGeneration: string;
+    client: PasskeySyncClient;
+    /** Lease again now (right before an action), taking over from any other browser. */
+    refresh?: boolean;
+    now?: () => number;
+    log?: InteractionSecretsLog;
+};
+/** Release the BrowserSession's passkey leases (session end). Best effort. */
+export declare function releaseBrowserPasskeys(port: InteractionSecretsPort | null | undefined, browserSessionId: string): Promise<void>;
+export {};

package/dist/mcp/action-catalog-types.d.ts

@@ -0,0 +1,14 @@
+export type ActionCatalogEntry = {
+    /** Stable name an agent calls: the SDK method ("listSessions"), else "METHOD /path". */
+    id: string;
+    method: string;
+    path: string;
+    /** Contract schema names for the JSON body and response, when known. */
+    request: string[];
+    response: string[];
+    /**
+     * Why no MCP caller can complete this action: it needs the person's own
+     * Opengeni browser session. Set only on such actions; the server hides them.
+     */
+    browserOnly?: string;
+};

package/dist/mcp/action-catalog.gen.d.ts

@@ -0,0 +1,2 @@
+import type { ActionCatalogEntry } from "./action-catalog-types.js";
+export declare const ACTION_CATALOG: readonly ActionCatalogEntry[];

package/dist/mcp/action-descriptions.d.ts

@@ -0,0 +1,4 @@
+import type { ActionCatalogEntry } from "./action-catalog-types.js";
+/** Actions that must carry a description (subscription and model settings). */
+export declare const DESCRIBED_ACTION_PATH: RegExp;
+export declare function actionDescription(entry: Pick<ActionCatalogEntry, "method" | "path">): string | undefined;

package/dist/mcp/action-schema-imports.gen.d.ts

@@ -0,0 +1 @@
+export declare const ACTION_REQUEST_SCHEMAS: Readonly<Record<string, unknown>>;

package/dist/mcp/capability-account-readiness.d.ts

@@ -0,0 +1,7 @@
+import type { McpConnectionAccountBinding } from "@opengeni/contracts";
+/** Canonical readiness comes only from routes present in this exact attempt,
+ * joined to this turn's accepted bindings. It never grants account access. */
+export declare function capabilityAccountReadiness(availableRoutes: Iterable<string>, bindings: readonly McpConnectionAccountBinding[] | null): {
+    available: Set<string>;
+    accepted: Set<string>;
+};