@opengeni/api-router 0.30.1 → 1.0.0

package/dist/workspace-artifact-content.d.ts

@@ -0,0 +1,28 @@
+import { type ToolGatewayIdentity, type WorkspaceArtifactSourceBundle as WorkspaceArtifactSourceBundleValue, type WorkspaceArtifactVersion } from "@opengeni/contracts";
+import type { ObjectStorageDependency } from "@opengeni/core";
+export type PreparedWorkspaceArtifactContent = {
+    contentKey: string;
+    contentSha256: null;
+    sizeBytes: number;
+    sourceKey: string | null;
+    sourceSha256: null;
+    sourceSizeBytes: number | null;
+    requestedTools?: ToolGatewayIdentity[];
+    persistContent: () => Promise<void>;
+    discardContent: () => Promise<void>;
+};
+export declare function prepareWorkspaceArtifactContent(objectStorage: NonNullable<ObjectStorageDependency>, workspaceId: string, input: {
+    html: string;
+    source?: WorkspaceArtifactSourceBundleValue;
+    requestedTools?: ToolGatewayIdentity[];
+}): PreparedWorkspaceArtifactContent;
+export declare function readWorkspaceArtifactContent(objectStorage: NonNullable<ObjectStorageDependency>, input: {
+    contentKey: string;
+    sourceKey: string | null;
+    version: WorkspaceArtifactVersion;
+}): Promise<{
+    html: string;
+    source: WorkspaceArtifactSourceBundleValue;
+    requestedTools: ToolGatewayIdentity[];
+}>;
+export declare function sourceBundleFromHtml(html: string): WorkspaceArtifactSourceBundleValue;

package/dist/workspace-artifact-provenance.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceArtifactDetailResponse, WorkspaceArtifactListResponse, WorkspaceArtifactMutationResponse, WorkspaceArtifactVersion } from "@opengeni/contracts";
+type CanReadSession = (sessionId: string) => Promise<boolean>;
+export declare function redactWorkspaceArtifactListProvenance(response: WorkspaceArtifactListResponse): WorkspaceArtifactListResponse;
+export declare function projectWorkspaceArtifactVersionProvenance(version: WorkspaceArtifactVersion, canReadSession: CanReadSession): Promise<WorkspaceArtifactVersion>;
+export declare function projectWorkspaceArtifactDetailProvenance(detail: WorkspaceArtifactDetailResponse, canReadSession: CanReadSession): Promise<WorkspaceArtifactDetailResponse>;
+export declare function projectWorkspaceArtifactMutationProvenance(response: WorkspaceArtifactMutationResponse, canReadSession: CanReadSession): Promise<WorkspaceArtifactMutationResponse>;
+export {};

package/dist/workspace-delete-observability.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceDeleteObserver } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+/**
+ * Retain exact workspace deletion timing and inventory without putting tenant
+ * identifiers in metric labels. Observer failures never change deletion truth.
+ */
+export declare function workspaceDeleteObserver(observability: Observability | null | undefined, identity: {
+    accountId: string;
+    workspaceId: string;
+}): WorkspaceDeleteObserver | undefined;

package/dist/workspace-deletion.d.ts

@@ -0,0 +1,6 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+export declare function deleteWorkspaceForRequest(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    organizationAdministratorSubjectId?: string;
+}): Promise<void>;

package/dist/workspace-state-projection.d.ts

@@ -1,9 +1,7 @@
-import { type WorkspaceInstructionPolicyListResponse, type WorkspaceInstructionPolicySnapshot, type WorkspaceStateResponse as WorkspaceStateResponseType } from "@opengeni/contracts";
-import type { WorkspaceStateMemoryRecord } from "@opengeni/db";
-import type { DocumentInventory } from "@opengeni/documents";
+import { type KnowledgeEntrySummary, type WorkspaceInstructionPolicyListResponse, type WorkspaceInstructionPolicySnapshot, type WorkspaceStateResponse as WorkspaceStateResponseType } from "@opengeni/contracts";
 type KnowledgeProjectionInput = {
-    documents: DocumentInventory;
-    memories: WorkspaceStateMemoryRecord[];
+    entries: Pick<KnowledgeEntrySummary, "id" | "scope" | "revision" | "updatedAt">[];
+    nextCursor: string | null;
 };
 type PreferenceGovernanceIdentity = {
     id: string;

package/dist/workspace-tool-gateway-observability.d.ts

@@ -0,0 +1,17 @@
+import type { ToolGatewayCatalogEntry } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+export type WorkspaceToolGatewayAdapter = "http" | "mcp";
+export type WorkspaceToolGatewayOperation = "approval" | "call";
+export type WorkspaceToolGatewayOutcome = "ok" | "tool_error" | "approval_required" | "catalog_stale" | "invalid_input" | "not_found" | "rate_limited" | "failed";
+/**
+ * Low-cardinality gateway telemetry shared by HTTP/SDK/Site and aggregate MCP
+ * adapters. Tool names, workspace/subject ids, arguments, results, credentials,
+ * and approval tokens are excluded by construction.
+ */
+export declare function startWorkspaceToolGatewayObservation(observability: Observability | null | undefined, input: {
+    adapter: WorkspaceToolGatewayAdapter;
+    operation: WorkspaceToolGatewayOperation;
+    source: ToolGatewayCatalogEntry["source"] | "aggregate";
+}): {
+    end: (outcome: WorkspaceToolGatewayOutcome) => void;
+};

package/dist/workspace-tool-gateway.d.ts

@@ -0,0 +1,123 @@
+import { resolveSiteSessionOrigin } from "./site-session-origin.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Settings } from "@opengeni/config";
+import { ToolGatewayDeclarationsResponse, type AccessGrant, type ToolGatewayCatalog, type ToolGatewayIdentity } from "@opengeni/contracts";
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+import { buildConnectionTokenResolver, consumeToolGatewayApproval, getWorkspaceArtifactContentRef, issueToolGatewayApproval } from "@opengeni/db";
+import { type PreparedWorkspaceToolGatewayTools } from "@opengeni/runtime/workspace-tool-gateway";
+import { type ToolGatewayDefinition } from "@opengeni/tool-gateway";
+import type { Observability } from "@opengeni/observability";
+export type PreparedWorkspaceToolGateway = Pick<PreparedWorkspaceToolGatewayTools, "toolGateway" | "toolGatewayCatalog" | "close"> & {
+    toolGateway: NonNullable<PreparedWorkspaceToolGatewayTools["toolGateway"]>;
+    toolGatewayCatalog: NonNullable<PreparedWorkspaceToolGatewayTools["toolGatewayCatalog"]>;
+    reauthorize?: () => Promise<void>;
+};
+type WorkspaceSiteToolContext = {
+    siteArtifactId: string;
+    siteVersionId: string;
+    identity: {
+        serverId: string;
+        toolName: string;
+    };
+};
+type AuthorizeWorkspaceSiteTool = (db: ApiRouteDeps["db"], grant: AccessGrant, context: WorkspaceSiteToolContext) => Promise<void>;
+export declare function grantUsesAttemptScopedMcp(grant: AccessGrant): boolean;
+export declare function requireWorkspaceToolGatewayGrant(grant: AccessGrant): void;
+export declare function requireWorkspaceToolGatewayAuthorization(authorization: AccessGrantAuthorization): AccessGrant;
+export declare function prepareWorkspaceToolGateway(routeDeps: ApiRouteDeps, authorization: AccessGrantAuthorization): Promise<PreparedWorkspaceToolGateway>;
+export declare function prepareMcpOAuthWorkspaceToolGateway(routeDeps: ApiRouteDeps, grant: AccessGrant, allowedIdentities: readonly {
+    serverId: string;
+    toolName: string;
+}[]): Promise<PreparedWorkspaceToolGateway>;
+export declare function prepareWorkspaceToolGatewayForGrant(routeDeps: ApiRouteDeps, grant: AccessGrant, allowedIdentities?: readonly {
+    serverId: string;
+    toolName: string;
+}[]): Promise<PreparedWorkspaceToolGateway>;
+/** Keep live caller authority independent of native connection acquisition and refresh. */
+export declare function withWorkspaceConnectionAuthorization(resolve: ReturnType<typeof buildConnectionTokenResolver>, reauthorize?: () => Promise<void>): ReturnType<typeof buildConnectionTokenResolver>;
+export declare function workspaceToolGatewayDefinitionFilter(settings: Pick<Settings, "allowedFirstPartyMcpTools">, allowedIdentities?: readonly ToolGatewayIdentity[]): (definition: ToolGatewayDefinition) => boolean;
+export declare function workspaceToolGatewaySettingsForGrant(settings: Settings, grant: AccessGrant, allowedIdentities?: readonly {
+    serverId: string;
+    toolName: string;
+}[]): Settings;
+export declare function buildWorkspaceToolGatewayMcpServer(prepared: PreparedWorkspaceToolGateway, grant: AccessGrant, observability?: Observability): Server;
+export declare function callWorkspaceToolGateway(prepared: PreparedWorkspaceToolGateway, grant: AccessGrant, input: unknown, db?: ApiRouteDeps["db"], consumeApproval?: typeof consumeToolGatewayApproval, observability?: Observability, authorizeSiteTool?: AuthorizeWorkspaceSiteTool, resolveOrigin?: typeof resolveSiteSessionOrigin): Promise<{
+    operationId: string;
+    catalogDigest: string;
+    result: {
+        [x: string]: unknown;
+        content: ({
+            [x: string]: unknown;
+            type: "text";
+            text: string;
+            annotations?: Record<string, import("zod").JSONType> | undefined;
+            _meta?: Record<string, import("zod").JSONType> | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: Record<string, import("zod").JSONType> | undefined;
+            _meta?: Record<string, import("zod").JSONType> | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: Record<string, import("zod").JSONType> | undefined;
+            _meta?: Record<string, import("zod").JSONType> | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "resource_link";
+            name: string;
+            title?: string | undefined;
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            annotations?: Record<string, import("zod").JSONType> | undefined;
+            _meta?: Record<string, import("zod").JSONType> | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "resource";
+            resource: {
+                [x: string]: unknown;
+                uri: string;
+                mimeType?: string | undefined;
+                text: string;
+                _meta?: Record<string, import("zod").JSONType> | undefined;
+            } | {
+                [x: string]: unknown;
+                uri: string;
+                mimeType?: string | undefined;
+                blob: string;
+                _meta?: Record<string, import("zod").JSONType> | undefined;
+            };
+            annotations?: Record<string, import("zod").JSONType> | undefined;
+            _meta?: Record<string, import("zod").JSONType> | undefined;
+        })[];
+        structuredContent?: Record<string, import("zod").JSONType> | undefined;
+        isError?: boolean | undefined;
+        _meta?: Record<string, import("zod").JSONType> | undefined;
+    };
+}>;
+export declare function approveWorkspaceToolGatewayCall(prepared: PreparedWorkspaceToolGateway, grant: AccessGrant, db: ApiRouteDeps["db"], input: unknown, issueApproval?: typeof issueToolGatewayApproval, observability?: Observability): Promise<{
+    operationId: string;
+    catalogDigest: string;
+    identity: {
+        serverId: string;
+        toolName: string;
+    };
+    approvalToken: string;
+    expiresAt: string;
+}>;
+export declare function requireWorkspaceSiteToolAuthorization(db: ApiRouteDeps["db"], grant: AccessGrant, context: WorkspaceSiteToolContext, resolveVersion?: typeof getWorkspaceArtifactContentRef): Promise<void>;
+export declare function toolGatewayCatalogResponse(catalog: ToolGatewayCatalog): ToolGatewayCatalog;
+export declare function workspaceToolGatewayDeclarations(prepared: PreparedWorkspaceToolGateway): ToolGatewayDeclarationsResponse;
+export {};

package/dist/workspace-webhook-dispatch.d.ts

@@ -0,0 +1,26 @@
+import { type Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+import { pinnedFetch } from "@opengeni/network";
+import type { Observability } from "@opengeni/observability";
+export declare const WORKSPACE_WEBHOOK_DISPATCH_BATCH_SIZE = 32;
+export type WorkspaceWebhookDispatchDeps = {
+    db: Database;
+    settings: Settings;
+    observability?: Pick<Observability, "info" | "warn" | "error">;
+    fetch?: typeof pinnedFetch;
+};
+export type WorkspaceWebhookBatchResult = {
+    claimed: number;
+    delivered: number;
+    failed: number;
+};
+/** Claim and deliver one globally bounded batch. At-least-once: receivers dedupe on event id. */
+export declare function drainWorkspaceWebhookDeliveries(deps: WorkspaceWebhookDispatchDeps): Promise<WorkspaceWebhookBatchResult>;
+/**
+ * One non-overlapping loop per API replica. PostgreSQL claims coordinate
+ * replicas; a crash only delays a delivery until its claim expires.
+ */
+export declare function startWorkspaceWebhookDispatchPump(deps: WorkspaceWebhookDispatchDeps, options?: {
+    intervalMs?: number;
+    drain?: (deps: WorkspaceWebhookDispatchDeps) => Promise<WorkspaceWebhookBatchResult>;
+}): () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.30.1",
+  "version": "1.0.0",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,32 +41,36 @@
     "@aws-sdk/client-s3": "^3.1044.0",
     "@aws-sdk/s3-request-presigner": "^3.1044.0",
     "@hono/zod-validator": "^0.7.6",
-    "@llamaindex/liteparse": "^1.5.3",
+    "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.5.0",
-    "@opengeni/artifact-tool": "^0.2.8",
-    "@opengeni/capabilities": "^0.2.0",
-    "@opengeni/codemode": "^0.4.2",
-    "@opengeni/codex": "^0.2.17",
-    "@opengeni/config": "^0.16.2",
-    "@opengeni/contracts": "^0.50.0",
-    "@opengeni/core": "^0.28.1",
-    "@opengeni/db": "^0.36.1",
-    "@opengeni/documents": "^0.5.39",
-    "@opengeni/events": "^0.3.110",
-    "@opengeni/github": "^0.4.57",
-    "@opengeni/network": "^0.2.2",
-    "@opengeni/observability": "^0.7.5",
-    "@opengeni/runtime": "^0.23.1",
-    "@opengeni/storage": "^0.2.94",
-    "@opengeni/xai-subscription": "^0.1.0",
+    "@opengeni/agent-proto": "1.0.0",
+    "@opengeni/artifact-tool": "1.0.0",
+    "@opengeni/capabilities": "1.0.0",
+    "@opengeni/codemode": "1.0.0",
+    "@opengeni/codex": "1.0.0",
+    "@opengeni/config": "1.0.0",
+    "@opengeni/contracts": "1.0.0",
+    "@opengeni/core": "1.0.0",
+    "@opengeni/db": "1.0.0",
+    "@opengeni/documents": "1.0.0",
+    "@opengeni/events": "1.0.0",
+    "@opengeni/github": "1.0.0",
+    "@opengeni/interaction": "1.0.0",
+    "@opengeni/network": "1.0.0",
+    "@opengeni/observability": "1.0.0",
+    "@opengeni/runtime": "1.0.0",
+    "@opengeni/storage": "1.0.0",
+    "@opengeni/tool-gateway": "1.0.0",
+    "@opengeni/xai-subscription": "1.0.0",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",
+    "json-bigint": "^1.0.0",
     "pg": "^8.21.0",
     "resend": "^6.12.4",
     "sharp": "^0.34.5",
     "stripe": "^22.2.0",
+    "ws": "8.21.1",
     "zod": "^4.2.1"
   },
   "engines": {

package/src/access-grant-rls.ts

@@ -0,0 +1,75 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import {
+  requireLiveAgentAttemptAuthorization,
+  SessionAuthorizationDeniedError,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  freezeAgentLearningPolicy,
+  withSessionRlsActorContext,
+  withCreditDebitAttribution,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+export async function withAccessGrantSessionRlsContext<T>(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: AccessGrant,
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (grant.principalKind !== "agent_attempt") {
+    return await withCreditDebitAttribution(
+      grant.principalKind === "human_session"
+        ? { kind: "human", initiatingHumanSubjectId: grant.subjectId }
+        : grant.principalKind === "service" ||
+            grant.principalKind === "api_key" ||
+            grant.principalKind === "configured_key" ||
+            grant.principalKind === "mcp_gateway"
+          ? { kind: "service" }
+          : { kind: "unknown" },
+      () => withSessionRlsActorContext({ subjectId: grant.subjectId }, fn),
+    );
+  }
+  const callerSessionId = grant.metadata?.sessionId;
+  if (typeof callerSessionId !== "string") {
+    throw new HTTPException(403, { message: "agent attempt authority is invalid" });
+  }
+  try {
+    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
+    const learning = await freezeAgentLearningPolicy(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "agent",
+        sessionId: actor.callerSessionId,
+        turnId: actor.turnId,
+        attemptId: actor.attemptId,
+        executionGeneration: actor.executionGeneration,
+      },
+    });
+    return await withCreditDebitAttribution(
+      {
+        kind: "turn",
+        turnId: actor.turnId,
+        initiatingHumanSubjectId: actor.initiatingHumanSubjectId ?? null,
+      },
+      () =>
+        withSessionRlsActorContext(
+          {
+            subjectId: actor.subjectId,
+            initiatingHumanSubjectId: actor.initiatingHumanSubjectId,
+            privateFileOwnerSubjectId:
+              learning.defaultScope === "personal" ? learning.subjectId : null,
+          },
+          fn,
+        ),
+    );
+  } catch (error) {
+    if (error instanceof SessionAuthorizationDeniedError) {
+      throw new HTTPException(403, {
+        message: "agent attempt authority is invalid",
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}

package/src/admission-trace.ts

@@ -0,0 +1,14 @@
+import type { Observability } from "@opengeni/observability";
+
+/** Only committed, non-replayed server event identities mint admission anchors. */
+export function recordAcceptedApiAdmission(
+  observability: Observability | undefined,
+  result: { accepted: { id: string }; replay: boolean },
+): void {
+  if (result.replay) return;
+  try {
+    observability?.recordAdmissionTrace(result.accepted.id);
+  } catch {
+    // Telemetry must never turn a committed admission into an HTTP failure.
+  }
+}

package/src/api-websocket.ts

@@ -0,0 +1,23 @@
+export type ApiWebSocketConnection = Readonly<{
+  attach(socket: ApiWebSocketLike): void;
+  receive(message: string | Uint8Array | ArrayBuffer): void;
+  transportClosed(): void;
+}>;
+
+export type ApiWebSocketLike = Readonly<{
+  data: ApiWebSocketConnection;
+  send(data: Uint8Array, compress?: boolean): number;
+  close(code?: number, reason?: string): void;
+  readonly bufferedAmount?: number;
+  getBufferedAmount?(): number;
+}>;
+
+export type ApiWebSocketUpgradeServer = Readonly<{
+  upgrade(
+    request: Request,
+    options: Readonly<{
+      data: ApiWebSocketConnection;
+      headers: HeadersInit;
+    }>,
+  ): boolean;
+}>;