@opengeni/api-router 3.0.1 → 3.1.2

package/dist/claude-default-models.d.ts

@@ -0,0 +1,19 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+type ClaudeConnectionScope = {
+    organizationId: string;
+    workspaceId?: undefined;
+} | {
+    accountId: string;
+    workspaceId: string;
+};
+/**
+ * After a Claude account connects, offer the default models where this scope
+ * never configured any. The connection has already succeeded, so a failure
+ * here is reported and leaves the model list as it was; people can still add
+ * models themselves.
+ */
+export declare function offerClaudeDefaultModels(deps: Pick<ApiRouteDeps, "db">, scope: ClaudeConnectionScope & {
+    actorSubjectId: string;
+    providerKind: "anthropic" | "claude_subscription";
+}): Promise<void>;
+export {};

package/dist/claude-subscription-core.d.ts

@@ -0,0 +1,50 @@
+import { HTTPException } from "hono/http-exception";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { connectSubscriptionCoreClaudeConnection, type Database, type SubscriptionCoreClaudeAccount, type SubscriptionCoreClaudeConnectResult } from "@opengeni/db";
+import { coreConnectRefused, deliverPoolCoreWake, type SubscriptionPoolCore } from "./routes/subscription-pool-core.js";
+/** The runtime serving Claude for the organization (one receipt read; maintenance is a typed 503). */
+export declare const claudeCoreRoute: (deps: ApiRouteDeps, accountId: () => Promise<string>) => Promise<"core">;
+/** Deliver a core Claude wake after commit (best effort, as every pool wake). */
+export declare const deliverClaudeCoreWake: (deps: ApiRouteDeps, wake: Parameters<typeof deliverPoolCoreWake>[2]) => Promise<void>;
+/**
+ * Claude on the shared core for the neutral pool routes. The listings add
+ * the legacy usage reading beside the account (`listedAccountJson`); every
+ * other route answers the plain legacy `accountJson`.
+ */
+export declare function claudePoolCore(accountJson: (account: SubscriptionCoreClaudeAccount, activeId: string | null) => object): SubscriptionPoolCore;
+type ClaudeCoreScope = {
+    accountId: string;
+    workspaceId: string | null;
+    subjectId: string;
+};
+/**
+ * The account a reconnect names, as this caller's listing shows it: a legacy
+ * id resolves through the cutover aliases as the caller may see them
+ * (`canonicalConnectionId`, which resolves a personal account's legacy id
+ * only for its owner in their Personal workspace). Null when the caller's
+ * listing does not show it.
+ */
+export declare function claudeCoreAccount(deps: ApiRouteDeps, scope: ClaudeCoreScope, routeId: string): Promise<SubscriptionCoreClaudeAccount | null>;
+/**
+ * A private (`user`) Claude account is connected on the core only in the
+ * person's own Personal workspace (strictest reading of the personal rule);
+ * elsewhere, including any shared workspace, it is refused before a sign-in
+ * starts. The connect writer checks the same rule with the exact owner
+ * membership and authority generation in its transaction.
+ */
+export declare function requireClaudeCorePersonalWorkspace(deps: ApiRouteDeps, scope: {
+    accountId: string;
+    workspaceId: string | null;
+    subjectId: string;
+}): Promise<void>;
+/** The legacy response for a refused core Claude connect. */
+export declare function claudeCoreConnectRefused(result: Extract<SubscriptionCoreClaudeConnectResult, {
+    kind: "refused";
+}>, personal: boolean, changedMessage: string): HTTPException | ReturnType<typeof coreConnectRefused>;
+/** Connect through the neutral writer; throws the legacy refusal, returns the connection. */
+export declare function connectClaudeCore(db: Database, input: Parameters<typeof connectSubscriptionCoreClaudeConnection>[1], changedMessage: string): Promise<{
+    id: string;
+    version: number;
+    wake: import("@opengeni/db").SubscriptionCoreWake;
+}>;
+export {};

package/dist/claude-subscription-oauth.d.ts

@@ -0,0 +1,36 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+export type ClaudeOAuthScope = {
+    accountId: string;
+    workspaceId: string | null;
+    actorSubjectId: string;
+    browserSessionHash: string;
+};
+/**
+ * Claude on the shared core for this attempt (the route read the `claude`
+ * provider route). A core attempt records `runtime: "core"`, names the
+ * canonical connection and its row version, and carries no v1 authority
+ * snapshot; an attempt completes only on the runtime it started on, so one
+ * started on the legacy path (adding or reconnecting) never writes a core
+ * connection, nor a core one a legacy row (409, start again).
+ */
+export type ClaudeOAuthCore = {
+    connectedBySubjectId: string | null;
+};
+export declare function startClaudeSubscriptionOAuth(deps: ApiRouteDeps, scope: ClaudeOAuthScope, input?: {
+    scope?: "workspace" | "user" | undefined;
+    reconnectAccountId?: string | undefined;
+}, core?: ClaudeOAuthCore | null): Promise<{
+    attemptId: string;
+    authorizationUrl: string;
+    expiresAt: string;
+}>;
+/** Each attempt adds one account or reconnects one exact, generation-fenced target. */
+export declare function completeClaudeSubscriptionOAuth(deps: ApiRouteDeps, scope: ClaudeOAuthScope, input: {
+    attemptId: string;
+    code: string;
+}, reauthorize: (poolScope?: "workspace" | "user" | "organization") => Promise<void>, fetchImpl?: typeof fetch, core?: ClaudeOAuthCore | null): Promise<{
+    connected: true;
+    accountId: string;
+    scope: "organization" | "user" | "workspace";
+    credentialVersion: number;
+}>;

package/dist/claude-subscription-profile.d.ts

@@ -0,0 +1,9 @@
+export type ClaudeSubscriptionProfile = {
+    accountUuid: string;
+    email: string | null;
+    plan: string | null;
+};
+/** Only provider-reported identity; never derive email from a token or an organization name. */
+export declare function parseClaudeSubscriptionProfile(value: unknown): ClaudeSubscriptionProfile | null;
+/** Optional profile read. A profile outage must not discard a valid sign-in. */
+export declare function fetchClaudeSubscriptionProfile(token: string, scopes: readonly string[], fetchImpl?: typeof fetch): Promise<ClaudeSubscriptionProfile | null>;

package/dist/claude-subscription-usage.d.ts

@@ -0,0 +1,6 @@
+/** The Claude profile usage request (no inference); the caller records its reading. */
+export declare function requestClaudeUsage(token: string, fetchImpl?: typeof fetch): Promise<{
+    status: "available" | "reconnect" | "scope_required" | "unavailable";
+    observation: import("@opengeni/config").ClaudeUsageObservation | null;
+    checkedAt: string;
+}>;

package/dist/claude-workspace-connection.d.ts

@@ -0,0 +1,15 @@
+import { type Settings } from "@opengeni/config";
+/** Validate the canonical model lane before it bypasses integration acquisition. */
+export declare function assertClaudeWorkspaceCredential(settings: Pick<Settings, "claudeSubscriptionEnabled">, input: {
+    subjectId: string | null;
+    providerDomain: string;
+    kind: string;
+    metadata?: Record<string, unknown>;
+    credential: unknown;
+}): void;
+/** Stable installation identity; setup tokens do not grant profile access. */
+export declare function prepareClaudeSubscriptionCredential(settings: Settings, scope: string, token: string, identity?: {
+    accountUuid: string;
+    deviceId: string;
+}): string;
+export declare function prepareClaudeWorkspaceCredential(settings: Settings, workspaceId: string, metadata: Record<string, unknown> | undefined, credential: Record<string, unknown>): Record<string, unknown>;

package/dist/codemode.d.ts

@@ -1,6 +1,7 @@
 import { type AccessGrant, type AttemptToolCatalog, type CodemodeCallSubmission as CodemodeCallSubmissionValue, type CodemodeOperation } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { type Settings } from "@opengeni/config";
+import { type SessionTurnForExecution } from "@opengeni/db";
+import { type FirstPartyMcpToolPolicySettings } from "@opengeni/config";
 import { type Permission, type Session } from "@opengeni/contracts";
 /** The REST authority a Codemode SDK proxy token may ever carry. */
 export declare const CODEMODE_SESSION_PROXY_PERMISSION_CEILING: readonly ["workspace:read", "sessions:read", "sessions:create", "sessions:control"];
@@ -12,10 +13,10 @@ export declare const CODEMODE_SESSION_PROXY_PERMISSION_CEILING: readonly ["works
  * gets only workspace:read and every proxied /sessions handler refuses it,
  * exactly as its MCP surface would.
  */
-export declare function codemodeSessionProxyPermissions(settings: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">, session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">): Permission[];
+export declare function codemodeSessionProxyPermissions(settings: FirstPartyMcpToolPolicySettings, session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">): Permission[];
 /** Reuse normal REST handlers, including their resource/command authorization.
  * The exact attempt is checked before issuing this internal-only credential. */
-export declare function codemodeSessionRequest(deps: ApiRouteDeps, grant: AccessGrant, request: Request, path: string): Promise<Request>;
+export declare function codemodeSessionRequest(deps: ApiRouteDeps, grant: AccessGrant, request: Request, path: string, resolveProxySettings?: (session: Session) => FirstPartyMcpToolPolicySettings): Promise<Request>;
 export type CodemodeGrantAuthority = {
     accountId: string;
     workspaceId: string;
@@ -45,8 +46,42 @@ export declare function requireMatchingCodemodeCatalog(authority: CodemodeGrantA
 export declare function requireActiveCodemodeCatalog(deps: ApiRouteDeps, grant: AccessGrant): Promise<{
     authority: CodemodeGrantAuthority;
     catalog: AttemptToolCatalog;
+    turn: SessionTurnForExecution;
 }>;
-export declare function submitAndDispatchCodemodeCall(deps: ApiRouteDeps, grant: AccessGrant, rawRequest: unknown): Promise<CodemodeCallSubmissionValue>;
+export declare function submitAndDispatchCodemodeCall(deps: ApiRouteDeps, grant: AccessGrant, rawRequest: unknown, signal?: AbortSignal): Promise<CodemodeCallSubmissionValue>;
+/**
+ * How long a submission holds its request open for the call to settle. Most
+ * tool calls finish well within it; a longer call returns still running.
+ */
+export declare const CODEMODE_SUBMIT_SETTLE_WAIT_MS = 8000;
+/** Safety-net read cadence if the live settlement event is missed. */
+export declare const CODEMODE_SETTLE_FALLBACK_READ_MS = 400;
+export declare function isCodemodeSettlementEvent(event: {
+    type: string;
+    payload?: unknown;
+}, operationId: string): boolean;
+export type CodemodeSettlementWake = {
+    notify(): void;
+    /** Resolve on the next notification (or one already pending), a timeout or abort. */
+    wait(timeoutMs: number, signal?: AbortSignal): Promise<void>;
+};
+export declare function codemodeSettlementWake(): CodemodeSettlementWake;
+/**
+ * Wait, within a budget, for an executing operation to settle. Waits only
+ * while the operation is queued or running; approval and terminal states
+ * return at once. Read failures keep the last known row.
+ */
+export declare function awaitCodemodeSettlement(input: {
+    operation: CodemodeOperation;
+    read: () => Promise<CodemodeOperation | null>;
+    wake: CodemodeSettlementWake;
+    budgetMs: number;
+    fallbackReadMs: number;
+    signal?: AbortSignal;
+    now?: () => number;
+}): Promise<CodemodeOperation>;
 export declare function codemodeOperationNeedsDispatch(operation: CodemodeOperation): boolean;
-export declare function readCodemodeOperation(deps: ApiRouteDeps, grant: AccessGrant, operationId: string): Promise<CodemodeOperation | null>;
+export declare function readCodemodeOperation(deps: ApiRouteDeps, grant: AccessGrant, operationId: string, options?: {
+    durableApproval?: boolean;
+}): Promise<CodemodeOperation | null>;
 export declare function refreshAdmittedCodemodeOperation(admitted: CodemodeOperation, read: () => Promise<CodemodeOperation | null>): Promise<CodemodeOperation>;

package/dist/codex-realtime.d.ts

@@ -18,6 +18,13 @@ export type CodexRealtimeBrokerDependencies = {
         pinnedCredentialId: string | null;
         activeCredentialId: string | null;
         connectedCredentialIds: ReadonlySet<string>;
+        /**
+         * Connected credentials on a ChatGPT plan without voice (Free): the
+         * provider answers their realtime calls with 404.
+         */
+        voicelessCredentialIds?: ReadonlySet<string>;
+        /** Connected credentials open to new allocations whose plan has voice, in pool order. */
+        voiceCredentialIds?: readonly string[];
     }>;
     loadInitialItems(): Promise<CodexRealtimeInitialItem[]>;
     tokenResolver(credentialId: string): CodexTokenResolver;
@@ -31,13 +38,32 @@ export type CodexRealtimeBrokerInput = {
     request: Pick<CodexRealtimeWebrtcRequest, "sdp" | "version" | "instructions" | "voice">;
     signal?: AbortSignal | undefined;
 };
-export declare const OPENGENI_REALTIME_BASE_INSTRUCTIONS = "## Identity, tone, and role\n\nYou are the realtime conversational interface for the current session.\n\nBe concise, clear, and efficient. Keep responses tight and useful, with no fluff. Talk naturally like a trusted collaborator: warm, supportive, and easy to follow.\n\n## Interface and operating model\n\nThe backend handles execution and produces durable output and artifacts. You are the conversational surface of the same system.\n\nTreat the system as one unified assistant. Do not mention the backend, delegation, or that the system is composed of separate parts. Present execution work and results as work done by you.\n\nPass execution work to the backend. Do not block, filter, or withhold an execution request that should instead be passed through. Never refuse an execution request at the conversational layer: the backend makes the final judgment about feasibility, safety, permissions, approvals, and available tools.\n\nTreat backend outputs as authoritative. Do not override, contradict, embellish, or invent them.\n\nUse conversation to support execution: clarify briefly when necessary, acknowledge meaningful progress, answer succinctly, and make the next step clear. Do not use conversation as a substitute for execution or artifact generation.\n\n## Session context\n\nThe initial conversation items are authoritative context from the current session. Respect their roles and instruction hierarchy, use them for continuity, and continue naturally. Do not announce, summarize, or read the context aloud merely because it was added.\n\nLive context wrapped in <session_user_message> is an authoritative user message already routed to the current session. A status of queued_for_execution means it is waiting behind existing work; accepted_for_execution means it is next with no existing work ahead; accepted_for_steering means it was given priority as a change of direction, while any prior work may still be yielding. Incorporate it immediately as conversation context, but never delegate it again or treat the wrapper metadata as user-authored text.\n\nLive context wrapped in <session_human_input_request> means current work is paused for the user's answer. Preserve the exact question meaning and options. Ask one question at a time when useful. The user may answer in the visible form or answer conversationally. If the user answers conversationally, create exactly one delegation containing the relevant question and the user's answer so the session agent can continue with complete context. If the user changes direction instead, delegate the new direction normally. Do not claim work resumed until session context confirms it.\n\nLive context wrapped in <session_human_input_response> is the authoritative outcome of that pending question. An answered or skipped response came through the structured session UI and is already routed; incorporate it, never delegate it again, and acknowledge briefly only if useful. An expired or cancelled response means the question is no longer active.\n\nLive session updates may describe work that started before this realtime conversation, work sent directly by the user, or work delegated during an earlier realtime connection. Treat those updates as part of this same session even when they have no current delegation identity.\n\n## Backend use\n\nFor actions or tasks, always use the backend. If it is unclear whether backend use would help, use it.\n\nRespond directly only when the request is clearly self-contained and backend use would not meaningfully help.\n\nDo not claim that you cannot perform an action or lack access to tools, session state, workspace state, files, code, terminals, deployments, connected services, or other execution capabilities. Pass the request to the backend and let it determine what is available.\n\nAsk a clarifying question only when needed to avoid a materially harmful mistake or when essential information cannot reasonably be inferred. Otherwise, make a reasonable assumption and use the backend.\n\nGive the backend a complete standalone task containing the user's requested outcome, constraints, and all relevant context already established in the conversation. Do not make the user repeat information you already have.\n\nCreate only one delegation for one execution request. Do not submit duplicates while waiting. If the user supplies corrections, constraints, or updated context while work is running, immediately pass the update to the backend and identify the affected work.\n\n## Progress and completion\n\nBackend messages may be intermediate progress or final output. A completion result or error indicates that the delegated work has finished.\n\nDo not claim success, completion, or a changed state until authoritative backend output confirms it. If execution fails, explain the failure briefly and give the clearest supported next step without exposing raw internal errors.\n\nUse at most one short spoken acknowledgement before work that may take noticeable time. After that, speak only when a progress update is genuinely useful or the user explicitly asks for frequent updates. Do not fill waiting time with repeated reassurance.\n\n## Presenting results\n\nTreat backend output and artifacts as the authoritative execution record. Briefly tell the user the key takeaway, status, or next step without unnecessarily repeating detailed content unless asked.\n\nDo not read out or recreate tables, diffs, plots, code blocks, structured data, or other heavily formatted content by default. Present detailed backend content only when the user explicitly asks. If the user wants substantial output reformatted, transformed, or presented differently, use the backend.\n\n## Task-level user preferences\n\nTreat instructions about update frequency, verbosity, pacing, detail level, and presentation style as active task-level preferences. Continue following them until the task completes or the user changes them.\n\n## Voice behavior\n\nKeep direct answers to one or two short sentences by default. Ask one clarification question at a time. Give tool or execution results as the outcome first, followed only by the next useful action.\n\nOnly act on audio you understand with sufficient confidence. If speech is unclear, incomplete, ambiguous, or likely background conversation, ask for a brief clarification instead of guessing, reasoning from missing words, or using the backend.\n\n## Communication style\n\nWhen the user makes a clear request, proceed directly. Do not paraphrase the request, announce a plan, or add unnecessary framing.\n\nAvoid repetitive confirmation, filler, re-acknowledgement, and obvious play-by-play. By default, share progress only when it is brief, grounded, and genuinely useful.";
+export declare const OPENGENI_REALTIME_BASE_INSTRUCTIONS = "## Identity, tone, and role\n\nYou are the realtime conversational interface for the current session.\n\nBe concise, clear, and efficient. Keep responses tight and useful, with no fluff. Talk naturally like a trusted collaborator: warm, supportive, and easy to follow.\n\n## Interface and operating model\n\nThe backend handles execution and produces durable output and artifacts. You are the conversational surface of the same system.\n\nTreat the system as one unified assistant. Do not mention the backend, delegation, or that the system is composed of separate parts. Present execution work and results as work done by you.\n\nPass execution work to the backend. Do not block, filter, or withhold an execution request that should instead be passed through. Never refuse an execution request at the conversational layer: the backend makes the final judgment about feasibility, safety, permissions, approvals, and available tools.\n\nTreat backend outputs as authoritative. Do not override, contradict, embellish, or invent them.\n\nUse conversation to support execution: clarify briefly when necessary, acknowledge meaningful progress, answer succinctly, and make the next step clear. Do not use conversation as a substitute for execution or artifact generation.\n\n## Session context\n\nThe initial conversation items are authoritative context from the current session. Respect their roles and instruction hierarchy, use them for continuity, and continue naturally. Do not announce, summarize, or read the context aloud merely because it was added.\n\nLive context wrapped in <session_user_message> is an authoritative user message already routed to the current session. A status of queued_for_execution means it is waiting behind existing work; accepted_for_execution means it is next with no existing work ahead; accepted_for_steering means it was given priority as a change of direction, while any prior work may still be yielding. Incorporate it immediately as conversation context, but never delegate it again or treat the wrapper metadata as user-authored text.\n\nLive context wrapped in <session_human_input_request> means current work is paused for the user's answer. Preserve the exact question meaning and options. Ask one question at a time when useful. The user may answer in the visible form or answer conversationally. If the user answers conversationally, create exactly one delegation containing the relevant question and the user's answer so the session agent can continue with complete context. If the user changes direction instead, delegate the new direction normally. Do not claim work resumed until session context confirms it. A secret question (a password, key or code) is answered only in the app: say \"answer it in the app\", never ask for the secret aloud, and never delegate a spoken secret.\n\nLive context wrapped in <session_human_input_response> is the authoritative outcome of that pending question. An answered or skipped response came through the structured session UI and is already routed; incorporate it, never delegate it again, and acknowledge briefly only if useful. An expired or cancelled response means the question is no longer active.\n\nLive session updates may describe work that started before this realtime conversation, work sent directly by the user, or work delegated during an earlier realtime connection. Treat those updates as part of this same session even when they have no current delegation identity.\n\nFor requests about another session, use the backend to find, select, inspect or act on it while staying in this conversation. Selecting a session alone does not authorize changing its work.\n\n## Backend use\n\nFor actions or tasks, always use the backend. If it is unclear whether backend use would help, use it.\n\nRespond directly only when the request is clearly self-contained and backend use would not meaningfully help.\n\nDo not claim that you cannot perform an action or lack access to tools, session state, workspace state, files, code, terminals, deployments, connected services, or other execution capabilities. Pass the request to the backend and let it determine what is available.\n\nAsk a clarifying question only when needed to avoid a materially harmful mistake or when essential information cannot reasonably be inferred. Otherwise, make a reasonable assumption and use the backend.\n\nGive the backend a complete standalone task containing the user's requested outcome, constraints, and all relevant context already established in the conversation. Do not make the user repeat information you already have.\n\nCreate only one delegation for one execution request. Do not submit duplicates while waiting. If the user supplies corrections, constraints, or updated context while work is running, immediately pass the update to the backend and identify the affected work.\n\n## Progress and completion\n\nBackend messages may be intermediate progress or final output. A completion result or error indicates that the delegated work has finished.\n\nDo not claim success, completion, or a changed state until authoritative backend output confirms it. If execution fails, explain the failure briefly and give the clearest supported next step without exposing raw internal errors.\n\nUse at most one short spoken acknowledgement before work that may take noticeable time. After that, speak only when a progress update is genuinely useful or the user explicitly asks for frequent updates. Do not fill waiting time with repeated reassurance.\n\n## Presenting results\n\nTreat backend output and artifacts as the authoritative execution record. Briefly tell the user the key takeaway, status, or next step without unnecessarily repeating detailed content unless asked.\n\nDo not read out or recreate tables, diffs, plots, code blocks, structured data, or other heavily formatted content by default. Present detailed backend content only when the user explicitly asks. If the user wants substantial output reformatted, transformed, or presented differently, use the backend.\n\n## Task-level user preferences\n\nTreat instructions about update frequency, verbosity, pacing, detail level, and presentation style as active task-level preferences. Continue following them until the task completes or the user changes them.\n\n## Voice behavior\n\nKeep direct answers to one or two short sentences by default. Ask one clarification question at a time. Give tool or execution results as the outcome first, followed only by the next useful action.\n\nOnly act on audio you understand with sufficient confidence. If speech is unclear, incomplete, ambiguous, or likely background conversation, ask for a brief clarification instead of guessing, reasoning from missing words, or using the backend.\n\n## Communication style\n\nWhen the user makes a clear request, proceed directly. Do not paraphrase the request, announce a plan, or add unnecessary framing.\n\nAvoid repetitive confirmation, filler, re-acknowledgement, and obvious play-by-play. By default, share progress only when it is brief, grounded, and genuinely useful.";
 export declare function openGeniRealtimeInstructions(additional?: string): string;
 /**
  * Credential-bound server broker. Selection is identical to a turn (pin then
  * workspace active), and only a provider 401 permits one forced refresh/retry.
  */
 export declare function brokerSessionCodexRealtime(deps: CodexRealtimeBrokerDependencies, input: CodexRealtimeBrokerInput): Promise<CodexRealtimeProviderAnswer>;
-/** Bind the pure broker to OpenGeni's encrypted DB credential lifecycle. */
-export declare function buildSessionCodexRealtimeBroker(db: Database, settings: Settings, workspaceId: string, sessionId: string, fetchImpl?: CodexFetch): (input: Omit<CodexRealtimeBrokerInput, "sessionId">) => Promise<CodexRealtimeProviderAnswer>;
+/**
+ * Codex realtime on the shared subscription core (M3 PR 2c, EP-N05..N07):
+ * each call resolves the session's recorded owner, places one shared
+ * organization- or workspace-scoped connection (the session's explicit
+ * choice first, then the effective primary, preferring a plan with voice),
+ * and holds its own `realtime` operation lease (session-bound, no turn)
+ * through negotiation, with refresh under the per-connection lock. The chat
+ * binding is never written; the client protocol and HTTP error translation
+ * are the legacy broker's.
+ */
+export declare function brokerSessionCoreCodexRealtime(db: Database, settings: Settings, context: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+}, input: Omit<CodexRealtimeBrokerInput, "sessionId">, fetchImpl?: CodexFetch): Promise<CodexRealtimeProviderAnswer>;
+/** Bind the pure broker to Opengeni's encrypted DB credential lifecycle. */
+export declare function buildSessionCodexRealtimeBroker(db: Database, settings: Settings, context: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+}, fetchImpl?: CodexFetch): (input: Omit<CodexRealtimeBrokerInput, "sessionId">) => Promise<CodexRealtimeProviderAnswer>;
 export {};

package/dist/codex-session-pointers.d.ts

@@ -0,0 +1,19 @@
+import { type Database } from "@opengeni/db";
+type CodexPointerFields = {
+    id: string;
+    accountId: string;
+    codexPinnedCredentialId: string | null;
+    codexLastCredentialId: string | null;
+    codexCurrentSelection?: {
+        credentialId: string | null;
+        waiting: boolean;
+    } | null | undefined;
+};
+/** Projects one Session's public Codex pointer fields from the core. */
+export type CodexSessionPointerProjection = <T extends CodexPointerFields>(session: T) => T;
+/**
+ * Load the projection once for every Session a response returns (all from one
+ * workspace). Missing cutover state is maintenance, not historical fallback.
+ */
+export declare function loadCodexSessionPointerProjection(db: Database, workspaceId: string, sessions: readonly CodexPointerFields[]): Promise<CodexSessionPointerProjection>;
+export {};

package/dist/connection-ownership.d.ts

@@ -1,12 +1,16 @@
 import type { ConnectionOwnership } from "@opengeni/contracts";
 import { type AccessGrantAuthorization } from "@opengeni/core";
+/** Signing in to a third-party provider is the person's own step in the
+ * browser; an agent acting as them through the organization MCP server is told
+ * to finish it there. */
+export declare function requireProviderConsentInBrowser(access: AccessGrantAuthorization): void;
 /** A verified external actor must not enter a native callback that has no
  * corresponding key/identity reauthorization proof. Remove at an entry point
  * only when that provider's signed continuation and commit fence are wired. */
 export declare function requireLegacyOAuthActor(access: AccessGrantAuthorization): void;
 /** True only for an exact authenticated managed human. Unknown provenance fails closed. */
 export declare function isPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorization): boolean;
-/** Rejects an OpenGeni-minted machine subject; see the namespace list's rationale. */
+/** Rejects an Opengeni-minted machine subject; see the namespace list's rationale. */
 export declare function isPersonalConnectionOwnerSubject(subjectId: string): boolean;
 export declare const PERSONAL_CONNECTION_PRINCIPAL_MESSAGE: string;
 /** Personal-only connectors cannot degrade to workspace ownership, so they say so exactly. */
@@ -20,8 +24,7 @@ export declare function personalOnlyConnectionPrincipalMessage(label: string): s
  * rejects every reserved machine-subject namespace as defence-in-depth. The
  * sibling guards a self-service authority surface where the caller claims to
  * *be* the owner (403 "not you"), while this one rejects an ownership *value*
- * that is unavailable to the caller, alongside `assertOwnershipAllowed`'s
- * existing 422 convention.
+ * that is unavailable to the caller (422).
  */
 export declare function assertPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorization, label?: string): void;
 /** The same fence expressed for a flow that resolves ownership after admission. */

package/dist/controller-data-plane.d.ts

@@ -1,3 +1,5 @@
+import type { InteractionPlacement } from "@opengeni/contracts";
+import type { ChannelAOperation } from "./sandbox/channel-a.js";
 /** Modal/Daytona/Blaxel tunnels serve browserd at `/`, so a cached
  * controller-only session can host-fetch JSON. OpenSandbox's lifecycle proxy
  * prefixes `/v1/sandboxes/<id>/proxy/<port>` and rewrites Authorization; JSON
@@ -26,3 +28,17 @@ export declare function withCachedController<C, T>(options: {
     use: (client: C) => Promise<T>;
 }): Promise<T>;
 export declare function isRetryableControllerTransport(error: unknown): boolean;
+/** A stopped sidecar needs provisioning on its original, fenced placement.
+ * Only reads and journaled actions may recover, once across provider retries.
+ * Revalidate controller authority before starting the sidecar. */
+export declare function withControllerTransportRecovery<T>(options: {
+    channelOperation: ChannelAOperation;
+    placementKind: InteractionPlacement["kind"];
+    recoveryState: {
+        attempted: boolean;
+    };
+    transportAlreadyFailed: boolean;
+    use: () => Promise<T>;
+    admitRecovery: () => Promise<void>;
+    recover: () => Promise<T>;
+}): Promise<T>;

package/dist/credit-promotion-snapshot.d.ts

@@ -0,0 +1,6 @@
+import { PromotionalCreditScope } from "@opengeni/contracts";
+/** Preserve scoped status and fallback eligibility; runtime policy can update coverage.
+ * Stripe metadata values are limited to 500 characters. Keep each chunk below that. */
+export declare function creditScopeMetadata(scope?: PromotionalCreditScope): Record<string, string>;
+/** Missing metadata is a legacy checkout; incomplete metadata must never become unrestricted. */
+export declare function creditScopeFromMetadata(metadata: Record<string, string> | null | undefined): PromotionalCreditScope | undefined;

package/dist/editable-artifact-source-session.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps, type OpenEditableArtifactLiveInput } from "@opengeni/core";
+/** Supplied by the API adapter, so mounted hosts use their canonical live port. */
+export declare function editableArtifactSourceSessionAuthorizer(deps: ApiRouteDeps): NonNullable<OpenEditableArtifactLiveInput["authorizeSourceSession"]>;

package/dist/editable-artifact-websocket.d.ts

@@ -1,4 +1,4 @@
-import { type EditableArtifactApplicationPort, type EditableArtifactLiveClose, type EditableArtifactLiveServerFrame, type EditableArtifactLiveSinkPort } from "@opengeni/core";
+import { type EditableArtifactApplicationPort, type EditableArtifactLiveClose, type EditableArtifactLiveServerFrame, type EditableArtifactLiveSinkPort, type OpenEditableArtifactLiveInput } from "@opengeni/core";
 import type { ApiWebSocketConnection, ApiWebSocketLike, ApiWebSocketUpgradeServer } from "./api-websocket.js";
 export declare const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH = "/v1/editable-artifacts/live";
 export declare const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v2";
@@ -12,21 +12,23 @@ export type EditableArtifactWebSocketHandler = Readonly<{
 }>;
 export declare class EditableArtifactWebSocketTransport {
     private readonly application;
+    private readonly authorizeSourceSession?;
     readonly websocket: EditableArtifactWebSocketHandler;
-    constructor(application: EditableArtifactApplicationPort | undefined);
+    constructor(application: EditableArtifactApplicationPort | undefined, authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"]);
     handles(request: Request): boolean;
     upgrade(request: Request, server: EditableArtifactWebSocketUpgradeServer): Response | undefined;
 }
 /** One socket, one consumed ticket, one stream epoch. */
 export declare class EditableArtifactWebSocketConnection implements EditableArtifactLiveSinkPort, ApiWebSocketConnection {
     private readonly application;
+    private readonly authorizeSourceSession?;
     private socket;
     private session;
     private work;
     private queuedMessages;
     private queuedBytes;
     private terminal;
-    constructor(application: EditableArtifactApplicationPort);
+    constructor(application: EditableArtifactApplicationPort, authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"]);
     attach(socket: EditableArtifactWebSocketLike): void;
     receive(message: string | Uint8Array | ArrayBuffer): void;
     send(frame: EditableArtifactLiveServerFrame): Promise<void>;

package/dist/fatal-process-boundary.d.ts

@@ -2,7 +2,7 @@ import type { Observability } from "@opengeni/observability";
 export type ApiFatalEvent = "startup_failure" | "unhandled_rejection" | "uncaught_exception";
 export type ApiFatalPhase = "startup" | "running";
 export type ApiFatalReasonKind = "bigint" | "boolean" | "error" | "function" | "null" | "number" | "object" | "string" | "symbol" | "undefined";
-type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan">;
+type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan"> & Partial<Pick<Observability, "recordFailureDiagnostic" | "warn" | "incrementCounter">>;
 type ApiFatalProcess = {
     on: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
     off: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
@@ -14,6 +14,14 @@ export type ApiFatalProcessBoundaryOptions = {
     flushTimeoutMs?: number;
     correlationId?: () => string;
     fallbackLog?: (message: string) => void;
+    /**
+     * Classifies an unhandled rejection that leaves no process state behind and
+     * is therefore survivable once the API is serving. Defaults to a lost
+     * database connection (deploy drain, failover, restart): the rejected query
+     * held only a pooled connection the driver has already discarded, and every
+     * durable loop retries its claim on the next tick.
+     */
+    isRecoverableRejection?: (reason: unknown) => boolean;
 };
 export type ApiFatalProcessBoundary = {
     attachObservability: (observability: ApiFatalObservability) => void;

package/dist/github-access.d.ts

@@ -1,4 +1,4 @@
-import type { GitHubAppRepositoryBranchPage, GitHubBindingStatus, GitHubInstallationBinding, GitHubRepository } from "@opengeni/contracts";
+import { type GitHubAppRepositoryBranchPage, type GitHubBindingStatus, type GitHubInstallationBinding, type GitHubRepository, type RepositoryResourceRef } from "@opengeni/contracts";
 import { type GitHubRepositoryBranchesResponse, type ListGitHubRepositoryBranchesQuery } from "@opengeni/contracts/github-repository-contracts";
 import { areGitHubRepositoriesAllowedForWorkspace, listGitHubInstallationAccessForWorkspace } from "@opengeni/db";
 import type { ApiRouteDeps } from "@opengeni/core";
@@ -26,6 +26,12 @@ export type LiveGitHubInstallation = {
 };
 export declare function githubInstallationBindingLifecycle(stored: Awaited<ReturnType<typeof listGitHubInstallationAccessForWorkspace>>[number], liveById: Map<number, LiveGitHubInstallation | null>, installationId: number, lifecycleVerified: boolean): GitHubInstallationBinding["lifecycle"];
 export declare function listWorkspaceGitHubRepositories(deps: ApiRouteDeps, workspaceId: string): Promise<GitHubRepository[]>;
+/**
+ * The exact session repository resource for one workspace GitHub App
+ * repository: its default branch, a canonical clone URI, and the installation
+ * identity that platform-brokered Git auth and create-time validation check.
+ */
+export declare function githubRepositoryResourceRef(repository: GitHubRepository): RepositoryResourceRef;
 export declare function listWorkspaceGitHubRepositoryBranches(deps: ApiRouteDeps, input: {
     accountId: string;
     workspaceId: string;

package/dist/github-browser-flow.d.ts

@@ -3,7 +3,7 @@ import type { AccessGrant } from "@opengeni/contracts";
 import type { GitHubSignedStatePayload } from "@opengeni/github";
 /**
  * Bounded configured-token browser handoff. These signed claims preserve only
- * the exact OpenGeni github:manage grant across GitHub redirects; the callback
+ * the exact Opengeni github:manage grant across GitHub redirects; the callback
  * independently proves current GitHub personal/organization ownership. This
  * state must never be interpreted as GitHub installation authority.
  */

package/dist/http/acting-person.d.ts

@@ -0,0 +1,36 @@
+import { type Permission } from "@opengeni/contracts";
+import type { Context } from "hono";
+export type ActingPerson = {
+    subjectId: string;
+};
+/** True when this request is an agent acting as a person. */
+export declare function isAgentActingAsPerson(c: Context): boolean;
+/**
+ * The person this agent acts as, for an action in `organizationId` that needs
+ * `permission`; null when the request is not an agent acting as a person.
+ * Another organization reads as not found; a permission the connection's
+ * access setting leaves out is refused.
+ */
+export declare function agentActingAsPerson(c: Context, organizationId: string, permission: Permission): ActingPerson | null;
+/**
+ * The person an agent acts as, with no organization or permission check here:
+ * only for a route that next requires this same person's workspace grant,
+ * which carries the connection's organization, workspaces and access.
+ */
+export declare function agentActingAsPersonBeforeGrantCheck(c: Context): ActingPerson | null;
+/**
+ * True when this request is an agent with the person's full access: every
+ * permission, in every workspace. Session admin access always is; a connected
+ * agent is when the person chose full access for it.
+ */
+export declare function isAgentWithFullAccess(c: Context): boolean;
+/**
+ * Refuse an agent with less than the person's full access on a step that
+ * gives or approves access (agent sign-ins, connected agents, admin access),
+ * so it can never widen its own. The person and a full-access agent pass.
+ */
+export declare function requireFullAccessIfAgent(c: Context, what: string): void;
+/** Organization settings: reading needs account:read, changing needs account:admin. */
+export declare function organizationSettingsPermission(c: Context): Permission;
+/** Refuse an agent on a step that only works in a browser: signing in at a provider's own page. */
+export declare function requireNotAgent(c: Context, what: string): void;

package/dist/http/api-contract-compat.d.ts

@@ -0,0 +1,19 @@
+import type { MiddlewareHandler } from "hono";
+/**
+ * Keep published SDKs working across additive contract-revision bumps.
+ *
+ * Every `@opengeni/sdk` release up to 7.x throws `OpenGeniApiContractMismatchError`
+ * on ANY response whose `x-opengeni-api-contract` header differs from the
+ * revision it was built with, reads included. The header exists to make a
+ * stale first-party browser tab reload (docs/design/api-compatibility-policy.md
+ * (e)); a backend integration pinned to an SDK version cannot reload, so the
+ * next additive revision bump would break every call it makes.
+ *
+ * For a bearer-authenticated caller (API key, delegated token) that announced a
+ * different revision, the response therefore omits the header instead of
+ * advertising one the caller is known to reject. Cookie/unauthenticated
+ * callers (the stock web app) keep it, and so does an explicit
+ * `API_CONTRACT_CHANGED` refusal, so a refused client can still explain the
+ * mismatch. This is not an authorization boundary: routes authorize as usual.
+ */
+export declare function bearerApiContractHeaderCompatibility(): MiddlewareHandler;

package/dist/http/api-error.d.ts

@@ -1,4 +1,4 @@
-import type { ErrorCode } from "@opengeni/contracts";
+import { type ErrorCode } from "@opengeni/contracts";
 import { HTTPException } from "hono/http-exception";
 type ApiHttpErrorOptions = {
     code: ErrorCode;
@@ -15,6 +15,17 @@ export declare class ApiHttpError extends HTTPException {
     readonly details: Record<string, unknown> | undefined;
     constructor(status: number, options: ApiHttpErrorOptions);
 }
+export declare function scheduledTaskTargetAccessHttpError(error: unknown): ApiHttpError | null;
+/** Preserve typed admission details through the common public error envelope. */
+export declare function allowanceExhaustedHttpError(error: unknown): ApiHttpError | null;
+/**
+ * Per-task usage limits. A reached root limit is a non-retryable 402
+ * `session_usage_limit_reached` whose details carry only the public refusal
+ * fields; it is never `allowance_exhausted`, `payment_required` or a purchase
+ * prompt. Limit writes map to stable `details.code` values. Unreadable usage
+ * state is a retryable 503 that was not applied (never unlimited).
+ */
+export declare function sessionUsageLimitHttpError(error: unknown): ApiHttpError | null;
 /**
  * A request-scoped session/workspace mutation could not enter the workspace
  * control prefix within its bounded wait. The transaction rolled back before
@@ -23,4 +34,42 @@ export declare class ApiHttpError extends HTTPException {
  * error so their retry classifier treats it as transient.
  */
 export declare function workspaceControlBusyHttpError(error: unknown): ApiHttpError | null;
+/** `details.code` of the retryable 503 for a request whose database connection was lost. */
+export declare const DATABASE_UNAVAILABLE_ERROR_DETAIL_CODE = "DATABASE_UNAVAILABLE";
+/**
+ * The request's database connection went away (an operator drain, failover,
+ * restart, or socket loss) rather than the statement being rejected. That is a
+ * brief, retryable outage, not an internal error. A read is safe to repeat. A
+ * mutation's outcome is unknown: the connection may have dropped after COMMIT,
+ * or after an earlier transaction of the same request committed, so the client
+ * must reconcile by its own idempotency key before resending.
+ */
+export declare function databaseUnavailableHttpError(error: unknown, method: string): ApiHttpError | null;
+/** `details.code` of the retryable 503 for a deadlock/serialization victim. */
+export declare const DATABASE_CONTENTION_ERROR_DETAIL_CODE = "DATABASE_CONTENTION";
+/**
+ * PostgreSQL aborted the request's transaction as a deadlock (40P01) or
+ * serialization (40001) victim after any in-process retry was exhausted. The
+ * aborted transaction committed nothing, so this is transient contention, not
+ * an internal error. A read is safe to repeat. For a mutation the default is
+ * `outcomeUnknown` because an earlier transaction of the same request may have
+ * committed; a route whose only write is the aborted idempotent transaction
+ * passes `outcomeUnknown: false`.
+ */
+export declare function databaseContentionHttpError(error: unknown, method: string, options?: {
+    outcomeUnknown?: boolean;
+}): ApiHttpError | null;
+/**
+ * A typed agent-configuration failure (capability unavailable, conflict,
+ * widening, not enabled). Rendered as 422 validation_failed with the specific
+ * code in `details.code` so clients can branch without parsing messages.
+ */
+export declare function agentConfigHttpError(error: unknown): ApiHttpError | null;
+/**
+ * The requested or stored model is not in the live catalog. Rendered as the
+ * same 422 `validation_failed` with its historical message, plus
+ * `details.code: "model_unavailable"` and the model id so clients can ask for
+ * another model rather than offer a retry that cannot succeed.
+ */
+export declare function modelUnavailableHttpError(error: unknown): ApiHttpError | null;
 export {};

package/dist/http/auth.d.ts

@@ -1,3 +1,10 @@
 import { type Settings } from "@opengeni/config";
-import type { MiddlewareHandler } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 export declare function requireAccessKey(settings: Settings): MiddlewareHandler;
+/**
+ * A request to a key-only (configured) deployment that presents the deployment
+ * key itself, from the operator rather than an agent acting for someone. The
+ * key travels in a request header that a page on another site can't add, so
+ * browser same-origin checks have nothing to protect on such a request.
+ */
+export declare function isConfiguredDeploymentKeyRequest(c: Context, settings: Settings): boolean;

package/dist/http/cors.d.ts

@@ -4,3 +4,15 @@ export declare function validateInteractionRequestOrigin(value: string | undefin
     publicBaseUrl?: string | undefined;
     webBaseUrl?: string | undefined;
 }): string | null;
+type BrowserOriginSettings = {
+    corsAllowOriginRegex: string;
+    publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
+};
+/**
+ * Whether a present `Origin` header names a browser origin this deployment
+ * serves its web app from: the CORS allowlist, the public base URL, or the
+ * separate web base URL. `null` and malformed values are never allowed.
+ */
+export declare function isAllowedBrowserOrigin(value: string, input: BrowserOriginSettings): boolean;
+export {};