@opengeni/api-router 3.0.1 → 3.1.2

package/dist/workspace-tool-target-fence.d.ts

@@ -0,0 +1,116 @@
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+import { type Database } from "@opengeni/db";
+import { ApiHttpError } from "./http/api-error.js";
+/**
+ * One evaluation's budget. Below the MCP SDK's 5 s setup-request timeout, so a
+ * stalled authority read is reported as unavailable authority rather than
+ * silently dropping the target connector (a 404).
+ */
+export declare const TARGET_FENCE_DEADLINE_MS = 2500;
+/**
+ * A part of the live fence. `db` is the evaluation's bounded transaction;
+ * `stop` aborts once the evaluation's deadline passes or its request ends. The
+ * evaluation checks it before each part; the route part also checks it between
+ * its capability, integration and connection reads.
+ */
+export type TargetFenceCheck = (db: Database, stop: AbortSignal) => Promise<void>;
+export type TargetFenceCaller = {
+    /** Read inside the evaluation's bounded transaction. */
+    scoped?: TargetFenceCheck;
+    /** Runs beside it: its own bounded transaction, or the route's fresh grant. */
+    standalone?: (stop: AbortSignal) => Promise<void>;
+};
+type Outcome = "denied" | "approval_required" | "unavailable" | "aborted" | "closed";
+export type TargetFenceStats = {
+    /** Started evaluations (caller-only plus full). */
+    evaluations: number;
+    full: number;
+    /** Wall time spent inside evaluations, summed (they may overlap). */
+    durationMs: number;
+    outcomes: Partial<Record<Outcome, number>>;
+};
+/**
+ * Authority could not be read in time: a 503 distinct from a provider failure
+ * (502, outcome unknown). Never names the target, its connector or its owner.
+ */
+export declare function targetAuthorityUnavailable(retryable: boolean): ApiHttpError;
+/**
+ * Live caller authority for one targeted request. A verified organization key
+ * is read without a lock or write (admission already recorded its use); an
+ * external continuation keeps its complete commit authorizer; a person keeps
+ * the route's fresh grant (`reauthorize`), unchanged. That grant runs outside
+ * the evaluation's transaction: the deadline answers the request without
+ * cancelling it.
+ */
+export declare function targetFenceCaller(deps: Pick<ApiRouteDeps, "db">, authorization: AccessGrantAuthorization, reauthorize: (() => Promise<void>) | undefined): TargetFenceCaller;
+/**
+ * The single live fence of one targeted request: exact caller, pinned Site,
+ * selected route (connector configuration and connection) and action policy.
+ *
+ * Every evaluation reads current state; nothing is cached, shared between
+ * physical requests, or reused across requests. `full()` runs once for each
+ * installed physical-request boundary, after that request's last credential
+ * step. Its Site, route, policy and organization-key reads share one
+ * transaction bounded by `statement_timeout`; an external actor's authorizer
+ * runs in a second bounded transaction and a person's fresh grant beside them.
+ * At the deadline the evaluation is answered as unavailable authority and no
+ * further part starts. The running part may still finish its current read and
+ * issue its remaining ones (a pinned Site's version after its artifact, the
+ * next selected connection), each bounded by the statement timeout; the
+ * transaction then rolls back.
+ * Boundaries swallow hook failures, so the fence records each outcome itself;
+ * `settle()` reports a recorded denial or unavailable authority instead of an
+ * opaque missing connector. After `close()` (strictly after the awaited
+ * cleanup) every evaluation fails, so nothing is authorized once the request
+ * scope ends.
+ */
+export declare class TargetAuthorityFence {
+    #private;
+    private readonly input;
+    readonly stats: TargetFenceStats;
+    constructor(input: {
+        db: Database;
+        /** A targeted request must install its route before any full evaluation. */
+        targeted: boolean;
+        caller: TargetFenceCaller;
+        signal?: AbortSignal | undefined;
+        deadlineMs?: number;
+    });
+    /** Each part is installed once; a later install never replaces it. */
+    setSite(check: TargetFenceCheck): void;
+    /** Installed by preparation before any provider is constructed. */
+    setRoute(check: TargetFenceCheck): void;
+    /** Installed when the selected call's action policy is decided. */
+    setPolicy(check: TargetFenceCheck): void;
+    /** Live caller only: before credential acquisition may refresh or record use. */
+    caller(): Promise<void>;
+    /** Admission: the live caller, with unavailable authority as a retryable 503. */
+    admit(): Promise<void>;
+    /** Caller, Site, route and policy: once per physical provider request. */
+    full(): Promise<void>;
+    /** Credential hooks report a boolean; their failure is recorded, not lost. */
+    allows(): Promise<boolean>;
+    /**
+     * An explicit fence before an application step. Denials keep their error;
+     * unavailable authority becomes a 503 (retryable only before begin).
+     */
+    check(options: {
+        retryable: boolean;
+    }): Promise<void>;
+    /** Transport boundary of a credential-fenced connector: no database read. */
+    assertOpen(): void;
+    close(): void;
+    /**
+     * Classify a failed preparation or a missing target. Waits (bounded) for
+     * evaluations already started, then prefers a recorded denial, then an
+     * approval change, then unavailable authority; otherwise `error` stands.
+     * In-flight, aborted and post-close evaluations never decide by themselves.
+     */
+    settle(error: unknown, options?: {
+        retryable: boolean;
+    }): Promise<never>;
+    failure(options?: {
+        retryable: boolean;
+    }): Promise<unknown>;
+}
+export {};

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

@@ -0,0 +1,225 @@
+import { type ToolGatewayResolveRequest, type ToolGatewayInvokeRequest, type ToolGatewayTargetApprovalRequest, type ToolGatewayManifestRequest } from "@opengeni/contracts";
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+import { beginTargetToolGatewayCall, issueToolGatewayApproval } from "@opengeni/db";
+import { prepareWorkspaceToolGateway, requireWorkspaceSiteToolAuthorization, type WorkspaceToolGatewayAuthorization } from "./workspace-tool-gateway.js";
+import { TargetAuthorityFence } from "./workspace-tool-target-fence.js";
+export type TargetGatewayOptions = {
+    signal?: AbortSignal;
+    /** The route's fresh human grant; organization keys and external actors use their own reads. */
+    reauthorize?: () => Promise<void>;
+    prepare?: typeof prepareWorkspaceToolGateway;
+    begin?: typeof beginTargetToolGatewayCall;
+    issue?: typeof issueToolGatewayApproval;
+    authorizeSite?: typeof requireWorkspaceSiteToolAuthorization;
+    /** Observes the request's fence (statistics), never its authority. */
+    onFence?: (fence: TargetAuthorityFence) => void;
+};
+/**
+ * The request's single live fence. The owner closes it strictly after the
+ * awaited preparation cleanup. `targeted` requests must install their route.
+ */
+export declare function createTargetFence(deps: ApiRouteDeps, authorization: WorkspaceToolGatewayAuthorization, options: TargetGatewayOptions, targeted: boolean): TargetAuthorityFence;
+export declare function resolveWorkspaceToolTarget(deps: ApiRouteDeps, authorization: WorkspaceToolGatewayAuthorization, request: ToolGatewayResolveRequest, options?: TargetGatewayOptions): Promise<{
+    version: 1;
+    definitionDigest: string;
+    entry: {
+        identity: {
+            serverId: string;
+            toolName: string;
+        };
+        modelName: string;
+        codemodePath: string[];
+        title?: string | undefined;
+        description?: string | undefined;
+        inputSchema: Record<string, import("zod").JSONType>;
+        outputSchema?: Record<string, import("zod").JSONType> | undefined;
+        annotations?: {
+            [x: string]: unknown;
+            title?: string | undefined;
+            readOnlyHint?: boolean | undefined;
+            destructiveHint?: boolean | undefined;
+            idempotentHint?: boolean | undefined;
+            openWorldHint?: boolean | undefined;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "dark" | "light" | undefined;
+        }[] | undefined;
+        source: "codex_apps" | "docs" | "files" | "interaction" | "mcp" | "opengeni";
+        approval: "human" | "none" | "policy";
+    };
+}>;
+export declare function invokeWorkspaceToolTarget(deps: ApiRouteDeps, authorization: WorkspaceToolGatewayAuthorization, request: ToolGatewayInvokeRequest, options?: TargetGatewayOptions): Promise<{
+    operationId: string;
+    tool: {
+        version: 1;
+        definitionDigest: string;
+        entry: {
+            identity: {
+                serverId: string;
+                toolName: string;
+            };
+            modelName: string;
+            codemodePath: string[];
+            title?: string | undefined;
+            description?: string | undefined;
+            inputSchema: Record<string, import("zod").JSONType>;
+            outputSchema?: Record<string, import("zod").JSONType> | undefined;
+            annotations?: {
+                [x: string]: unknown;
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            source: "codex_apps" | "docs" | "files" | "interaction" | "mcp" | "opengeni";
+            approval: "human" | "none" | "policy";
+        };
+    };
+    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 approveWorkspaceToolTarget(deps: ApiRouteDeps, authorization: AccessGrantAuthorization, request: ToolGatewayTargetApprovalRequest, options?: TargetGatewayOptions): Promise<{
+    bindingVersion: 2;
+    operationId: string;
+    tool: {
+        version: 1;
+        definitionDigest: string;
+        entry: {
+            identity: {
+                serverId: string;
+                toolName: string;
+            };
+            modelName: string;
+            codemodePath: string[];
+            title?: string | undefined;
+            description?: string | undefined;
+            inputSchema: Record<string, import("zod").JSONType>;
+            outputSchema?: Record<string, import("zod").JSONType> | undefined;
+            annotations?: {
+                [x: string]: unknown;
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            source: "codex_apps" | "docs" | "files" | "interaction" | "mcp" | "opengeni";
+            approval: "human" | "none" | "policy";
+        };
+    };
+    approvalToken: string;
+    expiresAt: string;
+}>;
+/** Compatibility discovery is bounded by requested identities, grouped per connector. */
+export declare function resolveWorkspaceToolManifest(deps: ApiRouteDeps, authorization: AccessGrantAuthorization, request: ToolGatewayManifestRequest, options?: TargetGatewayOptions): Promise<{
+    version: 1;
+    digest: string;
+    tools: {
+        version: 1;
+        entry: {
+            identity: {
+                serverId: string;
+                toolName: string;
+            };
+            modelName: string;
+            codemodePath: string[];
+            title?: string | undefined;
+            description?: string | undefined;
+            inputSchema: Record<string, import("zod").JSONType>;
+            outputSchema?: Record<string, import("zod").JSONType> | undefined;
+            annotations?: {
+                [x: string]: unknown;
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            source: "codex_apps" | "docs" | "files" | "interaction" | "mcp" | "opengeni";
+            approval: "human" | "none" | "policy";
+        };
+        definitionDigest: string;
+    }[];
+}>;

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"> & Partial<Pick<Observability, "incrementCounter">>;
+    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/dist/xai-subscription-core.d.ts

@@ -0,0 +1,60 @@
+import type { Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+/**
+ * Whether SuperGrok can serve a workspace-level operation (video funding,
+ * realtime catalog, transcription): "a shared xAI candidate exists for
+ * this workspace" on the shared core, organization- or workspace-scoped
+ * shared connections only, never the viewer's personal accounts (design 5.3,
+ * EP-N11). Any route other than `core` (maintenance, or no receipt, which
+ * this binary's readiness check refuses) serves nothing.
+ */
+export declare function workspaceXaiOperationAvailable(db: Database, settings: Settings, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+}): Promise<boolean>;
+/** The SuperGrok status payload. */
+export type XaiStatusPayload<Model> = {
+    connected: boolean;
+    valid: boolean;
+    accountCount: number;
+    models?: Model[];
+    activeAccount?: {
+        id: string;
+        label: string | null;
+        subject: string | null;
+        scope: "workspace" | "organization" | "user";
+    };
+};
+/**
+ * The SuperGrok status after the cutover receipt (design 5.3, status
+ * probe): the workspace's shared pool and its effective primary, validated
+ * by one live model read through the adapter on that connection. Any route
+ * other than the shared core reports nothing usable.
+ *
+ * The viewer's own personal connections count as connected wherever the
+ * owner-only reader shows them. Only in the viewer's own Personal workspace,
+ * only without a shared primary, and only for a caller who passes the
+ * owner check of a private account (`ownerVerified`: the verified owning
+ * person with `connections:write`, by browser sign-in, a verified
+ * external-identity assertion linked to them, or an agent acting with their
+ * full access; never a read-only agent, a plain bearer or the person's own
+ * API keys), is a personal connection the effective account (legacy scope
+ * `user`),
+ * validated by one live usage read as its owner there; that read also
+ * applies the organization's personal-connections rule (0735). Any other
+ * caller gets the stored count only, with no live read and no wake.
+ * Another person's personal connections are never listed.
+ */
+export declare function readXaiCoreStatus<Model>(deps: {
+    db: Database;
+    settings: Settings;
+}, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    models: () => Promise<Model[]>;
+    /** Asked only before a live personal read; false refuses it. */
+    ownerVerified: () => Promise<boolean>;
+    fetch?: unknown;
+}): Promise<XaiStatusPayload<Model>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opengeni/api-router",
-  "version": "3.0.1",
-  "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.",
+  "version": "3.1.2",
+  "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": {
     "type": "git",
@@ -38,30 +38,35 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
+    "@1password/sdk": "0.5.0",
     "@aws-sdk/client-s3": "^3.1044.0",
     "@aws-sdk/s3-request-presigner": "^3.1044.0",
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.6.0",
-    "@opengeni/artifact-tool": "^0.3.29",
-    "@opengeni/capabilities": "^0.3.4",
-    "@opengeni/codemode": "^0.5.9",
-    "@opengeni/codex": "^0.2.23",
-    "@opengeni/config": "^1.2.2",
-    "@opengeni/contracts": "^4.1.0",
-    "@opengeni/core": "^3.0.1",
-    "@opengeni/db": "^5.0.1",
-    "@opengeni/documents": "^0.8.30",
-    "@opengeni/events": "^0.4.28",
-    "@opengeni/github": "^0.7.13",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.29",
-    "@opengeni/runtime": "^3.0.1",
-    "@opengeni/storage": "^0.2.130",
-    "@opengeni/tool-gateway": "^0.1.10",
-    "@opengeni/xai-subscription": "^0.1.4",
+    "@opengeni/agent-proto": "3.1.2",
+    "@opengeni/artifact-tool": "3.1.2",
+    "@opengeni/capabilities": "3.1.2",
+    "@opengeni/codemode": "3.1.2",
+    "@opengeni/codex": "3.1.2",
+    "@opengeni/config": "3.1.2",
+    "@opengeni/contracts": "3.1.2",
+    "@opengeni/core": "3.1.2",
+    "@opengeni/db": "3.1.2",
+    "@opengeni/documents": "3.1.2",
+    "@opengeni/events": "3.1.2",
+    "@opengeni/github": "3.1.2",
+    "@opengeni/interaction": "3.1.2",
+    "@opengeni/network": "3.1.2",
+    "@opengeni/observability": "3.1.2",
+    "@opengeni/runtime": "3.1.2",
+    "@opengeni/storage": "3.1.2",
+    "@opengeni/tool-gateway": "3.1.2",
+    "@opengeni/vaults": "3.1.2",
+    "@opengeni/vaults-onepassword": "3.1.2",
+    "@opengeni/xai-subscription": "3.1.2",
     "@temporalio/client": "^1.17.0",
+    "ajv": "^8.20.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",
     "json-bigint": "^1.0.0",

package/src/access-grant-rls.ts

@@ -4,20 +4,64 @@ import {
   SessionAuthorizationDeniedError,
   type ApiRouteDeps,
 } from "@opengeni/core";
-import { freezeAgentLearningPolicy, withSessionRlsActorContext } from "@opengeni/db";
-import { HTTPException } from "hono/http-exception";
+import {
+  freezeAgentLearningPolicy,
+  withSessionRlsActorContext,
+  withCreditDebitAttribution,
+  type CreditDebitAttribution,
+  currentCreditDebitAttribution,
+} from "@opengeni/db";
+import { ApiHttpError } from "./http/api-error";
+
+const AGENT_ATTEMPT_AUTHORITY_INVALID = "agent attempt authority is invalid";
+
+/**
+ * A refused agent-attempt credential. The detail code names why, so request
+ * telemetry can tell a process that outlived its turn (`caller_stale`) from a
+ * malformed or revoked credential instead of reporting it as unclassified.
+ */
+function agentAttemptAuthorityError(
+  reason: "malformed" | SessionAuthorizationDeniedError["reason"],
+  cause?: unknown,
+): ApiHttpError {
+  const error = new ApiHttpError(403, {
+    code: "forbidden",
+    message: AGENT_ATTEMPT_AUTHORITY_INVALID,
+    retryable: false,
+    outcomeUnknown: false,
+    details: { code: `agent_attempt_${reason}` },
+  });
+  if (cause !== undefined) error.cause = cause;
+  return error;
+}
+
+/**
+ * Trusted payer for a non-agent grant: an authenticated human session pays as
+ * that human; keys and services are service work. An agent attempt must be
+ * resolved through the validated middleware context installed below.
+ */
+export function creditDebitAttributionForGrant(grant: AccessGrant): CreditDebitAttribution {
+  if (grant.principalKind === "agent_attempt") return currentCreditDebitAttribution();
+  return grant.principalKind === "human_session"
+    ? { kind: "human", initiatingHumanSubjectId: grant.subjectId }
+    : ["service", "api_key", "configured_key", "mcp_gateway"].includes(grant.principalKind ?? "")
+      ? { kind: "service" }
+      : { kind: "unknown" };
+}
 
 export async function withAccessGrantSessionRlsContext<T>(
-  deps: ApiRouteDeps,
+  deps: Pick<ApiRouteDeps, "db">,
   grant: AccessGrant,
   fn: () => Promise<T>,
 ): Promise<T> {
   if (grant.principalKind !== "agent_attempt") {
-    return await withSessionRlsActorContext({ subjectId: grant.subjectId }, fn);
+    return await withCreditDebitAttribution(creditDebitAttributionForGrant(grant), () =>
+      withSessionRlsActorContext({ subjectId: grant.subjectId }, fn),
+    );
   }
   const callerSessionId = grant.metadata?.sessionId;
   if (typeof callerSessionId !== "string") {
-    throw new HTTPException(403, { message: "agent attempt authority is invalid" });
+    throw agentAttemptAuthorityError("malformed");
   }
   try {
     const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
@@ -32,20 +76,26 @@ export async function withAccessGrantSessionRlsContext<T>(
         executionGeneration: actor.executionGeneration,
       },
     });
-    return await withSessionRlsActorContext(
+    return await withCreditDebitAttribution(
       {
-        subjectId: actor.subjectId,
-        initiatingHumanSubjectId: actor.initiatingHumanSubjectId,
-        privateFileOwnerSubjectId: learning.defaultScope === "personal" ? learning.subjectId : null,
+        kind: "turn",
+        turnId: actor.turnId,
+        initiatingHumanSubjectId: actor.initiatingHumanSubjectId ?? null,
       },
-      fn,
+      () =>
+        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 agentAttemptAuthorityError(error.reason, 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.
+  }
+}