@opengeni/api-router 3.0.1 → 3.1.2

package/dist/site-agent-guard.d.ts

@@ -0,0 +1,53 @@
+import { type ApiRouteDeps, type SiteClampedResource } from "@opengeni/core";
+import type { Context, Next } from "hono";
+/**
+ * The only writes (any method but `GET`, `HEAD` and `OPTIONS`) a
+ * Site-started agent may send under `/v1/workspaces/:workspaceId`, matched
+ * on the path after the workspace id. Every other write is refused, so a
+ * route family added later starts closed to it.
+ */
+export declare const SITE_AGENT_WRITES: readonly RegExp[];
+/**
+ * Writes open to a Site-started agent for one method only, where the same
+ * path also manages something. A Site's named query runs with `POST`
+ * (exactly what its page may call, under the query's audience; Site SQL's
+ * own clamp limits it to the Site the agent was started from), while `PUT`
+ * and `DELETE` on that path define and delete the query and stay closed, as
+ * does every other Site SQL route (settings, migrations, ad hoc statements,
+ * import and reset).
+ */
+export declare const SITE_AGENT_METHOD_WRITES: readonly {
+    method: string;
+    pattern: RegExp;
+}[];
+/**
+ * Whether a Site-started agent may send a `method` write to `path` (before
+ * the Site content rule). Without a method only the path-wide allowlist
+ * applies.
+ */
+export declare function siteAgentMayWrite(path: string, method?: string): boolean;
+/** What a refused write to `path` names. */
+export declare function siteAgentWriteResource(path: string): SiteClampedResource;
+/**
+ * Server-side boundary for agents started from a Site page (a published
+ * Site, or a console frame). Such an agent acts with the page's reach: it
+ * does not learn and cannot widen anyone's access. Under
+ * `/v1/workspaces/:workspaceId` it may send only the writes in
+ * `SITE_AGENT_WRITES` (its tools, its conversations, files and content, and
+ * reads sent as POST) and `SITE_AGENT_METHOD_WRITES` (running a Site's named
+ * SQL queries); any other write, including `PATCH` or `DELETE` on the
+ * workspace itself and browser or computer sessions (which can drive the
+ * viewer's Chrome or screen), is refused with 403 before the route runs. It also
+ * changes a published Site's content only for a Site it was started from.
+ * Reads are unaffected, and so is every caller that is not a Site-clamped
+ * agent. The first-party tools that write workspace state (`knowledge_save`,
+ * `instruction_policy_save`, `secret_save`, `skill_save`,
+ * `company_profile_propose`, the Connected Machine, sandbox environment and
+ * fleet tools (`run_on`, `sandbox_attach`, `sandbox_swap`,
+ * `sandbox_provision`), the artifact tools and their siblings) check the
+ * same clamp themselves.
+ *
+ * Paths are matched as Hono routes them (`c.req.path`, percent-decoded), so
+ * an encoded segment cannot reach a route this guard did not recognize.
+ */
+export declare function siteClampedAgentGuard(deps: ApiRouteDeps): (c: Context, next: Next) => Promise<void>;

package/dist/site-data/operations.d.ts

@@ -0,0 +1,103 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { SiteDataCollectionDefinitionRequest, SiteDataDescribeResponse, SiteDataFileScope, SiteDataImportRequest, SiteDataQueryRequest, SiteDataWriteOperation } from "@opengeni/contracts";
+import { type SiteDataFile, type SiteDataRecord } from "@opengeni/db";
+import { type SiteDataAuthority, type SiteDataDeps, type SiteDataSurface } from "./service.js";
+/** Shared Site Data operations for HTTP routes, the Site bridge and agent tools. */
+export declare const SITE_DATA_EXPORT_MAX_RECORDS = 10000;
+export declare const SITE_DATA_IMPORT_MAX_RECORDS = 1000;
+/** CSV imports accept at most this many columns. */
+export declare const SITE_DATA_IMPORT_MAX_COLUMNS = 1000;
+/** CSV exports name at most this many data columns; wider data goes in one JSON column. */
+export declare const SITE_DATA_EXPORT_MAX_COLUMNS = 200;
+/** Exports stop adding records past this many bytes and report truncation. */
+export declare const SITE_DATA_EXPORT_MAX_BYTES: number;
+export declare function describeSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string): Promise<SiteDataDescribeResponse>;
+export declare function defineSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string, definition: SiteDataCollectionDefinitionRequest): Promise<{
+    collection: import("@opengeni/db").SiteDataCollection;
+    created: boolean;
+}>;
+export declare function deleteSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string): Promise<{
+    deletedRecords: number;
+}>;
+export declare function resetSiteDataCollection(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, name: string): Promise<{
+    deletedRecords: number;
+}>;
+export declare function querySiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, query: SiteDataQueryRequest, surface?: SiteDataSurface): Promise<import("@opengeni/db").SiteDataQueryResult>;
+export declare function getSiteDataRecord(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, request: {
+    collection: string;
+    id?: string | undefined;
+    key?: string | undefined;
+}, surface?: SiteDataSurface): Promise<SiteDataRecord | null>;
+export declare function writeSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, operations: SiteDataWriteOperation[], surface?: SiteDataSurface): Promise<{
+    results: import("@opengeni/db").SiteDataWriteResultItem[];
+    summary: import("@opengeni/db").SiteDataWriteSummary;
+}>;
+/** RFC 4180 CSV: quoted fields, doubled quotes, CRLF or LF rows. */
+/**
+ * Parse CSV text into rows (the first is the header). Optional limits stop
+ * parsing as soon as a row has too many cells or there are too many records,
+ * before any record is built.
+ */
+export declare function parseSiteDataCsv(text: string, limits?: {
+    maxColumns?: number;
+    maxRecords?: number;
+}): string[][];
+export declare function siteDataCsvCell(value: unknown): string;
+/**
+ * Turn import CSV into records: the header names dotted data paths. Column
+ * and row caps apply while parsing, before any record is built, and each
+ * record is built in one pass.
+ */
+export declare function siteDataCsvRecords(csv: string): Record<string, unknown>[];
+export declare function importSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, collection: string, request: SiteDataImportRequest): Promise<{
+    imported: number;
+}>;
+/**
+ * An import's error, with how many records it had already imported. Once a
+ * batch committed, sending the same import again would duplicate it, so the
+ * error is no longer retryable and its message says what was imported.
+ */
+export declare function siteDataImportFailure(error: unknown, imported: number): unknown;
+/**
+ * About how much JSON a CSV becomes once parsed: its text, plus the header
+ * repeated as field names on every row.
+ */
+export declare function csvValidationBytes(csv: string): number;
+export declare function exportSiteData(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, collection: string, format: "json" | "csv"): Promise<{
+    collection: string;
+    format: "json" | "csv";
+    records: number;
+    truncated: boolean;
+    content: string;
+}>;
+export declare function uploadSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, input: {
+    name: string | null | undefined;
+    contentType: string | null | undefined;
+    /**
+     * The file's bytes, or a reader for a request body: it is called only
+     * after access, the rate window and the quota (with the declared size,
+     * when known) have passed, so refused uploads are never read.
+     */
+    body: Uint8Array | {
+        declaredBytes?: number | undefined;
+        read: () => Promise<Uint8Array>;
+    };
+    scope?: SiteDataFileScope | undefined;
+}, surface?: SiteDataSurface): Promise<SiteDataFile>;
+export declare function listSiteDataFiles(deps: SiteDataDeps, grant: SiteDataAuthority, siteId: string, options: {
+    limit?: number;
+    cursor?: string | null;
+}, surface?: SiteDataSurface): Promise<{
+    files: SiteDataFile[];
+    nextCursor: string | null;
+}>;
+export declare function getSiteDataFileUrl(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, fileId: string, surface?: SiteDataSurface, audience?: "public" | "sandbox"): Promise<{
+    file: SiteDataFile;
+    url: string;
+    expiresAt: string;
+}>;
+export declare function deleteSiteDataFile(deps: SiteDataDeps & Pick<ApiRouteDeps, "objectStorage">, grant: SiteDataAuthority, siteId: string, fileId: string, surface?: SiteDataSurface): Promise<{
+    deleted: {
+        id: string;
+    };
+}>;

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

@@ -0,0 +1,203 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { AccessGrant, SiteDataDescribeResponse } from "@opengeni/contracts";
+import { type Database, type SiteDataCaller, type SiteDataLimits, type SiteDataSite, type SiteDataStore, type SiteDataWriteOptions, type SiteDataWriteSummary } from "@opengeni/db";
+/**
+ * Site Data service: resolves who is calling (manager or viewer, and their
+ * principal), applies Site state rules, and wires validation and usage
+ * metering into the backend-neutral store. Every surface (HTTP, the Site
+ * bridge, first-party agent tools) goes through here.
+ */
+export type SiteDataDeps = Pick<ApiRouteDeps, "db" | "settings">;
+export type SiteDataAccess = {
+    site: SiteDataSite;
+    caller: SiteDataCaller;
+    subjectId: string | null;
+    store: SiteDataStore;
+    limits: SiteDataLimits;
+    writeOptions: SiteDataWriteOptions;
+};
+/** One store per database handle. */
+export declare function siteDataStore(db: Database): SiteDataStore;
+export declare function siteDataLimits(settings: ApiRouteDeps["settings"]): SiteDataLimits;
+export declare function publicSiteDataLimits(limits: SiteDataLimits): SiteDataDescribeResponse["limits"];
+/** Most schema nodes (objects or booleans) a collection schema may have. */
+export declare const SITE_DATA_MAX_SCHEMA_NODES = 2000;
+/** Most properties one object schema may name (CSV imports allow 1,000 columns). */
+export declare const SITE_DATA_MAX_SCHEMA_PROPERTIES = 1000;
+/** Most branches one allOf, anyOf or oneOf may have. */
+export declare const SITE_DATA_MAX_SCHEMA_BRANCHES = 16;
+/** Most enum values a whole collection schema may list. */
+export declare const SITE_DATA_MAX_SCHEMA_ENUM_TOTAL = 500;
+/** Deepest schema nesting a collection schema may have. */
+export declare const SITE_DATA_MAX_SCHEMA_DEPTH = 16;
+/** Most values an `enum` may list. */
+export declare const SITE_DATA_MAX_SCHEMA_ENUM = 100;
+/**
+ * Most checks a schema may run on each repeated value (an array element or an
+ * additional property): see siteDataSchemaRepeatedCost. A record can repeat a
+ * value up to about 128K times, so this bounds the cost of checking it.
+ */
+export declare const SITE_DATA_MAX_SCHEMA_REPEATED_COST = 600;
+/**
+ * Validators with more generated code than this run unoptimized, about four
+ * times slower (measured), so their repeated cost counts four times.
+ */
+export declare const SITE_DATA_LARGE_VALIDATOR_SOURCE = 200000;
+/** Every keyword a collection schema may use. */
+export declare const SITE_DATA_SCHEMA_KEYWORDS: readonly string[];
+/**
+ * The most checks a schema runs on one repeated value: an array element or an
+ * additional property's value, which a record can hold about 128K of. Each
+ * schema object costs 1, plus 1 per enum value, property and required name;
+ * an allOf, anyOf or oneOf branch costs 6 (a failed branch is the costliest
+ * check, measured). Branches apply to the same value, so their costs add;
+ * children apply to different values, so only the costliest counts. Per node:
+ *
+ * - all(n): the costliest value n's subtree checks, n's own value included;
+ * - repeated(n): the costliest value below n that sits under `items` or
+ *   `additionalProperties`.
+ *
+ * Both are upper bounds, computed in one pass over the schema.
+ */
+export declare function siteDataSchemaRepeatedCost(schema: unknown): number;
+/**
+ * Walk a collection schema against the keyword allowlist, counting nodes,
+ * properties, enum values and depth, then bound its cost per repeated value.
+ * Returns the first problem, or null when the schema is supported.
+ */
+export declare function siteDataSchemaProblem(schema: unknown): string | null;
+/** Compiled validators currently cached (for tests). */
+export declare function siteDataSchemaCacheSize(): number;
+export declare function validateSiteDataRecord(schema: Record<string, unknown>, data: Record<string, unknown>): string | null;
+/** Check a collection's JSON Schema is supported and compiles before it is stored. */
+export declare function assertSiteDataSchema(schema: Record<string, unknown> | null | undefined): void;
+/** Total record JSON one write, batch or import request may carry. */
+export declare const SITE_DATA_MAX_REQUEST_RECORD_BYTES: number;
+/**
+ * Schema validation time one request may spend, checked before each record
+ * after the first, so one record always completes.
+ */
+export declare const SITE_DATA_VALIDATION_BUDGET_MS = 250;
+/** Validation time every validating request reserves at admission. */
+export declare const SITE_DATA_VALIDATION_RESERVE_BASE_MS = 25;
+/** Additional reservation per byte of JSON the request validates (1 µs). */
+export declare const SITE_DATA_VALIDATION_RESERVE_MS_PER_BYTE = 0.001;
+/** How far a write may pass its reservation before records that grew are sent again. */
+export declare const SITE_DATA_VALIDATION_RESERVE_SLACK_MS = 25;
+/**
+ * The validation time a request reserves at admission: a base plus a little
+ * per byte it will validate, capped at the request budget. Small requests
+ * reserve little, so many can run at once; an overrun is charged when the
+ * request settles.
+ */
+export declare function siteDataValidationReservationMs(bytes: number): number;
+/**
+ * Bytes of JSON in these values, counting only until the reservation would
+ * reach the budget (larger requests reserve the whole budget anyway).
+ */
+export declare function siteDataValidationBytes(values: Iterable<unknown>): number;
+/** The clock validation time is measured with; tests replace `now`. */
+export declare const siteDataValidationClock: {
+    now: () => number;
+};
+/** Schema compile and validation time one request spent, in milliseconds. */
+export type SiteDataValidationMeter = {
+    ms: number;
+};
+/**
+ * Check a write, batch or import before the store takes the Site's lock:
+ *
+ * - its records total at most 4 MB of JSON (`quota_exceeded`, `request_bytes`);
+ * - every insert and put record matches its collection's schema;
+ * - every patch and increment result, merged from the stored record, matches
+ *   too (if the record changes before the lock, the write checks it again);
+ * - schema compiling and validation spend at most 250 ms per request: once
+ *   anything was compiled or checked, each later operation is refused before
+ *   it runs when the budget is spent, and the event loop gets a turn after
+ *   every compile or check, even for a skipped record.
+ *
+ * Every millisecond spent, here and inside the write, is added to `meter`
+ * for the caller to settle. Returns write options that skip re-validating
+ * the records already checked and keep any check left for inside the write on
+ * the same budget. Inside the write only this request's compiled validators
+ * are used: a schema that changed since is a retryable `conflict`
+ * (reason `schema_changed`), never a compile under the Site's lock.
+ *
+ * With `reservedMs` (what the request reserved at admission), every patch
+ * or increment result it checks is counted at 1 µs per byte of JSON, and one
+ * is refused before it is checked when the request's total would pass its
+ * reservation by more than 25 ms. That happens when a record grew after
+ * admission (a large write landing first): a retryable `conflict` (reason
+ * `record_grew`), so the retry reserves for its real size. A re-check inside
+ * the write first uses what the check before the lock already counted, so
+ * only real growth counts. Inserts, puts and imports carry their data at
+ * admission and stay on the time budget, as does a reservation already at
+ * the budget (a retry could not reserve more).
+ */
+export declare function prevalidateSiteDataWrite(access: Pick<SiteDataAccess, "store" | "caller" | "limits" | "writeOptions">, operations: readonly unknown[], options?: {
+    budgetMs?: number;
+    meter?: SiteDataValidationMeter;
+    reservedMs?: number;
+}): Promise<SiteDataWriteOptions>;
+/**
+ * The record owner: the person, or the person an agent or schedule acts for.
+ * A person-less agent owns records as its scheduled task when a schedule's
+ * run created its session (`schedule:<taskId>`, stable across runs), and as
+ * its own session otherwise (`agent:session:<sessionId>`).
+ */
+export declare function siteDataPrincipal(grant: AccessGrant, subjectId: string | null, scheduledTaskId?: string | null): string;
+/** The writer recorded on records: agents are distinct from the person they act for. */
+export declare function siteDataActor(grant: AccessGrant, subjectId: string | null): string;
+/**
+ * Managers may manage the Site's data, each with `artifacts:publish`: its
+ * owner, a workspace admin, an agent acting for one of those people, or a
+ * person-less workspace API key, configured key or service credential. A Site
+ * without an owner is managed by its creator. An agent without a person (for
+ * example a person-less scheduled task) is a viewer, whatever credential
+ * started it. Agents whose session came from a Site page are clamped to that
+ * Site's viewer rules in resolveSiteDataAccess.
+ */
+export declare function siteDataRole(grant: AccessGrant, site: Pick<SiteDataSite, "ownerSubjectId" | "createdBySubjectId">, subjectId: string | null): "manager" | "viewer";
+export type SiteDataSurface = {
+    /** The pinned Site id a host attached to a Site-originated request. */
+    frameSiteId?: string | null;
+    /** Management surfaces: describe, define, delete, reset, import, export. */
+    management?: boolean;
+};
+/**
+ * A viewer of a published Site, resolved and authorized by site-runtime (the
+ * gateway-signed API): a signed-in person (`user:<subject>`) or an anonymous
+ * guest (`guest:<visitor>`). Always a framed viewer of exactly this Site;
+ * guests reach only what each collection's guest rule allows.
+ */
+export type PublishedSiteDataViewer = {
+    kind: "published_viewer";
+    accountId: string;
+    workspaceId: string;
+    site: SiteDataSite;
+    principal: string;
+    guest: boolean;
+};
+/** Who is calling Site Data: an access grant, or a published Site viewer. */
+export type SiteDataAuthority = AccessGrant | PublishedSiteDataViewer;
+/**
+ * Resolve the Site and caller. not_found when the caller cannot see the Site
+ * (by audience); forbidden for an archived Site (viewers and Site frames) and
+ * for management by anyone but a manager outside the Site frame.
+ */
+export declare function resolveSiteDataAccess(deps: SiteDataDeps, authority: SiteDataAuthority, siteId: string, surface?: SiteDataSurface): Promise<SiteDataAccess>;
+/**
+ * Usage metering in `usage_only` mode (docs/credit-boundaries-rollout.md): the
+ * workspace pays for viewer-triggered usage; events are recorded in the write
+ * transaction and never debit credits until a reviewed rate is enabled. The
+ * workspace's Site storage level (Site SQL plus Site Data) is refreshed in
+ * its platform usage in the same transaction; any charge for it settles with
+ * the next platform usage the API meters (a Site SQL call or a gateway
+ * request report).
+ */
+export declare function meterSiteData(tx: Database, grant: Pick<AccessGrant, "accountId" | "workspaceId">, caller: SiteDataCaller, subjectId: string | null, kind: "write" | "upload", summary: SiteDataWriteSummary): Promise<void>;
+/** Normalize and check a declared upload type; images and PDFs must match their bytes. */
+export declare function siteDataFileContentType(declared: string | null | undefined, bytes: Uint8Array): string;
+export declare function siteDataFileName(name: string | null | undefined): string;
+export declare function siteDataObjectKey(workspaceId: string, siteId: string, fileId: string): string;
+export declare function sha256Hex(bytes: Uint8Array): string;

package/dist/site-frame-guard.d.ts

@@ -0,0 +1,32 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Context, Next } from "hono";
+import { ApiHttpError } from "./http/api-error.js";
+/**
+ * Server-side boundary for requests a host forwarded from a Site frame (the
+ * console bridge, a Codemode preview). Hosts already hold Site code to the
+ * `SITE_OPERATIONS` allowlist; the API enforces it again for any request that
+ * carries the host's frame headers:
+ *
+ * - only allowlisted operations reach a handler;
+ * - Site Data only for the frame's own published Site (403, as the Site Data
+ *   service's own frame clamp answers);
+ * - a session list names only the frame's own Site;
+ * - a per-session operation reaches only a session the same Site (or, for a
+ *   frame without a published Site, the same mounted frame) started; anything
+ *   else is the same 404 as a missing session;
+ * - a message, draft, queue or control body carries only the fields Site
+ *   code may set (`siteFrameBodyRefusal`): text and how the model answers it.
+ *   Approval decisions, answers to questions, resources, personal resource
+ *   attachments, MCP credential updates, connection accounts and model
+ *   context are refused with 403 `site_frame_field_forbidden`; the person
+ *   gives those in the console. Session creates get the same treatment in
+ *   the create route, which also applies the minimal Site profile;
+ * - a session operation runs inside its validated Site origin, so every
+ *   session or turn it starts records which Site it came from.
+ *
+ * Ordinary handlers still authorize every allowed operation with the
+ * viewer's own authority.
+ */
+export declare function siteFrameGuard(deps: ApiRouteDeps): (c: Context, next: Next) => Promise<void>;
+/** 403 for a body field Site code may not send; names the field, never its value. */
+export declare function siteFrameFieldForbidden(field: string): ApiHttpError;

package/dist/site-publishing/agent-data-tools.d.ts

@@ -0,0 +1,84 @@
+import { type FirstPartyMcpToolName, type SiteLimitProfileKind } from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { type SiteRuntimeConversationViewerKind } from "@opengeni/db";
+import type { PublishedSiteDataViewer } from "../site-data/service.js";
+import { type SiteRuntimeHost } from "./runtime.js";
+/**
+ * A published Site's own data tools for its agent. Every Site agent
+ * conversation (members, invited people and public visitors) gets them,
+ * pinned on the server to that Site and acting as the conversation's viewer:
+ * the same audience checks and row binding as the Site's page (per-viewer
+ * collections, owner binding, `:viewer` and query audiences such as
+ * `signed_in` or `managers`). Site management tools (publication, migrate,
+ * define, reset, import, export, enable, files and so on) are never given.
+ *
+ * - `site_data_query`, `site_data_write`: the Site's collections under the
+ *   viewer's access rules (guests only what each collection's guest rule allows).
+ * - `site_sql_run`: the Site's named queries, when Site SQL is on.
+ * - `site_sql_query`: read-only statements, for workspace members only, when
+ *   Site SQL is on.
+ */
+export declare const SITE_AGENT_DATA_TOOLS: readonly ["site_data_query", "site_data_write"];
+export declare const SITE_AGENT_SQL_TOOLS: readonly ["site_sql_run"];
+export declare const SITE_AGENT_MEMBER_SQL_TOOLS: readonly ["site_sql_query"];
+/** The first-party permissions those tools need (Site Data writes need publish). */
+export declare const SITE_AGENT_DATA_TOOL_PERMISSIONS: readonly ["artifacts:read", "artifacts:publish"];
+export declare const SITE_AGENT_OTHER_SITE_MESSAGE = "This Site's assistant can only use this Site's data";
+export declare const SITE_AGENT_MANAGEMENT_MESSAGE = "This Site's assistant can use the Site's data, not manage the Site";
+/** The data tools one viewer's Site agent conversation gets, within the deployment's tools. */
+export declare function siteAgentDataToolNames(input: {
+    viewerKind: SiteRuntimeConversationViewerKind;
+    /** Site SQL is offered here and turned on for this Site. */
+    siteSql: boolean;
+    /** The deployment's first-party tool allowlist. */
+    allowed: readonly string[];
+}): FirstPartyMcpToolName[];
+/** Whether Site SQL is offered on this deployment and turned on for the Site. */
+export declare function siteAgentSiteSqlOn(deps: Pick<ApiRouteDeps, "db" | "settings">, scope: {
+    accountId: string;
+    workspaceId: string;
+}, siteId: string): Promise<boolean>;
+/** The data tools for a new conversation of this viewer on this Site. */
+export declare function siteAgentDataToolsForStart(deps: Pick<ApiRouteDeps, "db" | "settings">, scope: {
+    accountId: string;
+    workspaceId: string;
+}, siteId: string, viewerKind: SiteRuntimeConversationViewerKind): Promise<FirstPartyMcpToolName[]>;
+/** This Site's viewer (`user:<subject>` or `guest:<visitor>`) as Site Data and Site SQL see it. */
+export declare function sitePublishedDataViewer(host: Pick<SiteRuntimeHost, "scope" | "site">, principal: string, guest: boolean): PublishedSiteDataViewer;
+/**
+ * The Site agent's instructions: which Site and viewer it serves and what its
+ * data tools may do, then the owner's own instructions for the Site.
+ */
+export declare function siteAgentInstructions(host: Pick<SiteRuntimeHost, "site">, viewer: {
+    kind: SiteRuntimeConversationViewerKind;
+}, dataTools: readonly string[], ownerInstructions: string | null | undefined): string;
+/** A Site agent conversation's data context: the pinned Site and the viewer it acts as. */
+export type SiteAgentDataContext = {
+    kind: "site";
+    siteId: string;
+    viewerKind: SiteRuntimeConversationViewerKind;
+    viewer: PublishedSiteDataViewer;
+    /** The limit profile kind in force (Site SQL limits follow it). */
+    profileKind: SiteLimitProfileKind;
+    /**
+     * Count one write against the guest write limit (anonymous guests only);
+     * null when allowed, else the seconds to wait.
+     */
+    guestWrite: () => Promise<number | null>;
+};
+export type SiteAgentDataResolution = {
+    kind: "ordinary";
+} | {
+    kind: "refused";
+    message: string;
+} | SiteAgentDataContext;
+/**
+ * Whether an agent session is a published Site's agent and, if so, the Site
+ * and viewer its data tools act for. Ordinary sessions resolve `ordinary`.
+ * A Site agent whose conversation, Site or publication cannot be confirmed,
+ * or whose member viewer has left the workspace, is refused (fail closed).
+ */
+export declare function resolveSiteAgentDataContext(deps: Pick<ApiRouteDeps, "db" | "settings" | "objectStorage">, scope: {
+    accountId: string;
+    workspaceId: string;
+}, sessionId: string): Promise<SiteAgentDataResolution>;

package/dist/site-publishing/agent-model.d.ts

@@ -0,0 +1,58 @@
+import type { Settings } from "@opengeni/config";
+import { type OrganizationModelDefaults, type WorkspaceSessionDefaults } from "@opengeni/contracts";
+import { type WorkspaceModelSelection } from "@opengeni/core";
+import { type Database } from "@opengeni/db";
+/**
+ * The model of a Site agent conversation by who the viewer is.
+ *
+ * People outside the workspace (invited people and public visitors) never
+ * use a subscription-billed model (a connected Codex, Claude or other
+ * subscription): Site limits measure real money, and visitors must not use
+ * up a subscription's rate limits or terms. When the Site agent's model is a
+ * subscription model (or the workspace default it falls back to is one),
+ * they get the workspace's default credit-billed model instead, chosen the
+ * same way as the workspace's ordinary default over the credit-billed models
+ * only. When the workspace has none, they are refused. Workspace members use
+ * the Site agent's model, subscriptions included.
+ */
+export type SiteOutsideModelChoice = 
+/** The Site agent's model (or the workspace default it resolves to), not a subscription. */
+{
+    kind: "same";
+    model: string;
+} | {
+    kind: "fallback";
+    model: string;
+} | {
+    kind: "unavailable";
+};
+/** Whether a model is billed through a subscription rather than credits. */
+export declare function isSubscriptionBilledModel(selections: readonly WorkspaceModelSelection[], model: string): boolean;
+/** The decision for people outside the workspace, from already-loaded selections. */
+export declare function siteOutsideModelChoice(input: {
+    settings: Settings;
+    selections: readonly WorkspaceModelSelection[];
+    /** The Site agent's model; null uses the workspace default. */
+    agentModel: string | null;
+    workspaceDefaults: WorkspaceSessionDefaults | null;
+    organizationDefaults: OrganizationModelDefaults["sessionDefaults"] | null;
+}): SiteOutsideModelChoice;
+/** Actual catalog billing, not just provider-name heuristics, fences every admission. */
+export declare function siteCreditModelIds(deps: {
+    db: Database;
+    settings: Settings;
+}, scope: {
+    accountId: string;
+    workspaceId: string;
+}, siteId: string): Promise<string[]>;
+/** Load the workspace's model selection and decide for people outside the workspace. */
+export declare function resolveSiteOutsideModel(deps: {
+    db: Database;
+    settings: Settings;
+}, scope: {
+    accountId: string;
+    workspaceId: string;
+}, input: {
+    siteId: string;
+    agentModel: string | null;
+}): Promise<SiteOutsideModelChoice>;

package/dist/site-publishing/agent-session.d.ts

@@ -0,0 +1,16 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { SiteRuntimeHost } from "./runtime.js";
+import type { SiteRuntimeViewer } from "./viewer.js";
+export declare const SITE_AGENT_DEFAULTS_VERSION = 1;
+/**
+ * Before admitting more work, converge pre-redesign published-host sessions to
+ * the same Site-local tools as a new conversation. This is a trusted host
+ * upgrade, not a caller-controlled tool-policy edit. The route has already
+ * checked ownership, current audience, models and the retained connector set;
+ * each data-tool execution still resolves the live viewer independently.
+ *
+ * The session writer lock makes the config, permissions, sandbox, instructions,
+ * audit event and completion marker atomic. Failed writes remain retryable.
+ * Existing attempts keep their accepted execution policy; no turn is rewritten.
+ */
+export declare function normalizeSiteAgentSession(deps: Pick<ApiRouteDeps, "db" | "settings" | "bus" | "objectStorage">, host: SiteRuntimeHost, viewer: SiteRuntimeViewer, sessionId: string, retainedToolIds: readonly string[]): Promise<void>;

package/dist/site-publishing/content-scanner.d.ts

@@ -0,0 +1,31 @@
+import type { Settings } from "@opengeni/config";
+/**
+ * Pluggable content scanning for published Sites. `none` is the default; the
+ * Google Web Risk scanner runs only with OPENGENI_SITES_WEB_RISK_API_KEY. A
+ * scan looks up the absolute URLs found in a Site's HTML when it is published
+ * and records findings for moderation. It never blocks publishing, and a
+ * disabled or failing scanner records nothing that blocks either.
+ */
+export type SiteContentScanFinding = {
+    url: string;
+    threatTypes: string[];
+};
+export type SiteContentScanResult = {
+    status: "none" | "clean" | "flagged" | "error";
+    findings: SiteContentScanFinding[];
+};
+export type SiteContentScanner = {
+    readonly name: "none" | "web_risk";
+    scanHtml(html: string): Promise<SiteContentScanResult>;
+};
+/** Most distinct URLs one scan looks up (bounds cost per publish). */
+export declare const SITE_SCAN_MAX_URLS = 20;
+/** Distinct absolute http(s) URLs in the HTML, first seen first, at most `limit`. */
+export declare function siteHtmlUrls(html: string, limit?: number): string[];
+export declare const noneSiteContentScanner: SiteContentScanner;
+export declare function createWebRiskSiteContentScanner(apiKey: string, options?: {
+    fetch?: typeof fetch;
+}): SiteContentScanner;
+export declare function createSiteContentScanner(settings: Pick<Settings, "sitesWebRiskApiKey">, options?: {
+    fetch?: typeof fetch;
+}): SiteContentScanner;

package/dist/site-publishing/edge-sync.d.ts

@@ -0,0 +1,48 @@
+import { SiteHostMapRecord } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+/**
+ * Optional Cloudflare edge sync for published Sites. Postgres is the source
+ * of truth; the KV host map and the edge cache are rebuildable copies. With
+ * no Cloudflare settings every call is a no-op.
+ *
+ * Writes go through the Cloudflare REST API with plain fetch (no SDK, each
+ * call bounded by a 10 s timeout) and never block the database write: callers
+ * schedule them after commit, each is retried a few times and then logged.
+ * The caller reads what a hostname should hold in a short transaction under
+ * the hostname's lock and commits before any of these calls, so no database
+ * transaction or lock waits on Cloudflare; after writing it re-reads the
+ * hostname and writes again if it moved meanwhile. One process runs at most
+ * one sync per hostname at a time. A writer never replaces a newer
+ * generation (read, compare, write; KV has no compare-and-set, so writers in
+ * two processes racing within one round trip can still land out of order,
+ * until the entry's TTL ends it). Generations come from one database
+ * sequence shared by every hostname, so a later change to a label (a move,
+ * an unpublish tombstone, a takedown) always carries a higher generation
+ * than anything written before.
+ *
+ * Staleness bound: the API itself refuses a suspended or unpublished Site on
+ * the very next site-runtime call (it re-checks publication status and access
+ * every time). The edge copies lag behind: Cloudflare KV propagates a write
+ * to other locations within about 60 s, every KV entry expires after
+ * `sitesHostMapTtlSeconds` (default 300 s), and the gateway caches host
+ * lookups for up to 60 s and access checks for 30 s. A takedown also purges
+ * the host's edge cache when a zone id is configured. The after-commit sync
+ * runs in process, so a restart can lose a pending write; the next signed
+ * host lookup for that label re-syncs a stale record, and the TTL bounds the
+ * rest. A missed sync is therefore corrected within TTL + 60 s at worst.
+ */
+export type SiteEdgeSyncSettings = Pick<Settings, "sitesCloudflareApiToken" | "sitesCloudflareAccountId" | "sitesCloudflareKvNamespaceId" | "sitesCloudflareZoneId" | "sitesHostMapTtlSeconds">;
+export type SiteEdgeSync = {
+    readonly kvEnabled: boolean;
+    readonly purgeEnabled: boolean;
+    /** Write the host-map record unless the edge already holds a newer generation. */
+    putHostRecord(record: SiteHostMapRecord): Promise<"written" | "skipped_newer" | "disabled">;
+    /** Purge the edge cache for one hostname. */
+    purgeHost(hostname: string): Promise<"purged" | "disabled">;
+};
+export type SiteEdgeSyncOptions = {
+    fetch?: typeof fetch;
+    attempts?: number;
+    backoffMs?: number;
+};
+export declare function createSiteEdgeSync(settings: SiteEdgeSyncSettings, options?: SiteEdgeSyncOptions): SiteEdgeSync;