@opengeni/api-router 2.11.3 → 2.12.1-canary.0

package/dist/integrations/atlassian.d.ts

@@ -1,3 +1,4 @@
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { AccessGrant, ScheduledTask } from "@opengeni/contracts";
 import { AtlassianOAuthStartResponse, type AtlassianDisconnectRequest, type AtlassianLifecycleActionRequest, type AtlassianOAuthStartRequest } from "@opengeni/contracts/atlassian";
 import { type ApiRouteDeps } from "@opengeni/core";
@@ -9,6 +10,8 @@ export declare function startAtlassianOAuth(deps: ApiRouteDeps, input: {
     subjectId: string;
     requestUrl: string;
     payload: AtlassianOAuthStartRequest;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
 }): Promise<AtlassianOAuthStartResponse>;
 export declare function completeAtlassianOAuthCallback(deps: ApiRouteDeps, input: {
     code?: string | undefined;
@@ -17,6 +20,7 @@ export declare function completeAtlassianOAuthCallback(deps: ApiRouteDeps, input
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
 export declare function browseAtlassianSources(deps: ApiRouteDeps, input: {
     workspaceId: string;

package/dist/integrations/connect-authority.d.ts

@@ -0,0 +1 @@
+export { requireConnectOwnerAuthority } from "@opengeni/core";

package/dist/integrations/connect-callback-return.d.ts

@@ -0,0 +1,6 @@
+import type { Hono } from "hono";
+import type { ApiRouteDeps } from "@opengeni/core";
+/** Navigation-only recovery. Recently expired signed state can identify the host's saved
+ * destination, but cannot authorize exchange, persistence, or credential use.
+ * Normal callbacks independently enforce current time and live authority. */
+export declare function registerConnectCallbackReturns(app: Hono, deps: ApiRouteDeps): void;

package/dist/integrations/fiken.d.ts

@@ -1,9 +1,13 @@
 import type { ApiRouteDeps } from "@opengeni/core";
 import type { Settings } from "@opengeni/config";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import { FikenOAuthStartResponse, type AccessGrant, type ConnectionMetadata, type FikenCompanySummary, type FikenConnectionMetadata, type FikenOAuthStartRequest } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 import { type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+/** Shared native/embedded token adapter. Provider verification happens before
+ * persistence; the caller reauthorizes inside its durable commit transaction. */
+export declare function prepareFikenTokenInstall(deps: ApiRouteDeps, grant: Pick<AccessGrant, "accountId" | "workspaceId" | "subjectId">, raw: unknown, expectedVersion?: number): Promise<(tx: Database) => Promise<ConnectionMetadata>>;
 export type FikenOperation = "companies.list" | "contacts.list" | "contact.create" | "products.list" | "invoices.list" | "invoice.get" | "invoice_draft.create" | "bank_accounts.list" | "purchases.list" | "sales.list";
 export declare class FikenProviderError extends Error {
     readonly code: string;
@@ -226,6 +230,8 @@ export declare function startFikenOAuth(deps: ApiRouteDeps, input: {
     subjectId: string;
     requestUrl: string;
     payload: FikenOAuthStartRequest;
+    externalContinuation?: ExternalActorContinuation;
+    connectAttemptId?: string;
 }): Promise<FikenOAuthStartResponse>;
 export declare function completeFikenOAuthCallback(deps: ApiRouteDeps, input: {
     code?: string | undefined;
@@ -234,5 +240,6 @@ export declare function completeFikenOAuthCallback(deps: ApiRouteDeps, input: {
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
 export {};

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { ConnectAdvance, ConnectAttempt } from "@opengeni/contracts/connect";
+import { type ConnectActorScope } from "@opengeni/db";
+import type { ApiRouteDeps, PreparedConnectOperation } from "@opengeni/core";
+declare const stateSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"github_app_connect">;
+    accountId: z.ZodString;
+    workspaceId: z.ZodString;
+    subjectId: z.ZodString;
+    personalOwnerVerified: z.ZodBoolean;
+    connectAttemptId: z.ZodString;
+    phase: z.ZodEnum<{
+        bind: "bind";
+        discover: "discover";
+        install: "install";
+    }>;
+    installationId: z.ZodOptional<z.ZodNumber>;
+    providerId: z.ZodDefault<z.ZodEnum<{
+        "github-app": "github-app";
+        "github-lens": "github-lens";
+    }>>;
+    nonce: z.ZodString;
+    iat: z.ZodNumber;
+}, z.core.$strip>;
+type State = z.infer<typeof stateSchema>;
+export declare function isGitHubAppConnectState(deps: ApiRouteDeps, raw: string | undefined): boolean;
+type GitHubConnectScope = ConnectActorScope & {
+    personalOwnerVerified?: boolean;
+    providerId?: "github-app" | "github-lens";
+};
+export declare function githubAppConnectNavigation(deps: ApiRouteDeps, scope: GitHubConnectScope, attemptId: string, requestUrl: string, phase?: State["phase"], installationId?: number, providerId?: State["providerId"]): {
+    authorizationUrl: string;
+    expiresAt: string;
+};
+export declare function prepareGitHubAppConnectAction(deps: ApiRouteDeps, scope: GitHubConnectScope, requestUrl: string, attempt: ConnectAttempt, action: ConnectAdvance): PreparedConnectOperation;
+/** No browser login/cookie required: signed attempt + current stored origin,
+ * then fresh GitHub owner proof, are the two separate authority boundaries. */
+export declare function completeGitHubAppConnect(deps: ApiRouteDeps, input: {
+    state?: string | undefined;
+    code?: string | undefined;
+    installationId?: string | undefined;
+    setupAction?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+    expectedProvider?: "github-app" | "github-lens";
+}): Promise<Response>;
+export {};

package/dist/integrations/github-installation-proof.d.ts

@@ -0,0 +1,3 @@
+import type { GitHubInstallationBindingCandidate, GitHubInstallationBindingProof } from "@opengeni/contracts";
+export declare function isConsistentGitHubBindingCandidates(candidates: GitHubInstallationBindingCandidate[]): boolean;
+export declare function isConsistentGitHubBindingProof(proof: GitHubInstallationBindingProof, installationId: number): boolean;

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

@@ -0,0 +1,153 @@
+import { type GitHubInstallationBindingProof } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type Database } from "@opengeni/db";
+export declare function requireGitHubLensConnect(deps: ApiRouteDeps, workspaceId: string): Promise<{
+    installation: {
+        skillWrites?: {
+            operationId: string;
+            skillId: string;
+            revisionId: string;
+            outcome: "applied" | "pending" | "preserved";
+            decision?: "rejected" | undefined;
+            pendingReason?: "approval" | "source_finalization" | undefined;
+            skillReview?: {
+                sourceOperationId: string;
+                skillId: string;
+                revisionId: string;
+                expectedRevisionId: string | null;
+                expectedScopeVersion: number;
+            } | undefined;
+            replayed: boolean;
+        }[] | undefined;
+        skillPublications?: {
+            operationId: string;
+            skillId: string;
+            revisionId: string;
+            outcome: "applied" | "pending" | "preserved";
+            decision?: "rejected" | undefined;
+            pendingReason?: "approval" | "source_finalization" | undefined;
+            skillReview?: {
+                sourceOperationId: string;
+                skillId: string;
+                revisionId: string;
+                expectedRevisionId: string | null;
+                expectedScopeVersion: number;
+            } | undefined;
+            replayed: boolean;
+            sourceOperationId: string;
+            activationEventId: string | null;
+        }[] | undefined;
+        skillReleases?: {
+            skillId: string;
+            revisionId: string | null;
+            disposition: "deactivated" | "inactive" | "preserved";
+            eventId: string | null;
+            warning: string | null;
+        }[] | undefined;
+        id: string;
+        accountId: string;
+        workspaceId: string;
+        packId: string;
+        status: "active" | "disabled" | "installing" | "needs_attention";
+        version: number;
+        manifestSnapshot: Record<string, unknown> | null;
+        manifestDigest: string | null;
+        selectedRigId: string | null;
+        installedBySubjectId: string | null;
+        metadata: Record<string, unknown>;
+        enabledAt: string;
+        updatedAt: string;
+    };
+    template: {
+        id: string;
+        name: string;
+        description: string;
+        adapterId: string;
+        eventTypes: string[];
+        sessionTemplate: {
+            bundledSkillIds?: ("builtin:opengeni-documents" | "builtin:opengeni-presentations" | "builtin:opengeni-projects" | "builtin:opengeni-sites" | "builtin:opengeni-skills" | "builtin:opengeni-spreadsheets" | "builtin:opengeni-video-generation")[] | undefined;
+            prompt: string;
+            instructions: string | null;
+            resources: ({
+                kind: "repository";
+                uri: string;
+                ref: string;
+                expectedCommitSha?: string | undefined;
+                mountPath?: string | undefined;
+                subpath?: string | undefined;
+                provider?: "azure_devops" | "github" | "gitlab" | undefined;
+                connectionType?: "github_personal" | undefined;
+                credentialBindingId?: string | undefined;
+                access?: "read" | "write" | undefined;
+                repositoryId?: string | number | undefined;
+                installationId?: string | number | undefined;
+                projectId?: string | number | undefined;
+                connectionId?: string | undefined;
+                githubInstallationId?: number | undefined;
+                githubRepositoryId?: number | undefined;
+            } | {
+                kind: "file";
+                fileId: string;
+                mountPath?: string | undefined;
+            })[];
+            skills: {
+                name: string;
+                description: string;
+                files: {
+                    path: string;
+                    content: string;
+                }[];
+            }[];
+            tools: {
+                kind: "mcp";
+                id: string;
+                eager?: boolean | undefined;
+                optional?: boolean | undefined;
+            }[];
+            firstPartyMcpTools: ("artifacts_archive" | "artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_prepare_upload" | "artifacts_publish" | "artifacts_restore" | "artifacts_rollback" | "atlassian_get" | "atlassian_search" | "atlassian_sources_list" | "browser_act" | "browser_auth" | "browser_clipboard" | "browser_debug" | "browser_identity" | "browser_lifecycle" | "browser_observe" | "browser_open" | "browser_publish" | "browser_tabs" | "capability_authorization_request" | "capability_catalog_search" | "command_read" | "command_wait" | "company_profile_confirm" | "company_profile_propose" | "computer_act" | "computer_clipboard" | "computer_lifecycle" | "computer_observe" | "computer_open" | "computer_targets" | "connected_machine_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_propose" | "interaction_discover" | "interaction_request_human" | "knowledge_correct" | "knowledge_propose" | "memory_correct" | "memory_save" | "memory_search" | "preference_propose" | "preference_registry_get" | "preference_registry_summary" | "project_create" | "project_delete" | "project_get" | "project_list" | "project_reorder" | "project_update" | "reddit_accounts_list" | "reddit_mentions_live" | "reddit_post_reply" | "reddit_posts_sync" | "reddit_search_live" | "reddit_thread_fetch" | "remember" | "remember_confirm" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_file_publish" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_human_input_respond" | "session_pause" | "session_resume" | "session_send_message" | "session_set_project" | "session_steer" | "session_wait" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_search" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "task_note_archive" | "task_note_promote_instruction_policy" | "task_note_promote_knowledge" | "task_note_promote_preference" | "task_note_replace" | "task_note_save" | "task_notes_list" | "variable_set_get_variable" | "variable_set_list" | "variable_set_set_variable" | "wait_for_input" | "work_claim_release" | "work_claim_upsert" | "x_accounts_list" | "x_mentions_live" | "x_post_reply" | "x_posts_sync" | "x_search_live" | "x_thread_fetch")[];
+            firstPartyMcpPermissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
+            model: string | null;
+            reasoningEffort: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | null;
+            sandboxBackend: "blaxel" | "cloudflare" | "daytona" | "docker" | "e2b" | "local" | "modal" | "none" | "opensandbox" | "runloop" | "selfhosted" | "vercel" | null;
+            policyRole: string | null;
+            metadata: Record<string, unknown>;
+        };
+        configuration: Record<string, unknown>;
+        connectionRequirement: string | null;
+    };
+}>;
+/** Separate Lens registration/source/automation domain, not a repository-access
+ * binding. Invoked inside the Connect receipt's authorized transaction. */
+export declare function commitGitHubLensConnect(deps: ApiRouteDeps, tx: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    installationId: number;
+    proof: GitHubInstallationBindingProof;
+    checkedAt: Date;
+    expiresAt: Date;
+    nonce: string;
+}): Promise<{
+    id: string;
+    sourceId: string;
+    accountId: string;
+    workspaceId: string;
+    name: string;
+    provider: "azure_devops" | "github" | "gitlab";
+    providerBaseUrl: string;
+    appId: string | null;
+    installationId: string | null;
+    providerAccountLogin: string | null;
+    providerAccountType: "Organization" | "User" | null;
+    credentialKind: "github_app" | "managed_github_app" | "provider_token";
+    hasCredential: boolean;
+    accessTokenExpiresAt: string | null;
+    webhookAuthKind: "basic" | "hmac_sha256" | "shared_token";
+    hasWebhookSecret: boolean;
+    webhookUsername: string | null;
+    webhookPath: string;
+    status: "active" | "disabled";
+    createdBySubjectId: string;
+    createdAt: string;
+    updatedAt: string;
+}>;

package/dist/integrations/google-drive.d.ts

@@ -1,3 +1,4 @@
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { AccessGrant, ScheduledTask } from "@opengeni/contracts";
 import { GoogleDriveOAuthStartResponse, type GoogleDriveDisconnectRequest, type GoogleDriveLifecycleActionRequest, type GoogleDriveOAuthStartRequest } from "@opengeni/contracts/google-drive";
 import { IntegrationFacetMutationResult } from "@opengeni/contracts";
@@ -21,6 +22,8 @@ export declare function startGoogleDriveOAuth(deps: ApiRouteDeps, input: {
     subjectId: string;
     requestUrl: string;
     payload: GoogleDriveOAuthStartRequest;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
 }): Promise<GoogleDriveOAuthStartResponse>;
 export declare function completeGoogleDriveOAuthCallback(deps: ApiRouteDeps, input: {
     code?: string | undefined;
@@ -30,6 +33,7 @@ export declare function completeGoogleDriveOAuthCallback(deps: ApiRouteDeps, inp
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
 export declare function transitionGoogleDriveLifecycle(deps: ApiRouteDeps, input: {
     workspaceId: string;

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

@@ -1,5 +1,6 @@
 import { type Settings } from "@opengeni/config";
 import { OAuthStartResponse, type ConnectionOwnership, type OAuthStartRequest } from "@opengeni/contracts";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { Observability } from "@opengeni/observability";
 import { type Database } from "@opengeni/db";
 import { type McpAuthorizationServerMetadata } from "@opengeni/network";
@@ -15,6 +16,8 @@ type OAuthClientDeps = {
     oauthCallbackDeadlineMs?: number | undefined;
 };
 export type OAuthStartContext = {
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
     accountId: string;
     workspaceId: string;
     subjectId: string;
@@ -29,6 +32,7 @@ export type OAuthStartContext = {
 };
 export type OAuthCallbackResult = {
     redirectTo: string;
+    exactReturn?: boolean;
 };
 type AuthorizationServerMetadata = McpAuthorizationServerMetadata;
 export declare const OAUTH_START_DEADLINE_MS = 15000;

package/dist/integrations/oauth-return-path.d.ts

@@ -0,0 +1 @@
+export declare function safeReturnPath(value: string): string;

package/dist/integrations/personal-github.d.ts

@@ -24,6 +24,7 @@ export declare function startPersonalGitHubOAuth(deps: ApiRouteDeps, input: {
     workspaceId: string;
     connectionId?: string;
     returnPath?: string;
+    connectAttemptId?: string;
 }): Promise<{
     authorizationUrl: string;
     expiresAt: string;
@@ -35,6 +36,7 @@ export declare function completePersonalGitHubOAuthCallback(deps: ApiRouteDeps,
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
 export declare function personalGitHubReviewUrl(settings: Settings): string | null;
 export declare const PERSONAL_GITHUB_CONNECTION_PRINCIPAL_MESSAGE: string;

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

@@ -1,6 +1,8 @@
+import { type IntegrationDefinition } from "@opengeni/capabilities";
 import { type Settings } from "@opengeni/config";
-import { OAuthStartResponse, type ApiIntegrationOAuthStartRequest } from "@opengeni/contracts";
+import { OAuthStartResponse, type ApiIntegrationOAuthStartRequest, type ConnectionOwnership } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 export declare function startApiIntegrationProviderOAuth(deps: ApiRouteDeps, input: {
     accountId: string;
     workspaceId: string;
@@ -11,6 +13,8 @@ export declare function startApiIntegrationProviderOAuth(deps: ApiRouteDeps, inp
      * route from the live authenticated principal, never inferred here.
      */
     personalOwnershipAllowed: boolean;
+    externalContinuation?: ExternalActorContinuation;
+    connectAttemptId?: string;
     requestUrl: string;
     payload: ApiIntegrationOAuthStartRequest;
 }): Promise<OAuthStartResponse>;
@@ -21,5 +25,11 @@ export declare function completeApiIntegrationProviderOAuth(deps: ApiRouteDeps,
     requestUrl: string;
 }): Promise<{
     redirectTo: string;
+    exactReturn?: boolean;
 }>;
+/** Configuration readiness only: consent and installation are still separate. */
+export declare function curatedOAuthReadiness(settings: Settings, definition: IntegrationDefinition): {
+    configured: boolean;
+    ownership: ConnectionOwnership[];
+};
 export declare function isApiIntegrationProviderOAuthState(value: string | undefined, settings: Settings): boolean;

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

@@ -0,0 +1,20 @@
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { type ApiRouteDeps } from "@opengeni/core";
+export declare function requireOpenGeniSlackOAuthSettings(settings: ApiRouteDeps["settings"]): {
+    clientId: string;
+    clientSecret: string;
+};
+/** Only authenticated route admission may invoke this workspace-bot starter.
+ * Hosted personal Slack MCP deliberately uses its own OAuth profile. */
+export declare function startSlackBotInstall(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    connectionId?: string;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
+}): Promise<{
+    authorizationUrl: string;
+    expiresAt: string;
+}>;

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

@@ -42,6 +42,7 @@ type SocialOAuthDeps = {
     providerFetch?: SocialProviderFetch | undefined;
 };
 export type SocialOAuthStartContext = {
+    connectAttemptId?: string;
     accountId: string;
     workspaceId: string;
     subjectId: string;
@@ -66,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/mcp/scheduled-task-view.d.ts

@@ -82,8 +82,8 @@ export declare function scheduledTaskMcpSummary(task: ScheduledTask): {
     runMode: "existing_session" | "new_session_per_run" | "reusable_session";
     overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
     action: {
-        readonly sourceId?: never;
         kind: "agent_turn";
+        sourceId?: never;
         sourceGeneration?: never;
         sourceLifecycleGeneration?: never;
         destination?: never;
@@ -205,8 +205,8 @@ export declare function boundScheduledTaskDetailMcp(task: ScheduledTask): {
     runMode: "existing_session" | "new_session_per_run" | "reusable_session";
     overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
     action: {
-        readonly sourceId?: never;
         kind: "agent_turn";
+        sourceId?: never;
         sourceGeneration?: never;
         sourceLifecycleGeneration?: never;
         destination?: never;
@@ -389,8 +389,8 @@ export declare function boundScheduledTaskMcpPage(input: {
         runMode: "existing_session" | "new_session_per_run" | "reusable_session";
         overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
         action: {
-            readonly sourceId?: never;
             kind: "agent_turn";
+            sourceId?: never;
             sourceGeneration?: never;
             sourceLifecycleGeneration?: never;
             destination?: never;

package/dist/routes/api-integrations.d.ts

@@ -1,8 +1,22 @@
+import { createPinnedIntegrationTransport } from "@opengeni/capabilities";
+import { InstallApiIntegrationRequest, PreviewApiIntegrationRequest, type AccessGrant } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
+import { installApiIntegration } from "@opengeni/db";
 import type { FetchLike } from "@opengeni/network";
 import type { Hono } from "hono";
+import { resolveApiIntegrationPreview, type ResolvedApiIntegrationPreview } from "../integrations/api-integrations.js";
 export type ApiIntegrationRouteOverrides = Readonly<{
     fetchImpl?: FetchLike;
 }>;
 export declare function apiIntegrationRequiresConnection(authScheme: Record<string, unknown>): boolean;
+/** Shared native/embedded install validation. The caller must still authorize
+ * capabilities:manage and commit under its own live-authority boundary. */
+export declare function validatedIntegrationInstallInput(grant: AccessGrant, workspaceId: string, payload: InstallApiIntegrationRequest, resolved: ResolvedApiIntegrationPreview): Parameters<typeof installApiIntegration>[1];
 export declare function registerApiIntegrationRoutes(app: Hono, deps: ApiRouteDeps, overrides?: ApiIntegrationRouteOverrides): void;
+export declare function resolveForRoute(input: {
+    deps: ApiRouteDeps;
+    transport: ReturnType<typeof createPinnedIntegrationTransport>;
+    workspaceId: string;
+    subjectId: string;
+    payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
+}): ReturnType<typeof resolveApiIntegrationPreview>;

package/dist/routes/connect.d.ts

@@ -0,0 +1,5 @@
+import type { Hono } from "hono";
+import { type ApiRouteDeps } from "@opengeni/core";
+/** Shared durable setup entry. Provider completion is distinct from
+ * subsequent preview/install; never report an OAuth token as a ready integration. */
+export declare function registerConnectRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/external-identity-links.d.ts

@@ -0,0 +1,6 @@
+import type { Hono } from "hono";
+import { type ApiRouteDeps } from "@opengeni/core";
+/** Both products address the link through a workspace they already own. The
+ * link itself is organization-local; the host's Personal workspace need not be
+ * exposed to the native human, and neither side names the other's subject. */
+export declare function registerExternalIdentityLinkRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/host-mcp-bindings.d.ts

@@ -0,0 +1,5 @@
+import type { Hono } from "hono";
+import { type ApiRouteDeps } from "@opengeni/core";
+/** Registration is not an execution grant. The durable runtime must separately
+ * validate the exact binding generation and accepted execution context. */
+export declare function registerHostMcpBindingRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/workspace-tool-gateway.d.ts

@@ -10,6 +10,7 @@ import type { Observability } from "@opengeni/observability";
 export type PreparedWorkspaceToolGateway = Pick<PreparedWorkspaceToolGatewayTools, "toolGateway" | "toolGatewayCatalog" | "close"> & {
     toolGateway: NonNullable<PreparedWorkspaceToolGatewayTools["toolGateway"]>;
     toolGatewayCatalog: NonNullable<PreparedWorkspaceToolGatewayTools["toolGatewayCatalog"]>;
+    reauthorize?: () => Promise<void>;
 };
 type WorkspaceSiteToolContext = {
     siteArtifactId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "2.11.3",
+  "version": "2.12.1-canary.0",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,24 +43,24 @@
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.5.1",
-    "@opengeni/artifact-tool": "^0.3.23",
-    "@opengeni/capabilities": "^0.3.3",
-    "@opengeni/codemode": "^0.5.3",
-    "@opengeni/codex": "^0.2.22",
-    "@opengeni/config": "^1.0.4",
-    "@opengeni/contracts": "^2.15.2",
-    "@opengeni/core": "^2.8.3",
-    "@opengeni/db": "^4.2.2",
-    "@opengeni/documents": "^0.8.23",
-    "@opengeni/events": "^0.4.21",
-    "@opengeni/github": "^0.7.7",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.23",
-    "@opengeni/runtime": "^2.4.3",
-    "@opengeni/storage": "^0.2.124",
-    "@opengeni/tool-gateway": "^0.1.4",
-    "@opengeni/xai-subscription": "^0.1.4",
+    "@opengeni/agent-proto": "^0.5.1-canary.24",
+    "@opengeni/artifact-tool": "^0.3.24-canary.0",
+    "@opengeni/capabilities": "^0.3.3-canary.6",
+    "@opengeni/codemode": "^0.5.4-canary.0",
+    "@opengeni/codex": "^0.2.22-canary.6",
+    "@opengeni/config": "^1.1.0-canary.0",
+    "@opengeni/contracts": "^3.0.0-canary.0",
+    "@opengeni/core": "^2.9.1-canary.0",
+    "@opengeni/db": "^4.3.0-canary.0",
+    "@opengeni/documents": "^0.8.24-canary.0",
+    "@opengeni/events": "^0.4.22-canary.0",
+    "@opengeni/github": "^0.7.8-canary.0",
+    "@opengeni/network": "^0.3.1-canary.6",
+    "@opengeni/observability": "^0.8.24-canary.0",
+    "@opengeni/runtime": "^2.5.1-canary.0",
+    "@opengeni/storage": "^0.2.125-canary.0",
+    "@opengeni/tool-gateway": "^0.1.5-canary.0",
+    "@opengeni/xai-subscription": "^0.1.4-canary.6",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -1,3 +1,4 @@
+import { registerConnectCallbackReturns } from "./integrations/connect-callback-return";
 import { registerFeedbackRoutes } from "./routes/feedback";
 import { codemodeSessionRequest } from "./codemode";
 import { SiteSessionPathError } from "@opengeni/contracts";
@@ -40,6 +41,8 @@ import {
   CodemodePayloadTooLargeError,
   CodemodeToolApprovalRequiredError,
   CodemodeToolNotInCatalogError,
+  ConnectAttemptConflictError,
+  ConnectAttemptNotFoundError,
   configureChildLifecycleNotices,
   configureWorkspaceControlRequestLockTimeoutMs,
   dbSql,
@@ -149,6 +152,9 @@ import { registerCodexRoutes } from "./routes/codex";
 import { registerOrganizationModelProviderRoutes } from "./routes/organization-model-providers";
 import { registerSuperGrokRoutes } from "./routes/supergrok";
 import { registerConnectionRoutes } from "./routes/connections";
+import { registerConnectRoutes } from "./routes/connect";
+import { registerHostMcpBindingRoutes } from "./routes/host-mcp-bindings";
+import { registerExternalIdentityLinkRoutes } from "./routes/external-identity-links";
 import { registerDocumentRoutes } from "./routes/documents";
 import { registerEnrollmentRoutes } from "./routes/enrollments";
 import { registerMachineRoutes } from "./routes/machines";
@@ -1039,9 +1045,14 @@ export function createAppComposition(deps: AppDependencies): {
       // read and write. A missing row resolves to no Memory tools.
       const sessionMemory =
         typeof boundSessionId === "string"
-          ? ((await resolveSessionMemoryAgentScope(routeDeps.db, workspaceId, boundSessionId)) ?? {
+          ? ((await resolveSessionMemoryAgentScope(
+              routeDeps.db,
+              workspaceId,
+              boundSessionId,
+              grant.metadata,
+            )) ?? {
               mode: "off" as const,
-              endUserSubjectId: null,
+              userSubjectId: null,
               rootSessionId: null,
             })
           : null;
@@ -1224,6 +1235,7 @@ export function createAppComposition(deps: AppDependencies): {
     }
   });
 
+  registerConnectCallbackReturns(app, routeDeps);
   registerFileRoutes(app, routeDeps);
   registerApiKeyRoutes(app, routeDeps);
   registerBillingRoutes(app, routeDeps);
@@ -1249,6 +1261,9 @@ export function createAppComposition(deps: AppDependencies): {
   registerPersonalGitHubRoutes(app, routeDeps);
   registerPersonalGitHubGitBrokerRoutes(app, routeDeps);
   registerConnectionRoutes(app, routeDeps);
+  registerConnectRoutes(app, routeDeps);
+  registerHostMcpBindingRoutes(app, routeDeps);
+  registerExternalIdentityLinkRoutes(app, routeDeps);
   registerCapabilityRoutes(app, routeDeps);
   registerApiIntegrationRoutes(app, routeDeps);
   registerIntegrationFacetRoutes(app, routeDeps);
@@ -1573,6 +1588,8 @@ function codexCompactionV2ProviderLockedError(
 }
 
 export function httpStatusForError(error: unknown): number {
+  if (error instanceof ConnectAttemptConflictError) return 409;
+  if (error instanceof ConnectAttemptNotFoundError) return 404;
   if (codexCompactionV2ProviderLockedError(error)) {
     return 422;
   }
@@ -1605,6 +1622,9 @@ function retryableHttpStatus(status: number): boolean {
 }
 
 function publicErrorMessage(error: unknown, status: number): string {
+  if (error instanceof ConnectAttemptConflictError)
+    return "Connection setup changed or is still in progress. Reload its current status before retrying.";
+  if (error instanceof ConnectAttemptNotFoundError) return "Connection setup not found.";
   if (status === 502 || status === 503 || status === 504) {
     return "OpenGeni is temporarily unavailable — retry.";
   }