@opengeni/api-router 0.30.1 → 1.0.0

package/dist/chunk-OGQDXVXY.js

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+export {
+  __reExport
+};
+//# sourceMappingURL=chunk-OGQDXVXY.js.map

package/dist/chunk-OGQDXVXY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/claude-subscription-account-conflicts.d.ts

@@ -0,0 +1 @@
+export declare function claudeAccountMutationFailure(error: unknown): never;

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

@@ -0,0 +1,39 @@
+import { type Settings } from "@opengeni/config";
+import { type ClaudeAccountUsageAuthority, type Database } from "@opengeni/db";
+/** Profile quota requests never run inference and never select a different account. */
+export declare function refreshClaudeAccountUsage(db: Database, settings: Settings, authority: ClaudeAccountUsageAuthority, fetchImpl?: typeof fetch): Promise<{
+    connected: boolean;
+    credentialVersion: number | null;
+    windows: {
+        id: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet";
+        usedPercent: number | null;
+        resetsAt: string | null;
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    }[];
+    observedAt: string | null;
+    source: "provider" | "response_headers" | null;
+    refreshStatus: "available" | "not_checked" | "reconnect" | "scope_required" | "unavailable";
+    refreshCheckedAt: string | null;
+    requestStatus?: {
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        resetsAt: string | null;
+        representativeClaim: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet" | null;
+        overageStatus: "allowed" | "allowed_warning" | "rejected" | null;
+        overageResetsAt: string | null;
+        upstreamModelId: string | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    } | null | undefined;
+    requestRestrictions?: {
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        resetsAt: string | null;
+        representativeClaim: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet" | null;
+        overageStatus: "allowed" | "allowed_warning" | "rejected" | null;
+        overageResetsAt: string | null;
+        upstreamModelId: string | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    }[] | undefined;
+}>;

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

@@ -0,0 +1,25 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+export type ClaudeOAuthScope = {
+    accountId: string;
+    workspaceId: string | null;
+    actorSubjectId: string;
+    browserSessionHash: string;
+};
+export declare function startClaudeSubscriptionOAuth(deps: ApiRouteDeps, scope: ClaudeOAuthScope, input?: {
+    scope?: "workspace" | "user" | undefined;
+    reconnectAccountId?: string | undefined;
+}): 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): 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,44 @@
+import { type Settings } from "@opengeni/config";
+import { type ClaudeUsageScope, type Database } from "@opengeni/db";
+export declare function requestClaudeUsage(token: string, fetchImpl?: typeof fetch): Promise<{
+    status: "available" | "reconnect" | "scope_required" | "unavailable";
+    observation: import("@opengeni/config").ClaudeUsageObservation | null;
+    checkedAt: string;
+}>;
+/** No inference calls. Inference-only setup tokens retain their response-header cache. */
+export declare function refreshClaudeSubscriptionUsage(db: Database, settings: Settings, scope: ClaudeUsageScope, fetchImpl?: typeof fetch): Promise<{
+    connected: boolean;
+    credentialVersion: number | null;
+    windows: {
+        id: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet";
+        usedPercent: number | null;
+        resetsAt: string | null;
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    }[];
+    observedAt: string | null;
+    source: "provider" | "response_headers" | null;
+    refreshStatus: "available" | "not_checked" | "reconnect" | "scope_required" | "unavailable";
+    refreshCheckedAt: string | null;
+    requestStatus?: {
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        resetsAt: string | null;
+        representativeClaim: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet" | null;
+        overageStatus: "allowed" | "allowed_warning" | "rejected" | null;
+        overageResetsAt: string | null;
+        upstreamModelId: string | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    } | null | undefined;
+    requestRestrictions?: {
+        status: "allowed" | "allowed_warning" | "rejected" | null;
+        resetsAt: string | null;
+        representativeClaim: "five_hour" | "overage" | "seven_day" | "seven_day_opus" | "seven_day_overage_included" | "seven_day_sonnet" | null;
+        overageStatus: "allowed" | "allowed_warning" | "rejected" | null;
+        overageResetsAt: string | null;
+        upstreamModelId: string | null;
+        observedAt: string;
+        source?: "provider" | "response_headers" | undefined;
+    }[] | undefined;
+}>;

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,5 +1,22 @@
 import { type AccessGrant, type AttemptToolCatalog, type CodemodeCallSubmission as CodemodeCallSubmissionValue, type CodemodeOperation } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { type SessionTurnForExecution } from "@opengeni/db";
+import { type Settings } 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"];
+/**
+ * Proxy permissions = the session's effective first-party permissions, cut
+ * down to what its exact model-visible tool selection could actually
+ * exercise (plus workspace:read for the context routes), under the fixed
+ * ceiling above. A session whose selection has no session_* tool therefore
+ * 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[];
+/** 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, resolveProxySettings?: (session: Session) => Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">): Promise<Request>;
 export type CodemodeGrantAuthority = {
     accountId: string;
     workspaceId: string;
@@ -9,15 +26,29 @@ export type CodemodeGrantAuthority = {
     executionGeneration: number;
     subjectId: string;
 };
+export type CodemodeAuthorityFailureReason = "invalid_grant" | "inactive_attempt" | "catalog_mismatch";
 export declare class CodemodeAuthorityError extends Error {
-    readonly code = "codemode_authority_invalid";
+    readonly reason: CodemodeAuthorityFailureReason;
+    readonly code: `codemode_${CodemodeAuthorityFailureReason}`;
+    constructor(reason: CodemodeAuthorityFailureReason);
+}
+export declare class CodemodeCatalogNotReadyError extends Error {
+    readonly code = "codemode_catalog_not_ready";
+    constructor();
+}
+export declare class CodemodeCatalogStaleError extends Error {
+    readonly code = "codemode_catalog_stale";
     constructor();
 }
 export declare function codemodeAuthorityForGrant(grant: AccessGrant): CodemodeGrantAuthority | null;
 export declare function isCodemodeGrant(grant: AccessGrant): boolean;
+export declare function requireMatchingCodemodeCatalog(authority: CodemodeGrantAuthority, catalog: AttemptToolCatalog | null): AttemptToolCatalog;
 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 codemodeOperationNeedsDispatch(operation: CodemodeOperation): boolean;
 export declare function readCodemodeOperation(deps: ApiRouteDeps, grant: AccessGrant, operationId: string): Promise<CodemodeOperation | null>;
+export declare function refreshAdmittedCodemodeOperation(admitted: CodemodeOperation, read: () => Promise<CodemodeOperation | null>): Promise<CodemodeOperation>;

package/dist/company-brain-okf.d.ts

@@ -0,0 +1,24 @@
+import { type CompanyBrainGuidanceEntry, type CompanyBrainOkfPackage as CompanyBrainOkfPackageType, type CompanyProfileListResponse, type WorkspaceInstructionPolicyListResponse, type WorkspaceInstructionPolicyRevision, type WorkspaceStateKnowledge } from "@opengeni/contracts";
+import type { CompanyBrainPreferenceGuidancePage } from "@opengeni/db";
+export declare function boundCompanyBrainGuidanceEntries(entries: CompanyBrainGuidanceEntry[]): {
+    entries: CompanyBrainGuidanceEntry[];
+    itemCountTruncated: boolean;
+    contentBytesTruncated: boolean;
+};
+export declare function createCompanyBrainOkfPackage(input: {
+    workspaceId: string;
+    generatedAt: string;
+    companyProfile: CompanyProfileListResponse;
+    instructionPolicies: WorkspaceInstructionPolicyListResponse;
+    activeInstructionPolicyRevisions: WorkspaceInstructionPolicyRevision[];
+    activatedInstructionPolicyRevisionIds: string[];
+    preferences: CompanyBrainPreferenceGuidancePage;
+    knowledge: WorkspaceStateKnowledge;
+}): CompanyBrainOkfPackageType;
+/**
+ * JSON is a strict subset of YAML 1.2. Keeping the payload in one fenced YAML
+ * block gives humans a readable Markdown package while making arbitrary
+ * guidance Markdown structurally inert and exactly round-trippable.
+ */
+export declare function serializeCompanyBrainOkf(value: CompanyBrainOkfPackageType): string;
+export declare function parseCompanyBrainOkf(markdown: string): CompanyBrainOkfPackageType;

package/dist/connected-machine-computer-access.d.ts

@@ -0,0 +1,11 @@
+export type ConnectedMachineComputerAccessState = {
+    hasDisplay: boolean;
+    desktopUnavailableReason: string | null;
+    allowScreenControl: boolean;
+};
+export type ConnectedMachineComputerAccessError = {
+    status: 403 | 409;
+    message: string;
+};
+/** Keep passive desktop viewing separate from input consent. */
+export declare function connectedMachineComputerAccessError(state: ConnectedMachineComputerAccessState, requiresControl: boolean): ConnectedMachineComputerAccessError | null;

package/dist/connection-ownership.d.ts

@@ -0,0 +1,54 @@
+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. */
+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. */
+export declare function personalOnlyConnectionPrincipalMessage(label: string): string;
+/**
+ * Rejects a non-human principal before a personal Connection is created.
+ * `label` names a personal-only connector, whose message must not suggest a
+ * workspace-owned alternative that its provider profile forbids.
+ *
+ * This shares that helper's core caller-integrity checks, then additionally
+ * 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 (422).
+ */
+export declare function assertPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorization, label?: string): void;
+/** The same fence expressed for a flow that resolves ownership after admission. */
+export declare function assertConnectionOwnershipAllowedForPrincipal(ownership: ConnectionOwnership, personalOwnershipAllowed: boolean): void;
+/**
+ * The claim a start path mints into its HMAC-signed OAuth state when it has
+ * verified the live principal may own a personal Connection.
+ *
+ * An OAuth callback carries signed state, not a live principal, so it cannot
+ * re-evaluate `principalKind`. Requiring this claim makes the callback enforce
+ * exactly what the start path decided with the full signal, instead of guessing
+ * from the subject's shape. A state minted before this claim existed simply
+ * lacks it and fails closed for personal ownership - which is precisely the
+ * in-flight rolling-deploy window these fences exist to close.
+ */
+export declare const PERSONAL_OWNER_VERIFIED_STATE_CLAIM: "personalOwnerVerified";
+/** True only for an explicit boolean `true` claim; absent or malformed fails closed. */
+export declare function personalOwnerVerifiedInState(payload: Record<string, unknown>): boolean;
+/**
+ * Callback-side fence for every path that persists a personal owner. Requires
+ * both the signed start-time verification and a non-machine subject.
+ */
+export declare function personalOwnerStateAccepted(state: {
+    ownership: ConnectionOwnership;
+    subjectId: string;
+    personalOwnerVerified: boolean;
+}): boolean;

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

@@ -1,3 +1,21 @@
+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
+ * must stay on an exec-capable in-box curl session. OSEP-0011 signed URIs are
+ * Authorization-preserving and host-fetch like a native tunnel, but they are
+ * not durable cache keys. */
+export declare function controllerCacheAllowsHostFetch(url: string): boolean;
+export declare function isOpenSandboxSignedControllerUrl(url: string): boolean;
+/** Signed Channel B URLs expire. Do not treat a lease-cached signed URI as an
+ * infinite controller endpoint. Unsigned native `/` tunnels stay cacheable. */
+export declare function controllerCachedUrlIsUsable(url: string, nowMs?: number): boolean;
+export declare function shouldPersistControllerDataPlaneUrl(input: {
+    backend: string | null | undefined;
+    signedEndpoints: boolean;
+    url: string;
+}): boolean;
 /** Prefer a lease-fenced controller endpoint for the idempotent create path.
  * Only a transport-class failure invalidates the cache and provisions once;
  * semantic failures belong to the caller and must never be replayed. */
@@ -10,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/editable-artifact-office-import.d.ts

@@ -1,6 +1,6 @@
 import { prepareArtifactOfficeImport } from "@opengeni/artifact-tool/office-import";
-import { type EditableArtifactOfficeImportPort } from "@opengeni/core/editable-artifacts";
-import { getFile } from "@opengeni/db";
+import { type EditableArtifactActor, type EditableArtifactOfficeImportPort, type EditableArtifactScope } from "@opengeni/core/editable-artifacts";
+import { getFilesForSubject } from "@opengeni/db";
 import { type BoundedImmutableObjectWritePort, type ObjectStorage } from "@opengeni/storage";
 import type { Database } from "@opengeni/db";
 import type { VerifiedNativeArtifactRuntimeBinding } from "./editable-artifact-native-kernel.js";
@@ -10,13 +10,16 @@ export type EditableArtifactOfficeImportAdapterDependencies = Readonly<{
     runtime: VerifiedNativeArtifactRuntimeBinding;
     sourceObjects: BoundedImmutableObjectWritePort;
     snapshotObjects: BoundedImmutableObjectWritePort;
-    readFile?: typeof getFile;
+    readFiles?: typeof getFilesForSubject;
+    resolveFileAuthoritySubjectId?: typeof editableArtifactFileAuthoritySubjectId;
     prepareOffice?: typeof prepareArtifactOfficeImport;
 }>;
 /** Trusted import boundary from one ready workspace file into native sequence-zero state. */
 export declare class EditableArtifactOfficeImportAdapter implements EditableArtifactOfficeImportPort {
     private readonly dependencies;
-    private readonly readFile;
+    private readonly readFiles;
+    private readonly resolveFileAuthoritySubjectId;
     constructor(dependencies: EditableArtifactOfficeImportAdapterDependencies);
     prepare(input: Parameters<EditableArtifactOfficeImportPort["prepare"]>[0]): ReturnType<EditableArtifactOfficeImportPort["prepare"]>;
 }
+export declare function editableArtifactFileAuthoritySubjectId(db: Database, scope: EditableArtifactScope, actor: EditableArtifactActor): Promise<string | null>;

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,20 +1,10 @@
-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-v1";
+export declare const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v2";
 export declare const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES: number;
-export type EditableArtifactWebSocketLike = Readonly<{
-    data: EditableArtifactWebSocketConnection;
-    send(data: Uint8Array, compress?: boolean): number;
-    close(code?: number, reason?: string): void;
-    readonly bufferedAmount?: number;
-    getBufferedAmount?(): number;
-}>;
-export type EditableArtifactWebSocketUpgradeServer = Readonly<{
-    upgrade(request: Request, options: Readonly<{
-        data: EditableArtifactWebSocketConnection;
-        headers: HeadersInit;
-    }>): boolean;
-}>;
+export type EditableArtifactWebSocketLike = ApiWebSocketLike;
+export type EditableArtifactWebSocketUpgradeServer = ApiWebSocketUpgradeServer;
 export type EditableArtifactWebSocketHandler = Readonly<{
     open(socket: EditableArtifactWebSocketLike): void;
     message(socket: EditableArtifactWebSocketLike, message: string | Uint8Array | ArrayBuffer): void;
@@ -22,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 {
+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/editable-artifact-workspace-files.d.ts

@@ -1,6 +1,6 @@
 import { type EditableArtifactAgentWorkspaceFilePort, type EditableArtifactDurableExportService } from "@opengeni/core/editable-artifacts";
 import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
-import type { ObjectStorage } from "@opengeni/storage";
+import { type ObjectStorage } from "@opengeni/storage";
 export type EditableArtifactWorkspaceFileAdapterDependencies = Readonly<{
     db: Database;
     objectStorage: ObjectStorage;

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

@@ -0,0 +1,25 @@
+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"> & Partial<Pick<Observability, "recordFailureDiagnostic">>;
+type ApiFatalProcess = {
+    on: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
+    off: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
+    exit: (code: number) => void;
+};
+export type ApiFatalProcessBoundaryOptions = {
+    process?: ApiFatalProcess;
+    observability?: ApiFatalObservability;
+    flushTimeoutMs?: number;
+    correlationId?: () => string;
+    fallbackLog?: (message: string) => void;
+};
+export type ApiFatalProcessBoundary = {
+    attachObservability: (observability: ApiFatalObservability) => void;
+    markRunning: () => void;
+    reportStartupFailure: (reason: unknown) => Promise<void>;
+    dispose: () => void;
+};
+export declare function installApiFatalProcessBoundary(options?: ApiFatalProcessBoundaryOptions): ApiFatalProcessBoundary;
+export {};

package/dist/github-access.d.ts

@@ -1,6 +1,22 @@
-import type { GitHubBindingStatus, GitHubInstallationBinding, GitHubRepository } from "@opengeni/contracts";
-import { listGitHubInstallationAccessForWorkspace } from "@opengeni/db";
+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";
+export type GitHubRepositoryBranchAuthorityErrorCode = "changed" | "not_authorized";
+export declare class GitHubRepositoryBranchAuthorityError extends Error {
+    readonly code: GitHubRepositoryBranchAuthorityErrorCode;
+    constructor(code: GitHubRepositoryBranchAuthorityErrorCode);
+}
+export type WorkspaceGitHubRepositoryBranchServices = {
+    listInstallationAccess: typeof listGitHubInstallationAccessForWorkspace;
+    areRepositoriesAllowed: typeof areGitHubRepositoriesAllowedForWorkspace;
+    listProviderBranches: (deps: ApiRouteDeps, input: {
+        installationId: number;
+        repositoryId: number;
+        page: number;
+        limit: number;
+    }) => Promise<GitHubAppRepositoryBranchPage | null>;
+};
 export declare function listWorkspaceGitHubInstallationBindings(deps: ApiRouteDeps, workspaceId: string): Promise<GitHubInstallationBinding[]>;
 export declare function githubBindingStatus(configured: boolean, installations: GitHubInstallationBinding[]): GitHubBindingStatus;
 export type LiveGitHubInstallation = {
@@ -10,3 +26,16 @@ 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;
+    installationId: number;
+    repositoryId: number;
+    query: ListGitHubRepositoryBranchesQuery;
+}, services?: WorkspaceGitHubRepositoryBranchServices): Promise<GitHubRepositoryBranchesResponse>;

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

@@ -0,0 +1,24 @@
+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;
+/** Organization settings: reading needs account:read, changing needs account:admin. */
+export declare function organizationSettingsPermission(c: Context): Permission;
+/** Refuse an agent on a browser-only step (provider consent, cross-organization actions). */
+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,16 +1,42 @@
-import type { ErrorCode } from "@opengeni/contracts";
+import { type ErrorCode } from "@opengeni/contracts";
 import { HTTPException } from "hono/http-exception";
 type ApiHttpErrorOptions = {
     code: ErrorCode;
     message: string;
     retryable?: boolean;
+    outcomeUnknown?: boolean;
     details?: Record<string, unknown>;
 };
 /** A public, structured API failure whose message and details are safe for clients. */
 export declare class ApiHttpError extends HTTPException {
     readonly code: ErrorCode;
     readonly retryable: boolean | undefined;
+    readonly outcomeUnknown: boolean | undefined;
     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;
+/**
+ * A request-scoped session/workspace mutation could not enter the workspace
+ * control prefix within its bounded wait. The transaction rolled back before
+ * any write, so the outcome is known and the client may retry. `app.onError`
+ * applies this once for every route; Slack interactions keep the raw typed
+ * error so their retry classifier treats it as transient.
+ */
+export declare function workspaceControlBusyHttpError(error: unknown): 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/cors.d.ts

@@ -1 +1,18 @@
 export declare function allowedCorsOrigin(pattern: string, origin: string): boolean;
+export declare function validateInteractionRequestOrigin(value: string | undefined, input: {
+    corsAllowOriginRegex: string;
+    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 {};