@opengeni/api-router 0.30.3 → 2.2.0-canary.0

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

@@ -1,5 +1,5 @@
 import { type Settings } from "@opengeni/config";
-import { OPENGENI_SLACK_BOT_CREDENTIAL_LABEL, OPENGENI_SLACK_BOT_CREDENTIAL_ROLE, type AccessGrant, type ConnectionMetadata, type OpenGeniSlackBotConnectionMetadata } from "@opengeni/contracts";
+import { OPENGENI_SLACK_BOT_CREDENTIAL_LABEL, OPENGENI_SLACK_BOT_CREDENTIAL_ROLE, type AccessGrant, type ConnectionMetadata, type OpenGeniSlackBotDisplayName, type OpenGeniSlackBotConnectionMetadata } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 import { type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
@@ -34,12 +34,16 @@ export type DownloadedSlackReactionImage = Readonly<{
     contentType: "image/png" | "image/jpeg" | "image/webp";
     bytes: Uint8Array;
 }>;
+export type ExchangedOpenGeniSlackAuthorization = Readonly<{
+    accessToken: string;
+    appId: string;
+}>;
 export declare function exchangeOpenGeniSlackAuthorizationCode(input: {
     code: string;
     clientId: string;
     clientSecret: string;
     redirectUri: string;
-}, fetchImpl?: FetchLike): Promise<string>;
+}, fetchImpl?: FetchLike): Promise<ExchangedOpenGeniSlackAuthorization>;
 export type SlackBotReceipt = {
     credentialRole: typeof OPENGENI_SLACK_BOT_CREDENTIAL_ROLE;
     credentialLabel: typeof OPENGENI_SLACK_BOT_CREDENTIAL_LABEL;
@@ -71,10 +75,69 @@ export type SlackMessageBlock = {
         };
         style?: "primary" | "danger";
     }>;
+} | {
+    type: "context";
+    block_id?: string;
+    elements: Array<{
+        type: "mrkdwn" | "plain_text";
+        text: string;
+        emoji?: boolean;
+    }>;
 } | {
     type: "divider";
 };
-type SlackBotOperation = "channels.list" | "channel_history.read" | "thread_replies.read" | "users.list" | "files.list" | "file.info" | "file.content.read" | "message.post" | "message.update" | "message.delete";
+export type SlackHomeBlock = {
+    type: "header";
+    block_id?: string;
+    text: {
+        type: "plain_text";
+        text: string;
+        emoji?: boolean;
+    };
+} | {
+    type: "section";
+    block_id?: string;
+    text: {
+        type: "mrkdwn" | "plain_text";
+        text: string;
+        emoji?: boolean;
+    };
+    accessory?: {
+        type: "button";
+        action_id: string;
+        text: {
+            type: "plain_text";
+            text: string;
+            emoji?: boolean;
+        };
+        url: string;
+    };
+} | {
+    type: "context";
+    block_id?: string;
+    elements: Array<{
+        type: "mrkdwn" | "plain_text";
+        text: string;
+        emoji?: boolean;
+    }>;
+} | {
+    type: "actions";
+    block_id: string;
+    elements: Array<{
+        type: "button";
+        action_id: string;
+        text: {
+            type: "plain_text";
+            text: string;
+            emoji?: boolean;
+        };
+        url: string;
+        style?: "primary" | "danger";
+    }>;
+} | {
+    type: "divider";
+};
+type SlackBotOperation = "channels.list" | "search.context" | "channel_history.read" | "thread_replies.read" | "users.list" | "files.list" | "file.info" | "file.content.read" | "home.publish" | "message.post" | "message.update" | "message.delete";
 type SlackBotContext = {
     accountId: string;
     workspaceId: string;
@@ -82,6 +145,7 @@ type SlackBotContext = {
     sessionId?: string | null;
     scheduledTaskId?: string | null;
 };
+type SlackProviderAuthorization = () => Promise<boolean | void>;
 export type SlackReactionContextCheckpointBinding = {
     inboxId: string;
     accountId: string;
@@ -125,6 +189,14 @@ export declare class SlackBotProviderError extends Error {
     readonly retryAfterMs: number | null;
     constructor(code: string, retryAfterMs?: number | null);
 }
+export declare function authorizeSlackSharedImageRead(channel: {
+    isArchived: boolean;
+    isShared: boolean;
+    isExternallyShared: boolean;
+    isOrgShared: boolean;
+    isPendingExternallyShared: boolean;
+    isMpim: boolean;
+}, authorizeSharedRead: (() => Promise<void>) | undefined): Promise<void>;
 export type SlackBotCredentialVerificationFailureReason = "scope_mismatch" | "identity_mismatch";
 export declare class SlackBotCredentialVerificationError extends HTTPException {
     readonly failureReason: SlackBotCredentialVerificationFailureReason;
@@ -132,11 +204,14 @@ export declare class SlackBotCredentialVerificationError extends HTTPException {
 }
 /**
  * Validates a write-only xoxb credential before it can enter encrypted storage.
- * Slack does not expose the app's display_information name to this scope set;
- * users.info provides the authoritative installed bot display name, while the
- * documented manifest fixes the app name itself to the same exact value.
+ * The OAuth exchange's app_id is the immutable app authority. Slack bot profile
+ * names are mutable presentation data and may lag manifest/App Home changes, so
+ * they must not decide whether a credential belongs to this installation.
  */
-export declare function verifyOpenGeniSlackBotCredential(token: string, fetchImpl?: FetchLike, now?: Date): Promise<VerifiedOpenGeniSlackBot>;
+export declare function verifyOpenGeniSlackBotCredential(token: string, expected: Readonly<{
+    appId: string;
+    displayName: OpenGeniSlackBotDisplayName;
+}>, fetchImpl?: FetchLike, now?: Date): Promise<VerifiedOpenGeniSlackBot>;
 export declare function resolveSlackBotConnectionForTool(input: {
     db: Database;
     grant: AccessGrant;
@@ -154,8 +229,9 @@ export declare class OpenGeniSlackBotClient {
     private readonly metadata;
     private readonly context;
     private readonly fetchImpl;
+    private readonly authorizeProviderRequest?;
     private readonly resolveCredential;
-    constructor(db: Database, settings: Settings, connection: ConnectionMetadata, metadata: OpenGeniSlackBotConnectionMetadata, context: SlackBotContext, fetchImpl?: FetchLike);
+    constructor(db: Database, settings: Settings, connection: ConnectionMetadata, metadata: OpenGeniSlackBotConnectionMetadata, context: SlackBotContext, fetchImpl?: FetchLike, authorizeProviderRequest?: SlackProviderAuthorization | undefined);
     listChannels(input?: {
         limit?: number;
         cursor?: string;
@@ -202,6 +278,20 @@ export declare class OpenGeniSlackBotClient {
         purpose: string;
         numMembers: number | null;
     }>;
+    /**
+     * Replace one Slack user's private App Home view. `views.publish` is a
+     * naturally convergent replace operation: Slack event retries may safely
+     * repeat the exact bounded view without creating duplicate provider state.
+     */
+    publishHomeView(input: {
+        userId: string;
+        blocks: SlackHomeBlock[];
+        hash?: string | null;
+    }): Promise<{
+        viewId: string;
+    } & {
+        receipt: SlackBotReceipt;
+    }>;
     slackTaskPolicyFacts(channelId: string, userId: string): Promise<({
         conversation: {
             id: string;
@@ -433,9 +523,10 @@ export declare class OpenGeniSlackBotClient {
             name: string;
             title: string;
         }[];
+        authorizeSharedRead?: () => Promise<void>;
     }): Promise<PreparedSlackReactionImage[]>;
     /** Download and fully validate one previously authorized Slack image. */
-    downloadReactionImage(input: PreparedSlackReactionImage): Promise<DownloadedSlackReactionImage>;
+    downloadReactionImage(input: PreparedSlackReactionImage, authorizeSharedRead?: () => Promise<void>): Promise<DownloadedSlackReactionImage>;
     listUsers(input?: {
         limit?: number;
         cursor?: string;
@@ -452,6 +543,61 @@ export declare class OpenGeniSlackBotClient {
     } & {
         receipt: SlackBotReceipt;
     }>;
+    /**
+     * Workspace-wide public search through Slack's Real-time Search API
+     * (`assistant.search.context`) under the bot identity.
+     *
+     * The bot never carries private-search authority: `channel_types` is pinned
+     * to `public_channel` server-side regardless of caller input, so private
+     * channels, DMs, and MPIMs remain reachable only through a member's personal
+     * hosted-MCP grant. An install predating the search scopes fails closed with
+     * a reinstall hint instead of leaking Slack's `missing_scope` error.
+     */
+    searchContext(input: {
+        query: string;
+        contentTypes?: readonly ("messages" | "files" | "channels")[];
+        includeBots?: boolean;
+        /** UNIX seconds bounds on message timestamps. */
+        before?: number;
+        after?: number;
+        sort?: "score" | "timestamp";
+        sortDir?: "asc" | "desc";
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        messages: {
+            channelId: string;
+            channelName: string;
+            ts: string;
+            authorUserId: string;
+            authorName: string;
+            isAuthorBot: boolean;
+            content: string;
+            permalink: string | null;
+        }[];
+        files: {
+            id: string;
+            title: string;
+            filetype: string;
+            authorUserId: string;
+            authorName: string;
+            dateCreated: number | null;
+            dateUpdated: number | null;
+            content: string;
+            permalink: string | null;
+        }[];
+        channels: {
+            name: string;
+            topic: string;
+            purpose: string;
+            creatorUserId: string;
+            dateCreated: number | null;
+            permalink: string | null;
+        }[];
+        nextCursor: string | null;
+    } & {
+        receipt: SlackBotReceipt;
+    }>;
     listFiles(input: {
         channelId: string;
         limit?: number;
@@ -641,11 +787,13 @@ export declare function createOpenGeniSlackBotClient(deps: {
     db: Database;
     settings: Settings;
     slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
 }, resolved: Awaited<ReturnType<typeof resolveSlackBotConnectionForTool>>): OpenGeniSlackBotClient;
 export declare function createOpenGeniSlackBotInteractionClient(deps: {
     db: Database;
     settings: Settings;
     slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
 }, input: {
     accountId: string;
     workspaceId: string;

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

@@ -1,12 +1,12 @@
 import { type FileResourceRef, type WorkspaceSlackReactionSummonSettings } from "@opengeni/contracts";
-import { type SlackInstallationRoute, type SlackInteractionInboxEntry, type SlackInteractionTriggerKind } from "@opengeni/db";
+import { type SlackInstallationRoute, type SlackInteraction, type SlackInteractionInboxEntry, type SlackInteractionTriggerKind } from "@opengeni/db";
 import { type ApiRouteDeps } from "@opengeni/core";
 import type { Hono } from "hono";
-import { type OpenGeniSlackBotClient } from "./slack-bot.js";
+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"];
+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"];
 /**
  * Slack delivery restrictions are durable session-level authority, not
  * attacker-adjacent user-message context. Migration 0240 backfills this exact
@@ -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_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_publish" | "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" | "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_set" | "goal_update" | "interaction_discover" | "interaction_request_human" | "memory_correct" | "memory_save" | "memory_search" | "preference_registry_get" | "preference_registry_summary" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "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_pause" | "session_resume" | "session_send_message" | "session_steer" | "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_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_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "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_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_publish" | "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" | "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_set" | "goal_update" | "goal_wait" | "instruction_policy_propose" | "interaction_discover" | "interaction_request_human" | "knowledge_correct" | "knowledge_propose" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "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_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" | "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;
@@ -53,12 +53,45 @@ export declare function startSlackInteractionPump(deps: ApiRouteDeps, options?:
     intervalMs?: number;
     maxPerTick?: number;
 }): () => void;
+/**
+ * Say where the work went, quietly.
+ *
+ * The line exists to stop work landing somewhere surprising, so it appears only
+ * when the routing decision was a genuine choice: a null label means routing is
+ * off, or the person had exactly one workspace anyway, and a constant footer on
+ * every message would be noise rather than information.
+ *
+ * The label is frozen on the interaction rather than looked up here, because a
+ * workspace rename between the original post and a reconciliation would make the
+ * post ledger's byte comparison raise.
+ */
+export declare function withWorkspaceLine(label: string | null, text: string, blocks?: SlackMessageBlock[]): {
+    text: string;
+    blocks?: SlackMessageBlock[];
+};
+/**
+ * The post-ledger seed for one interaction's messages.
+ *
+ * The ledger binds one operation id to a digest over the rendered bytes, so
+ * adding the workspace line under an unchanged id would wedge every interaction
+ * with a claimed-but-unposted row. But bumping the id for interactions whose
+ * bytes did NOT change is not free either: their ledger rows become unreachable,
+ * so a repair or a cross-deploy retry posts a duplicate instead of finding the
+ * completed original, and an action handle still points at the old operation.
+ *
+ * Only a labelled interaction renders different bytes, and the label is written
+ * once at insert and never updated, so it is a stable discriminator. Version the
+ * 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.
+ */
+export declare function slackPostSeed(interaction: Pick<SlackInteraction, "routedWorkspaceLabel">, seed: string): string;
 export type SlackInvocationMessageContext = {
     messages: Awaited<ReturnType<OpenGeniSlackBotClient["threadReplies"]>>["messages"];
     nextCursor: string | null;
     kind: "thread" | "channel";
 };
-export declare function slackInvocationTaskText(entry: Pick<SlackInteractionInboxEntry, "slackMessageTs" | "slackUserId" | "text">, context: SlackInvocationMessageContext): string;
+export declare function slackInvocationModelContext(invocationTimestamp: string, context: SlackInvocationMessageContext): string;
 type SlackReactionMessageContext = Awaited<ReturnType<OpenGeniSlackBotClient["reactionMessageContext"]>>;
 type PreparedSlackReactionTask = Readonly<{
     resources: FileResourceRef[];
@@ -69,6 +102,7 @@ type PreparedSlackReactionTask = Readonly<{
 export declare function slackReactionTaskText(context: SlackReactionMessageContext, prepared?: PreparedSlackReactionTask): string;
 export declare function slackDeliveryTextsCoalesce(left: string, right: string): boolean;
 export declare function normalizedBlockActionInteraction(payload: Record<string, unknown>): NormalizedSlackInteraction;
+export declare function isSlackInfoCommand(text: string): boolean;
 type SlackUserLinkToken = {
     workspaceId: string;
     connectionId: string;

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

@@ -0,0 +1,120 @@
+/**
+ * Per-channel and per-DM Slack workspace routing.
+ *
+ * Routing is decided BEFORE any agent runs, from durable facts only, so it can
+ * never be a model judgement. The resolver is pure with respect to the database
+ * reads it is handed: it returns a decision, and the caller persists and acts on
+ * it.
+ *
+ * Two rules are load-bearing and easy to break by accident:
+ *
+ *   A mapped thread keeps the workspace it was created in, unconditionally,
+ *   including after the channel has been re-pointed. Otherwise a live
+ *   conversation would silently change tenants mid-thread.
+ *
+ *   A subject who lacks access to the routed workspace is NEVER quietly served
+ *   from another workspace they happen to belong to. Every failure is explicit
+ *   and creates no session.
+ */
+import type { AccessGrant } from "@opengeni/contracts";
+import type { SlackChannelRoute, SlackInteractionInboxEntry, SlackRoutableWorkspace, SlackUserDmRoute } from "@opengeni/db";
+export type SlackRouteTenancy = {
+    accountId: string;
+    workspaceId: string;
+};
+export type SlackRouteResolution = (SlackRouteTenancy & {
+    kind: "resolved";
+    label: string | null;
+    source: "thread" | "prefix" | "channel" | "dm_route" | "dm_personal" | "sole_candidate" | "installation";
+}) | {
+    kind: "ask";
+    candidates: readonly SlackRoutableWorkspace[];
+} | {
+    kind: "denied";
+    reason: "no_access_to_named" | "no_access_to_route" | "no_candidates";
+    requested: string | null;
+    candidates: readonly SlackRoutableWorkspace[];
+};
+/**
+ * A Slack direct message to the bot, by any trigger that can carry one.
+ *
+ * `isDirectMessageShortcut` is deliberately narrower: it means "a message
+ * shortcut invoked inside a DM", which is a private-handoff concern. Routing
+ * cares about the broader question of whether this conversation is one human's
+ * private channel with the bot, which is also true of an ordinary `dm` event.
+ */
+export declare function isSlackDirectMessageConversation(entry: Pick<SlackInteractionInboxEntry, "triggerKind" | "slackChannelId">): boolean;
+/**
+ * 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
+ * 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
+ * from the addressing the person used to route it.
+ */
+export declare function splitSlackLeadingMention(text: string, botUserId: string | null): {
+    lead: string;
+    rest: string;
+};
+/**
+ * The strict `in <workspace>: ...` override.
+ *
+ * Parsed only at byte 0, so ordinary prose that happens to contain the word
+ * cannot trigger it, and matched case-insensitively against the exact label of a
+ * workspace the subject can already start work in. A prefix that names nothing
+ * recognizable is NOT a suggestion that falls through: it is a refusal, because
+ * silently ignoring an explicit override is how a message lands somewhere the
+ * person did not intend.
+ */
+export declare function parseSlackWorkspacePrefix(text: string): {
+    requested: string;
+    remainder: string;
+} | null;
+export type SlackRouteInputs = {
+    /** The installation binding's tenancy. Always the fallback, never a silent one. */
+    home: SlackRouteTenancy;
+    entry: Pick<SlackInteractionInboxEntry, "triggerKind" | "slackChannelId" | "slackUserId" | "text">;
+    /**
+     * The tenancy of an interaction already mapped to this thread, if any. A
+     * mapped thread wins unconditionally.
+     */
+    threadTenancy: SlackRouteTenancy | null;
+    channelRoute: SlackChannelRoute | null;
+    dmRoute: SlackUserDmRoute | null;
+    /** The subject's own personal workspace in the home organization, if any. */
+    personalWorkspaceId: string | null;
+    /** Workspaces this subject may actually start work in, ordered stably. */
+    candidates: readonly SlackRoutableWorkspace[];
+    /** The installation's bot user, so a mention does not hide the prefix. */
+    botUserId: string | null;
+    /** `OPENGENI_SLACK_WORKSPACE_ROUTING_ENABLED`. */
+    routingEnabled: boolean;
+    /** Whether the first-use picker exists yet. Until it does, ambiguity keeps home. */
+    askEnabled: boolean;
+};
+/**
+ * Decide which workspace this Slack message starts work in.
+ *
+ * First match wins, and the order is deliberate: continuity beats an explicit
+ * override beats configuration beats derivation beats asking.
+ */
+export declare function resolveSlackWorkspaceRoute(input: SlackRouteInputs): SlackRouteResolution;
+/**
+ * The message text the model actually sees.
+ *
+ * A prefix override is addressing information, not part of the request, so it is
+ * stripped exactly once and only when it matched.
+ */
+export declare function slackRoutedRequestText(text: string, resolution: SlackRouteResolution, botUserId: string | null): string;
+export type SlackRouteAuthorization = {
+    kind: "authorized";
+    grant: AccessGrant;
+    tenancy: SlackRouteTenancy;
+    label: string | null;
+} | {
+    kind: "denied";
+    reason: "no_access_to_route";
+    tenancy: SlackRouteTenancy;
+};

package/dist/integrations/social-oauth.d.ts

@@ -45,6 +45,11 @@ export type SocialOAuthStartContext = {
     accountId: string;
     workspaceId: string;
     subjectId: string;
+    /**
+     * False for every principal that cannot own a personal Connection. Resolved
+     * by the route from the live authenticated principal, never inferred here.
+     */
+    personalOwnershipAllowed: boolean;
     requestUrl: string;
     payload: SocialOAuthStartRequest;
 };

package/dist/interaction-frame-proxy.d.ts

@@ -0,0 +1,68 @@
+import type { ApiWebSocketConnection, ApiWebSocketLike, ApiWebSocketUpgradeServer } from "./api-websocket.js";
+export declare const INTERACTION_FRAME_PROXY_PATH = "/v1/interaction/frame-proxy";
+export declare const INTERACTION_FRAME_PROXY_PROTOCOL_PREFIX = "opengeni-frame-proxy.";
+type ProxyGrant = Readonly<{
+    version: 1;
+    upstreamUrl: string;
+    upstreamProtocols: readonly string[];
+    responseProtocol: string;
+    origin: string | null;
+    expiresAt: number;
+}>;
+export type InteractionFrameProxyAttachment = Readonly<{
+    url: string;
+    protocols: readonly string[];
+}>;
+/** Docker boxes cannot carry browserd's WebSocket subprotocol grant to the
+ * viewer. Unsigned OpenSandbox Channel B still uses the lifecycle proxy, so
+ * it needs the same hatch. Signed URI-mode ingress keeps native subprotocols;
+ * `openSandboxInteractionFrameProxy` is an emergency override only. */
+export declare function placementUsesInteractionFrameProxy(backend: string | null | undefined, options?: {
+    openSandboxSignedEndpoints?: boolean;
+    openSandboxInteractionFrameProxy?: boolean;
+}): boolean;
+/** Public origin the browser can open. TLS-terminating reverse proxies make
+ * `requestUrl` `http://127.0.0.1` / the API container; that would mint `ws://`
+ * and Chrome blocks it from an `https://` console. */
+export declare function resolveInteractionFrameProxyRequestUrl(input: {
+    requestUrl: string;
+    publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
+    forwardedProto?: string | null | undefined;
+    forwardedHost?: string | null | undefined;
+}): string;
+export declare function createInteractionFrameProxyAttachment(input: {
+    requestUrl: string;
+    publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
+    forwardedProto?: string | null | undefined;
+    forwardedHost?: string | null | undefined;
+    rootSecret: string;
+    upstreamUrl: string;
+    upstreamProtocols: readonly string[];
+    origin: string | null;
+    expiresAt: string;
+}): InteractionFrameProxyAttachment;
+export declare class InteractionFrameProxyTransport {
+    private readonly rootSecret;
+    private readonly clock;
+    constructor(rootSecret: string | undefined, clock?: () => number);
+    handles(request: Request): boolean;
+    upgrade(request: Request, server: ApiWebSocketUpgradeServer): Response | undefined;
+}
+export declare class InteractionFrameProxyConnection implements ApiWebSocketConnection {
+    private readonly grant;
+    private socket;
+    private upstream;
+    private upstreamOpen;
+    private terminal;
+    private queued;
+    private queuedBytes;
+    constructor(grant: ProxyGrant);
+    attach(socket: ApiWebSocketLike): void;
+    receive(message: string | Uint8Array | ArrayBuffer): void;
+    transportClosed(): void;
+    private fail;
+    private clear;
+}
+export {};

package/dist/mcp/company-brain-governed-writes.d.ts

@@ -0,0 +1,26 @@
+import { type CompanyBrainGovernedWriteAttempt } from "@opengeni/contracts";
+import { createCompanyBrainLearningPolicyRouter } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type JsonResult = (value: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export type RegisterCompanyBrainGovernedWriteToolsInput = {
+    server: McpServer;
+    db: Database;
+    attempt: CompanyBrainGovernedWriteAttempt;
+    authorize: () => Promise<void>;
+    json: JsonResult;
+    router?: Pick<ReturnType<typeof createCompanyBrainLearningPolicyRouter>, "write">;
+};
+/**
+ * Register explicit proposal-only Company Brain tools. The signed host attempt
+ * owns tenant/session authority and the exact evidence id owns the learning
+ * policy source override. Tool input cannot select scope, active authority, or
+ * another policy source.
+ */
+export declare function registerCompanyBrainGovernedWriteTools(input: RegisterCompanyBrainGovernedWriteToolsInput): void;
+export {};

package/dist/mcp/company-profile-agent-admin.d.ts

@@ -0,0 +1,44 @@
+import { type CompanyProfileAgentAttempt, type CompanyProfileEntry } from "@opengeni/contracts";
+import { createCompanyProfileAgentAdminRouter } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod/v4";
+type JsonResult = (value: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export type RegisterCompanyProfileAgentAdminToolsInput = {
+    server: McpServer;
+    db: Database;
+    attempt: CompanyProfileAgentAttempt;
+    authorize: () => Promise<void>;
+    json: JsonResult;
+    router?: Pick<ReturnType<typeof createCompanyProfileAgentAdminRouter>, "propose" | "confirm">;
+};
+declare const entry: z.ZodObject<{
+    key: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+}, z.core.$strip>;
+type EntryInput = z.infer<typeof entry>;
+/**
+ * Derive a stable key from entry content: the first few words, normalized into
+ * the company-profile key alphabet and bounded to the stable-key length.
+ */
+export declare function deriveCompanyProfileStableKey(content: string): string;
+/**
+ * Resolve explicit or derived keys for one list and de-duplicate by suffixing
+ * `-2`, `-3`, ... so the profile passes the unique-key contract.
+ */
+export declare function resolveCompanyProfileEntries(input: readonly EntryInput[]): CompanyProfileEntry[];
+/**
+ * Register the explicit owner-confirmed organization profile path. This is
+ * administration, not derived learning: workspace learning mode is never
+ * consulted, the initiating human must be the organization's active owner (the
+ * same authority as the manual `account:admin` route), and the proposal cannot
+ * become active without the exact bound human-input response returned by the
+ * first call.
+ */
+export declare function registerCompanyProfileAgentAdminTools(input: RegisterCompanyProfileAgentAdminToolsInput): void;
+export {};

package/dist/mcp/documents.d.ts

@@ -3,6 +3,7 @@ import { type Database } from "@opengeni/db";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function buildDocumentsMcpServer(db: Database, accountId: string, workspaceId: string, documentServices: DocumentServices, options: {
     createdBySessionId?: string | undefined;
+    attemptId?: string | undefined;
     /** Immutable human subject whose agent is making this retrieval request. */
     initiatingSubjectId: string;
 }): McpServer;

package/dist/mcp/remember.d.ts

@@ -0,0 +1,28 @@
+import { type CompanyBrainGovernedWriteAttempt } from "@opengeni/contracts";
+import { createRememberRouter } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type JsonResult = (value: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export type RegisterRememberToolsInput = {
+    server: McpServer;
+    db: Database;
+    attempt: CompanyBrainGovernedWriteAttempt;
+    authorize: () => Promise<void>;
+    json: JsonResult;
+    router?: Pick<ReturnType<typeof createRememberRouter>, "remember" | "confirm">;
+};
+/**
+ * Explicit user-directed remember. Content becomes exact task-note evidence,
+ * promotion runs through the frozen workspace learning policy, and activation
+ * is either automatic (preference under Automatic mode) or requires exactly one
+ * bound human confirmation through the built-in `request_human_input` tool.
+ * Tool input cannot select scope beyond the workspace, active authority, or
+ * another learning-policy source.
+ */
+export declare function registerRememberTools(input: RegisterRememberToolsInput): void;
+export {};