@genesislcap/ai-assistant 15.34.1 → 15.35.0

package/dist/dts/genesis/register-genesis-assistant.d.ts

@@ -0,0 +1,52 @@
+import { type TieredAIProviderSwitcherOptions } from '../provider/tiered-provider-switcher';
+import type { GenesisAiConfig, GenesisAssistantRegistration, RegisterGenesisAssistantOptions } from './types';
+/**
+ * The name of the agent {@link registerGenesisAssistant} builds.
+ *
+ * @beta
+ */
+export declare const GENESIS_AGENT_NAME = "genesis-assistant";
+/**
+ * The system-prompt line behind ADR P9. The tools stamp their results as untrusted app data;
+ * this tells the model what that means. Defence in depth — no other rule relies on it.
+ *
+ * @internal
+ */
+export declare const UNTRUSTED_DATA_PROMPT: string;
+/**
+ * The exported app's own AI proxy: `<PUBLIC_PATH>/gwf/ai-service`.
+ *
+ * @internal
+ */
+export declare function defaultEndpointBase(publicPath?: string): string;
+/**
+ * The provider options {@link registerGenesisAssistant} registers — split out so the choice of
+ * vendor, tier and endpoint can be checked without building providers.
+ *
+ * @remarks
+ * No model id appears anywhere: the vendor and tier name a row of the platform tier table, and
+ * that row supplies the model, the output ceiling and both timeouts. The app's proxy may clamp
+ * the ceiling further.
+ *
+ * @internal
+ */
+export declare function genesisProviderOptions(config: GenesisAiConfig, options?: Pick<RegisterGenesisAssistantOptions, 'endpointBase' | 'vendors'>): Omit<TieredAIProviderSwitcherOptions, 'container'>;
+/**
+ * Sets up the AI assistant for a Genesis app from its generated AI config: providers by tier,
+ * and one agent whose tools read the app's resources.
+ *
+ * @remarks
+ * Call it once at start-up and bind the returned `agents` to the assistant element. It is
+ * synchronous on purpose — the element resolves its providers as it connects, and one that
+ * connects before they are registered keeps the empty fallback for the whole page load.
+ *
+ * It never throws. Anything that stops the assistant working — AI switched off for the build,
+ * an invalid config, an extension tool reusing a generated tool's name — is logged as an error
+ * and returned as `blockedReason`, with no agents. The mount code applies it with the element's
+ * `setBlocked(true, blockedReason)`. The app keeps working: one misnamed chat tool, for instance
+ * after a regeneration renames a resource onto an extension's tool, must never take it down.
+ *
+ * @beta
+ */
+export declare function registerGenesisAssistant(options: RegisterGenesisAssistantOptions): GenesisAssistantRegistration;
+//# sourceMappingURL=register-genesis-assistant.d.ts.map

package/dist/dts/genesis/register-genesis-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-genesis-assistant.d.ts","sourceRoot":"","sources":["../../../src/genesis/register-genesis-assistant.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,sCAAsC,CAAC;AAI9C,OAAO,KAAK,EACV,eAAe,EACf,4BAA4B,EAC5B,+BAA+B,EAChC,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAGN,CAAC;AAE7B;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,GAAE,MAAoB,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,IAAI,CAAC,+BAA+B,EAAE,cAAc,GAAG,SAAS,CAAM,GAC9E,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC,CAUpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,4BAA4B,CAuG9B"}

package/dist/dts/genesis/resource-tools.d.ts

@@ -0,0 +1,86 @@
+import type { ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+import { type Connect } from '@genesislcap/foundation-comms';
+import type { GenesisAiResource } from './types';
+/**
+ * The provenance stamped on everything a tool returns from the app (ADR P9). Rows are written by
+ * the app's other users, so the model must treat their text as data, never as instructions; the
+ * system prompt says the same thing in words.
+ *
+ * @beta
+ */
+export declare const GENESIS_DATA_SOURCE = "app-database";
+/**
+ * What a read tool returns to the model.
+ *
+ * @beta
+ */
+export interface GenesisReadResult {
+    source: typeof GENESIS_DATA_SOURCE;
+    untrusted: true;
+    resource: string;
+    rows: unknown[];
+    /** True when more rows match than this call returned. */
+    truncated: boolean;
+    /** When `truncated`: that these rows are not the full set, and how to narrow the read. */
+    note?: string;
+}
+/**
+ * What any Genesis tool returns instead of throwing. A thrown tool error invites the model to
+ * "retry it", which for a write can mean doing it twice (ADR P7), so none of these tools throw.
+ *
+ * @beta
+ */
+export interface GenesisToolError {
+    source: typeof GENESIS_DATA_SOURCE;
+    untrusted: true;
+    resource: string;
+    error: 'not_connected' | 'invalid_filter' | 'rejected' | 'request_failed';
+    message: string;
+}
+/**
+ * Options for {@link createGenesisResourceTools}.
+ *
+ * @beta
+ */
+export interface GenesisResourceToolsOptions {
+    /** The connection to read through. Defaults to the app's own, resolved from DI on first use. */
+    connect?: Connect;
+    /**
+     * How long a metadata fetch and a read may take before they are abandoned. Both exist because
+     * a request Connect drops on reconnect never settles; the defaults suit a real app, and tests
+     * shorten them.
+     *
+     * @internal
+     */
+    timeouts?: {
+        metadataMs?: number;
+        readMs?: number;
+    };
+}
+/**
+ * The tools built from an app's resources, in the shape an agent config takes.
+ *
+ * @beta
+ */
+export interface GenesisResourceTools {
+    /**
+     * Resolves the definitions lazily — schemas are fetched on the first turn, not at
+     * registration — and returns the same list, in name order, every time after, so the tool
+     * list does not re-serialise between iterations and break prompt caching.
+     */
+    toolDefinitions: () => Promise<ChatToolDefinition[]>;
+    toolHandlers: ChatToolHandlers;
+}
+/**
+ * Builds the assistant's tools from an app's resources.
+ *
+ * @remarks
+ * Each request resource becomes a read tool: filters from the resource's own schema, a row cap
+ * (ADR P10: 50 by default, never more than the resource's `maxRows` whatever the model asks),
+ * no paging (see `truncationNote`), and every result stamped as untrusted app data (P9). Event resources are not turned
+ * into tools yet; the write path, with its review table, comes separately.
+ *
+ * @beta
+ */
+export declare function createGenesisResourceTools(resources: readonly GenesisAiResource[], options?: GenesisResourceToolsOptions): GenesisResourceTools;
+//# sourceMappingURL=resource-tools.d.ts.map

package/dist/dts/genesis/resource-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-tools.d.ts","sourceRoot":"","sources":["../../../src/genesis/resource-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAMzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAalD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,UAAU,GAAG,gBAAgB,CAAC;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACrD,YAAY,EAAE,gBAAgB,CAAC;CAChC;AAmID;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CAkFtB"}

package/dist/dts/genesis/types.d.ts

@@ -0,0 +1,115 @@
+import type { AITierId, AITierVendor, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+import type { Connect } from '@genesislcap/foundation-comms';
+import type { Container } from '@genesislcap/web-core';
+import type { AgentConfig } from '../config/config';
+import type { TieredAIProviderSwitcher } from '../provider/tiered-provider-switcher';
+/**
+ * What a Genesis resource is to the assistant: a request/reply it can read, or an event it
+ * can propose a write to.
+ *
+ * @beta
+ */
+export type GenesisResourceKind = 'request' | 'event';
+/**
+ * The wire vocabulary for an event resource's operation. Custom handlers keep their own name.
+ *
+ * @beta
+ */
+export declare const GENESIS_EVENT_OPS: readonly ["insert", "modify", "delete", "custom"];
+/**
+ * One of {@link GENESIS_EVENT_OPS}. Declared from the array so the type and the validator
+ * cannot drift apart, the way the platform's own tier ids are.
+ *
+ * @beta
+ */
+export type GenesisEventOp = (typeof GENESIS_EVENT_OPS)[number];
+/**
+ * One app resource exposed to the assistant — an entry of the generated `ai-config.json`.
+ *
+ * @beta
+ */
+export interface GenesisAiResource {
+    /** `REQ_<NAME>` for a request, `EVENT_<NAME>` for an event. Unique within the config. */
+    name: string;
+    kind: GenesisResourceKind;
+    /** Events only. */
+    op?: GenesisEventOp;
+    /** What the resource is for, in plain words. Becomes the tool's description. */
+    context: string;
+    /** Requests only: the most rows one read may return (1–1000). Defaults to 50. */
+    maxRows?: number;
+}
+/**
+ * The AI block of a generated app's configuration (`client/src/ai/generated/ai-config.json`).
+ *
+ * @remarks
+ * Carries no model id, endpoint, key or budget: the model comes from the platform tier table,
+ * the endpoint from the app's own proxy, and the key never leaves the server.
+ *
+ * @beta
+ */
+export interface GenesisAiConfig {
+    enabled: boolean;
+    /** Defaults to `'gemini'`. */
+    vendor?: AITierVendor;
+    /** Defaults to `'high'`. */
+    tier?: AITierId;
+    systemPrompt?: string;
+    resources?: GenesisAiResource[];
+}
+/**
+ * An app's own additions to the assistant — the hand-written tools under
+ * `client/src/ai/extensions/`.
+ *
+ * @beta
+ */
+export interface GenesisAssistantExtensions {
+    toolDefinitions?: ChatToolDefinition[];
+    toolHandlers?: ChatToolHandlers;
+    /** Appended to the configured system prompt. */
+    systemPrompt?: string;
+}
+/**
+ * Options for {@link registerGenesisAssistant}.
+ *
+ * @beta
+ */
+export interface RegisterGenesisAssistantOptions {
+    config: GenesisAiConfig;
+    /** DI container the providers are registered on. Defaults to the DOM container. */
+    container?: Container;
+    /**
+     * Base of the app's AI proxy routes; `/<vendor>/chat` is appended. Defaults to the exported
+     * app's own proxy, `<PUBLIC_PATH>/gwf/ai-service`. A preview build passes its own.
+     */
+    endpointBase?: string;
+    /**
+     * The Genesis connection the tools read through. Defaults to the app's own, resolved from DI
+     * when a tool first runs rather than at registration, so registering stays synchronous.
+     */
+    connect?: Connect;
+    extensions?: GenesisAssistantExtensions;
+    /**
+     * Vendors the user may switch between. Defaults to the configured vendor alone: an app whose
+     * proxy holds one key would otherwise offer a switch to a vendor that cannot answer.
+     */
+    vendors?: readonly AITierVendor[];
+}
+/**
+ * What {@link registerGenesisAssistant} hands back to the app's mount code.
+ *
+ * @beta
+ */
+export interface GenesisAssistantRegistration {
+    /** Bind to the assistant element's `agents` property. Empty when blocked. */
+    agents: AgentConfig[];
+    /** The vendor switcher, when providers were registered. */
+    switcher?: TieredAIProviderSwitcher;
+    /**
+     * Set when the assistant cannot run — AI switched off, an invalid config, a tool-name clash.
+     * Apply it with the element's `setBlocked(true, blockedReason)`. The app itself keeps working:
+     * a problem with one chat tool must never take the whole app down at start-up.
+     */
+    blockedReason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/dts/genesis/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/genesis/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAErF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,mDAAoD,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;IAC1B,mBAAmB;IACnB,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,eAAe,CAAC;IACxB,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/esm/genesis/config.js

@@ -0,0 +1,86 @@
+import { AI_TIER_IDS, AI_TIER_VENDORS } from '@genesislcap/foundation-ai';
+import { GENESIS_EVENT_OPS } from './types';
+/** The default read cap, and the ceiling the config may raise it to. */
+export const DEFAULT_MAX_ROWS = 50;
+export const MAX_ROWS_CEILING = 1000;
+/** Tool names are the lowercased resource name; vendors reject names over 64 characters. */
+const MAX_TOOL_NAME_LENGTH = 64;
+const RESOURCE_NAME = /^(REQ|EVENT)_[A-Z0-9_]+$/;
+/**
+ * The model-facing tool name for a resource. Deterministic and collision-free (resource names
+ * are unique), and trivially mapped back to the resource in a debug log. What the tool is FOR
+ * reaches the model through its description, not its name.
+ */
+export const toolNameOf = (resourceName) => resourceName.toLowerCase();
+/**
+ * Checks a generated AI config before anything is registered, returning every problem found.
+ *
+ * @remarks
+ * The config is machine-generated and schema-checked upstream, so a violation here is a bug in
+ * that pipeline, not something to work around. The caller turns problems into a blocked
+ * assistant with the reason on screen — scoped to the assistant, never an exception that could
+ * take the app down at start-up — rather than running with part of the config quietly missing.
+ *
+ * @internal
+ */
+export function validateGenesisAiConfig(config) {
+    if (!config || typeof config !== 'object')
+        return ['the AI config is missing or not an object'];
+    const c = config;
+    const problems = [];
+    if (c.enabled !== true)
+        problems.push(`enabled must be true (got ${String(c.enabled)})`);
+    if (c.vendor !== undefined && !AI_TIER_VENDORS.includes(c.vendor)) {
+        problems.push(`unknown vendor '${String(c.vendor)}' (expected ${AI_TIER_VENDORS.join(' or ')})`);
+    }
+    if (c.tier !== undefined && !AI_TIER_IDS.includes(c.tier)) {
+        problems.push(`unknown tier '${String(c.tier)}' (expected ${AI_TIER_IDS.join(', ')})`);
+    }
+    if (c.systemPrompt !== undefined && typeof c.systemPrompt !== 'string') {
+        problems.push('systemPrompt must be a string');
+    }
+    if (c.resources === undefined)
+        return problems;
+    if (!Array.isArray(c.resources))
+        return [...problems, 'resources must be an array'];
+    const seen = new Set();
+    c.resources.forEach((resource, i) => {
+        const at = `resources[${i}]`;
+        const name = resource === null || resource === void 0 ? void 0 : resource.name;
+        if (typeof name !== 'string' || !RESOURCE_NAME.test(name)) {
+            problems.push(`${at}: name must look like REQ_<NAME> or EVENT_<NAME> (got ${String(name)})`);
+            return;
+        }
+        if (toolNameOf(name).length > MAX_TOOL_NAME_LENGTH) {
+            problems.push(`${name}: longer than the ${MAX_TOOL_NAME_LENGTH} characters a tool name allows`);
+        }
+        // A duplicate is not harmless: two tools with one name are rejected by the vendor, and the
+        // same list feeds the generated MCP script, which refuses a repeated name at load.
+        if (seen.has(name))
+            problems.push(`${name}: appears more than once`);
+        seen.add(name);
+        const expectedKind = name.startsWith('REQ_') ? 'request' : 'event';
+        if (resource.kind !== expectedKind) {
+            problems.push(`${name}: kind must be '${expectedKind}' (got ${String(resource.kind)})`);
+        }
+        if (typeof resource.context !== 'string')
+            problems.push(`${name}: context must be a string`);
+        if (expectedKind === 'event') {
+            if (!GENESIS_EVENT_OPS.includes(resource.op)) {
+                problems.push(`${name}: op must be one of ${GENESIS_EVENT_OPS.join(', ')}`);
+            }
+            if (resource.maxRows !== undefined)
+                problems.push(`${name}: maxRows applies to requests only`);
+        }
+        else {
+            if (resource.op !== undefined)
+                problems.push(`${name}: op applies to events only`);
+            const { maxRows } = resource;
+            if (maxRows !== undefined &&
+                !(Number.isInteger(maxRows) && maxRows >= 1 && maxRows <= MAX_ROWS_CEILING)) {
+                problems.push(`${name}: maxRows must be a whole number from 1 to ${MAX_ROWS_CEILING}`);
+            }
+        }
+    });
+    return problems;
+}