@opengeni/api-router 0.23.1 → 0.30.0

package/dist/codemode.d.ts

@@ -0,0 +1,23 @@
+import { type AccessGrant, type AttemptToolCatalog, type CodemodeCallSubmission as CodemodeCallSubmissionValue, type CodemodeOperation } from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+export type CodemodeGrantAuthority = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+    subjectId: string;
+};
+export declare class CodemodeAuthorityError extends Error {
+    readonly code = "codemode_authority_invalid";
+    constructor();
+}
+export declare function codemodeAuthorityForGrant(grant: AccessGrant): CodemodeGrantAuthority | null;
+export declare function isCodemodeGrant(grant: AccessGrant): boolean;
+export declare function requireActiveCodemodeCatalog(deps: ApiRouteDeps, grant: AccessGrant): Promise<{
+    authority: CodemodeGrantAuthority;
+    catalog: AttemptToolCatalog;
+}>;
+export declare function submitAndDispatchCodemodeCall(deps: ApiRouteDeps, grant: AccessGrant, rawRequest: unknown): Promise<CodemodeCallSubmissionValue>;
+export declare function readCodemodeOperation(deps: ApiRouteDeps, grant: AccessGrant, operationId: string): Promise<CodemodeOperation | null>;

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

@@ -0,0 +1,12 @@
+/** 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. */
+export declare function withCachedController<C, T>(options: {
+    cachedUrl: string | null;
+    createCachedClient: (url: string) => C;
+    prepareCachedClient?: (client: C) => Promise<void>;
+    invalidateCachedUrl: () => Promise<unknown>;
+    provisionClient: () => Promise<C>;
+    use: (client: C) => Promise<T>;
+}): Promise<T>;
+export declare function isRetryableControllerTransport(error: unknown): boolean;

package/dist/editable-artifact-live-hints.d.ts

@@ -0,0 +1,11 @@
+import { type EditableArtifactLiveHintPort } from "@opengeni/core";
+import type { EventBus } from "@opengeni/events";
+/**
+ * Uses the API's existing resilient NATS connection. Hints carry no operation
+ * bytes; every callback causes a durable DB head read and contiguous gap-fill.
+ */
+export declare class EventBusEditableArtifactLiveHints implements EditableArtifactLiveHintPort {
+    private readonly bus;
+    constructor(bus: Pick<EventBus, "getOpStreamConnection">);
+    subscribe(input: Parameters<EditableArtifactLiveHintPort["subscribe"]>[0]): Promise<() => void>;
+}

package/dist/editable-artifact-native-kernel.d.ts

@@ -0,0 +1,37 @@
+import type { ArtifactKernelRuntime } from "@opengeni/artifact-tool/runtime";
+import { type ConfiguredArtifactRuntimeLocation } from "@opengeni/artifact-tool/runtime/development";
+import { type ApplyAuthoritativeEditableArtifactKernelRequest, type ApplyAuthoritativeEditableArtifactKernelResult, type AuthoritativeEditableArtifactCompactionKernelPort, type AuthoritativeEditableArtifactCompactionKernelResult, type AuthoritativeEditableArtifactGenesisKernelPort, type AuthoritativeEditableArtifactGenesisKernelResult, type AuthoritativeEditableArtifactKernelPort, type EditableArtifactAgentInspectionKernelPort, type EditableArtifactKernelState, type IsolatedEditableArtifactSnapshotKernelPort, type IsolatedEditableArtifactSnapshotKernelResult } from "@opengeni/core";
+import type { BoundedObjectReadPort } from "@opengeni/storage";
+type RuntimeFacadeModule = Readonly<{
+    getConfiguredArtifactRuntime?: () => unknown;
+}> & Readonly<Record<string, unknown>>;
+export type VerifiedNativeArtifactRuntimeBinding = Readonly<{
+    runtime: ArtifactKernelRuntime;
+    location: ConfiguredArtifactRuntimeLocation;
+    facade: RuntimeFacadeModule;
+}>;
+/** Loads only the manifest-pinned, byte-verified native runtime. */
+export declare function loadVerifiedNativeArtifactRuntime(): Promise<ArtifactKernelRuntime>;
+/** Same verified load plus the pinned package identity used by export profiles. */
+export declare function loadVerifiedNativeArtifactRuntimeBinding(): Promise<VerifiedNativeArtifactRuntimeBinding>;
+/** Exact native authority shared by mutation, genesis, and snapshot verification. */
+export declare class NativeEditableArtifactKernelAdapter implements AuthoritativeEditableArtifactKernelPort, AuthoritativeEditableArtifactGenesisKernelPort, AuthoritativeEditableArtifactCompactionKernelPort, IsolatedEditableArtifactSnapshotKernelPort, EditableArtifactAgentInspectionKernelPort {
+    readonly runtime: ArtifactKernelRuntime;
+    private readonly objects;
+    constructor(runtime: ArtifactKernelRuntime, objects: BoundedObjectReadPort);
+    applyTransaction(request: ApplyAuthoritativeEditableArtifactKernelRequest): Promise<ApplyAuthoritativeEditableArtifactKernelResult>;
+    query(input: Parameters<EditableArtifactAgentInspectionKernelPort["query"]>[0]): ReturnType<EditableArtifactAgentInspectionKernelPort["query"]>;
+    private openCurrentState;
+    createCanonicalEmptySnapshot(input: {
+        scope: Parameters<AuthoritativeEditableArtifactGenesisKernelPort["createCanonicalEmptySnapshot"]>[0]["scope"];
+        artifactId: Parameters<AuthoritativeEditableArtifactGenesisKernelPort["createCanonicalEmptySnapshot"]>[0]["artifactId"];
+        modality: Parameters<AuthoritativeEditableArtifactGenesisKernelPort["createCanonicalEmptySnapshot"]>[0]["modality"];
+        signal?: AbortSignal;
+    }): Promise<AuthoritativeEditableArtifactGenesisKernelResult>;
+    createCanonicalSnapshot(input: {
+        state: EditableArtifactKernelState;
+        signal?: AbortSignal;
+    }): Promise<AuthoritativeEditableArtifactCompactionKernelResult>;
+    verifyAndReconstruct(input: Parameters<IsolatedEditableArtifactSnapshotKernelPort["verifyAndReconstruct"]>[0]): Promise<IsolatedEditableArtifactSnapshotKernelResult>;
+}
+export {};

package/dist/editable-artifact-office-import.d.ts

@@ -0,0 +1,22 @@
+import { prepareArtifactOfficeImport } from "@opengeni/artifact-tool/office-import";
+import { type EditableArtifactOfficeImportPort } from "@opengeni/core/editable-artifacts";
+import { getFile } 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";
+export type EditableArtifactOfficeImportAdapterDependencies = Readonly<{
+    db: Database;
+    objectStorage: ObjectStorage;
+    runtime: VerifiedNativeArtifactRuntimeBinding;
+    sourceObjects: BoundedImmutableObjectWritePort;
+    snapshotObjects: BoundedImmutableObjectWritePort;
+    readFile?: typeof getFile;
+    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;
+    constructor(dependencies: EditableArtifactOfficeImportAdapterDependencies);
+    prepare(input: Parameters<EditableArtifactOfficeImportPort["prepare"]>[0]): ReturnType<EditableArtifactOfficeImportPort["prepare"]>;
+}

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

@@ -0,0 +1,29 @@
+import { EditableArtifactDurableExportService, EditableArtifactAgentApplication, type EditableArtifactAuthorizationDecision, type EditableArtifactAuthorizationPort, type EditableArtifactAuthorizationRequest } from "@opengeni/core/editable-artifacts";
+import { type EditableArtifactApplicationPort } from "@opengeni/core/editable-artifact-live";
+import { type Database } from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import { type ObjectStorage } from "@opengeni/storage";
+import { EditableArtifactOfficeImportAdapter } from "./editable-artifact-office-import.js";
+export type StandaloneEditableArtifactApplication = Readonly<{
+    application: EditableArtifactApplicationPort;
+    durableExports: EditableArtifactDurableExportService;
+    agent: EditableArtifactAgentApplication;
+    officeImports: EditableArtifactOfficeImportAdapter;
+    kernelVersion: string;
+    close(): void;
+}>;
+/**
+ * Standalone production composition. Every authority is durable: PostgreSQL
+ * owns admission/authorization/history, object storage owns immutable model
+ * bytes, and NATS carries wake-up hints only.
+ */
+export declare function createStandaloneEditableArtifactApplication(input: {
+    db: Database;
+    bus: EventBus;
+    objectStorage: ObjectStorage;
+}): Promise<StandaloneEditableArtifactApplication>;
+export declare class PostgresEditableArtifactAuthorization implements EditableArtifactAuthorizationPort {
+    private readonly db;
+    constructor(db: Database);
+    authorize(request: EditableArtifactAuthorizationRequest): Promise<EditableArtifactAuthorizationDecision>;
+}

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

@@ -0,0 +1,49 @@
+import { type EditableArtifactApplicationPort, type EditableArtifactLiveClose, type EditableArtifactLiveServerFrame, type EditableArtifactLiveSinkPort } from "@opengeni/core";
+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_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 EditableArtifactWebSocketHandler = Readonly<{
+    open(socket: EditableArtifactWebSocketLike): void;
+    message(socket: EditableArtifactWebSocketLike, message: string | Uint8Array | ArrayBuffer): void;
+    close(socket: EditableArtifactWebSocketLike): void;
+}>;
+export declare class EditableArtifactWebSocketTransport {
+    private readonly application;
+    readonly websocket: EditableArtifactWebSocketHandler;
+    constructor(application: EditableArtifactApplicationPort | undefined);
+    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 {
+    private readonly application;
+    private socket;
+    private session;
+    private work;
+    private queuedMessages;
+    private queuedBytes;
+    private terminal;
+    constructor(application: EditableArtifactApplicationPort);
+    attach(socket: EditableArtifactWebSocketLike): void;
+    receive(message: string | Uint8Array | ArrayBuffer): void;
+    send(frame: EditableArtifactLiveServerFrame): Promise<void>;
+    bufferedBytes(): number;
+    close(close: EditableArtifactLiveClose): void;
+    transportClosed(): void;
+    private process;
+    private handleFailure;
+    private fail;
+}

package/dist/editable-artifact-workspace-files.d.ts

@@ -0,0 +1,23 @@
+import { type EditableArtifactAgentWorkspaceFilePort, type EditableArtifactDurableExportService } from "@opengeni/core/editable-artifacts";
+import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
+import type { ObjectStorage } from "@opengeni/storage";
+export type EditableArtifactWorkspaceFileAdapterDependencies = Readonly<{
+    db: Database;
+    objectStorage: ObjectStorage;
+    durableExports: EditableArtifactDurableExportService;
+    now?: () => Date;
+    prepareFile?: typeof prepareGeneratedWorkspaceFile;
+    completeFile?: typeof completeFileUpload;
+}>;
+/**
+ * Promotes one immutable materialization into the normal workspace-file domain.
+ * The returned file ID is the only artifact export handle exposed to agents.
+ */
+export declare class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAgentWorkspaceFilePort {
+    private readonly dependencies;
+    private readonly now;
+    private readonly prepareFile;
+    private readonly completeFile;
+    constructor(dependencies: EditableArtifactWorkspaceFileAdapterDependencies);
+    ensureMaterializationFile(input: Parameters<EditableArtifactAgentWorkspaceFilePort["ensureMaterializationFile"]>[0]): ReturnType<EditableArtifactAgentWorkspaceFilePort["ensureMaterializationFile"]>;
+}

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

@@ -10,5 +10,11 @@ import type { GitHubSignedStatePayload } from "@opengeni/github";
 export declare const githubBrowserGrantMaxAgeSeconds: number;
 export declare function githubBrowserGrantClaims(settings: Pick<Settings, "productAccessMode">, grant: AccessGrant, nowSeconds?: number): Record<string, unknown>;
 export declare function continuedGitHubBrowserGrantClaims(payload: GitHubSignedStatePayload): Record<string, unknown>;
+/**
+ * GitHub may return only to the session that initiated setup. This rejects
+ * absolute/protocol-relative URLs and paths for another workspace before the
+ * value is signed into provider state.
+ */
+export declare function githubSessionReturnPath(value: string | undefined | null, workspaceId: string): string | null;
 export declare function githubBrowserGrantFromState(settings: Pick<Settings, "productAccessMode">, payload: GitHubSignedStatePayload, workspaceId: string, nowSeconds?: number): AccessGrant | null;
 export declare function githubBrowserBaseUrl(settings: Pick<Settings, "githubAppManifestBaseUrl" | "publicBaseUrl">, requestOrigin?: string | null): string;

package/dist/http/auth.d.ts

@@ -1,3 +1,3 @@
-import type { Settings } from "@opengeni/config";
+import { type Settings } from "@opengeni/config";
 import type { MiddlewareHandler } from "hono";
 export declare function requireAccessKey(settings: Settings): MiddlewareHandler;

package/dist/http/cors.d.ts

@@ -0,0 +1 @@
+export declare function allowedCorsOrigin(pattern: string, origin: string): boolean;

package/dist/http/sse.d.ts

@@ -1,4 +1,4 @@
-import type { SessionEvent } from "@opengeni/contracts";
+import { type SessionEvent } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
@@ -58,6 +58,23 @@ export declare function createLatestWinsDelivery<T extends {
 export declare function sseSessionStream(db: Database, bus: EventBus, workspaceId: string, sessionId: string, after: number, signal: AbortSignal, options?: SessionSseDeliveryOptions): Promise<Response>;
 export declare function replaySessionEvents(loadPage: (after: number, limit: number) => Promise<SessionEvent[]>, send: (event: SessionEvent) => Promise<void>, after: number, pageSize?: number): Promise<void>;
 export declare function sseWorkspaceControlStream(db: Database, bus: EventBus, workspaceId: string, after: number, signal: AbortSignal, options?: SseDeliveryOptions): Promise<Response>;
+export type WorkspaceInteractionSseOptions = SseDeliveryOptions & {
+    pollIntervalMs?: number | undefined;
+};
+/**
+ * One HTTP connection for the two workspace-wide invalidation domains used by
+ * every visible OpenGeni surface. Keeping these as separate HTTP/1 streams
+ * consumes all six per-origin browser connections with only two windows and
+ * starves ordinary mutations/terminal grants. The durable cursors remain
+ * independent; this function only multiplexes their already-bounded SSE frames.
+ */
+export declare function sseWorkspaceLiveStream(db: Database, bus: EventBus, accountId: string, workspaceId: string, controlAfter: number, interactionAfter: number, signal: AbortSignal, options?: WorkspaceInteractionSseOptions): Promise<Response>;
+/**
+ * Latest-wins interaction invalidation stream. The durable truth is one
+ * monotonic workspace row, not an ever-growing event log. Each poll reads only
+ * that row; reconnect immediately projects the newest revision after `after`.
+ */
+export declare function sseWorkspaceInteractionRevisionStream(db: Database, accountId: string, workspaceId: string, after: number, signal: AbortSignal, options?: WorkspaceInteractionSseOptions): Promise<Response>;
 export type SseDeliveryOptions = {
     maxQueuedBytes?: number;
     stallTimeoutMs?: number;

package/dist/index.d.ts

@@ -3,14 +3,15 @@ import type { ScheduledTaskOverlapPolicy, ScheduledTaskScheduleSpec } from "@ope
 import { type Database } from "@opengeni/db";
 import { ScheduleOverlapPolicy } from "@temporalio/client";
 import type { ScheduleSpec } from "@temporalio/client";
-import { type DocumentIndexClient, type SessionWorkflowClient } from "./app";
+import { type DocumentIndexClient, type SessionWorkflowClient } from "./app.js";
+import { type EditableArtifactWebSocketConnection } from "./editable-artifact-websocket.js";
 export declare function createTemporalWorkflowClient(settings: ReturnType<typeof getSettings>, db: Database): Promise<{
     client: SessionWorkflowClient;
     documentIndexer: DocumentIndexClient;
     close: () => Promise<void>;
 }>;
 export declare function startApi(): Promise<{
-    server: Bun.Server<undefined>;
+    server: Bun.Server<EditableArtifactWebSocketConnection>;
     close: () => Promise<void>;
 }>;
 export declare function temporalOverlapPolicy(policy: ScheduledTaskOverlapPolicy): ScheduleOverlapPolicy;