@opengeni/api-router 0.30.1 → 1.0.0

package/dist/mcp/session-wait.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `session_wait`: one blocking first-party MCP call that replaces the
+ * `sleep 55` plus three or four `session_events`/`session_get` probes an agent
+ * otherwise runs per loop while it waits for a child or peer session.
+ *
+ * The durable `session_events` table is the only authority. The NATS event bus
+ * is live fanout only, so every wake (bus, deadline, or the initial call) is
+ * followed by a database read and the returned rows are always the exact
+ * durable events, never the bus payload. Subscriptions are opened before the
+ * first read so an event committed between the read and the subscription
+ * cannot be missed.
+ *
+ * Timing facts: the built-in `opengeni` MCP server entry carries no
+ * `timeoutMs`, so the worker's MCP client uses the SDK default request timeout
+ * of 60 s and a longer call would surface as a `-32001` tool error. The wait is
+ * therefore capped at {@link SESSION_WAIT_MAX_SECONDS} both in the tool schema
+ * and inside {@link waitForSessionChanges}. The API's `Bun.serve`
+ * `idleTimeout` is 255 s, far above that cap.
+ *
+ * Cancellation: the API serves one transport per POST, so the worker's MCP
+ * `notifications/cancelled` never reaches this handler; instead the route binds
+ * the HTTP request's own abort to `transport.close()` (`request-abort.ts`),
+ * which aborts `extra.signal`. A worker that drops the call on Steer/Pause
+ * therefore ends the server-side wait promptly; the deadline bounds it anyway.
+ *
+ * The live bus is best-effort: a failed subscription degrades the wait to the
+ * durable pre-check plus the deadline re-check and is reported as
+ * `liveFanout: false` rather than failing the tool.
+ */
+import type { SessionEvent, SessionEventSemanticClass, SessionEventType } from "@opengeni/contracts";
+export declare const SESSION_WAIT_MAX_TARGETS = 16;
+export declare const SESSION_WAIT_MAX_SECONDS = 50;
+export declare const SESSION_WAIT_DEFAULT_SECONDS = 45;
+/** Newest-first durable rows read per target on every database check. */
+export declare const SESSION_WAIT_EVENTS_PER_TARGET = 20;
+/**
+ * The durable event types that matter to a waiter: turn lifecycle, completed
+ * agent messages, blocking failures, goal facts, and session status/control
+ * changes. Raw deltas, tool receipts, sandbox/machine diagnostics, and PTY
+ * noise never wake a waiter; `session_events` remains the drill-down for them.
+ * The change mode further drops per-message completions: see
+ * {@link sessionWaitChangeEventMatches}.
+ */
+export declare const SESSION_WAIT_EVENT_TYPES: readonly ["turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.superseded", "turn.capacity_waiting", "agent.message.completed", "session.status.changed", "session.requiresAction", "session.humanInput.requested", "session.control.paused", "session.control.resumed", "session.wait.started", "session.wait.finished", "tool.auth_needed", "session.command.finished", "credential.auth_needed", "rig.setup.failed", "goal.set", "goal.updated", "goal.progress", "goal.rewrite.proposed", "goal.rewrite.rejected", "goal.completed", "goal.paused", "goal.resumed", "goal.cleared", "goal.continuation"];
+/**
+ * Settlement and blocking events that make a child result usable.
+ * Goal facts are deliberately absent: an agent can complete its durable goal
+ * before it emits the final assistant message and settles the turn. Completed
+ * agent messages are also absent because commentary messages use the same
+ * event type; an ordinary result-bearing `turn.completed` carries the
+ * authoritative final output.
+ */
+export declare const SESSION_WAIT_COMPLETION_EVENT_TYPES: readonly ["turn.completed", "turn.failed", "turn.cancelled", "turn.superseded", "turn.capacity_waiting", "session.requiresAction", "session.humanInput.requested", "session.control.paused", "tool.auth_needed", "credential.auth_needed", "rig.setup.failed", "goal.paused"];
+/**
+ * A completed turn is result-bearing only when it carries the ordinary final
+ * output. Segment-limit and maintenance turns settle one execution segment
+ * while the session still has work to do, so they must not release a parent.
+ */
+export declare function sessionWaitCompletionEventMatches(event: SessionEvent): boolean;
+/**
+ * `waitFor=change` wakes on settled changes. A per-message assistant completion
+ * (commentary, or a final message the turn is about to settle) is not one: the
+ * `turn.completed` that follows carries the answer. Waking on every progress
+ * note would only buy the waiter another poll. The phase-less, id-less
+ * completion older workers publish with `turn.completed` still matches.
+ * Readers pair this with `excludeStreamedAssistantMessages` in SQL.
+ */
+export declare function sessionWaitChangeEventMatches(event: SessionEvent): boolean;
+/** The self-session event that announces a newly pending machine input. */
+export declare const SESSION_WAIT_OWN_PENDING_EVENT_TYPE = "system.update.pending";
+/**
+ * Whether a pending own machine input of this kind ends the wait. Every
+ * pre-existing kind and `child_requires_action` are `immediate`; deferred
+ * child notices are reported but do not end the wait by themselves.
+ */
+export declare function ownPendingKindWakes(kind: string): boolean;
+/**
+ * Re-derive the caller's own pending-input facts after the returned content
+ * consumed some of that input, keeping the same byte bound.
+ */
+export declare function withOwnPendingUpdateKinds(result: SessionWaitResult, kinds: readonly string[]): SessionWaitResult;
+export declare function sessionWaitSemanticClass(type: SessionEventType): SessionEventSemanticClass;
+export type SessionWaitTarget = {
+    sessionId: string;
+    afterSequence: number;
+};
+export type SessionWaitEventSummary = {
+    /** True only when every semantic result field survived all projections. */
+    contentComplete?: boolean;
+    id: string;
+    sequence: number;
+    type: SessionEventType;
+    occurredAt: string;
+    turnId: string | null;
+    turnGeneration: number | null;
+    status: string;
+    text: string | null;
+    failure: {
+        error: string | null;
+        code: string | null;
+        retryable: boolean | null;
+        recovery: string | null;
+    } | null;
+    result?: unknown;
+};
+export type SessionWaitTargetResult = {
+    sessionId: string;
+    afterSequence: number;
+    /** Cursor for the next `session_wait`/`session_events after=` call. */
+    latestSequence: number;
+    hasMore: boolean;
+    events: SessionWaitEventSummary[];
+};
+export type SessionWaitResult = {
+    changed: SessionWaitTargetResult[];
+    ownPendingUpdates: number;
+    ownPendingUpdateKinds: string[];
+    /**
+     * Pending own inputs whose kind wakes the session by itself (every
+     * pre-existing kind plus `child_requires_action`). Only these end the wait;
+     * `deferred` child notices (resolution, pause, capacity wait, progress) are
+     * reported but keep the wait on the targets.
+     */
+    ownPendingImmediateUpdates: number;
+    ownPendingDeferredUpdateKinds: string[];
+    waitedMs: number;
+    timedOut: boolean;
+    aborted: boolean;
+    /** False when at least one live-fanout subscription failed; the wait then relied on the deadline re-check. */
+    liveFanout: boolean;
+    truncated: boolean;
+    bytes: number;
+    maxBytes: number;
+};
+export type SessionWaitTargetRead = {
+    events: readonly SessionEvent[];
+    hasMore: boolean;
+};
+export type SessionWaitSource = {
+    /** Durable forward read of matching events strictly after the target cursor. */
+    readTargetEvents: (target: SessionWaitTarget) => Promise<SessionWaitTargetRead>;
+    /** Kinds of the caller's own pending machine inputs; null disables self tracking. */
+    readOwnPendingUpdateKinds: (() => Promise<readonly string[]>) | null;
+    /** Live fanout subscription for one session; the returned function unsubscribes. */
+    subscribe: (sessionId: string, onEvents: (events: SessionEvent[]) => void | Promise<void>) => Promise<() => void>;
+    /**
+     * Re-run target authorization for the sessions about to be returned after a
+     * wait (parity with SSE re-authorization). Throws to refuse the result.
+     */
+    reauthorizeTargets?: ((sessionIds: readonly string[]) => Promise<void>) | undefined;
+};
+export type SessionWaitInput = {
+    targets: readonly SessionWaitTarget[];
+    ownSessionId: string | null;
+    maxWaitMs: number;
+    /** Target events that end the wait. Defaults to the ordinary activity set. */
+    targetEventTypes?: readonly SessionEventType[] | undefined;
+    /** Optional payload-aware refinement applied after the event-type filter. */
+    targetEventMatches?: ((event: SessionEvent) => boolean) | undefined;
+    source: SessionWaitSource;
+    signal?: AbortSignal | undefined;
+    now?: (() => number) | undefined;
+    maxBytes?: number | undefined;
+};
+export declare function waitForSessionChanges(input: SessionWaitInput): Promise<SessionWaitResult>;
+/** One bounded, result-bearing summary of a durable event for a waiter. */
+export declare function summarizeSessionWaitEvent(event: SessionEvent, textChars?: number): SessionWaitEventSummary;
+/**
+ * Keep the whole model-visible result at or below the `session_events` MCP
+ * envelope. Text is tightened first; only then are newest rows dropped from the
+ * largest target, which keeps each target's `latestSequence` an exact cursor
+ * for the rows actually delivered and marks the remainder as `hasMore`.
+ */
+export declare function boundSessionWaitResult(input: Omit<SessionWaitResult, "truncated" | "bytes" | "maxBytes">, maxBytes?: number): SessionWaitResult;

package/dist/mcp-oauth.d.ts

@@ -0,0 +1,52 @@
+import { OrganizationAccessPolicy, type AccessGrant, type ToolGatewayCatalog, type ToolGatewayIdentity } from "@opengeni/contracts";
+import { type McpOAuthAccess } from "@opengeni/db";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { Hono, type Context } from "hono";
+/** One organization MCP server for everyone; the sign-in chooses the organization. */
+export declare const ORGANIZATION_MCP_PATH = "/v1/mcp";
+export type McpOAuthResource = {
+    resource: string;
+    /** Null for the organization server. */
+    workspaceId: string | null;
+    kind: "all" | "docs" | "files" | "organization";
+};
+export type McpOAuthRouteAccess = {
+    grant: AccessGrant;
+    allowedToolIdentities: ToolGatewayIdentity[];
+};
+export declare function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void;
+export declare function resolveMcpOAuthRouteAccess(deps: ApiRouteDeps, request: Request, workspaceId: string): Promise<McpOAuthRouteAccess | null>;
+export declare function mcpOAuthBearerToken(request: Request): string | null;
+export declare function isMcpOAuthResourcePath(pathname: string): boolean;
+export declare function mcpOAuthConsentToolIdentities(catalog: ToolGatewayCatalog): ToolGatewayIdentity[];
+export declare function isMcpOAuthPublicProtocolPath(pathname: string): boolean;
+export declare function mcpOAuthAuthenticateHeader(deps: ApiRouteDeps, pathname: string): string;
+export declare function mcpOAuthRedirectUriCandidates(registered: string[], requested: string): string[];
+export declare function completeAuthorizationRedirect(c: Context, redirectTo: string): Response;
+export type McpOAuthConsentAccount = {
+    id: string;
+    name: string;
+};
+export type McpOAuthConsentWorkspace = {
+    id: string;
+    accountId: string;
+    name: string;
+    kind: "personal" | "shared";
+};
+export declare function renderMcpOAuthConsentPage(input: {
+    clientName: string;
+    requestToken: string;
+    accounts: McpOAuthConsentAccount[];
+    workspaces: McpOAuthConsentWorkspace[];
+    selectedWorkspaceId: string;
+}): string;
+export declare function renderMcpOAuthContinuePage(redirectTo: string): string;
+export declare function renderMcpOAuthExpiredPage(message: string): string;
+/**
+ * The organization connection behind an organization-server bearer, or null
+ * when the request carries no MCP OAuth token. Invalid, revoked, expired or
+ * workspace-bound tokens are refused.
+ */
+export declare function resolveOrganizationMcpOAuthAccess(deps: ApiRouteDeps, request: Request): Promise<(McpOAuthAccess & {
+    organizationAccess: OrganizationAccessPolicy;
+}) | null>;

package/dist/model-catalog.d.ts

@@ -1,23 +1,7 @@
-import { type ConfiguredModel, type Settings } from "@opengeni/config";
-import { ClientModel, type WorkspaceModelCatalogResponse as WorkspaceModelCatalogResponseType, type WorkspaceModelPolicyContract } from "@opengeni/contracts";
-export type ModelAvailabilityObservation = {
-    status: "available" | "degraded" | "unavailable";
-    reason: "not_entitled" | "provider_unhealthy" | null;
-    checkedAt: string;
-};
-export type ModelCredentialReadinessObservation = {
-    status: "ready";
-    checkedAt: string;
-} | {
-    status: "not_ready";
-    reason: "prerequisites_missing" | "needs_reauth";
-    checkedAt: string;
-} | {
-    status: "error";
-    reason: "resolver_error";
-    checkedAt: string;
-};
-export declare const MODEL_CREDENTIAL_READINESS_OBSERVATION_MAX_AGE_MS: number;
+import { type ConfiguredModel } from "@opengeni/config";
+import { ClientModel, type DefaultModelSelection, type WorkspaceModelCatalogResponse as WorkspaceModelCatalogResponseType } from "@opengeni/contracts";
+import { type WorkspaceModelSelection, type WorkspaceModelSelectionInput } from "@opengeni/core";
+export { MODEL_CREDENTIAL_READINESS_OBSERVATION_MAX_AGE_MS, type ModelAvailabilityObservation, type ModelCredentialReadinessObservation, } from "@opengeni/core";
 /** Static, client-safe definition projection. No provider secret is reachable. */
 export declare function projectClientModel(model: ConfiguredModel): ClientModel;
 /**
@@ -28,14 +12,10 @@ export declare function projectClientModel(model: ConfiguredModel): ClientModel;
  * successful typed resolver observation; credential health and provider health
  * are separate inputs and neither is fabricated.
  */
-export declare function buildWorkspaceModelCatalog(input: {
-    settings: Settings;
-    policy: WorkspaceModelPolicyContract | null;
-    codexSubscriptionActive: boolean;
-    xaiSubscriptionActive?: boolean;
-    workspaceGatewayConnectionActive?: boolean;
-    credentialReadinessObservations?: Readonly<Record<string, ModelCredentialReadinessObservation>> | undefined;
-    observations?: Readonly<Record<string, ModelAvailabilityObservation>> | undefined;
-    now?: Date | undefined;
-    credentialReadinessMaxAgeMs?: number | undefined;
-}): WorkspaceModelCatalogResponseType;
+export declare function buildWorkspaceModelCatalog(input: WorkspaceModelSelectionInput, defaults?: WorkspaceModelCatalogDefaults): WorkspaceModelCatalogResponseType;
+/** Resolved new-chat defaults published beside the catalog rows. */
+export type WorkspaceModelCatalogDefaults = {
+    defaultSelection: DefaultModelSelection;
+    creditsSelection: DefaultModelSelection | null;
+};
+export declare function projectWorkspaceModelCatalog(selections: readonly WorkspaceModelSelection[], defaults?: WorkspaceModelCatalogDefaults): WorkspaceModelCatalogResponseType;

package/dist/observability.d.ts

@@ -1,3 +1,5 @@
-import type { EventLogger } from "@opengeni/events";
+import { type EventBusOptions, type EventLogger } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
+/** Logger plus the closed-label subscription-termination counter for NATS connections. */
+export declare function observabilityEventBusOptions(observability: Observability): Pick<EventBusOptions, "logger" | "onSubscriptionTerminated">;
 export declare function observabilityEventLogger(observability: Observability): EventLogger;

package/dist/organization-mcp.d.ts

@@ -0,0 +1,52 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type OrganizationAccessPolicy } from "@opengeni/contracts";
+import type { ActionCatalogEntry } from "./mcp/action-catalog-types.js";
+export type OrganizationMcpCaller = {
+    kind: "person";
+    accountId: string;
+    subjectId: string;
+    access: OrganizationAccessPolicy;
+} | {
+    kind: "key";
+    authorization: string;
+    accessKey: string | null;
+};
+/**
+ * Requests that only read but are sent as POST (a search query or a file path
+ * in the body). Read only connections may run them; each route still checks
+ * its own read permission.
+ */
+export declare const READ_ONLY_POST_ACTIONS: ReadonlySet<string>;
+export declare function buildOrganizationMcpServer(input: {
+    caller: OrganizationMcpCaller;
+    /** This API's own origin; the call never leaves the process. */
+    origin: string;
+    dispatch: (request: Request) => Promise<Response>;
+    signal?: AbortSignal;
+}): Server;
+export declare function findAction(id: string): ActionCatalogEntry | undefined;
+export declare function searchActions(input: {
+    query: string;
+    limit: number;
+    offset: number;
+}): {
+    total: number;
+    offset: number;
+    actions: {
+        id: string;
+        method: string;
+        path: string;
+    }[];
+};
+export declare function describeAction(entry: ActionCatalogEntry): {
+    id: string;
+    method: string;
+    path: string;
+    pathParameters: string[];
+    input: {
+        name: string;
+        in: string;
+        schema: unknown;
+    }[];
+    response: string[];
+};

package/dist/organization-recovery-notifications.d.ts

@@ -0,0 +1,41 @@
+import type { Database } from "@opengeni/db";
+import { prepareOrganizationRecoveryNotifications, settleOrganizationRecoveryNotification, type OrganizationRecoveryNotificationClaim, type OrganizationRecoveryNotificationSettlement } from "@opengeni/db";
+export type OrganizationRecoveryNotificationDeliveryResult = {
+    status: "sent";
+    providerMessageId: string | null;
+} | {
+    status: "failed";
+    errorClass: string;
+} | {
+    status: "outcome_unknown";
+};
+export interface OrganizationRecoveryNotificationTransport {
+    readonly provider: string;
+    send(claim: OrganizationRecoveryNotificationClaim): Promise<OrganizationRecoveryNotificationDeliveryResult>;
+}
+export type OrganizationRecoveryNotificationLifecycle = {
+    prepare: typeof prepareOrganizationRecoveryNotifications;
+    settle: typeof settleOrganizationRecoveryNotification;
+};
+export declare function dispatchOrganizationRecoveryNotifications(input: {
+    db: Database;
+    transport: OrganizationRecoveryNotificationTransport;
+    claimOwner: string;
+    limit?: number;
+    leaseSeconds?: number;
+    lifecycle?: OrganizationRecoveryNotificationLifecycle;
+}): Promise<OrganizationRecoveryNotificationSettlement[]>;
+export declare class InMemoryOrganizationRecoveryNotificationTransport implements OrganizationRecoveryNotificationTransport {
+    readonly provider = "fake";
+    readonly attempts: Array<{
+        idempotencyKey: string;
+        payloadDigest: string;
+        recipientCanonicalIdentityId: string;
+        providerMessageId: string;
+    }>;
+    private readonly deliveries;
+    private readonly scripted;
+    enqueue(...results: OrganizationRecoveryNotificationDeliveryResult[]): void;
+    logicalDeliveryCount(): number;
+    send(claim: OrganizationRecoveryNotificationClaim): Promise<OrganizationRecoveryNotificationDeliveryResult>;
+}

package/dist/routes/analytics-consent.d.ts

@@ -0,0 +1,26 @@
+import type { Settings } from "@opengeni/config";
+import { ANALYTICS_CONSENT_DECISIONS, ANALYTICS_CONSENT_PATH, type AnalyticsConsentDecision } from "@opengeni/contracts/analytics-consent-report";
+import type { Observability } from "@opengeni/observability";
+import type { Hono } from "hono";
+import { z } from "zod";
+import { type KeyedAdmission } from "../http/keyed-admission.js";
+export { ANALYTICS_CONSENT_DECISIONS, ANALYTICS_CONSENT_PATH, type AnalyticsConsentDecision };
+export declare const AnalyticsConsentReport: z.ZodObject<{
+    decision: z.ZodEnum<{
+        denied: "denied";
+        granted: "granted";
+    }>;
+}, z.core.$strict>;
+export type AnalyticsConsentReport = z.infer<typeof AnalyticsConsentReport>;
+export type AnalyticsConsentAdmission = KeyedAdmission<AnalyticsConsentDecision>;
+export declare function parseAnalyticsConsentReport(body: string | null): AnalyticsConsentReport | null;
+/**
+ * The exact beacon request. The app-wide request-body limit skips it because
+ * the route enforces its own small limit on the streamed body.
+ */
+export declare function isAnalyticsConsentReportRequest(method: string, pathname: string): boolean;
+export declare function registerAnalyticsConsentRoutes(app: Hono, deps: {
+    observability: Observability;
+    settings: Pick<Settings, "corsAllowOriginRegex" | "publicBaseUrl" | "webBaseUrl">;
+    admission?: AnalyticsConsentAdmission;
+}): void;

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

@@ -1,8 +1,33 @@
+import { createPinnedIntegrationTransport } from "@opengeni/capabilities";
+import { InstallApiIntegrationRequest, PreviewApiIntegrationRequest, type AccessGrant } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
+import { installApiIntegration } from "@opengeni/db";
 import type { FetchLike } from "@opengeni/network";
 import type { Hono } from "hono";
+import { resolveApiIntegrationPreview, type ResolvedApiIntegrationPreview } from "../integrations/api-integrations.js";
 export type ApiIntegrationRouteOverrides = Readonly<{
     fetchImpl?: FetchLike;
 }>;
 export declare function apiIntegrationRequiresConnection(authScheme: Record<string, unknown>): boolean;
+/** Shared native/embedded install validation. The caller must still authorize
+ * capabilities:manage and commit under its own live-authority boundary. */
+export declare function validatedIntegrationInstallInput(grant: AccessGrant, workspaceId: string, payload: InstallApiIntegrationRequest, resolved: ResolvedApiIntegrationPreview): Parameters<typeof installApiIntegration>[1];
+/**
+ * `allowedTools` names tools by their preview `id`, the stable identity the
+ * install persists. Reject anything else as a client error that lists the
+ * valid ids; a caller that sent a preview `operationKey` is told which id it
+ * maps to rather than having it silently reinterpreted.
+ */
+export declare function validatedAllowedToolIds(allowedTools: readonly string[], tools: readonly {
+    id: string;
+    operationKey: string;
+}[]): string[];
 export declare function registerApiIntegrationRoutes(app: Hono, deps: ApiRouteDeps, overrides?: ApiIntegrationRouteOverrides): void;
+export declare function resolveForRoute(input: {
+    deps: ApiRouteDeps;
+    transport: ReturnType<typeof createPinnedIntegrationTransport>;
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
+}): ReturnType<typeof resolveApiIntegrationPreview>;

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

@@ -1,3 +1,20 @@
+import { CreateOrganizationApiKeyRequest, Permission, type AccessContext, type OrganizationApiKeyAccess } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
+export { organizationApiKeyAccess } from "@opengeni/core";
+/** Permissions minted onto a `full` organization API key. */
+export declare const organizationApiKeyPermissions: Permission[];
+/**
+ * Permissions minted onto a `read` organization API key. The key inventories
+ * shared workspaces and reads their sessions, events, and files; it holds no
+ * `workspace:admin` wildcard, so every control, create, and key-management
+ * route denies it, and no `api_keys:manage`, so it cannot mint keys.
+ */
+export declare const organizationReadApiKeyPermissions: Permission[];
+export declare function organizationApiKeyPermissionsForAccess(access: OrganizationApiKeyAccess): Permission[];
+/** Existing callers retain their expiry; setup keys default to one day. */
+export declare function organizationApiKeyExpiryDate(request: Pick<CreateOrganizationApiKeyRequest, "preset" | "expiresAt"> & Partial<Pick<CreateOrganizationApiKeyRequest, "access">>, now?: Date): Date | null;
 export declare function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void;
+/** Service account problems read as the person would expect. */
+export declare function throwServiceAccountError(error: unknown): void;
+export declare function requireOrganizationApiKeyControlPermission(context: AccessContext, organizationId: string): void;

package/dist/routes/artifact-catalog.d.ts

@@ -0,0 +1,6 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+import { type EditableArtifactRouteDependencies } from "./editable-artifacts.js";
+type Dependencies = ApiRouteDeps & EditableArtifactRouteDependencies;
+export declare function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): void;
+export {};

package/dist/routes/automations.d.ts

@@ -0,0 +1,19 @@
+import { AutomationNormalizedEvent } from "@opengeni/contracts";
+import { type AutomationSourceSecret } from "@opengeni/db";
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerAutomationRoutes(app: Hono, deps: ApiRouteDeps): void;
+export declare function acceptAutomationEvent(deps: ApiRouteDeps, source: AutomationSourceSecret, input: {
+    deliveryKey: string;
+    requestDigest: string;
+    normalizedEvent: AutomationNormalizedEvent;
+    /** Canonical manual caller restriction, not normalized event metadata. */
+    credentialRestriction?: "developer_setup";
+}): Promise<{
+    accepted: boolean;
+    duplicate: boolean;
+    ignoredReason: string | null;
+    eventId: string | null;
+    runIds: string[];
+}>;
+export declare function readAutomationWebhookBody(request: Request, maxBytes: number): Promise<Uint8Array>;

package/dist/routes/billing.d.ts

@@ -1,3 +1,4 @@
+import { type AccessContext, type Permission } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import Stripe from "stripe";
 import type { ApiRouteDeps } from "@opengeni/core";
@@ -9,8 +10,56 @@ export declare function stripeCheckoutSessionCreateParams(input: {
     amountMicros: number;
     creditsProductId?: string | undefined;
     publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
     successUrl?: string | undefined;
     cancelUrl?: string | undefined;
     idempotencyKey: string;
+    /** Apply this promotion code up front instead of letting Stripe ask for one. */
+    promotionCodeId?: string | undefined;
+    /**
+     * The applied code covers the whole package, so the total is $0. Nothing is
+     * taxable, so Checkout skips tax and with it the billing address: the
+     * customer only confirms.
+     */
+    fullyDiscounted?: boolean | undefined;
 }): Stripe.Checkout.SessionCreateParams;
+export declare function stripeBillingPortalSessionCreateParams(input: {
+    customerId: string;
+    publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
+    returnUrl?: string | undefined;
+}): Stripe.BillingPortal.SessionCreateParams;
+export type StripeCheckoutCreditDecision = {
+    action: "grant";
+    credit: CheckoutCreditMetadata;
+} | {
+    action: "ignore";
+    reason: "foreign_checkout" | "not_payment_mode" | "payment_not_paid";
+};
+/**
+ * Decides whether a Checkout Session webhook grants OpenGeni credits.
+ *
+ * Sessions created outside OpenGeni on the same Stripe account carry no
+ * `opengeni_` metadata and are acknowledged without effect. An OpenGeni
+ * session with malformed credit metadata still throws so the failure stays
+ * visible. Credits are granted once Stripe reports the payment `paid` or a
+ * completed checkout fully covered by a coupon:
+ * on `checkout.session.completed` for immediate methods, or on
+ * `checkout.session.async_payment_succeeded` for delayed methods, whose
+ * completion event arrives `unpaid`. Both events carry the same session
+ * metadata, so the ledger idempotency key grants at most once.
+ */
+export declare function stripeCheckoutCreditDecision(session: Stripe.Checkout.Session): StripeCheckoutCreditDecision;
+export type CheckoutCreditMetadata = {
+    accountId: string;
+    amountMicros: number;
+    idempotencyKey: string;
+    amountUsd?: string;
+    packageId?: string;
+};
 export declare function stripeCustomerProvider(input: ApiRouteDeps | Stripe.Event): "stripe:live" | "stripe:test";
+/** Billing routes do not traverse the workspace actor middleware. Always bind
+ * these reads explicitly; only a revalidated live attempt may supply a human
+ * initiator. Neither query parameters nor serviceInitiator claims are proof. */
+export declare function withBillingUsageActor<T>(deps: ApiRouteDeps, context: AccessContext, accountId: string, read: () => Promise<T>): Promise<T>;
+export declare function requireSelectedAccount(context: AccessContext, requested: string | undefined, permission: Permission): string;

package/dist/routes/browser-sessions.d.ts

@@ -1,6 +1,74 @@
-import { InteractionActor, type AccessGrant } from "@opengeni/contracts";
-import { type ApiRouteDeps } from "@opengeni/core";
+import { InteractionActor, type AccessGrant, type FileAsset, type CreateBrowserSessionRequest as CreateBrowserSessionRequestValue, type InteractionPlacement } from "@opengeni/contracts";
+import { type ApiRouteDeps, type ResolvedSessionAuthorization } from "@opengeni/core";
+import { type BrowserControlScreenshotOptions, type BrowserControlFrame } from "@opengeni/runtime/sandbox";
 import type { Hono } from "hono";
 export declare function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): void;
-export declare function validateBrowserRequestOrigin(value: string | undefined, allowedPattern: string): string | null;
+export declare function browserCreateInput(grant: AccessGrant, workspaceId: string, request: CreateBrowserSessionRequestValue, placement: InteractionPlacement): {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    associatedSessionId: string;
+    actorSubjectId: string;
+    name: string;
+    initialUrl: string | null;
+    placement: {
+        kind: "sandbox_group";
+        sandboxGroupId: string;
+    } | {
+        kind: "connected_machine";
+        sandboxId: string;
+    } | {
+        kind: "attached_device";
+        deviceId: string;
+    } | {
+        kind: "external_provider";
+        providerId: string;
+        placementId: string;
+    };
+    driverId: string;
+    engine: "chrome" | "chromium" | "external" | "lightpanda";
+    headless: boolean;
+    identityId: string | null;
+    baseRevisionId: string | null;
+    networkRouteId: string | null;
+    linkedComputerSessionId: string | null;
+    resolveDefaultRevision: boolean;
+    capabilities?: {
+        semanticObservation: boolean;
+        screenshots: boolean;
+        liveFrames: boolean;
+        humanInput: boolean;
+        tabs: boolean;
+        downloads: boolean;
+        uploads: boolean;
+        clipboard: boolean;
+        permissions: boolean;
+        diagnostics: boolean;
+        rawCdp: boolean;
+        linkedComputer: boolean;
+        privateCheckpoint: boolean;
+        identityPublication: boolean;
+        parallelTargets: boolean;
+    };
+};
+export declare function browserNeedsStandaloneDisplayStack(input: {
+    headless: boolean;
+    linkedComputer: boolean;
+    nativeBrowserControl: boolean;
+}): boolean;
+export declare function parseBrowserScreenshotOptions(query: URLSearchParams): BrowserControlScreenshotOptions;
+/** Keep a definite read timeout useful without publishing driver diagnostics. */
+export declare function browserScreenshotError(error: unknown): unknown;
+export declare function browserScreenshotResponse(frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">): Response;
 export declare function interactionActorForGrant(grant: AccessGrant): ReturnType<typeof InteractionActor.parse>;
+/** Resolve Drive authority from the same immutable session authorization that
+ * admitted the browser action. Agent-attempt subjects are technical worker
+ * identities; their frozen initiating human is the only personal Drive
+ * principal. Pure service attempts retain null and can read only ordinary
+ * workspace files through the database predicate. */
+export declare function browserFileAuthoritySubjectId(grant: AccessGrant, authorization: ResolvedSessionAuthorization | null): string | null;
+/** The batch authority query intentionally omits every unauthorized file. Any
+ * omission therefore fails the whole upload before an object-storage URL is
+ * minted, including mixed ordinary/Drive mappings and partially authorized
+ * batches. */
+export declare function requireAuthorizedBrowserUploadFiles(workspaceFileIds: readonly string[], authorizedFiles: readonly FileAsset[]): FileAsset[];

package/dist/routes/claude-subscription-accounts.d.ts

@@ -0,0 +1,3 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerClaudeSubscriptionAccountRoutes(app: Hono, deps: ApiRouteDeps): void;

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

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type Hono } from "hono";
+export declare function registerClaudeSubscriptionOAuthRoutes(app: Hono, deps: ApiRouteDeps, fetchImpl?: typeof fetch): void;