@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/dist/site-session-http.d.ts

@@ -1,11 +1,96 @@
+import { type SiteOperation } from "./site-operations.js";
+/** The list filter a frame without a published Site gets: it names no Site, so lists nothing. */
+export declare const SITE_NO_ORIGIN_ID = "00000000-0000-0000-0000-000000000000";
+/**
+ * The header a host sets on every request it forwards from a Site frame. The
+ * value names the host: `1` for the console bridge, `preview` for a Codemode
+ * local preview. The API treats a request carrying it (or the pinned Site id)
+ * as Site code: only `SITE_OPERATIONS`, only the frame's own sessions.
+ */
+export declare const SITE_FRAME_HEADER = "x-opengeni-site-frame";
+/** SITE_FRAME_HEADER value a Codemode local preview sets. */
+export declare const SITE_PREVIEW_FRAME = "preview";
+/**
+ * A random id the host mints per mounted frame. A frame without a published
+ * Site (inline HTML, previews) records it on the sessions it starts and may
+ * reach only those sessions afterwards.
+ */
+export declare const SITE_FRAME_ID_HEADER = "x-opengeni-site-frame-id";
+/** The published Site (artifact id) a host pinned the frame to. */
+export declare const SITE_ID_HEADER = "x-opengeni-site-id";
+/** The exact Site version the pinned frame runs. */
+export declare const SITE_VERSION_HEADER = "x-opengeni-site-version";
 /** A Site/Codemode SDK request named a route outside the proxied surface. */
 export declare class SiteSessionPathError extends Error {
     readonly code = "site_session_path_unsupported";
     constructor();
 }
-/** Route browser/preview SDK requests to the host workspace. This is a URL
- * boundary, not an endpoint or HTTP-method allowlist. Ordinary API handlers
- * authorize every operation with the viewer or agent's existing authority. */
-export declare function siteSessionPath(path: string, workspaceId: string, _method?: string, siteId?: string): string;
+/** The host serves no Site Data: it is not bound to a published Site (inline HTML, previews). */
+export declare class SiteDataUnsupportedError extends Error {
+    readonly code = "site_data_unsupported";
+    constructor();
+}
+/**
+ * Route a request from Site code (the in-Site SDK, the console bridge, a
+ * Codemode preview) to the host workspace. This is the `SITE_OPERATIONS`
+ * allowlist: anything else is refused with SiteSessionPathError before any
+ * request is made. Ordinary API handlers still authorize every allowed
+ * operation with the viewer's own authority, and the API independently
+ * refuses frame requests outside the allowlist or to another Site's sessions.
+ *
+ * `workspaceId` `site-host` checks a path inside the Site without rewriting
+ * it. A session list must name `originSiteId=current`; the host binds it to
+ * its pinned Site, or to no Site at all when the frame has none.
+ */
+export declare function siteSessionPath(path: string, workspaceId: string, method?: string, siteId?: string): string;
+/**
+ * Route an agent's own SDK request through the Codemode SDK proxy to its
+ * workspace. Unlike `siteSessionPath` this is a URL prefix boundary, not an
+ * operation allowlist: the proxy signs a short-lived credential bounded by
+ * the agent's own permission ceiling and ordinary handlers authorize every
+ * operation. Site Data is not served here (an agent uses its tools).
+ * Requests a Codemode preview forwards from Site code carry the frame marker
+ * and use `siteSessionPath` instead.
+ */
+export declare function siteHostWorkspacePath(path: string, workspaceId: string): string;
+/** The Site identity a host attached to a request, from its host-set headers. */
+export type SiteFrameHeaders = {
+    /** The pinned published Site id, or null for a frame without one. */
+    siteId: string | null;
+    versionId: string | null;
+    /** The host's frame marker value (`1`, `preview`), or null when only the Site id was set. */
+    marker: string | null;
+    frameId: string | null;
+};
+/** Read the host-set frame headers. Null when the request did not come from a Site frame. */
+export declare function siteFrameFromHeaders(header: (name: string) => string | null | undefined): SiteFrameHeaders | null;
+/**
+ * Match a request that reached a workspace route from a Site frame against
+ * `SITE_OPERATIONS`. `pathname` is the raw request path
+ * (`/v1/workspaces/<id>/...` or `/v1/config/client`). The frame's own pinned
+ * Site id maps back to `current`; any other Site id does not match.
+ */
+export declare function siteFrameOperation(method: string, pathname: string, workspaceId: string, frameSiteId: string | null): {
+    operation: SiteOperation;
+    suffix: string;
+    sessionId: string | null;
+} | null;
 /** Preserve SDK request semantics while the host supplies identity and transport headers. */
 export declare function siteRequestHeaders(input: HeadersInit): Headers;
+/**
+ * Session create fields a Site frame may send. The API starts the session
+ * with a minimal Site profile: no tools, servers, connections, permissions,
+ * vaults, sandbox or environment choice, resources, Skills, agent overrides,
+ * hidden model context, learning overrides, goals, channels, visibility,
+ * usage limits or nesting. Metadata keeps only keys outside `_opengeni`.
+ */
+export declare const SITE_FRAME_SESSION_CREATE_FIELDS: readonly string[];
+/**
+ * The first body field a Site frame may not send for this operation (for
+ * example `payload.resources` or `type`), or null when the body is allowed.
+ * `suffix` is the operation's site-host suffix (from `siteFrameOperation` or
+ * `matchSiteOperation`). A body that is not a JSON object is left to the
+ * route, which refuses it. Only `user.message` events are allowed:
+ * approvals and answers to questions happen in the console.
+ */
+export declare function siteFrameBodyRefusal(operationId: string, suffix: string, body: unknown): string | null;

package/dist/site-session-http.js

@@ -1,10 +1,34 @@
 import {
+  SITE_FRAME_HEADER,
+  SITE_FRAME_ID_HEADER,
+  SITE_FRAME_SESSION_CREATE_FIELDS,
+  SITE_ID_HEADER,
+  SITE_NO_ORIGIN_ID,
+  SITE_PREVIEW_FRAME,
+  SITE_VERSION_HEADER,
+  SiteDataUnsupportedError,
   SiteSessionPathError,
+  siteFrameBodyRefusal,
+  siteFrameFromHeaders,
+  siteFrameOperation,
+  siteHostWorkspacePath,
   siteRequestHeaders,
   siteSessionPath
-} from "./chunk-YRXAWWCU.js";
+} from "./chunk-TLU3UEMD.js";
 export {
+  SITE_FRAME_HEADER,
+  SITE_FRAME_ID_HEADER,
+  SITE_FRAME_SESSION_CREATE_FIELDS,
+  SITE_ID_HEADER,
+  SITE_NO_ORIGIN_ID,
+  SITE_PREVIEW_FRAME,
+  SITE_VERSION_HEADER,
+  SiteDataUnsupportedError,
   SiteSessionPathError,
+  siteFrameBodyRefusal,
+  siteFrameFromHeaders,
+  siteFrameOperation,
+  siteHostWorkspacePath,
   siteRequestHeaders,
   siteSessionPath
 };

package/dist/site-sql.d.ts

@@ -0,0 +1,421 @@
+import { z } from "zod";
+/**
+ * Site SQL: optional per-Site SQLite storage on Cloudflare (one SQLite-backed
+ * Durable Object per Site, `idFromName(siteId)`), offered next to Site Data.
+ * Postgres keeps the definitions (settings, migrations and named queries) so
+ * the database can always be rebuilt; the Durable Object holds the data.
+ * Shared by the API, the Site gateway Worker (which runs the Durable Object)
+ * and the SDK. See docs/design/published-sites-2026-10-14.md (PR B).
+ *
+ * Sites never send SQL: they call named, parameterized queries an owner
+ * defined (`site.sql.run(name, params)`). Every statement, whoever wrote it,
+ * passes `compileSiteSql` on the API and again in the Durable Object.
+ */
+/** A value a statement parameter may take. Booleans bind as 1 and 0. */
+export type SiteSqlValue = string | number | boolean | null;
+export type SiteSqlStatementKind = "read" | "write" | "schema";
+/**
+ * Who wrote the SQL, which decides what it may do:
+ * - `named`: a named query Site pages call. One read or write statement; no
+ *   schema changes, PRAGMA, EXPLAIN or recursive CTEs (no RECURSIVE keyword,
+ *   no CTE that refers to itself and no UNION/INTERSECT/EXCEPT inside a CTE).
+ * - `agent`: one read or write statement an owner's agent runs (query,
+ *   execute), plus read-only PRAGMA and EXPLAIN. Schema changes go through
+ *   migrations so the database can always be rebuilt from Postgres.
+ * - `script`: migrations and SQL imports. Many statements, run together,
+ *   schema changes included.
+ */
+export type SiteSqlProfile = "named" | "agent" | "script";
+export type SiteSqlProblem = "empty" | "too_long" | "syntax" | "multiple_statements" | "too_many_statements" | "statement_not_allowed" | "attach" | "vacuum" | "transaction" | "pragma" | "load_extension" | "reserved_name" | "parameter_style" | "parameter_name" | "too_many_parameters" | "recursive";
+export type SiteSqlStatement = {
+    /** The statement with every `:name` replaced by `?`, comments removed, no trailing semicolon. */
+    sql: string;
+    kind: SiteSqlStatementKind;
+    /** Parameter names in bind order (a name used twice appears twice). */
+    params: string[];
+};
+export type SiteSqlCompileResult = {
+    ok: true;
+    statements: SiteSqlStatement[];
+    /** Distinct parameter names in first-use order. */
+    paramNames: string[];
+} | {
+    ok: false;
+    problem: SiteSqlProblem;
+    message: string;
+};
+/** Longest SQL text per profile, in UTF-16 code units. */
+export declare const SITE_SQL_MAX_NAMED_LENGTH: number;
+export declare const SITE_SQL_MAX_AGENT_LENGTH: number;
+export declare const SITE_SQL_MAX_SCRIPT_LENGTH: number;
+export declare const SITE_SQL_MAX_SCRIPT_STATEMENTS = 2000;
+export declare const SITE_SQL_MAX_PARAMETERS = 100;
+/** PRAGMAs that only read the schema. Anything else (and any `=` form) is refused. */
+export declare const SITE_SQL_READ_PRAGMAS: readonly string[];
+/**
+ * Identifier prefixes Site SQL may not name: Cloudflare's own tables
+ * (`_cf_`) and names kept for Opengeni (`_og_`). Quoted identifiers count,
+ * and so do string literals that start with one (SQLite accepts any string
+ * as a table name, as in `FROM '_cf_KV'`), so such a value must be passed as
+ * a parameter.
+ */
+export declare const SITE_SQL_RESERVED_PREFIXES: readonly string[];
+/**
+ * Parameters the API binds from the verified viewer; a Site may never supply
+ * them. `:viewer` is the viewer's stable per-Site principal (`user:<id>`,
+ * `guest:<visitor>`, ...), `:viewer_kind` its kind, `:viewer_signed_in` 1 or 0.
+ */
+export declare const SITE_SQL_PRINCIPAL_PARAMS: readonly string[];
+/** `viewer` and every `viewer_*` name are reserved for the API. */
+export declare function isSiteSqlPrincipalParam(name: string): boolean;
+/**
+ * Check and compile Site SQL. Refuses ATTACH/DETACH, VACUUM, transaction
+ * control, PRAGMA writes, `pragma_*` functions outside the schema readers,
+ * load_extension, reserved table names, positional or `@`/`$`/`#`
+ * parameters and, per profile, more than one statement, schema changes and
+ * recursive CTEs. Parameters are `:name` only and are rewritten to `?` with
+ * their bind order, so values are always bound, never spliced.
+ */
+export declare function compileSiteSql(sql: string, profile: SiteSqlProfile): SiteSqlCompileResult;
+/** Bind values for one compiled statement; a missing name binds null. Booleans become 1 or 0. */
+export declare function siteSqlBindings(statement: SiteSqlStatement, params: Readonly<Record<string, SiteSqlValue | undefined>>): Array<string | number | null>;
+/** A SQLite identifier quoted for splicing (table and column names only, never values). */
+export declare function quoteSiteSqlIdentifier(name: string): string;
+/** Table and column names Site SQL tools accept as arguments. */
+export declare const SITE_SQL_IDENTIFIER: RegExp;
+export declare function isSiteSqlTableName(name: string): boolean;
+/** Hard ceilings that hold whatever the profile or settings say. */
+export declare const SITE_SQL_HARD_LIMITS: Readonly<{
+    maxRowsPerCall: 5000;
+    maxResponseBytes: number;
+    storageBytesPerSite: number;
+    exportBytesPerCall: number;
+    importRowsPerCall: 5000;
+    /** UTF-8 bytes of SQL all of a Site's migrations hold together, so a rebuild fits in bounded calls. */
+    migrationBytesPerSite: number;
+    /** Bytes one export call returns at most; follow nextCursor for the rest. */
+    exportBytesPerResponse: number;
+}>;
+/** Response header of the HTTP export: the cursor of the next piece, when there is one. */
+export declare const SITE_SQL_EXPORT_NEXT_CURSOR_HEADER = "X-OpenGeni-Export-Next-Cursor";
+/**
+ * Effective Site SQL limits for one Site. Null means no Opengeni cap (the
+ * hard limits still hold).
+ */
+export type SiteSqlLimits = {
+    storageBytesPerSite: number;
+    rowsReadPerSitePerMonth: number | null;
+    rowsWrittenPerSitePerMonth: number | null;
+    callsPerMinutePerViewer: number | null;
+    callsPerMinutePerSite: number | null;
+    maxRowsPerCall: number;
+    maxResponseBytes: number;
+};
+export declare const SITE_SQL_NAME: RegExp;
+export declare const SiteSqlValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const SiteSqlParams: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+export type SiteSqlParams = z.infer<typeof SiteSqlParams>;
+/**
+ * Who may run a named query from a Site page:
+ * - everyone: every viewer, including anonymous guests of public Sites;
+ * - signed_in: viewers signed in as a person (workspace members, invited
+ *   people and, on public Sites, any signed-in user). Callers with no person
+ *   behind them (service keys, agents and schedules acting on their own) are
+ *   refused unless they manage the Site;
+ * - managers: only the Site's managers, through agent tools and the console's
+ *   Data view; Site pages cannot run it.
+ */
+export declare const SiteSqlQueryAudience: z.ZodEnum<{
+    everyone: "everyone";
+    managers: "managers";
+    signed_in: "signed_in";
+}>;
+export type SiteSqlQueryAudience = z.infer<typeof SiteSqlQueryAudience>;
+/** site_sql_define_query and PUT .../sql/queries/:name. */
+export declare const SiteSqlQueryDefinitionRequest: z.ZodObject<{
+    sql: z.ZodString;
+    audience: z.ZodOptional<z.ZodEnum<{
+        everyone: "everyone";
+        managers: "managers";
+        signed_in: "signed_in";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SiteSqlQueryDefinitionRequest = z.infer<typeof SiteSqlQueryDefinitionRequest>;
+/** POST .../published-artifacts/current/sql/queries/:name (Site pages, `site.sql.run`). */
+export declare const SiteSqlRunRequest: z.ZodObject<{
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, z.core.$strip>;
+export type SiteSqlRunRequest = z.infer<typeof SiteSqlRunRequest>;
+/** POST .../sql/query and .../sql/execute: one ad hoc statement from a manager. */
+export declare const SiteSqlStatementRequest: z.ZodObject<{
+    sql: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SiteSqlStatementRequest = z.infer<typeof SiteSqlStatementRequest>;
+/** POST .../sql/reset. */
+export declare const SiteSqlResetRequest: z.ZodObject<{
+    confirm: z.ZodLiteral<true>;
+    schema: z.ZodOptional<z.ZodEnum<{
+        drop: "drop";
+        keep: "keep";
+    }>>;
+}, z.core.$strip>;
+export type SiteSqlResetRequest = z.infer<typeof SiteSqlResetRequest>;
+export declare const SiteSqlMigrationRequest: z.ZodObject<{
+    name: z.ZodString;
+    sql: z.ZodString;
+}, z.core.$strip>;
+export type SiteSqlMigrationRequest = z.infer<typeof SiteSqlMigrationRequest>;
+export declare const SiteSqlExportFormat: z.ZodEnum<{
+    csv: "csv";
+    json: "json";
+    sql: "sql";
+}>;
+export type SiteSqlExportFormat = z.infer<typeof SiteSqlExportFormat>;
+export declare const SiteSqlImportRequest: z.ZodObject<{
+    format: z.ZodEnum<{
+        csv: "csv";
+        json: "json";
+        sql: "sql";
+    }>;
+    sql: z.ZodOptional<z.ZodString>;
+    table: z.ZodOptional<z.ZodString>;
+    csv: z.ZodOptional<z.ZodString>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>>;
+    onConflict: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        ignore: "ignore";
+        replace: "replace";
+    }>>;
+}, z.core.$strip>;
+export type SiteSqlImportRequest = z.infer<typeof SiteSqlImportRequest>;
+/** PUT .../sql/settings: the owner turns Site SQL on or off for one Site. */
+export declare const SiteSqlSettingsRequest: z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type SiteSqlSettingsRequest = z.infer<typeof SiteSqlSettingsRequest>;
+export declare const SiteSqlErrorCode: z.ZodEnum<{
+    conflict: "conflict";
+    disabled: "disabled";
+    forbidden: "forbidden";
+    not_found: "not_found";
+    quota_exceeded: "quota_exceeded";
+    rate_limited: "rate_limited";
+    sql_error: "sql_error";
+    unavailable: "unavailable";
+    validation: "validation";
+}>;
+export type SiteSqlErrorCode = z.infer<typeof SiteSqlErrorCode>;
+export declare const SITE_SQL_ERROR_STATUS: Readonly<Record<SiteSqlErrorCode, number>>;
+/** A row as a Site sees it. Blobs come back as `{ "$base64": "..." }`. */
+export type SiteSqlRow = Record<string, unknown>;
+export type SiteSqlRunResponse = {
+    columns: string[];
+    rows: SiteSqlRow[];
+    /** True when maxRows or the response size cut the result short. */
+    truncated: boolean;
+    rowsRead: number;
+    rowsWritten: number;
+};
+export type SiteSqlQueryResponse = {
+    name: string;
+    sql: string;
+    mode: "read" | "write";
+    params: string[];
+    audience: SiteSqlQueryAudience;
+    description: string | null;
+    maxRows: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type SiteSqlMigrationResponse = {
+    ordinal: number;
+    name: string;
+    sql: string;
+    checksum: string;
+    createdAt: string;
+};
+export type SiteSqlUsageResponse = {
+    storageBytes: number;
+    rowsReadThisMonth: number;
+    rowsWrittenThisMonth: number;
+};
+export type SiteSqlDescribeResponse = {
+    siteId: string;
+    /** Site SQL is configured on this deployment. */
+    available: boolean;
+    /** The owner turned Site SQL on for this Site. */
+    enabled: boolean;
+    migrations: SiteSqlMigrationResponse[];
+    queries: SiteSqlQueryResponse[];
+    usage: SiteSqlUsageResponse;
+    limits: SiteSqlLimits;
+};
+export type SiteSqlMigrateResponse = {
+    migration: SiteSqlMigrationResponse;
+    /** Migrations the database applied now (earlier ones it was missing, then this one). */
+    applied: string[];
+};
+export type SiteSqlImportResponse = {
+    /** Rows inserted (csv, json) or data statements run (sql). */
+    imported: number;
+    /** The migration a sql import recorded for its schema statements (before the data), if any. */
+    migration: string | null;
+    /**
+     * Every migration a sql import recorded, in order: its schema statements
+     * before the data, then its triggers after the data (so they do not fire
+     * on imported rows).
+     */
+    migrations: string[];
+    rowsWritten: number;
+};
+export type SiteSqlResetResponse = {
+    applied: string[];
+    droppedSchema: boolean;
+};
+/**
+ * The gateway route the API calls for a Site's Durable Object:
+ * `POST <gateway internal origin>/_og/internal/site-db/<siteId>/<operation>`,
+ * signed like gateway -> API requests (`siteGatewayCanonicalString` over the
+ * internal path and the gateway's host, empty session, visitor, IP and human
+ * fields, the shared gateway secret, 30 s skew). The path prefix keeps these
+ * signatures distinct from any site-runtime request.
+ */
+export declare const SITE_DB_INTERNAL_PREFIX = "/_og/internal/site-db";
+export declare const SITE_DB_OPERATIONS: readonly ["run", "script", "migrate", "insert", "export", "inspect", "reset"];
+export type SiteDbOperation = (typeof SITE_DB_OPERATIONS)[number];
+export declare function siteDbInternalPath(siteId: string, operation: SiteDbOperation): string;
+/** Every internal request names a fresh id; the Durable Object refuses a replay within the skew window. */
+type SiteDbBase = {
+    requestId: string;
+};
+export type SiteDbRunRequest = SiteDbBase & {
+    sql: string;
+    profile: "named" | "agent";
+    params: Record<string, SiteSqlValue>;
+    /** The mode a named query was defined with; a read that writes is rolled back. */
+    expect?: "read" | "write";
+    maxRows: number;
+    maxResponseBytes: number;
+    maxDatabaseBytes: number;
+};
+export type SiteDbScriptRequest = SiteDbBase & {
+    sql: string;
+    maxDatabaseBytes: number;
+};
+export type SiteDbMigrateRequest = SiteDbBase & {
+    /**
+     * Migrations to apply in order; ones already applied (same checksum) are
+     * skipped. `position` is the migration's ordinal in Postgres, so the
+     * database keeps the order when the API sends only the missing ones.
+     * `checksum` is the lowercase hex SHA-256 of `sql` (UTF-8); the Durable
+     * Object recomputes it and refuses a mismatch.
+     */
+    migrations: Array<{
+        name: string;
+        sql: string;
+        checksum: string;
+        position?: number;
+    }>;
+    /**
+     * Delete everything first, then apply these migrations (the first call of
+     * a rebuild from Postgres; later calls send the rest without it).
+     */
+    rebuild?: boolean;
+    maxDatabaseBytes: number;
+};
+/** Inspect; `migrationsOnly` skips the tables (and their row counts). */
+export type SiteDbInspectRequest = SiteDbBase & {
+    migrationsOnly?: boolean;
+};
+export type SiteDbInsertRequest = SiteDbBase & {
+    table: string;
+    columns: string[];
+    rows: SiteSqlValue[][];
+    onConflict: "fail" | "replace" | "ignore";
+    maxDatabaseBytes: number;
+};
+export type SiteDbExportRequest = SiteDbBase & {
+    /** Tables to export; all user tables when omitted. */
+    tables?: string[];
+    /** nextCursor from the previous page. */
+    cursor?: string | null;
+    maxRows: number;
+    maxBytes: number;
+};
+export type SiteDbMeter = {
+    rowsRead: number;
+    rowsWritten: number;
+    /** Database size after the operation. */
+    databaseBytes: number;
+};
+export type SiteDbSchemaEntry = {
+    type: "table" | "index" | "view" | "trigger";
+    name: string;
+    table: string;
+    sql: string | null;
+};
+export type SiteDbRunResponse = SiteDbMeter & {
+    columns: string[];
+    rows: SiteSqlRow[];
+    truncated: boolean;
+};
+export type SiteDbMigrateResponse = SiteDbMeter & {
+    applied: string[];
+};
+export type SiteDbExportResponse = SiteDbMeter & {
+    /** The whole database schema, on every page. */
+    schema: SiteDbSchemaEntry[];
+    /** Row values in column order; blobs as `{ "$base64": "..." }`. */
+    tables: Array<{
+        name: string;
+        columns: string[];
+        rows: unknown[][];
+    }>;
+    nextCursor: string | null;
+};
+export type SiteDbInspectResponse = SiteDbMeter & {
+    tables: Array<{
+        name: string;
+        type: "table" | "view";
+        sql: string | null;
+        columns: Array<{
+            name: string;
+            type: string;
+            notNull: boolean;
+            primaryKey: boolean;
+            defaultValue: string | null;
+        }>;
+        /** Rows, counted up to 100,000 (rowCountCapped says the count stopped there). */
+        rowCount: number;
+        rowCountCapped: boolean;
+    }>;
+    indexes: SiteDbSchemaEntry[];
+    migrations: Array<{
+        name: string;
+        checksum: string;
+        appliedAt: string;
+    }>;
+};
+/** GET .../sql/inspect: the database as the Durable Object sees it. */
+export type SiteSqlInspectResponse = Omit<SiteDbInspectResponse, "rowsRead" | "rowsWritten"> & {
+    /** Migrations Postgres has that the database has not applied (migrate or reset to apply). */
+    pendingMigrations: string[];
+};
+export type SiteDbErrorCode = "validation" | "sql_error" | "quota_exceeded" | "conflict" | "replayed" | "too_large" | "unauthorized" | "not_found"
+/** SQLite or Durable Object failures that are not the caller's (busy, I/O, corruption); 500. */
+ | "internal";
+export type SiteDbErrorBody = {
+    error: {
+        code: SiteDbErrorCode;
+        message: string;
+    };
+};
+/** Encode a SQLite blob for JSON. */
+export declare function siteSqlBlobValue(bytes: Uint8Array): {
+    $base64: string;
+};
+export {};

package/dist/skill-catalog-context.d.ts

@@ -0,0 +1,7 @@
+/** Durable, model-visible catalog context. Text markers survive SDK/provider replay. */
+export declare const SKILL_CATALOG_CONTEXT_PREFIX = "<opengeni_skill_catalog>\n";
+export declare const SKILL_CATALOG_CONTEXT_SUFFIX = "\n</opengeni_skill_catalog>";
+export declare function skillCatalogContextItem(catalog: string): Record<string, unknown>;
+/** Accept the Chat Completions projection and SDK text-part normalization too. */
+export declare function readSkillCatalogContext(item: Record<string, unknown>): string | null;
+export declare function latestSkillCatalogContext(items: readonly Record<string, unknown>[]): Record<string, unknown> | undefined;

package/dist/skill-files.d.ts

@@ -1,5 +1,5 @@
 /** Shared text-folder limits for API admission, runtime imports and checkout. */
-export declare const SKILL_MAX_FILES = 128;
+export declare const SKILL_MAX_FILES = 1024;
 export declare const SKILL_MAX_FILE_BYTES: number;
 export declare const SKILL_MAX_TOTAL_BYTES: number;
 export declare function isSafeSkillRelativePath(path: string): boolean;

package/dist/skill-use.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * `_meta` key of the content-free Skill-use fact on a model `skill_read`
+ * result. MCP `_meta` never reaches the model: it survives only into the
+ * `agent.toolCall.output` event projection, never into model history.
+ */
+export declare const SKILL_USE_META_KEY: "opengeni/skillUse";
+/** Where the Skill a read resolved to comes from. `personal` is a user-scope Skill. */
+export declare const SkillUseSource: z.ZodEnum<{
+    builtin: "builtin";
+    organization: "organization";
+    personal: "personal";
+    session: "session";
+    workspace: "workspace";
+}>;
+export type SkillUseSource = z.infer<typeof SkillUseSource>;
+/**
+ * What a `skill_read` returned: `full` is the default SKILL.md read, `files`
+ * explicit paths, `list` a path inventory, and `already_in_context` the short
+ * repeat receipt. `refused` means the read returned an error instead of Skill
+ * text; it has no result, so it appears only in metrics.
+ */
+export declare const SkillReadKind: z.ZodEnum<{
+    already_in_context: "already_in_context";
+    files: "files";
+    full: "full";
+    list: "list";
+    refused: "refused";
+}>;
+export type SkillReadKind = z.infer<typeof SkillReadKind>;
+/**
+ * Ids, digests, and counts only. Never Skill text, user text, or a Skill's
+ * title or description. `label` is reserved for a platform display label of a
+ * built-in; user-authored Skills never set it. This is the writer's closed
+ * shape: an unknown field fails the parse, so nothing else can be attached.
+ */
+export declare const SkillUse: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodEnum<{
+        builtin: "builtin";
+        organization: "organization";
+        personal: "personal";
+        session: "session";
+        workspace: "workspace";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    contentSha256: z.ZodOptional<z.ZodString>;
+    revisionId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        already_in_context: "already_in_context";
+        files: "files";
+        full: "full";
+        list: "list";
+    }>;
+    bytes: z.ZodNumber;
+    inIndex: z.ZodBoolean;
+    searchedThisTurn: z.ZodBoolean;
+}, z.core.$strict>;
+export type SkillUse = z.infer<typeof SkillUse>;
+/** The Skill-use fact on a tool result or its event projection, when present and valid. */
+export declare function skillUseFromToolOutput(output: unknown): SkillUse | null;