@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/dist/codemode.d.ts

@@ -9,12 +9,19 @@ 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 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;

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-authority-owner.d.ts

@@ -0,0 +1,59 @@
+import type { AccessGrantAuthorization } from "@opengeni/core";
+import type { UserResourceAuthoritySummary } from "@opengeni/db";
+import { type IssueConnectionUseGrantRequest as IssueConnectionUseGrantRequestValue } from "@opengeni/contracts/connection-authority";
+/**
+ * Personal connection authority is available only to the exact authenticated
+ * human. API keys, delegated bearers, services, and agent attempts cannot name
+ * or substitute a personal owner.
+ */
+export declare function requireConnectionAuthorityOwner(access: AccessGrantAuthorization): string;
+/** Removes generic resource kind and refuses non-connection grant actions. */
+export declare function projectSelfConnectionAuthorities(page: {
+    authorities: UserResourceAuthoritySummary[];
+    nextCursor: string | null;
+}): {
+    scope: "user";
+    authorities: {
+        authorityId: string;
+        resourceId: string;
+        originWorkspaceId: string | null;
+        generation: number;
+        status: "active" | "retained" | "revoked";
+        grants: {
+            grantId: string;
+            targetWorkspaceId: string;
+            targetSessionId: string | null;
+            mode: "always" | "once" | "session";
+            context: "user_private" | "workspace_shared";
+            authorityEpoch: number | null;
+            generation: number;
+            status: "active" | "consumed" | "expired" | "revoked";
+            expiresAt: string | null;
+            delegation: {
+                authorityId: string;
+                grantId: string;
+                organizationId: string;
+                workspaceId: string;
+                sessionId: string | null;
+                action: string;
+                mode: "always" | "once" | "session";
+                context: "user_private" | "workspace_shared";
+                authorityEpoch: number | null;
+                authorityGeneration: number;
+                grantGeneration: number;
+                resourceVersionId?: string | null | undefined;
+            };
+            action: "connection.use";
+        }[];
+    }[];
+    nextCursor: string | null;
+};
+/** The API owns the action; callers supply neither action nor owner identity. */
+export declare function connectionUseGrantLifecycleInput(input: unknown): {
+    action: "connection.use";
+    mode: IssueConnectionUseGrantRequestValue["mode"];
+    context: IssueConnectionUseGrantRequestValue["context"];
+    sessionId: string | null;
+    expectedAuthorityEpoch: number | null;
+    workspaceSharedAcknowledged: boolean;
+};

package/dist/connection-ownership.d.ts

@@ -0,0 +1,47 @@
+import type { ConnectionOwnership } from "@opengeni/contracts";
+import type { AccessGrantAuthorization } from "@opengeni/core";
+/** 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, alongside `assertOwnershipAllowed`'s
+ * existing 422 convention.
+ */
+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,19 @@
+/** 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. */

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 { 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;
@@ -28,7 +18,7 @@ export declare class EditableArtifactWebSocketTransport {
     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 socket;
     private session;

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/http/api-error.d.ts

@@ -4,13 +4,23 @@ 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);
 }
+/**
+ * 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;
 export {};

package/dist/http/cors.d.ts

@@ -1 +1,6 @@
 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;

package/dist/http/interaction-control-error.d.ts

@@ -0,0 +1,13 @@
+import { ErrorCode as AgentErrorCode } from "@opengeni/agent-proto";
+import { type InteractionControlFailureCode } from "@opengeni/contracts";
+import { ApiHttpError } from "./api-error.js";
+export type InteractionControlSurface = "browser" | "computer";
+/**
+ * Projects an internal connected-machine control fault into the public API
+ * vocabulary. This is deliberately an allowlist: the agent's free-form message
+ * and detail map may contain paths, process output, or provider diagnostics and
+ * never cross this boundary. The exact inner request id is safe opaque
+ * correlation and links API logs back to the machine operation.
+ */
+export declare function interactionControlApiError(error: unknown, surface: InteractionControlSurface): ApiHttpError | null;
+export declare function publicControlFailureCode(code: AgentErrorCode): InteractionControlFailureCode;

package/dist/http/sse.d.ts

@@ -81,9 +81,8 @@ export type SseDeliveryOptions = {
     heartbeatIntervalMs?: number;
     observability?: Observability | undefined;
     onObservation?: ((observation: SseDeliveryBoundObservation) => void) | undefined;
-};
-export type SessionSseDeliveryOptions = SseDeliveryOptions & {
-    /** Host ACL re-check, run even while the event stream is otherwise idle. */
+    /** Current ACL re-check, run even while the event stream is idle. */
     reauthorize?: (() => Promise<void>) | undefined;
     reauthorizeAfterMs?: number | undefined;
 };
+export type SessionSseDeliveryOptions = SseDeliveryOptions;

package/dist/index.d.ts

@@ -4,14 +4,17 @@ import { type Database } from "@opengeni/db";
 import { ScheduleOverlapPolicy } from "@temporalio/client";
 import type { ScheduleSpec } from "@temporalio/client";
 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<EditableArtifactWebSocketConnection>;
+    server: Bun.Server<Readonly<{
+        attach(socket: import("./api-websocket.js").ApiWebSocketLike): void;
+        receive(message: string | Uint8Array | ArrayBuffer): void;
+        transportClosed(): void;
+    }>>;
     close: () => Promise<void>;
 }>;
 export declare function temporalOverlapPolicy(policy: ScheduledTaskOverlapPolicy): ScheduleOverlapPolicy;