@opengeni/api-router 3.0.1 → 3.1.2

package/dist/site-sql/service.d.ts

@@ -0,0 +1,213 @@
+import { type SiteSqlDescribeResponse, type SiteSqlErrorCode, type SiteSqlExportFormat, type SiteSqlImportRequest, type SiteSqlImportResponse, type SiteSqlInspectResponse, type SiteSqlLimits, type SiteSqlMigrateResponse, type SiteSqlQueryAudience, type SiteSqlQueryDefinitionRequest, type SiteSqlQueryResponse, type SiteSqlResetResponse, type SiteSqlRunResponse, type SiteSqlValue, type SiteLimitProfileKind } from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { type SiteSqlScope } from "@opengeni/db";
+import { resolveSiteDataAccess, type SiteDataAccess, type SiteDataSurface } from "../site-data/service.js";
+import { type SiteDbFetch } from "./gateway.js";
+/**
+ * Site SQL: optional per-Site Cloudflare storage. One SQLite Durable Object
+ * per Site holds the rows; Postgres holds whether the owner turned it on, the
+ * ordered migrations and the named queries (so the database can always be
+ * rebuilt), usage counters and call windows. Every surface (Site pages through
+ * the workspace API or site-runtime, the console and first-party agent tools)
+ * goes through here: it resolves the caller with Site Data's rules (a Site
+ * frame is always a viewer; managers manage), checks audiences, binds the
+ * viewer's principal into `:viewer` parameters, applies limits, meters usage
+ * in `usage_only` mode, and only then calls the gateway, which re-checks every
+ * statement in the Durable Object.
+ */
+export type SiteSqlDeps = Pick<ApiRouteDeps, "db" | "settings">;
+/** Who is calling: whatever Site Data accepts (an access grant, or a published Site viewer). */
+export type SiteSqlAuthority = Parameters<typeof resolveSiteDataAccess>[1];
+export declare class SiteSqlError extends Error {
+    readonly code: SiteSqlErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: SiteSqlErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** The transport to the gateway; tests replace `fetch`. */
+export declare const siteSqlTransport: {
+    fetch: SiteDbFetch;
+};
+/** Calls per minute all of a Site's managers may make together (console and agents). */
+export declare const SITE_SQL_MANAGER_CALLS_PER_MINUTE = 600;
+/** One export response stops adding rows past this many bytes and returns a next cursor. */
+export declare const SITE_SQL_EXPORT_MAX_BYTES: number;
+/**
+ * Default size of one SQL export piece: well under the 2 MB a SQL import
+ * takes per call, so every piece of a large dump re-imports in one call.
+ */
+export declare const SITE_SQL_EXPORT_SQL_DEFAULT_BYTES: number;
+/** Typed errors from every layer as SiteSqlError. */
+export declare function toSiteSqlError(error: unknown): unknown;
+export type SiteSqlLimitSettings = Pick<SiteSqlDeps["settings"], "sitesSqlFreeStorageBytes" | "sitesSqlFreeRowsReadPerMonth" | "sitesSqlFreeRowsWrittenPerMonth" | "sitesSqlFreeCallsPerMinutePerViewer" | "sitesSqlFreeCallsPerMinutePerSite" | "sitesSqlMaxRowsPerCall" | "sitesSqlMaxResponseBytes" | "sitesCreditsLimitMultiplier">;
+/** The limit profile kinds of published Sites (docs/published-sites.md). */
+export type SiteSqlProfileKind = SiteLimitProfileKind;
+/** Flood brakes that hold under every profile, including unlimited. */
+export declare const SITE_SQL_FLOOD_BRAKES: Readonly<{
+    callsPerMinutePerViewer: 600;
+    callsPerMinutePerSite: 6000;
+}>;
+/**
+ * Site SQL limits for a limit profile: standard and custom use the settings
+ * (custom overrides carry no SQL fields yet), credits multiplies the storage,
+ * monthly row and per-viewer caps, and unlimited removes the monthly caps but
+ * keeps the hard storage ceiling and the flood brakes. Rows per call and
+ * response size are the same everywhere. The per-Site monthly row quotas are
+ * off unless configured (platform usage is metered per workspace instead),
+ * and storage per Site defaults to the hard ceiling.
+ */
+export declare function siteSqlLimits(settings: SiteSqlLimitSettings, kind?: SiteSqlProfileKind): SiteSqlLimits;
+/**
+ * The limit profile in force for a Site, the same one published Sites use:
+ * the Site's own profile, else the workspace default, else standard. Sites that
+ * were never published have no profile of their own.
+ */
+export declare function siteSqlProfileKind(deps: Pick<SiteSqlDeps, "db">, scope: SiteSqlScope): Promise<SiteSqlProfileKind>;
+/**
+ * Why a caller may not run a named query of this audience, or null. Managers
+ * (outside a Site frame) run every query; `managers` admits nobody else;
+ * `signed_in` needs a person (not a guest, and not a service key, agent or
+ * schedule acting on its own); `everyone` admits all.
+ */
+export declare function siteSqlAudienceRefusal(audience: SiteSqlQueryAudience, caller: {
+    manager: boolean;
+    guest: boolean;
+    person: boolean;
+}): SiteSqlError | null;
+export declare function siteSqlChecksum(sql: string): string;
+export declare function describeSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string): Promise<SiteSqlDescribeResponse>;
+/** Turn Site SQL on or off for one Site. Turning it off keeps the data and definitions. */
+export declare function setSiteSqlSettings(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: {
+    enabled: boolean;
+}): Promise<SiteSqlDescribeResponse>;
+/** Create, replace or delete (`request` null) a named query. */
+export declare function defineSiteSqlQuery(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, name: string, request: SiteSqlQueryDefinitionRequest | null): Promise<{
+    query: SiteSqlQueryResponse | null;
+    created: boolean;
+    deleted: boolean;
+}>;
+/**
+ * Add a migration: checked against the Site's migration SQL cap, applied in
+ * the Durable Object together with any earlier migration it is missing (only
+ * those are sent, in bounded calls), then recorded in Postgres, all under the
+ * Site's database lock.
+ */
+export declare function migrateSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: {
+    name: string;
+    sql: string;
+}, options?: {
+    profileKind?: SiteSqlProfileKind;
+}): Promise<SiteSqlMigrateResponse>;
+/**
+ * Reset the Site's database. `schema: "keep"` (default) empties it and applies
+ * every migration again in bounded calls (a rebuild from Postgres); `schema:
+ * "drop"` deletes the database and forgets every migration and named query,
+ * and works whenever the gateway is configured.
+ */
+export declare function resetSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: {
+    schema?: "keep" | "drop" | undefined;
+}): Promise<SiteSqlResetResponse>;
+/**
+ * The Durable Object's tables, columns, row counts and applied migrations.
+ * Works whenever the gateway is configured.
+ */
+export declare function inspectSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string): Promise<SiteSqlInspectResponse>;
+/** The values Opengeni binds for `:viewer`, `:viewer_kind` and `:viewer_signed_in`. */
+export declare function siteSqlPrincipalParams(access: Pick<SiteDataAccess, "caller" | "subjectId">, guest: boolean): Record<string, SiteSqlValue>;
+/**
+ * Run a named query: what Site pages call with `site.sql.run(name, params)`.
+ * Site frames and published viewers are viewers; the query's audience decides
+ * who may run it (siteSqlAudienceRefusal). These calls count toward the
+ * Site's monthly caps. `profileKind` skips reading the limit profile again
+ * when the caller has it; `beforeWrite` runs for write queries before the
+ * call is counted (the published runtime applies its guest write limit).
+ */
+export declare function runSiteSqlQuery(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, name: string, params: Readonly<Record<string, SiteSqlValue>>, surface?: SiteDataSurface, options?: {
+    profileKind?: SiteSqlProfileKind;
+    beforeWrite?: () => Promise<void>;
+}): Promise<SiteSqlRunResponse>;
+/**
+ * One statement from a manager's agent or the console: `read` refuses writes
+ * (rolled back in the Durable Object), `write` allows them. Schema changes
+ * go through migrations so the database can be rebuilt. Management calls
+ * are metered but do not count toward (or stop at) the monthly caps of the
+ * Site's pages; the managers' call rate and the storage cap bound them.
+ *
+ * `asSiteMember`: a published Site's agent in a workspace member's
+ * conversation reads (never writes) the Site's database as that member,
+ * framed to that one Site. The caller checks the viewer is a member; this
+ * refuses guests and anyone without a person, and counts like page calls.
+ */
+export declare function runSiteSqlStatement(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: {
+    sql: string;
+    params?: Record<string, SiteSqlValue> | undefined;
+    maxRows?: number | undefined;
+}, mode: "read" | "write", options?: {
+    asSiteMember?: boolean;
+}): Promise<SiteSqlRunResponse>;
+export type SiteSqlExport = {
+    content: string;
+    contentType: string;
+    filename: string;
+    truncated: boolean;
+    /** Pass back as `cursor` for the next piece; null when this piece ends the export. */
+    nextCursor: string | null;
+};
+/**
+ * Export the Site's data so it can always leave Cloudflare: `sql` (schema and
+ * INSERT statements), `csv` (one table) or `json` (schema and rows per table).
+ * SQL and JSON keep every value; CSV turns values into text. Exports work
+ * whenever the gateway is configured, while Site SQL is off and past the
+ * monthly row caps (they are metered as management). One response holds
+ * about `maxBytes` (16 MiB at most; by default 1 MiB for SQL, so each piece
+ * re-imports in one call, and 16 MiB otherwise); a larger export comes in
+ * pieces: pass
+ * `nextCursor` back as `cursor` and append the pieces in order. Only the
+ * first piece has the header (SQL schema, CSV header row, JSON schema) and
+ * only the last SQL piece has the triggers, so the pieces together re-import
+ * as one dump.
+ */
+export declare function exportSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: {
+    format: SiteSqlExportFormat;
+    table?: string | undefined;
+    cursor?: string | null | undefined;
+    maxBytes?: number | undefined;
+}): Promise<SiteSqlExport>;
+/**
+ * Import data. `sql`: schema statements (tables, views, indexes) become a
+ * migration recorded in Postgres (so a rebuild keeps them), the data
+ * statements run in batches, then triggers become a second migration (so
+ * they do not fire on imported rows); `csv` and `json` insert rows into an
+ * existing table (a CSV header names the columns; an empty cell is NULL).
+ * Batches that ran stay when a later one fails; the error says how much
+ * landed and which migration was recorded. A dump larger than one call
+ * imports piece by piece, in order (the first piece holds the schema, the
+ * last the triggers). Imports are metered as management.
+ */
+export declare function importSiteSql(deps: SiteSqlDeps, authority: SiteSqlAuthority, siteId: string, request: SiteSqlImportRequest): Promise<SiteSqlImportResponse>;
+/**
+ * The Sites of a workspace that have a Site SQL database, read before the
+ * workspace is deleted (its Postgres rows cascade with it; the Durable
+ * Objects do not). Empty when no gateway is configured or the read fails.
+ */
+export declare function siteSqlSitesOfWorkspace(deps: Pick<ApiRouteDeps, "db"> & {
+    settings?: SiteSqlDeps["settings"] | undefined;
+}, scope: {
+    accountId: string;
+    workspaceId: string;
+}): Promise<string[]>;
+export type SiteSqlDropResult = {
+    dropped: string[];
+    failed: string[];
+    skipped: string[];
+};
+/**
+ * Drop the data of Site databases whose workspace was deleted, best effort:
+ * a few at a time, each call bounded, none started after a deadline. Ids
+ * that failed or were not tried are logged in one structured line (the data
+ * stays in its Durable Object until a later sweep; see docs/site-data.md).
+ */
+export declare function dropSiteSqlDatabases(deps: {
+    settings?: SiteSqlDeps["settings"] | undefined;
+}, siteIds: readonly string[], context?: {
+    workspaceId?: string;
+}): Promise<SiteSqlDropResult>;

package/dist/temporal-schedule-sync.d.ts

@@ -0,0 +1,26 @@
+import type { ScheduledTask } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+type TemporalScheduleSyncDependencies = {
+    db: Database;
+    withDeadline<T>(deadline: number, work: () => Promise<T>): Promise<T>;
+    upsert(task: ScheduledTask): Promise<void>;
+    /** Idempotent: an absent Temporal schedule is already removed. */
+    remove(temporalScheduleId: string): Promise<void>;
+};
+/**
+ * Serialize external writes across API replicas, independently of task edits.
+ * A queued sync rereads the newest committed row after acquiring this lock;
+ * input snapshots never become desired state. Cleanup uses the same key, so
+ * an in-flight upsert finishes before its tombstone's external deletion.
+ * Failure compensation commits before releasing the lock, so a queued writer
+ * cannot read the row being restored and then publish that failed edit.
+ *
+ * Deadlines bound both lock admission and network occupancy. A thrown network
+ * error retains its unknown-outcome semantics; this is not durable recovery
+ * for a process crash or a lost Temporal acknowledgement.
+ */
+export declare function createTemporalScheduleSynchronizer(deps: TemporalScheduleSyncDependencies): {
+    sync(task: Pick<ScheduledTask, "id" | "workspaceId" | "temporalScheduleId">, onFailure?: (tx: Database, error: unknown) => Promise<Error>): Promise<void>;
+    remove(temporalScheduleId: string): Promise<void>;
+};
+export {};

package/dist/transcription/billing-refusal.d.ts

@@ -0,0 +1,8 @@
+import type { TranscriptionBillingRefusedError } from "@opengeni/core";
+import type { Context } from "hono";
+/**
+ * Same body shape as session admission refusals (`code` + `message`, plus
+ * allowance `scope`/`resetsAt`), so SDK/React clients classify it as a
+ * definitive credit/allowance refusal rather than a retryable failure.
+ */
+export declare function transcriptionBillingRefusal(c: Context, error: TranscriptionBillingRefusedError): Response;

package/dist/transcription/normalize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode one uploaded recording to 16 kHz mono PCM WAV with a hard decode
+ * ceiling, and measure its duration from the bytes the server produced.
+ */
+export type TranscriptionAudioNormalizer = (input: {
+    audio: Uint8Array;
+    mimeType: string;
+    /** Longest accepted recording; anything longer is refused, never truncated. */
+    maxDurationSeconds: number;
+    signal?: AbortSignal | undefined;
+}) => Promise<{
+    bytes: Uint8Array;
+    durationSeconds: number;
+}>;
+/**
+ * ffmpeg decodes at most `maxDurationSeconds + 1` seconds (`-t`), so a long or
+ * hostile upload costs bounded CPU and disk. Output that reaches that ceiling
+ * was longer than the limit and is refused as `too_large` before any provider
+ * call, so the transcript the user receives is never silently cut short.
+ */
+export declare function createFfmpegAudioNormalizer(input: {
+    ffmpegPath: string;
+}): TranscriptionAudioNormalizer;

package/dist/transcription/providers/azure-mai.d.ts

@@ -0,0 +1,12 @@
+import type { VoiceInputPricing } from "@opengeni/config";
+import type { TranscriptionProvider } from "@opengeni/core";
+/** Azure Speech file transcription; credentials and model selection stay server-side. */
+export declare function createMaiTranscriptionProvider(input: {
+    endpoint: string;
+    apiKey: string;
+    apiVersion: string;
+    model: string;
+    pricing?: VoiceInputPricing | null;
+    ffmpegPath: string;
+    fetch?: typeof fetch;
+}): TranscriptionProvider;

package/dist/transcription/providers/azure-openai.d.ts

@@ -1,3 +1,4 @@
+import { type VoiceInputPricing } from "@opengeni/config";
 import type { TranscriptionProvider } from "@opengeni/core";
 export declare function createAzureOpenAiTranscriptionProvider(input: {
     endpoint: string;
@@ -5,5 +6,8 @@ export declare function createAzureOpenAiTranscriptionProvider(input: {
     apiVersion: string;
     apiKey: string | null;
     adToken: string | null;
+    /** Underlying model of the deployment; defaults to the deployment name. */
+    model?: string;
+    pricing?: VoiceInputPricing | null;
     fetch?: typeof fetch;
 }): TranscriptionProvider;

package/dist/transcription/providers/openai.d.ts

@@ -1,9 +1,25 @@
+import { type VoiceInputPricing, type VoiceInputUsage } from "@opengeni/config";
 import { type TranscriptionProvider, TranscriptionServiceError } from "@opengeni/core";
 export declare function createOpenAiTranscriptionProvider(input: {
     apiKey: string;
     baseUrl: string;
     model: string;
+    pricing?: VoiceInputPricing | null;
     fetch?: typeof fetch;
 }): TranscriptionProvider;
+/**
+ * OpenAI-compatible `/audio/transcriptions` JSON (OpenAI and Azure OpenAI).
+ * `usage` is `{type:"tokens", input_tokens, input_token_details:{audio_tokens,
+ * text_tokens}, output_tokens, total_tokens}` for the gpt-4o-transcribe family
+ * or `{type:"duration", seconds}` for duration-billed models; Whisper
+ * `verbose_json` carries the processed audio `duration`. Unusable usage is
+ * dropped (null), never guessed.
+ */
+export declare function parseTranscriptionResponseBody(body: unknown): {
+    text: string;
+    languages: string[];
+    usage: VoiceInputUsage | null;
+} | null;
+export declare function parseTranscriptionUsage(body: Record<string, unknown>): VoiceInputUsage | null;
 export declare function responseError(status: number): TranscriptionServiceError;
 export declare function fetchError(error: unknown): TranscriptionServiceError;

package/dist/transcription/providers/subscription-core.d.ts

@@ -0,0 +1,39 @@
+import type { Settings } from "@opengeni/config";
+import { TranscriptionServiceError } from "@opengeni/core";
+import { type Database, type SubscriptionCoreConnectionToken, type SubscriptionCoreFetch, type SubscriptionCoreProvider } from "@opengeni/db";
+/**
+ * Once a shared-core provider is selected, its failures are final for that
+ * audio: provider ordering chose the initial provider only (design 6.5).
+ */
+export declare function coreTranscriptionUnavailable(): TranscriptionServiceError;
+export declare function withoutFallback(error: TranscriptionServiceError): TranscriptionServiceError;
+/** Parse a `{ text, language }` transcription body (response already buffered by custody). */
+export declare function coreTranscriptionResult(response: Response): Promise<{
+    text: string;
+    languages: string[];
+}>;
+/**
+ * Transcription on the shared subscription core for any provider (the M3
+ * Codex rule, EP-N01..N04): a sessionless `transcription` operation for the
+ * authenticated caller in an explicit account/workspace context, on a shared
+ * organization- or workspace-scoped connection only, under its own operation
+ * lease and the per-connection refresh lock. One forced refresh and one
+ * retry when the provider refuses the bearer; nothing is retried through
+ * another provider once a connection was selected.
+ */
+export declare function transcribeOnSubscriptionCore(input: {
+    db: Database;
+    settings: Settings;
+    provider: SubscriptionCoreProvider;
+    fetch: SubscriptionCoreFetch;
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestId: string;
+    send: (token: SubscriptionCoreConnectionToken, fetchImpl: SubscriptionCoreFetch) => Promise<Response>;
+    /** The provider refused the bearer (refresh once and retry). */
+    unauthorized: (response: Response) => Promise<boolean>;
+}): Promise<{
+    text: string;
+    languages: string[];
+}>;

package/dist/transcription/service.d.ts

@@ -1,6 +1,7 @@
 import { type Settings } from "@opengeni/config";
-import { type TranscriptionAvailabilityContext, type TranscriptionProvider, type TranscriptionService } from "@opengeni/core";
+import { type TranscriptionAvailabilityContext, type TranscriptionBilling, type TranscriptionProvider, type TranscriptionService } from "@opengeni/core";
 import type { Database } from "@opengeni/db";
+import { type TranscriptionAudioNormalizer } from "./normalize.js";
 export declare function createTranscriptionService(input: {
     settings: Settings;
     db: Database;
@@ -11,6 +12,14 @@ export declare function createTranscriptionService(input: {
     providerRequestTimeoutMilliseconds?: number;
     /** Test seam for evaluating persisted absolute deadlines after delayed setup. */
     now?: () => Date;
+    /** Credit admission/settlement for deployment-funded providers. */
+    billing?: TranscriptionBilling;
+    /** Test seam: trusted one-shot decode + duration (defaults to ffmpeg). */
+    normalizeAudio?: TranscriptionAudioNormalizer;
+    /** Loud operator log for settlement failures after provider success. */
+    log?: (message: string, attributes: Record<string, string | number | boolean>) => void;
+    /** In-process settlement retry pacing after an inline failure. */
+    settlementRetryDelaysMilliseconds?: readonly number[];
 }): TranscriptionService;
 export declare function remainingTranscriptionProviderRequestMilliseconds(providerDeadlineAt: Date, now: Date): number;
 export declare function orderedProviders(providers: readonly TranscriptionProvider[], context: TranscriptionAvailabilityContext): TranscriptionProvider[];

package/dist/transcription/wav-duration.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Duration of a PCM RIFF/WAVE buffer the server itself produced (resumable
+ * provider segments are ffmpeg-normalized WAV). Used only as the trusted
+ * billing fallback when a provider reports no usage; never applied to
+ * client-uploaded bytes. Returns null for anything that is not a well-formed
+ * WAV with a positive byte rate.
+ */
+export declare function wavDurationSeconds(bytes: Uint8Array): number | null;

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

@@ -0,0 +1,37 @@
+import type { ToolGatewayCatalog, ToolGatewayIdentity } from "@opengeni/contracts";
+/**
+ * Content-free memory of complete workspace tool catalogs this API process
+ * produced for one exact caller scope.
+ *
+ * A complete catalog digest covers every enabled connector, so verifying a
+ * call's `catalogDigest` used to require connecting and listing every
+ * connector again. The attestation remembers, per complete digest, only the
+ * canonical digest of each entry. A later call can then prepare just its
+ * target connector live and prove that the entry it is about to execute is
+ * byte-for-byte the entry its caller saw in that complete catalog.
+ *
+ * It never stores credentials, prepared gateways, connections, schemas,
+ * arguments, or results, and grants no authority: every call still resolves
+ * live caller, account, connection, policy, and Site authority. A miss,
+ * expiry, or entry mismatch falls back to complete preparation and the exact
+ * historical stale-catalog contract.
+ */
+export type WorkspaceToolGatewayCatalogAttestations = {
+    record(scope: string, catalog: Pick<ToolGatewayCatalog, "digest" | "entries">): void;
+    /** The attested entry digest, or `undefined` when the catalog is unknown or expired. */
+    entryDigest(scope: string, catalogDigest: string, identity: ToolGatewayIdentity): string | undefined;
+    /** Entry digests currently retained (bounded by `maxEntries`). */
+    readonly retainedEntries: number;
+};
+export type WorkspaceToolGatewayCatalogAttestationOptions = {
+    /** Fixed lifetime from complete preparation; use never extends it. */
+    ttlMs?: number;
+    maxScopes?: number;
+    maxCatalogsPerScope?: number;
+    /** Global bound on retained entry digests across all scopes and catalogs. */
+    maxEntries?: number;
+    now?: () => number;
+};
+export declare const WORKSPACE_TOOL_GATEWAY_ATTESTATION_TTL_MS: number;
+export declare function createWorkspaceToolGatewayCatalogAttestations(options?: WorkspaceToolGatewayCatalogAttestationOptions): WorkspaceToolGatewayCatalogAttestations;
+export declare function digestWorkspaceToolGatewayCatalogEntry(entry: unknown): string;

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

@@ -3,6 +3,22 @@ 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";
+export declare function recordWorkspaceToolTargetOperation(observability: Observability | null | undefined, input: {
+    operation: "resolve" | "invoke" | "target-approvals" | "manifest";
+    outcome: "ok" | "failed";
+    durationSeconds: number;
+}): void;
+/**
+ * Bounded preparation telemetry: how long the request spent constructing,
+ * credentialing, connecting, and listing connectors before any execution, and
+ * whether a call used target-only preparation through a catalog attestation.
+ */
+export declare function recordWorkspaceToolGatewayPreparation(observability: Observability | null | undefined, input: {
+    operation: "catalog" | "call";
+    scope: "complete" | "target";
+    attestation: "hit" | "miss" | "mismatch" | "bypass" | "record";
+    durationSeconds: number;
+}): void;
 /**
  * Low-cardinality gateway telemetry shared by HTTP/SDK/Site and aggregate MCP
  * adapters. Tool names, workspace/subject ids, arguments, results, credentials,

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

@@ -0,0 +1,27 @@
+/**
+ * `{{secret:…}}` resolution for workspace tool gateway calls made by people,
+ * services and Sites (GW-4). The prepared gateway may serve many calls, so
+ * the Site context is request-local: a Site call resolves with the viewer's
+ * reach (`site_viewer`), any other call with the calling human or service.
+ * Values replace references only in the deep copy the gateway executes; the
+ * approval digest stays bound to the references.
+ */
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+import { type Settings } from "@opengeni/config";
+import { type AccessGrant, type SecretPrincipal } from "@opengeni/contracts";
+import type { Database } from "@opengeni/db";
+import type { ToolGatewayArgumentResolver } from "@opengeni/tool-gateway";
+export type SiteSecretContext = {
+    siteId: string;
+    siteVersion: string;
+};
+/** Runs `run` with the validated Site (or explicitly no Site) as secret context. */
+export declare function withSiteSecretContext<T>(context: SiteSecretContext | null, run: () => T): T;
+export declare function workspaceGatewaySecretPrincipal(grant: AccessGrant, site: SiteSecretContext | null): SecretPrincipal;
+export declare function workspaceGatewaySecretArguments(input: {
+    db: Database;
+    settings: Settings;
+    grant: AccessGrant;
+    /** Connected vaults (1Password, host) for the resolved acting subject. */
+    providersForSubject?: ((subjectId: string | null) => VaultProviderRegistry) | undefined;
+}): ToolGatewayArgumentResolver;

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

@@ -1,12 +1,16 @@
 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 { ToolGatewayCallRequest, ToolGatewayCallResponse, ToolGatewayDeclarationsResponse, type AccessGrant, type ToolGatewayCatalog, type ToolGatewayIdentity, type ToolGatewayTarget } from "@opengeni/contracts";
 import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
-import { consumeToolGatewayApproval, getWorkspaceArtifactContentRef, issueToolGatewayApproval } from "@opengeni/db";
+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 { TargetAuthorityFence } from "./workspace-tool-target-fence.js";
+import { type WorkspaceToolGatewayCatalogAttestations } from "./workspace-tool-gateway-attestations.js";
 import type { Observability } from "@opengeni/observability";
+import { type PublishedSiteToolAuthorization } from "./site-publishing/page-tool-authority.js";
+export type WorkspaceToolGatewayAuthorization = AccessGrantAuthorization | PublishedSiteToolAuthorization;
 export type PreparedWorkspaceToolGateway = Pick<PreparedWorkspaceToolGatewayTools, "toolGateway" | "toolGatewayCatalog" | "close"> & {
     toolGateway: NonNullable<PreparedWorkspaceToolGatewayTools["toolGateway"]>;
     toolGatewayCatalog: NonNullable<PreparedWorkspaceToolGatewayTools["toolGatewayCatalog"]>;
@@ -23,8 +27,60 @@ type WorkspaceSiteToolContext = {
 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 requireWorkspaceToolGatewayAuthorization(authorization: WorkspaceToolGatewayAuthorization): AccessGrant;
+export declare function prepareWorkspaceToolGateway(routeDeps: ApiRouteDeps, authorization: WorkspaceToolGatewayAuthorization, options?: {
+    /**
+     * Prepare only these exact (account-qualified) identities. Servers outside
+     * them are never constructed, credentialed, connected, or listed; the
+     * resulting catalog and digest describe only this subset.
+     */
+    allowedIdentities?: readonly ToolGatewayIdentity[];
+} & WorkspaceToolGatewayPreparationOptions): Promise<PreparedWorkspaceToolGateway>;
+/**
+ * Bounded caller scope for catalog attestations. It binds the exact caller,
+ * actor class, and permission set; attestations still grant no authority.
+ */
+export declare function workspaceToolGatewayAttestationScope(authorization: AccessGrantAuthorization): string;
+export type WorkspaceToolGatewayPreparationScope = "complete" | "target";
+export type WorkspaceToolGatewayAttestationOutcome = "hit" | "miss" | "mismatch" | "bypass";
+export type WorkspaceToolGatewayTiming = {
+    /** Wall time spent preparing gateways (all preparations, including fallback). */
+    prepareMs: number;
+    /** Wall time from the last successful preparation to the response. */
+    callMs: number;
+    scope: WorkspaceToolGatewayPreparationScope;
+    attestation: WorkspaceToolGatewayAttestationOutcome;
+};
+/** Prepare one complete current-caller catalog and remember its content-free attestation. */
+export declare function prepareAttestedWorkspaceToolGateway(routeDeps: ApiRouteDeps, authorization: AccessGrantAuthorization, attestations: WorkspaceToolGatewayCatalogAttestations | undefined, prepare?: typeof prepareWorkspaceToolGateway): Promise<PreparedWorkspaceToolGateway>;
+/**
+ * HTTP/SDK/Site call adapter. When the caller's `catalogDigest` names a
+ * complete catalog this process prepared for the same caller scope, only the
+ * target identity's connector is prepared live and its entry must match the
+ * attested entry exactly. Every other case (approval capability, unknown or
+ * expired digest, missing/changed entry) prepares the complete catalog and
+ * applies the unchanged stale-catalog contract.
+ */
+export declare function callWorkspaceToolGatewayForCaller(routeDeps: ApiRouteDeps, authorization: AccessGrantAuthorization, request: ToolGatewayCallRequest, options?: {
+    attestations?: WorkspaceToolGatewayCatalogAttestations;
+    observability?: Observability;
+    /** Must enforce current-caller gateway authorization before provider work. */
+    prepare?: typeof prepareWorkspaceToolGateway;
+    authorizeSiteTool?: AuthorizeWorkspaceSiteTool;
+    resolveOrigin?: typeof resolveSiteSessionOrigin;
+    /** Called once with the preparation split, whether the call succeeds or fails. */
+    onPreparation?: (preparation: Pick<WorkspaceToolGatewayTiming, "prepareMs" | "scope" | "attestation">) => void;
+}): Promise<{
+    response: ToolGatewayCallResponse;
+    timing: WorkspaceToolGatewayTiming;
+}>;
+/** Content-free Server-Timing for gateway preparation versus execution. */
+export declare function workspaceToolGatewayServerTiming(timing: {
+    prepareMs: number;
+    callMs?: number;
+    scope: WorkspaceToolGatewayPreparationScope;
+    attestation?: WorkspaceToolGatewayAttestationOutcome;
+}): string;
 export declare function prepareMcpOAuthWorkspaceToolGateway(routeDeps: ApiRouteDeps, grant: AccessGrant, allowedIdentities: readonly {
     serverId: string;
     toolName: string;
@@ -32,7 +88,41 @@ export declare function prepareMcpOAuthWorkspaceToolGateway(routeDeps: ApiRouteD
 export declare function prepareWorkspaceToolGatewayForGrant(routeDeps: ApiRouteDeps, grant: AccessGrant, allowedIdentities?: readonly {
     serverId: string;
     toolName: string;
-}[]): Promise<PreparedWorkspaceToolGateway>;
+}[], options?: WorkspaceToolGatewayPreparationOptions): Promise<PreparedWorkspaceToolGateway>;
+export type WorkspaceToolGatewayPreparationOptions = {
+    target?: ToolGatewayTarget;
+    signal?: AbortSignal;
+    /** Trusted transport callback, never a request-body field. */
+    reauthorize?: () => Promise<void>;
+    /**
+     * Trusted per-request live fence of a targeted or manifest request (never a
+     * request-body field). Required with `target`; replaces `reauthorize`.
+     */
+    fence?: TargetAuthorityFence;
+    /**
+     * Settings visible to first-party (opengeni/files/docs) tool handlers.
+     * `prepared` (default, MCP OAuth): the identity-narrowed server set.
+     * `caller`: the complete caller-authorized set, so a target-only call
+     * executes exactly as it would from the complete gateway.
+     */
+    firstPartySettings?: "prepared" | "caller";
+};
+/** 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>;
+/**
+ * Credential boundary of a fenced targeted request. Before an execution-mode
+ * resolve (which may refresh a token or record use) only the live caller is
+ * checked. The returned hook runs immediately before one physical provider
+ * request: the native hook, then (targeted) a non-refreshing native preflight
+ * that must still name the same connection version, then one full fence
+ * evaluation, the hook's last step. A hook retained past the request scope
+ * reads nothing.
+ */
+export declare function withTargetFenceConnectionAuthorization(resolve: ReturnType<typeof buildConnectionTokenResolver>, fence: Pick<TargetAuthorityFence, "caller" | "allows" | "assertOpen">, options: {
+    preflight: boolean;
+}): ReturnType<typeof buildConnectionTokenResolver>;
+/** Select one authorized connector without constructing any provider. */
+export declare function workspaceToolGatewayTargetServer(settings: Pick<Settings, "mcpServers">, target: ToolGatewayTarget): string;
 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;
@@ -115,7 +205,13 @@ export declare function approveWorkspaceToolGatewayCall(prepared: PreparedWorksp
     approvalToken: string;
     expiresAt: string;
 }>;
-export declare function requireWorkspaceSiteToolAuthorization(db: ApiRouteDeps["db"], grant: AccessGrant, context: WorkspaceSiteToolContext, resolveVersion?: typeof getWorkspaceArtifactContentRef): Promise<void>;
+export declare function throwWorkspaceToolGatewayHttpError(error: unknown): never;
+/** A saved Site version, only when the caller can see the Site. */
+export type WorkspaceSiteVersionResolver = (db: ApiRouteDeps["db"], grant: AccessGrant, artifactId: string, versionId: string) => Promise<{
+    status: Awaited<ReturnType<typeof getWorkspaceArtifactContentRef>>["status"];
+    version: Pick<Awaited<ReturnType<typeof getWorkspaceArtifactContentRef>>["version"], "id" | "requestedTools">;
+}>;
+export declare function requireWorkspaceSiteToolAuthorization(db: ApiRouteDeps["db"], grant: AccessGrant, context: WorkspaceSiteToolContext, resolveVersion?: WorkspaceSiteVersionResolver): Promise<void>;
 export declare function toolGatewayCatalogResponse(catalog: ToolGatewayCatalog): ToolGatewayCatalog;
 export declare function workspaceToolGatewayDeclarations(prepared: PreparedWorkspaceToolGateway): ToolGatewayDeclarationsResponse;
 export {};