@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/ai-runtime.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AiMessage, type AiProvider, type AiRequestBase, type AiResult, type AiStreamEvent, type AiSystemBlock, type AiTool } from '../providers/contract';
+import { type AiPluginSettings } from '../providers/routing';
+export { AI_UPSTREAM_FAILURE_COPY, AiRequestShapeError, AiUpstreamError, type AiCompletion, type AiEffort, type AiImagePart, type AiMessage, type AiMessagePart, type AiRefusal, type AiRequestBase, type AiResult, type AiStreamEvent, type AiSystemBlock, type AiThinking, type AiTool, type AiToolUse, type AiUsage, } from '../providers/contract';
+/**
+ * The one runtime every AI door calls (AGL-2903), provider-generic since
+ * AGL-2939.
+ *
+ * `/api/assist/chat` and `/api/ai/assist` each carried their own `fetch` to
+ * one vendor, their own SSE parser and their own usage extraction, and a
+ * third door would have been a third copy. This module owns the request
+ * shape, the cache-prefix rule, the provider resolution and the error
+ * boundary; an adapter owns one vendor's wire protocol; a door owns its
+ * prompt, its gate ladder and its wire format.
+ *
+ * The cache-prefix rule (AGL-2352) is enforced HERE, before any adapter:
+ * a block marked `volatile` may not sit at or before the last
+ * `cacheBreakpoint`, and more breakpoints than any provider caches are
+ * refused. A provider without a cache ignores the markers and keeps the
+ * order, so a request that is right for the caching adapter is right for
+ * every adapter.
+ *
+ * The picture rule (AGL-2916) is enforced here too, and for the same reason:
+ * a picture on an assistant turn, a picture for a model whose provider does
+ * not say it reads one, or a picture past the bounds is refused before any
+ * adapter is reached, so no door can send one a provider would reject.
+ */
+/** The most `cacheBreakpoint` markers a request may carry. */
+export declare const AI_MAX_CACHE_BREAKPOINTS = 4;
+/**
+ * The acceptable-use rules every generation prompt carries (AGL-2925).
+ *
+ * ONE constant, appended to each door's STATIC system text — inside the
+ * cached prefix on the console chat, ahead of the mode prompt on the copy
+ * assistant — so the rules the model is held to are the same at every
+ * door and carry no per-org byte. The Free taste is what makes them worth
+ * stating: a generated page that nobody paid for is the cheapest phishing
+ * kit there is, and the model declining it is the first line, ahead of the
+ * abuse-report route and the lockdown key.
+ *
+ * The categories are the platform's own Acceptable Use Policy, restated in
+ * the second person for the model. A decline from the model's safety layer
+ * arrives as a refusal, which the meter counts against the account's daily
+ * pause and never against its credits.
+ */
+export declare const AI_ACCEPTABLE_USE_BLOCK = "Acceptable use \u2014 decline these rather than write them, and say briefly why:\n- Pages, emails or copy that harvest credentials, payment details or personal data by deception (phishing, fake sign-in or checkout pages, fake \"verify your account\" notices).\n- Impersonating a real business, brand, public body or person you were not told the user represents \u2014 their name, logo, sign-in page or voice \u2014 or copy that claims an endorsement, certification or partnership that was not given to you as a fact.\n- Content that promotes or sells prohibited goods and services: weapons, illegal drugs, counterfeit goods, malware or deceptive downloads, unlicensed gambling, or adult content involving minors.\n- Scams and fraud: fake investment or crypto schemes, advance-fee offers, tech-support scams, fake charities, deceptive \"you have won\" pages, or copy built to defraud.\n- Harassment, threats, or hateful content targeting a person or a group.\n- Spam farms: bulk near-duplicate pages or copy whose only purpose is to game search engines or send unsolicited mail.\nWhen a brief is ordinary business content, write it well and do not lecture.";
+/** A door's request, with the org's settings when the door knows the org. */
+interface AiRuntimeOptions {
+    /** The org's resolved `pluginSettings/ai`, for its provider and model choices. */
+    settings?: AiPluginSettings;
+    /** A provider chosen by the caller, ahead of every setting; specs use it. */
+    provider?: AiProvider;
+}
+export interface AiRequest extends AiRequestBase, AiRuntimeOptions {
+    stream: false;
+}
+export interface AiStreamRequest extends AiRequestBase, AiRuntimeOptions {
+    stream: true;
+}
+/**
+ * The cache guard, applied to the system blocks before any adapter sees
+ * them. Exported so a spec and a door can assert a prompt's shape without
+ * a provider.
+ */
+export declare function validateAiSystemBlocks(system: readonly AiSystemBlock[]): void;
+/**
+ * Whether a provider's model reads a picture in a user turn (AGL-2916): what
+ * the provider's own descriptor of the model says. A model the provider does
+ * not describe reads none, so an adopter's provider is never sent a picture
+ * it did not say it can take.
+ */
+export declare function aiModelReadsImages(provider: AiProvider, model: string): boolean;
+/**
+ * Whether a model a door resolved reads pictures on the provider that would
+ * serve the request: what a door asks before it attaches one, so a model that
+ * does not is sent the text alone rather than refused.
+ */
+export declare function aiRouteReadsImages(model: string, settings?: AiPluginSettings): boolean;
+/**
+ * The picture guard (AGL-2916), applied to the messages before any adapter
+ * sees them. A picture rides only a user turn, only to a model that reads
+ * pictures, only in a format every such model takes, as bare base64 within
+ * the size a provider accepts, and no more of them than a request may carry.
+ * `readsImages` is asked only when a turn carries a picture. Exported so a
+ * spec and a door can assert a request's shape without a provider.
+ */
+export declare function validateAiMessages(messages: readonly AiMessage[], readsImages: () => boolean): void;
+/**
+ * Characters to a token when a prompt is measured rather than tokenized
+ * (AGL-2937). Four is the high end of English prose, so reading a prefix
+ * through it errs LOW on the token count — and a prefix counts as cached
+ * only when it clears its model's minimum even at that reading. Erring the
+ * other way would let a prompt claim a cache it does not get.
+ */
+export declare const AI_CACHE_PREFIX_TOKEN_CHARS = 4;
+/**
+ * The characters inside the cached span of a request: the tools, which a
+ * provider renders ahead of the system blocks and which therefore sit in
+ * every prefix, plus every system block up to and including the last
+ * breakpoint. Zero when the request marks no breakpoint at all.
+ */
+export declare function aiCachedPrefixChars(system: readonly AiSystemBlock[], tools?: readonly AiTool[]): number;
+/**
+ * Whether this request's cached span is long enough for the model to cache
+ * it at all (AGL-2937). A prefix under the model's `cacheMinTokens` is
+ * served with the breakpoints honored and nothing cached — no error, and a
+ * usage report that reads as a permanent miss — so a door designed around a
+ * cache has to answer this question before it believes its own markers, and
+ * `runtime/ai-prompt-cache.spec.ts` answers it for every door at once.
+ */
+export declare function aiCachedPrefixCaches(model: string, system: readonly AiSystemBlock[], tools?: readonly AiTool[]): boolean;
+/**
+ * Whether a provider is configured to answer: registered, and its key
+ * present. Every door asks this before it spends a reservation, and
+ * answers 501 (or the docs fallback) when it is false.
+ */
+export declare function aiProviderReady(settings?: AiPluginSettings): boolean;
+/** The provider that would answer, for a door that names it in its logs or its inventory. */
+export declare function aiActiveProvider(settings?: AiPluginSettings): AiProvider | undefined;
+/**
+ * Send one request through the resolved provider.
+ *
+ * Streaming: resolves once the provider has ACCEPTED the request — after
+ * the headers, before the first token — with an iterator of simplified
+ * events the caller wraps in its own wire format. A non-2xx answer rejects
+ * with `AiUpstreamError` before the iterator exists, so a door can still
+ * send a plain error status and hand back its reservation.
+ *
+ * Non-streaming: resolves with the parsed result, a decline typed as
+ * `AiRefusal` rather than thrown.
+ */
+export declare function runAiRequest(input: AiStreamRequest): Promise<AsyncIterable<AiStreamEvent>>;
+export declare function runAiRequest(input: AiRequest): Promise<AiResult>;

package/src/lib/runtime/ai-runtime.js

@@ -0,0 +1,237 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { aiModelCacheMinTokens } from "../providers/catalog.js";
+import { AI_IMAGE_MAX_BYTES, AI_IMAGE_MEDIA_TYPES, AI_REQUEST_MAX_IMAGES, AiRequestShapeError, aiBase64Bytes, aiMessageImages } from "../providers/contract.js";
+import { resolveAiProvider } from "../providers/routing.js";
+export { AI_UPSTREAM_FAILURE_COPY, AiRequestShapeError, AiUpstreamError } from "../providers/contract.js";
+/**
+ * The one runtime every AI door calls (AGL-2903), provider-generic since
+ * AGL-2939.
+ *
+ * `/api/assist/chat` and `/api/ai/assist` each carried their own `fetch` to
+ * one vendor, their own SSE parser and their own usage extraction, and a
+ * third door would have been a third copy. This module owns the request
+ * shape, the cache-prefix rule, the provider resolution and the error
+ * boundary; an adapter owns one vendor's wire protocol; a door owns its
+ * prompt, its gate ladder and its wire format.
+ *
+ * The cache-prefix rule (AGL-2352) is enforced HERE, before any adapter:
+ * a block marked `volatile` may not sit at or before the last
+ * `cacheBreakpoint`, and more breakpoints than any provider caches are
+ * refused. A provider without a cache ignores the markers and keeps the
+ * order, so a request that is right for the caching adapter is right for
+ * every adapter.
+ *
+ * The picture rule (AGL-2916) is enforced here too, and for the same reason:
+ * a picture on an assistant turn, a picture for a model whose provider does
+ * not say it reads one, or a picture past the bounds is refused before any
+ * adapter is reached, so no door can send one a provider would reject.
+ */ /** The most `cacheBreakpoint` markers a request may carry. */ export const AI_MAX_CACHE_BREAKPOINTS = 4;
+/**
+ * The acceptable-use rules every generation prompt carries (AGL-2925).
+ *
+ * ONE constant, appended to each door's STATIC system text — inside the
+ * cached prefix on the console chat, ahead of the mode prompt on the copy
+ * assistant — so the rules the model is held to are the same at every
+ * door and carry no per-org byte. The Free taste is what makes them worth
+ * stating: a generated page that nobody paid for is the cheapest phishing
+ * kit there is, and the model declining it is the first line, ahead of the
+ * abuse-report route and the lockdown key.
+ *
+ * The categories are the platform's own Acceptable Use Policy, restated in
+ * the second person for the model. A decline from the model's safety layer
+ * arrives as a refusal, which the meter counts against the account's daily
+ * pause and never against its credits.
+ */ export const AI_ACCEPTABLE_USE_BLOCK = `Acceptable use — decline these rather than write them, and say briefly why:
+- Pages, emails or copy that harvest credentials, payment details or personal data by deception (phishing, fake sign-in or checkout pages, fake "verify your account" notices).
+- Impersonating a real business, brand, public body or person you were not told the user represents — their name, logo, sign-in page or voice — or copy that claims an endorsement, certification or partnership that was not given to you as a fact.
+- Content that promotes or sells prohibited goods and services: weapons, illegal drugs, counterfeit goods, malware or deceptive downloads, unlicensed gambling, or adult content involving minors.
+- Scams and fraud: fake investment or crypto schemes, advance-fee offers, tech-support scams, fake charities, deceptive "you have won" pages, or copy built to defraud.
+- Harassment, threats, or hateful content targeting a person or a group.
+- Spam farms: bulk near-duplicate pages or copy whose only purpose is to game search engines or send unsolicited mail.
+When a brief is ordinary business content, write it well and do not lecture.`;
+/**
+ * The cache guard, applied to the system blocks before any adapter sees
+ * them. Exported so a spec and a door can assert a prompt's shape without
+ * a provider.
+ */ export function validateAiSystemBlocks(system) {
+    const breakpoints = system.filter((block)=>block.cacheBreakpoint);
+    if (breakpoints.length > AI_MAX_CACHE_BREAKPOINTS) {
+        throw new AiRequestShapeError(`${breakpoints.length} cache breakpoints; at most ${AI_MAX_CACHE_BREAKPOINTS} are cached`);
+    }
+    // Caching is a prefix match, so the LAST breakpoint decides what is
+    // cached, and every block at or before it is inside the cached prefix. A
+    // volatile block anywhere in that span — including one that is itself
+    // the breakpoint — puts a per-request byte into the prefix (AGL-2352).
+    const lastBreakpoint = system.reduce((last, block, index)=>block.cacheBreakpoint ? index : last, -1);
+    system.forEach((block, index)=>{
+        if (block.volatile && index <= lastBreakpoint) {
+            throw new AiRequestShapeError(`system block ${index} is volatile but sits inside the cached prefix (last breakpoint at block ${lastBreakpoint})`);
+        }
+    });
+}
+/**
+ * Whether a provider's model reads a picture in a user turn (AGL-2916): what
+ * the provider's own descriptor of the model says. A model the provider does
+ * not describe reads none, so an adopter's provider is never sent a picture
+ * it did not say it can take.
+ */ export function aiModelReadsImages(provider, model) {
+    return provider.models().some((descriptor)=>descriptor.id === model && descriptor.capabilities.vision === true);
+}
+/**
+ * Whether a model a door resolved reads pictures on the provider that would
+ * serve the request: what a door asks before it attaches one, so a model that
+ * does not is sent the text alone rather than refused.
+ */ export function aiRouteReadsImages(model, settings) {
+    const provider = resolveAiProvider(settings);
+    return provider ? aiModelReadsImages(provider, model) : false;
+}
+/** A character standard base64 does not use, outside its padding. */ const NOT_BASE64 = /[^A-Za-z0-9+/]/;
+/**
+ * Whether `data` is standard base64 and nothing else: its alphabet, then at
+ * most two `=` of padding; no `data:` prefix, no line breaks.
+ *
+ * Scanned for a character outside the alphabet rather than matched whole: a
+ * picture is megabytes of base64, and a whole-string pattern with a greedy
+ * loop can exhaust the regular expression engine's backtrack stack on input
+ * that large, which throws a RangeError instead of answering.
+ */ function isBareBase64(data) {
+    const body = data.endsWith('==') ? data.slice(0, -2) : data.endsWith('=') ? data.slice(0, -1) : data;
+    return body.length > 0 && !NOT_BASE64.test(body);
+}
+/**
+ * The picture guard (AGL-2916), applied to the messages before any adapter
+ * sees them. A picture rides only a user turn, only to a model that reads
+ * pictures, only in a format every such model takes, as bare base64 within
+ * the size a provider accepts, and no more of them than a request may carry.
+ * `readsImages` is asked only when a turn carries a picture. Exported so a
+ * spec and a door can assert a request's shape without a provider.
+ */ export function validateAiMessages(messages, readsImages) {
+    messages.forEach((message, index)=>{
+        if (typeof message.content === 'string') return;
+        if (!Array.isArray(message.content) || message.content.length === 0) {
+            throw new AiRequestShapeError(`message ${index} has neither text nor parts`);
+        }
+        for (const part of message.content){
+            if (part.type === 'text') {
+                if (typeof part.text !== 'string') {
+                    throw new AiRequestShapeError(`message ${index} has a text part with no text`);
+                }
+                continue;
+            }
+            if (part.type !== 'image') {
+                throw new AiRequestShapeError(`message ${index} has a part of an unknown type`);
+            }
+            if (message.role !== 'user') {
+                throw new AiRequestShapeError(`message ${index} is an assistant turn and carries a picture`);
+            }
+            if (!AI_IMAGE_MEDIA_TYPES.includes(part.mediaType)) {
+                throw new AiRequestShapeError(`message ${index} carries a picture of an unsupported type`);
+            }
+            if (typeof part.data !== 'string') {
+                throw new AiRequestShapeError(`message ${index} carries a picture that is not bare base64`);
+            }
+            // The size first: it needs only the length, so an oversized picture is
+            // refused without reading its bytes.
+            if (aiBase64Bytes(part.data) > AI_IMAGE_MAX_BYTES) {
+                throw new AiRequestShapeError(`message ${index} carries a picture over ${AI_IMAGE_MAX_BYTES} bytes`);
+            }
+            if (!isBareBase64(part.data)) {
+                throw new AiRequestShapeError(`message ${index} carries a picture that is not bare base64`);
+            }
+        }
+    });
+    const images = aiMessageImages(messages).length;
+    if (images > AI_REQUEST_MAX_IMAGES) {
+        throw new AiRequestShapeError(`${images} pictures; a request carries at most ${AI_REQUEST_MAX_IMAGES}`);
+    }
+    if (images > 0 && !readsImages()) {
+        throw new AiRequestShapeError('the request carries a picture and its model does not read pictures');
+    }
+}
+/**
+ * Characters to a token when a prompt is measured rather than tokenized
+ * (AGL-2937). Four is the high end of English prose, so reading a prefix
+ * through it errs LOW on the token count — and a prefix counts as cached
+ * only when it clears its model's minimum even at that reading. Erring the
+ * other way would let a prompt claim a cache it does not get.
+ */ export const AI_CACHE_PREFIX_TOKEN_CHARS = 4;
+/**
+ * The characters inside the cached span of a request: the tools, which a
+ * provider renders ahead of the system blocks and which therefore sit in
+ * every prefix, plus every system block up to and including the last
+ * breakpoint. Zero when the request marks no breakpoint at all.
+ */ export function aiCachedPrefixChars(system, tools = []) {
+    const lastBreakpoint = system.reduce((last, block, index)=>block.cacheBreakpoint ? index : last, -1);
+    if (lastBreakpoint < 0) return 0;
+    const toolChars = tools.reduce((total, tool)=>total + JSON.stringify(tool).length, 0);
+    return system.slice(0, lastBreakpoint + 1).reduce((total, block)=>total + block.text.length, toolChars);
+}
+/**
+ * Whether this request's cached span is long enough for the model to cache
+ * it at all (AGL-2937). A prefix under the model's `cacheMinTokens` is
+ * served with the breakpoints honored and nothing cached — no error, and a
+ * usage report that reads as a permanent miss — so a door designed around a
+ * cache has to answer this question before it believes its own markers, and
+ * `runtime/ai-prompt-cache.spec.ts` answers it for every door at once.
+ */ export function aiCachedPrefixCaches(model, system, tools = []) {
+    const chars = aiCachedPrefixChars(system, tools);
+    return chars / AI_CACHE_PREFIX_TOKEN_CHARS >= aiModelCacheMinTokens(model);
+}
+/**
+ * Whether a provider is configured to answer: registered, and its key
+ * present. Every door asks this before it spends a reservation, and
+ * answers 501 (or the docs fallback) when it is false.
+ */ export function aiProviderReady(settings) {
+    var _resolveAiProvider;
+    return Boolean((_resolveAiProvider = resolveAiProvider(settings)) == null ? void 0 : _resolveAiProvider.readApiKey());
+}
+/** The provider that would answer, for a door that names it in its logs or its inventory. */ export function aiActiveProvider(settings) {
+    return resolveAiProvider(settings);
+}
+function providerFor(input) {
+    var _input_provider;
+    const provider = (_input_provider = input.provider) != null ? _input_provider : resolveAiProvider(input.settings);
+    if (!provider) throw new Error('no AI provider is registered');
+    const apiKey = provider.readApiKey();
+    if (!apiKey) {
+        // Every door gates on `aiProviderReady` before it gets here, so this is
+        // a wiring fault rather than a customer path.
+        throw new Error(`${provider.apiKeyEnv} is not set`);
+    }
+    return {
+        provider,
+        apiKey
+    };
+}
+export async function runAiRequest(input) {
+    validateAiSystemBlocks(input.system);
+    const { provider, apiKey } = providerFor(input);
+    validateAiMessages(input.messages, ()=>aiModelReadsImages(provider, input.model));
+    const { stream, settings: _settings, provider: _provider } = input, request = _object_without_properties_loose(input, [
+        "stream",
+        "settings",
+        "provider"
+    ]);
+    const providerRequest = _extends({}, request, {
+        apiKey
+    });
+    return stream ? provider.stream(providerRequest) : provider.complete(providerRequest);
+}
+
+//# sourceMappingURL=ai-runtime.js.map

package/src/lib/runtime/ai-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-runtime.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { aiModelCacheMinTokens } from '../providers/catalog'\nimport {\n  AI_IMAGE_MAX_BYTES,\n  AI_IMAGE_MEDIA_TYPES,\n  AI_REQUEST_MAX_IMAGES,\n  AiRequestShapeError,\n  aiBase64Bytes,\n  aiMessageImages,\n  type AiMessage,\n  type AiProvider,\n  type AiRequestBase,\n  type AiResult,\n  type AiStreamEvent,\n  type AiSystemBlock,\n  type AiTool,\n} from '../providers/contract'\nimport { resolveAiProvider, type AiPluginSettings } from '../providers/routing'\n\nexport {\n  AI_UPSTREAM_FAILURE_COPY,\n  AiRequestShapeError,\n  AiUpstreamError,\n  type AiCompletion,\n  type AiEffort,\n  type AiImagePart,\n  type AiMessage,\n  type AiMessagePart,\n  type AiRefusal,\n  type AiRequestBase,\n  type AiResult,\n  type AiStreamEvent,\n  type AiSystemBlock,\n  type AiThinking,\n  type AiTool,\n  type AiToolUse,\n  type AiUsage,\n} from '../providers/contract'\n\n/**\n * The one runtime every AI door calls (AGL-2903), provider-generic since\n * AGL-2939.\n *\n * `/api/assist/chat` and `/api/ai/assist` each carried their own `fetch` to\n * one vendor, their own SSE parser and their own usage extraction, and a\n * third door would have been a third copy. This module owns the request\n * shape, the cache-prefix rule, the provider resolution and the error\n * boundary; an adapter owns one vendor's wire protocol; a door owns its\n * prompt, its gate ladder and its wire format.\n *\n * The cache-prefix rule (AGL-2352) is enforced HERE, before any adapter:\n * a block marked `volatile` may not sit at or before the last\n * `cacheBreakpoint`, and more breakpoints than any provider caches are\n * refused. A provider without a cache ignores the markers and keeps the\n * order, so a request that is right for the caching adapter is right for\n * every adapter.\n *\n * The picture rule (AGL-2916) is enforced here too, and for the same reason:\n * a picture on an assistant turn, a picture for a model whose provider does\n * not say it reads one, or a picture past the bounds is refused before any\n * adapter is reached, so no door can send one a provider would reject.\n */\n\n/** The most `cacheBreakpoint` markers a request may carry. */\nexport const AI_MAX_CACHE_BREAKPOINTS = 4\n\n/**\n * The acceptable-use rules every generation prompt carries (AGL-2925).\n *\n * ONE constant, appended to each door's STATIC system text — inside the\n * cached prefix on the console chat, ahead of the mode prompt on the copy\n * assistant — so the rules the model is held to are the same at every\n * door and carry no per-org byte. The Free taste is what makes them worth\n * stating: a generated page that nobody paid for is the cheapest phishing\n * kit there is, and the model declining it is the first line, ahead of the\n * abuse-report route and the lockdown key.\n *\n * The categories are the platform's own Acceptable Use Policy, restated in\n * the second person for the model. A decline from the model's safety layer\n * arrives as a refusal, which the meter counts against the account's daily\n * pause and never against its credits.\n */\nexport const AI_ACCEPTABLE_USE_BLOCK = `Acceptable use — decline these rather than write them, and say briefly why:\n- Pages, emails or copy that harvest credentials, payment details or personal data by deception (phishing, fake sign-in or checkout pages, fake \"verify your account\" notices).\n- Impersonating a real business, brand, public body or person you were not told the user represents — their name, logo, sign-in page or voice — or copy that claims an endorsement, certification or partnership that was not given to you as a fact.\n- Content that promotes or sells prohibited goods and services: weapons, illegal drugs, counterfeit goods, malware or deceptive downloads, unlicensed gambling, or adult content involving minors.\n- Scams and fraud: fake investment or crypto schemes, advance-fee offers, tech-support scams, fake charities, deceptive \"you have won\" pages, or copy built to defraud.\n- Harassment, threats, or hateful content targeting a person or a group.\n- Spam farms: bulk near-duplicate pages or copy whose only purpose is to game search engines or send unsolicited mail.\nWhen a brief is ordinary business content, write it well and do not lecture.`\n\n/** A door's request, with the org's settings when the door knows the org. */\ninterface AiRuntimeOptions {\n  /** The org's resolved `pluginSettings/ai`, for its provider and model choices. */\n  settings?: AiPluginSettings\n  /** A provider chosen by the caller, ahead of every setting; specs use it. */\n  provider?: AiProvider\n}\n\nexport interface AiRequest extends AiRequestBase, AiRuntimeOptions {\n  stream: false\n}\n\nexport interface AiStreamRequest extends AiRequestBase, AiRuntimeOptions {\n  stream: true\n}\n\n/**\n * The cache guard, applied to the system blocks before any adapter sees\n * them. Exported so a spec and a door can assert a prompt's shape without\n * a provider.\n */\nexport function validateAiSystemBlocks(system: readonly AiSystemBlock[]): void {\n  const breakpoints = system.filter((block) => block.cacheBreakpoint)\n  if (breakpoints.length > AI_MAX_CACHE_BREAKPOINTS) {\n    throw new AiRequestShapeError(\n      `${breakpoints.length} cache breakpoints; at most ${AI_MAX_CACHE_BREAKPOINTS} are cached`,\n    )\n  }\n  // Caching is a prefix match, so the LAST breakpoint decides what is\n  // cached, and every block at or before it is inside the cached prefix. A\n  // volatile block anywhere in that span — including one that is itself\n  // the breakpoint — puts a per-request byte into the prefix (AGL-2352).\n  const lastBreakpoint = system.reduce(\n    (last, block, index) => (block.cacheBreakpoint ? index : last),\n    -1,\n  )\n  system.forEach((block, index) => {\n    if (block.volatile && index <= lastBreakpoint) {\n      throw new AiRequestShapeError(\n        `system block ${index} is volatile but sits inside the cached prefix (last breakpoint at block ${lastBreakpoint})`,\n      )\n    }\n  })\n}\n\n/**\n * Whether a provider's model reads a picture in a user turn (AGL-2916): what\n * the provider's own descriptor of the model says. A model the provider does\n * not describe reads none, so an adopter's provider is never sent a picture\n * it did not say it can take.\n */\nexport function aiModelReadsImages(provider: AiProvider, model: string): boolean {\n  return provider\n    .models()\n    .some((descriptor) => descriptor.id === model && descriptor.capabilities.vision === true)\n}\n\n/**\n * Whether a model a door resolved reads pictures on the provider that would\n * serve the request: what a door asks before it attaches one, so a model that\n * does not is sent the text alone rather than refused.\n */\nexport function aiRouteReadsImages(model: string, settings?: AiPluginSettings): boolean {\n  const provider = resolveAiProvider(settings)\n  return provider ? aiModelReadsImages(provider, model) : false\n}\n\n/** A character standard base64 does not use, outside its padding. */\nconst NOT_BASE64 = /[^A-Za-z0-9+/]/\n\n/**\n * Whether `data` is standard base64 and nothing else: its alphabet, then at\n * most two `=` of padding; no `data:` prefix, no line breaks.\n *\n * Scanned for a character outside the alphabet rather than matched whole: a\n * picture is megabytes of base64, and a whole-string pattern with a greedy\n * loop can exhaust the regular expression engine's backtrack stack on input\n * that large, which throws a RangeError instead of answering.\n */\nfunction isBareBase64(data: string): boolean {\n  const body = data.endsWith('==') ? data.slice(0, -2) : data.endsWith('=') ? data.slice(0, -1) : data\n  return body.length > 0 && !NOT_BASE64.test(body)\n}\n\n/**\n * The picture guard (AGL-2916), applied to the messages before any adapter\n * sees them. A picture rides only a user turn, only to a model that reads\n * pictures, only in a format every such model takes, as bare base64 within\n * the size a provider accepts, and no more of them than a request may carry.\n * `readsImages` is asked only when a turn carries a picture. Exported so a\n * spec and a door can assert a request's shape without a provider.\n */\nexport function validateAiMessages(messages: readonly AiMessage[], readsImages: () => boolean): void {\n  messages.forEach((message, index) => {\n    if (typeof message.content === 'string') return\n    if (!Array.isArray(message.content) || message.content.length === 0) {\n      throw new AiRequestShapeError(`message ${index} has neither text nor parts`)\n    }\n    for (const part of message.content) {\n      if (part.type === 'text') {\n        if (typeof part.text !== 'string') {\n          throw new AiRequestShapeError(`message ${index} has a text part with no text`)\n        }\n        continue\n      }\n      if (part.type !== 'image') {\n        throw new AiRequestShapeError(`message ${index} has a part of an unknown type`)\n      }\n      if (message.role !== 'user') {\n        throw new AiRequestShapeError(`message ${index} is an assistant turn and carries a picture`)\n      }\n      if (!(AI_IMAGE_MEDIA_TYPES as readonly string[]).includes(part.mediaType)) {\n        throw new AiRequestShapeError(`message ${index} carries a picture of an unsupported type`)\n      }\n      if (typeof part.data !== 'string') {\n        throw new AiRequestShapeError(`message ${index} carries a picture that is not bare base64`)\n      }\n      // The size first: it needs only the length, so an oversized picture is\n      // refused without reading its bytes.\n      if (aiBase64Bytes(part.data) > AI_IMAGE_MAX_BYTES) {\n        throw new AiRequestShapeError(\n          `message ${index} carries a picture over ${AI_IMAGE_MAX_BYTES} bytes`,\n        )\n      }\n      if (!isBareBase64(part.data)) {\n        throw new AiRequestShapeError(`message ${index} carries a picture that is not bare base64`)\n      }\n    }\n  })\n  const images = aiMessageImages(messages).length\n  if (images > AI_REQUEST_MAX_IMAGES) {\n    throw new AiRequestShapeError(`${images} pictures; a request carries at most ${AI_REQUEST_MAX_IMAGES}`)\n  }\n  if (images > 0 && !readsImages()) {\n    throw new AiRequestShapeError('the request carries a picture and its model does not read pictures')\n  }\n}\n\n/**\n * Characters to a token when a prompt is measured rather than tokenized\n * (AGL-2937). Four is the high end of English prose, so reading a prefix\n * through it errs LOW on the token count — and a prefix counts as cached\n * only when it clears its model's minimum even at that reading. Erring the\n * other way would let a prompt claim a cache it does not get.\n */\nexport const AI_CACHE_PREFIX_TOKEN_CHARS = 4\n\n/**\n * The characters inside the cached span of a request: the tools, which a\n * provider renders ahead of the system blocks and which therefore sit in\n * every prefix, plus every system block up to and including the last\n * breakpoint. Zero when the request marks no breakpoint at all.\n */\nexport function aiCachedPrefixChars(\n  system: readonly AiSystemBlock[],\n  tools: readonly AiTool[] = [],\n): number {\n  const lastBreakpoint = system.reduce(\n    (last, block, index) => (block.cacheBreakpoint ? index : last),\n    -1,\n  )\n  if (lastBreakpoint < 0) return 0\n  const toolChars = tools.reduce((total, tool) => total + JSON.stringify(tool).length, 0)\n  return system\n    .slice(0, lastBreakpoint + 1)\n    .reduce((total, block) => total + block.text.length, toolChars)\n}\n\n/**\n * Whether this request's cached span is long enough for the model to cache\n * it at all (AGL-2937). A prefix under the model's `cacheMinTokens` is\n * served with the breakpoints honored and nothing cached — no error, and a\n * usage report that reads as a permanent miss — so a door designed around a\n * cache has to answer this question before it believes its own markers, and\n * `runtime/ai-prompt-cache.spec.ts` answers it for every door at once.\n */\nexport function aiCachedPrefixCaches(\n  model: string,\n  system: readonly AiSystemBlock[],\n  tools: readonly AiTool[] = [],\n): boolean {\n  const chars = aiCachedPrefixChars(system, tools)\n  return chars / AI_CACHE_PREFIX_TOKEN_CHARS >= aiModelCacheMinTokens(model)\n}\n\n/**\n * Whether a provider is configured to answer: registered, and its key\n * present. Every door asks this before it spends a reservation, and\n * answers 501 (or the docs fallback) when it is false.\n */\nexport function aiProviderReady(settings?: AiPluginSettings): boolean {\n  return Boolean(resolveAiProvider(settings)?.readApiKey())\n}\n\n/** The provider that would answer, for a door that names it in its logs or its inventory. */\nexport function aiActiveProvider(settings?: AiPluginSettings): AiProvider | undefined {\n  return resolveAiProvider(settings)\n}\n\nfunction providerFor(input: AiRuntimeOptions): { provider: AiProvider; apiKey: string } {\n  const provider = input.provider ?? resolveAiProvider(input.settings)\n  if (!provider) throw new Error('no AI provider is registered')\n  const apiKey = provider.readApiKey()\n  if (!apiKey) {\n    // Every door gates on `aiProviderReady` before it gets here, so this is\n    // a wiring fault rather than a customer path.\n    throw new Error(`${provider.apiKeyEnv} is not set`)\n  }\n  return { provider, apiKey }\n}\n\n/**\n * Send one request through the resolved provider.\n *\n * Streaming: resolves once the provider has ACCEPTED the request — after\n * the headers, before the first token — with an iterator of simplified\n * events the caller wraps in its own wire format. A non-2xx answer rejects\n * with `AiUpstreamError` before the iterator exists, so a door can still\n * send a plain error status and hand back its reservation.\n *\n * Non-streaming: resolves with the parsed result, a decline typed as\n * `AiRefusal` rather than thrown.\n */\nexport async function runAiRequest(\n  input: AiStreamRequest,\n): Promise<AsyncIterable<AiStreamEvent>>\nexport async function runAiRequest(input: AiRequest): Promise<AiResult>\nexport async function runAiRequest(\n  input: AiRequest | AiStreamRequest,\n): Promise<AsyncIterable<AiStreamEvent> | AiResult> {\n  validateAiSystemBlocks(input.system)\n  const { provider, apiKey } = providerFor(input)\n  validateAiMessages(input.messages, () => aiModelReadsImages(provider, input.model))\n  const { stream, settings: _settings, provider: _provider, ...request } = input\n  const providerRequest = { ...request, apiKey }\n  return stream ? provider.stream(providerRequest) : provider.complete(providerRequest)\n}\n"],"names":["aiModelCacheMinTokens","AI_IMAGE_MAX_BYTES","AI_IMAGE_MEDIA_TYPES","AI_REQUEST_MAX_IMAGES","AiRequestShapeError","aiBase64Bytes","aiMessageImages","resolveAiProvider","AI_UPSTREAM_FAILURE_COPY","AiUpstreamError","AI_MAX_CACHE_BREAKPOINTS","AI_ACCEPTABLE_USE_BLOCK","validateAiSystemBlocks","system","breakpoints","filter","block","cacheBreakpoint","length","lastBreakpoint","reduce","last","index","forEach","volatile","aiModelReadsImages","provider","model","models","some","descriptor","id","capabilities","vision","aiRouteReadsImages","settings","NOT_BASE64","isBareBase64","data","body","endsWith","slice","test","validateAiMessages","messages","readsImages","message","content","Array","isArray","part","type","text","role","includes","mediaType","images","AI_CACHE_PREFIX_TOKEN_CHARS","aiCachedPrefixChars","tools","toolChars","total","tool","JSON","stringify","aiCachedPrefixCaches","chars","aiProviderReady","Boolean","readApiKey","aiActiveProvider","providerFor","input","Error","apiKey","apiKeyEnv","runAiRequest","stream","_settings","_provider","request","providerRequest","complete"],"mappings":"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"}

package/src/lib/runtime/ai-template-examples.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type StarterTemplate } from '@aglyn/aglyn/app-utils/starter-templates';
+import { type AiDoctrineTree } from './ai-doctrine-validators';
+import type { AiSystemBlock } from './ai-runtime';
+/**
+ * The page examples a template generation is shown (AGL-2909): pages from
+ * the platform's own starter sites (`STARTER_TEMPLATES`), in the node-map
+ * shape the tool takes, as one cached block that is the same bytes for every
+ * org.
+ *
+ * Three things about a starter predate the building rules, and every example
+ * is brought up to them the same way rather than shown as it stands:
+ *
+ * - HEADINGS. A starter picks a heading's look with its variant, and rule 11
+ *   reads its level from the element. The page's first heading renders as
+ *   its h1, each later one as an h2, and a sixth-level subtitle as a
+ *   paragraph.
+ * - FORMS. A starter draws its contact form inline, and rule 3 places a form
+ *   built on the Forms page by id, so the form is left out.
+ * - LINKS. A starter's call to action points nowhere until a member picks
+ *   where it goes, and rule 10 refuses a Button or a Screen Link with no
+ *   destination (AGL-3072), so such a link is left out.
+ *
+ * Only props the palette declares are kept, since the model is held to the
+ * same palette, and none that holds a px, rem or em length, which rule 5
+ * names as a length never to write. A page that still breaks a rule, that
+ * the palette validator would change in any way, or that places an element
+ * the page surface does not offer (a commerce block) is not shown, and two
+ * pages of one shape are shown once: an example the model imitates is one
+ * the doctrine accepts exactly as written.
+ */
+export interface AiTemplateExample {
+    /** The starter site's name. */
+    starter: string;
+    /** The page's name within it. */
+    page: string;
+    tree: AiDoctrineTree;
+}
+/** The block's ceiling: 1,500 tokens at four characters a token. */
+export declare const AI_TEMPLATE_EXAMPLES_MAX_CHARS = 6000;
+type StarterNode = {
+    componentId?: string;
+    props?: Record<string, unknown>;
+    sx?: Record<string, unknown>;
+    nodes?: unknown;
+};
+/** A starter page as the tool's node map, brought up to the rules above; `null` when it cannot be shown. */
+export declare function aiStarterExampleTree(nodes: Record<string, StarterNode>): AiDoctrineTree | null;
+/** Every starter page the doctrine accepts as a template exactly as the example shows it. */
+export declare function aiStarterTemplateExamples(starters?: readonly StarterTemplate[]): AiTemplateExample[];
+export declare const AI_TEMPLATE_EXAMPLES_PREAMBLE: string;
+/** The examples as one cached system block, held to its ceiling an example at a time. */
+export declare function aiTemplateExamplesBlock(examples?: readonly AiTemplateExample[]): AiSystemBlock;
+/** The block a template generation sends, built once per process from the starters. */
+export declare function aiTemplateExamplesSystemBlock(): AiSystemBlock;
+export {};

package/src/lib/runtime/ai-template-examples.js

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { STARTER_TEMPLATES } from "@aglyn/aglyn/app-utils/starter-templates";
+import { CANVAS_ROOT_ELEMENT_ID } from "@aglyn/aglyn/foundation/constants/canvas";
+import { validateAiDoctrineTree } from "./ai-doctrine-validators.js";
+import { isHeadlineVariant } from "./ai-palette.js";
+import { AI_PALETTE, AI_SURFACES } from "./ai-palette.generated.js";
+/** The block's ceiling: 1,500 tokens at four characters a token. */ export const AI_TEMPLATE_EXAMPLES_MAX_CHARS = 6000;
+const FORM_COMPONENTS = new Set([
+    'form',
+    'formField'
+]);
+/** The elements a page links with, which go where their `screenId` or `href` says. */ const LINK_COMPONENTS = new Set([
+    'muiButton',
+    'muiScreenLink'
+]);
+/** Whether a starter node is a link that names nowhere to go. */ function linksNowhere(componentId, props) {
+    if (!LINK_COMPONENTS.has(componentId)) return false;
+    const named = (value)=>typeof value === 'string' && value.trim() !== '';
+    return !named(props == null ? void 0 : props['screenId']) && !named(props == null ? void 0 : props['href']);
+}
+/** A CSS length in the units rule 5 forbids. */ const CSS_LENGTH = /\d(?:\.\d+)?(?:px|rem|em)\b/i;
+/** A starter page as the tool's node map, brought up to the rules above; `null` when it cannot be shown. */ export function aiStarterExampleTree(nodes) {
+    if (!nodes[CANVAS_ROOT_ELEMENT_ID]) return null;
+    const allowed = new Set(AI_SURFACES.screen.allow);
+    const out = {};
+    let headings = 0;
+    let unavailable = false;
+    const visit = (id)=>{
+        var _ref, _ref1, _node_props;
+        var _AI_PALETTE_componentId;
+        const node = nodes[id];
+        const componentId = String((_ref = node == null ? void 0 : node.componentId) != null ? _ref : '');
+        if (!node || FORM_COMPONENTS.has(componentId) || linksNowhere(componentId, node.props)) return null;
+        const root = id === CANVAS_ROOT_ELEMENT_ID;
+        if (!root && !allowed.has(componentId)) {
+            unavailable = true;
+            return null;
+        }
+        // Inserted before the children, so the map reads top-down.
+        const shaped = {
+            componentId: root ? 'div' : componentId
+        };
+        out[id] = shaped;
+        const declared = (_ref1 = (_AI_PALETTE_componentId = AI_PALETTE[componentId]) == null ? void 0 : _AI_PALETTE_componentId.propsSchema.properties) != null ? _ref1 : {};
+        const props = {};
+        for (const [name, value] of Object.entries((_node_props = node.props) != null ? _node_props : {})){
+            if (!declared[name] || value === undefined) continue;
+            if (typeof value === 'string' && CSS_LENGTH.test(value)) continue;
+            props[name] = value;
+        }
+        if (componentId === 'muiTypography') {
+            const variant = props['variant'];
+            if (variant === 'h6') props['component'] = 'p';
+            else if (isHeadlineVariant(variant)) props['component'] = headings++ === 0 ? 'h1' : 'h2';
+        }
+        if (Object.keys(props).length) shaped.props = props;
+        if (node.sx && Object.keys(node.sx).length) shaped.sx = node.sx;
+        const children = (Array.isArray(node.nodes) ? node.nodes : []).map((child)=>typeof child === 'string' ? visit(child) : null).filter((child)=>child !== null);
+        if (children.length) shaped.nodes = children;
+        return id;
+    };
+    visit(CANVAS_ROOT_ELEMENT_ID);
+    return unavailable ? null : {
+        rootId: CANVAS_ROOT_ELEMENT_ID,
+        nodes: out
+    };
+}
+/** A tree's element structure without its copy or ids, to show one shape once. */ function shapeOf(tree, id = tree.rootId) {
+    var _node_nodes;
+    const node = tree.nodes[id];
+    return `${node.componentId}(${((_node_nodes = node.nodes) != null ? _node_nodes : []).map((child)=>shapeOf(tree, child)).join(',')})`;
+}
+/** Every starter page the doctrine accepts as a template exactly as the example shows it. */ export function aiStarterTemplateExamples(starters = STARTER_TEMPLATES) {
+    const examples = [];
+    const shapes = new Set();
+    for (const starter of starters){
+        for (const screen of starter.screens){
+            const tree = aiStarterExampleTree(screen.nodes);
+            if (!tree) continue;
+            const report = validateAiDoctrineTree(tree, 'template');
+            if (!report.ok || !report.tree || report.tree.repairs.length) continue;
+            const shape = shapeOf(tree);
+            if (shapes.has(shape)) continue;
+            shapes.add(shape);
+            examples.push({
+                starter: starter.displayName,
+                page: screen.displayName,
+                tree
+            });
+        }
+    }
+    return examples;
+}
+export const AI_TEMPLATE_EXAMPLES_PREAMBLE = [
+    'Examples: pages from the platform’s starter sites, in the node-map shape the tool takes.',
+    'Build the way they are built: each band a Container at a stock width (xl for a marketing band, lg for an interactive one, md for prose) with vertical padding on the spacing scale, its content in a Stack, and one h1 for the page.',
+    'Their copy is the starter’s own; a template binds its subject’s tokens wherever a record’s own words, links or pictures go.'
+].join(' ');
+/** The examples as one cached system block, held to its ceiling an example at a time. */ export function aiTemplateExamplesBlock(examples = aiStarterTemplateExamples()) {
+    const parts = [
+        AI_TEMPLATE_EXAMPLES_PREAMBLE
+    ];
+    let used = AI_TEMPLATE_EXAMPLES_PREAMBLE.length;
+    for (const example of examples){
+        const text = `Starter "${example.starter}", page "${example.page}":\n${JSON.stringify(example.tree)}`;
+        if (used + text.length + 2 > AI_TEMPLATE_EXAMPLES_MAX_CHARS) continue;
+        parts.push(text);
+        used += text.length + 2;
+    }
+    return {
+        text: parts.join('\n\n'),
+        cacheBreakpoint: true
+    };
+}
+let examplesBlock = null;
+/** The block a template generation sends, built once per process from the starters. */ export function aiTemplateExamplesSystemBlock() {
+    examplesBlock != null ? examplesBlock : examplesBlock = aiTemplateExamplesBlock();
+    return examplesBlock;
+}
+
+//# sourceMappingURL=ai-template-examples.js.map