@opengeni/api-router 0.30.1 → 1.0.0

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

@@ -1,20 +1,33 @@
-import { type FileResourceRef, type WorkspaceSlackReactionSummonSettings } from "@opengeni/contracts";
-import { type SlackInstallationRoute, type SlackInteractionInboxEntry, type SlackInteractionTriggerKind } from "@opengeni/db";
+import { type FileResourceRef, type FirstPartyMcpToolName, type WorkspaceSlackReactionSummonSettings } from "@opengeni/contracts";
+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 { type OpenGeniSlackBotClient } from "./slack-bot.js";
+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"];
-export declare const SLACK_TASK_INSTRUCTIONS: string;
+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
+ * policy onto every pre-cutover session reserved by a Slack interaction.
+ */
+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. Connector
+ * tools are explicit-only, so freeze that narrow selection at session creation;
+ * ordinary interaction messages remain 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_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_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" | "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_model" | "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_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 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 function slackTaskFirstPartyMcpTools(settings: Settings, workspaceSettings: unknown): FirstPartyMcpToolName[];
 export type NormalizedSlackInteraction = {
     providerEventId: string;
     providerMessageId: string;
@@ -48,12 +61,100 @@ 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.
+ *
+ * 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 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 slackInvocationTaskText(entry: Pick<SlackInteractionInboxEntry, "slackMessageTs" | "slackUserId" | "text">, 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): string;
 type SlackReactionMessageContext = Awaited<ReturnType<OpenGeniSlackBotClient["reactionMessageContext"]>>;
 type PreparedSlackReactionTask = Readonly<{
     resources: FileResourceRef[];
@@ -64,6 +165,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;
@@ -73,4 +175,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

@@ -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/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/social-oauth.d.ts

@@ -42,9 +42,15 @@ type SocialOAuthDeps = {
     providerFetch?: SocialProviderFetch | undefined;
 };
 export type SocialOAuthStartContext = {
+    connectAttemptId?: string;
     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;
 };
@@ -61,6 +67,7 @@ export declare function completeSocialOAuthCallback(deps: SocialOAuthDeps, input
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
 /**
  * Resolves a usable access token for a social connection, refreshing (and

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

@@ -0,0 +1,15 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+type AssociatedInteractionSession = {
+    associations: ReadonlyArray<{
+        sessionId: string;
+        relationship: string;
+    }>;
+};
+/**
+ * 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-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/interaction-metrics.d.ts

@@ -1,9 +1,11 @@
 import type { AuthRunMutationResponse, BrowserActionReceipt, BrowserActionRequest, PublishBrowserRevisionResponse, BrowserSessionMutationResponse, ComputerActionReceipt, ComputerActionRequest, ComputerSessionMutationResponse, InteractionInterventionMutationResponse, ProtectedAuthFillResponse } from "@opengeni/contracts";
 import { type Observability } from "@opengeni/observability";
+import type { ComputerFrameEvidenceMismatchReason } from "@opengeni/runtime/sandbox";
 type InteractionLifecycleMutation = BrowserSessionMutationResponse | ComputerSessionMutationResponse;
 type AuthMutation = AuthRunMutationResponse | ProtectedAuthFillResponse;
 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;
 export declare function observeLifecycleResult(observability: Observability | null | undefined, startedAtMs: number, response: InteractionLifecycleMutation): void;
 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;

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

@@ -0,0 +1,9 @@
+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[];
+};

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/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>;
+};

package/dist/mcp/child-read-evidence.d.ts

@@ -0,0 +1,9 @@
+/** Select only whole items that actually survived the model-facing envelope.
+ * A cursor is a position, never proof that preceding content was consumed. */
+export declare function completeChildReadSequences(page: {
+    view: string;
+    sourceExact: boolean;
+    events: readonly ({
+        sequence: number;
+    } & Record<string, unknown>)[];
+}): number[];

package/dist/mcp/command-read.d.ts

@@ -0,0 +1,24 @@
+import type { SessionEvent } from "@opengeni/contracts";
+export declare const COMMAND_READ_MAX_WAIT_SECONDS = 50;
+export declare const COMMAND_WAIT_DEFAULT_SECONDS = 45;
+/** Shared provider-neutral command_read/command_wait operation. Notifications
+ * are only wake hints. Every result, including timeout, comes from durable DB
+ * state. Subscribe before reading to close the finish/subscription race, and
+ * periodically recheck durable state because live hints may be lost. */
+export declare function readCommandWithWait<T extends {
+    terminal: boolean;
+    chunks: unknown[];
+    hasMore?: boolean;
+}>(input: {
+    commandId: string;
+    waitSeconds?: number;
+    maxOutputBytes?: number | undefined;
+    signal?: AbortSignal;
+    read: () => Promise<T>;
+    subscribe: (onEvents: (events: SessionEvent[]) => void) => Promise<() => void>;
+}): Promise<T & {
+    waitedMs: number;
+    timedOut: boolean;
+    aborted: boolean;
+    liveFanout: boolean;
+}>;