@aglyn/aglyn 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/plugin-manager/plugin-ai-capabilities.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @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.
+ */
+/**
+ * What an AI build can make, contributed by the plugin that owns each thing
+ * (AGL-3616).
+ *
+ * A build turns one request — "a few pages, a contact form and a way to book
+ * me" — into a plan of ITEMS, each an operation (`op`) with arguments, and
+ * runs them in dependency order. The AI plugin plans and meters the build;
+ * it does not know what a plugin's resource is, and the package map forbids
+ * it importing that plugin. So every operation is a CAPABILITY the owner
+ * registers from its server entry, and the build asks for one by `op`:
+ *
+ *  - the planner offers the model only the operations registered here, in
+ *    the owner's own words (`noun`, `intents`, `argsSchema`);
+ *  - admission removes an item whose capability this site, plan or member
+ *    cannot use (`feature`, `permission`, `quota`, `freeAllowed`), with a
+ *    sentence, so the rest of the plan still runs;
+ *  - the item is executed one of two ways: `runnerKind` hands it to an
+ *    existing AI job runner (the AI plugin's own operations), and
+ *    `draftResource` hands its content to the owner's writer on
+ *    `plugin-resource-drafts`, which checks it, meets the allowance and
+ *    writes a draft that nothing publishes.
+ *
+ * An operation lights up the moment its owner registers it; nothing in the
+ * AI plugin names it. Register by CALLING `registerPluginAiCapability` from a
+ * function the server entry runs — a top-level side effect is dropped by a
+ * bundler that sees no import of its result.
+ *
+ * Server-only: import this file by its own path, never from the barrel that
+ * every published page loads.
+ *
+ * ## One capability per operation
+ *
+ * An operation has one owner. A second plugin registering an `op` another
+ * plugin already owns is refused, naming both, and the incumbent keeps
+ * serving; the same plugin registering again replaces its own.
+ */
+/** A value an item's arguments may hold: scalars and lists of strings only. */
+export type PluginAiCapabilityArgValue = string | number | boolean | readonly string[];
+/** An item's arguments, in the shape its capability's `argsSchema` declares. */
+export type PluginAiCapabilityArgs = Readonly<Record<string, PluginAiCapabilityArgValue>>;
+/**
+ * One argument, as a JSON Schema property the model fills in directly. The
+ * subset is deliberately small: a flat object of scalars and string lists is
+ * what a planner can be held to, and what `pluginAiCapabilityArgsProblems`
+ * checks without a schema library.
+ */
+export interface PluginAiCapabilityArgProperty {
+    type: 'string' | 'integer' | 'number' | 'boolean' | 'array';
+    /** Read by the model: what the value means and how to choose it. */
+    description: string;
+    /** For `string`: the allowed values. */
+    enum?: readonly string[];
+    /** For `integer`/`number`. */
+    minimum?: number;
+    maximum?: number;
+    /** For `string`, and each item of an `array`. */
+    maxLength?: number;
+    /** For `array`: always a list of strings. */
+    items?: {
+        type: 'string';
+        enum?: readonly string[];
+        maxLength?: number;
+    };
+    maxItems?: number;
+}
+/** A flat JSON Schema object: no nesting, no extra keys. */
+export interface PluginAiCapabilityArgsSchema {
+    type: 'object';
+    properties: Readonly<Record<string, PluginAiCapabilityArgProperty>>;
+    required?: readonly string[];
+    additionalProperties: false;
+}
+/** How the items that depend on a failed item of this capability behave. */
+export type PluginAiCapabilityDegrade = 
+/** Dependents are built without it (a page loses the block that used it). */
+'omit'
+/** Dependents use something that already exists in its place (a site's own layout). */
+ | 'fallback';
+/** One planned item, as a capability sees it. */
+export interface PluginAiCapabilityItem {
+    /** The item's name in the plan, unique within it; other items cite it as `new:<name>`. */
+    name: string;
+    args: PluginAiCapabilityArgs;
+}
+/** What a capability's `draftContent` is told beside the item. */
+export interface PluginAiCapabilityDraftContext {
+    hostId: string;
+    /**
+     * The drafts written for the items this one depends on, keyed by the
+     * reference the plan used (`new:<name>`), each with its operation and the
+     * id its own writer or runner gave it. A dependency that did not succeed is
+     * absent.
+     */
+    dependencies: Readonly<Record<string, {
+        op: string;
+        id: string;
+    }>>;
+}
+export interface PluginAiCapability {
+    /** The operation's name in a plan, stable across releases: `page`, `note`. */
+    op: string;
+    /** What one is called in a sentence a person reads: "contact form". */
+    noun: string;
+    /** Where a person finds the draft afterwards: "Notes → Drafts". */
+    where: string;
+    /**
+     * What a person might ask for that this makes, as short phrases the chat's
+     * instructions list. True of the shipped product: never a promise the
+     * writer cannot keep.
+     */
+    intents: readonly string[];
+    /** The item's arguments, which the planner fills in. */
+    argsSchema: PluginAiCapabilityArgsSchema;
+    /** How many items of this operation one plan may hold. */
+    maxPerPlan: number;
+    /** Whether a workspace on the free plan may have one made. */
+    freeAllowed: boolean;
+    /** The entitlement a workspace needs, checked with the platform's entitlement read. */
+    feature?: string;
+    /** The site permission the member needs. */
+    permission?: string;
+    /** The allowance one counts against, which the owner's writer meets. */
+    quota?: string;
+    /**
+     * The resource whose writer on `plugin-resource-drafts` makes the draft.
+     * Exactly one of this and `runnerKind` is set.
+     */
+    draftResource?: string;
+    /**
+     * The AI job kind whose runner makes it — the AI plugin's own operations.
+     * Exactly one of this and `draftResource` is set.
+     */
+    runnerKind?: string;
+    /** The most this item can cost, in AI credits; a draft written without a model costs 0. */
+    estimateCredits(args: PluginAiCapabilityArgs): number;
+    /** Operations an item of this one may depend on. */
+    dependsOnOps?: readonly string[];
+    degrade: PluginAiCapabilityDegrade;
+    /**
+     * Blocks a page places when it uses an item of this operation (the block
+     * names the page palette knows). When the item fails, a dependent page is
+     * built without them, and says so.
+     */
+    pageBlocks?: readonly string[];
+    /**
+     * The writer's content for an item, from its arguments and its built
+     * dependencies. Pure. Absent means the arguments ARE the content.
+     */
+    draftContent?(item: PluginAiCapabilityItem, context: PluginAiCapabilityDraftContext): Readonly<Record<string, unknown>>;
+}
+export declare const PLUGIN_AI_CAPABILITIES: import("./plugin-services").PluginServiceContract<PluginAiCapability>;
+/** Why a capability cannot be registered, or `null`. */
+export declare function pluginAiCapabilityProblem(capability: PluginAiCapability): string | null;
+/**
+ * Registers what a plugin's AI builds can make. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`. An `op`
+ * another plugin owns throws naming both; a malformed capability throws.
+ */
+export declare function registerPluginAiCapability(capability: PluginAiCapability, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginAiCapability {
+    /** The plugin that owns the operation. */
+    pluginId: string;
+    capability: PluginAiCapability;
+}
+/** Every registered capability with its owner, in registration order. */
+export declare function pluginAiCapabilities(): ResolvedPluginAiCapability[];
+/** The capability for an operation, with its owner, or `null` when nothing registered it. */
+export declare function pluginAiCapability(op: string): ResolvedPluginAiCapability | null;
+/**
+ * What is wrong with an item's arguments against its schema; empty when
+ * nothing is. Pure, and the same answer on both sides of the seam: the
+ * planner holds the model to it, and an owner may hold its content to it.
+ */
+export declare function pluginAiCapabilityArgsProblems(schema: PluginAiCapabilityArgsSchema, args: Readonly<Record<string, unknown>>): string[];

package/src/lib/plugin-manager/plugin-ai-capabilities.js

@@ -0,0 +1,157 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_AI_CAPABILITIES = definePluginServiceContract('core.ai-capabilities', {
+    multiple: true
+});
+const OP_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+/** Why a capability cannot be registered, or `null`. */ export function pluginAiCapabilityProblem(capability) {
+    var _capability_argsSchema_required;
+    var _capability_argsSchema;
+    if (!OP_PATTERN.test(capability.op)) {
+        return `ai capability op "${capability.op}" must be lowercase letters, digits and dashes`;
+    }
+    const executors = [
+        capability.draftResource,
+        capability.runnerKind
+    ].filter((one)=>typeof one === 'string' && one.trim());
+    if (executors.length !== 1) {
+        return `ai capability "${capability.op}" needs exactly one of draftResource and runnerKind`;
+    }
+    if (!Number.isInteger(capability.maxPerPlan) || capability.maxPerPlan < 1) {
+        return `ai capability "${capability.op}" needs a maxPerPlan of at least 1`;
+    }
+    if (((_capability_argsSchema = capability.argsSchema) == null ? void 0 : _capability_argsSchema.type) !== 'object' || capability.argsSchema.additionalProperties !== false) {
+        return `ai capability "${capability.op}" needs a flat object argsSchema with additionalProperties: false`;
+    }
+    for (const required of (_capability_argsSchema_required = capability.argsSchema.required) != null ? _capability_argsSchema_required : []){
+        if (!(required in capability.argsSchema.properties)) {
+            return `ai capability "${capability.op}" requires "${required}", which its schema does not declare`;
+        }
+    }
+    if (!capability.noun.trim() || !capability.where.trim()) {
+        return `ai capability "${capability.op}" needs a noun and a where`;
+    }
+    return null;
+}
+/**
+ * Registers what a plugin's AI builds can make. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`. An `op`
+ * another plugin owns throws naming both; a malformed capability throws.
+ */ export function registerPluginAiCapability(capability, options) {
+    var _ref, _getRegisteringPluginId;
+    const problem = pluginAiCapabilityProblem(capability);
+    if (problem) throw new Error(problem);
+    const key = capability.op;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    const incumbent = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find((entry)=>entry.key === key);
+    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+        throw new Error(`ai capability "${key}" is already registered by "${incumbent.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_AI_CAPABILITIES, capability, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, {
+        key
+    }));
+}
+/** Every registered capability with its owner, in registration order. */ export function pluginAiCapabilities() {
+    return resolvePluginServices(PLUGIN_AI_CAPABILITIES).map((entry)=>({
+            pluginId: entry.pluginId,
+            capability: entry.impl
+        }));
+}
+/** The capability for an operation, with its owner, or `null` when nothing registered it. */ export function pluginAiCapability(op) {
+    const key = op.trim();
+    const entry = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find((one)=>one.key === key);
+    return entry ? {
+        pluginId: entry.pluginId,
+        capability: entry.impl
+    } : null;
+}
+/**
+ * What is wrong with an item's arguments against its schema; empty when
+ * nothing is. Pure, and the same answer on both sides of the seam: the
+ * planner holds the model to it, and an owner may hold its content to it.
+ */ export function pluginAiCapabilityArgsProblems(schema, args) {
+    var _schema_required;
+    const problems = [];
+    for (const name of (_schema_required = schema.required) != null ? _schema_required : []){
+        const value = args[name];
+        if (value === undefined || value === null || value === '') problems.push(`"${name}" is required`);
+    }
+    for (const [name, value] of Object.entries(args)){
+        const property = schema.properties[name];
+        if (!property) {
+            problems.push(`"${name}" is not an argument`);
+            continue;
+        }
+        if (value === undefined || value === null) continue;
+        switch(property.type){
+            case 'string':
+                if (typeof value !== 'string') problems.push(`"${name}" must be text`);
+                else {
+                    if (property.enum && !property.enum.includes(value)) {
+                        problems.push(`"${name}" must be one of ${property.enum.join(', ')}`);
+                    }
+                    if (property.maxLength !== undefined && value.length > property.maxLength) {
+                        problems.push(`"${name}" must be at most ${property.maxLength} characters`);
+                    }
+                }
+                break;
+            case 'integer':
+            case 'number':
+                if (typeof value !== 'number' || !Number.isFinite(value) || property.type === 'integer' && !Number.isInteger(value)) {
+                    problems.push(`"${name}" must be ${property.type === 'integer' ? 'a whole number' : 'a number'}`);
+                } else {
+                    if (property.minimum !== undefined && value < property.minimum) {
+                        problems.push(`"${name}" must be at least ${property.minimum}`);
+                    }
+                    if (property.maximum !== undefined && value > property.maximum) {
+                        problems.push(`"${name}" must be at most ${property.maximum}`);
+                    }
+                }
+                break;
+            case 'boolean':
+                if (typeof value !== 'boolean') problems.push(`"${name}" must be true or false`);
+                break;
+            case 'array':
+                if (!Array.isArray(value) || value.some((one)=>typeof one !== 'string')) {
+                    problems.push(`"${name}" must be a list of text`);
+                } else {
+                    if (property.maxItems !== undefined && value.length > property.maxItems) {
+                        problems.push(`"${name}" must hold at most ${property.maxItems}`);
+                    }
+                    const items = property.items;
+                    for (const one of value){
+                        if ((items == null ? void 0 : items.enum) && !items.enum.includes(one)) {
+                            problems.push(`"${name}" holds "${one}", which is not one of ${items.enum.join(', ')}`);
+                            break;
+                        }
+                        if ((items == null ? void 0 : items.maxLength) !== undefined && one.length > items.maxLength) {
+                            problems.push(`"${name}" holds an entry longer than ${items.maxLength} characters`);
+                            break;
+                        }
+                    }
+                }
+                break;
+        }
+    }
+    return problems;
+}
+
+//# sourceMappingURL=plugin-ai-capabilities.js.map

package/src/lib/plugin-manager/plugin-ai-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-ai-capabilities.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * What an AI build can make, contributed by the plugin that owns each thing\n * (AGL-3616).\n *\n * A build turns one request — \"a few pages, a contact form and a way to book\n * me\" — into a plan of ITEMS, each an operation (`op`) with arguments, and\n * runs them in dependency order. The AI plugin plans and meters the build;\n * it does not know what a plugin's resource is, and the package map forbids\n * it importing that plugin. So every operation is a CAPABILITY the owner\n * registers from its server entry, and the build asks for one by `op`:\n *\n *  - the planner offers the model only the operations registered here, in\n *    the owner's own words (`noun`, `intents`, `argsSchema`);\n *  - admission removes an item whose capability this site, plan or member\n *    cannot use (`feature`, `permission`, `quota`, `freeAllowed`), with a\n *    sentence, so the rest of the plan still runs;\n *  - the item is executed one of two ways: `runnerKind` hands it to an\n *    existing AI job runner (the AI plugin's own operations), and\n *    `draftResource` hands its content to the owner's writer on\n *    `plugin-resource-drafts`, which checks it, meets the allowance and\n *    writes a draft that nothing publishes.\n *\n * An operation lights up the moment its owner registers it; nothing in the\n * AI plugin names it. Register by CALLING `registerPluginAiCapability` from a\n * function the server entry runs — a top-level side effect is dropped by a\n * bundler that sees no import of its result.\n *\n * Server-only: import this file by its own path, never from the barrel that\n * every published page loads.\n *\n * ## One capability per operation\n *\n * An operation has one owner. A second plugin registering an `op` another\n * plugin already owns is refused, naming both, and the incumbent keeps\n * serving; the same plugin registering again replaces its own.\n */\n\n/** A value an item's arguments may hold: scalars and lists of strings only. */\nexport type PluginAiCapabilityArgValue = string | number | boolean | readonly string[]\n\n/** An item's arguments, in the shape its capability's `argsSchema` declares. */\nexport type PluginAiCapabilityArgs = Readonly<Record<string, PluginAiCapabilityArgValue>>\n\n/**\n * One argument, as a JSON Schema property the model fills in directly. The\n * subset is deliberately small: a flat object of scalars and string lists is\n * what a planner can be held to, and what `pluginAiCapabilityArgsProblems`\n * checks without a schema library.\n */\nexport interface PluginAiCapabilityArgProperty {\n  type: 'string' | 'integer' | 'number' | 'boolean' | 'array'\n  /** Read by the model: what the value means and how to choose it. */\n  description: string\n  /** For `string`: the allowed values. */\n  enum?: readonly string[]\n  /** For `integer`/`number`. */\n  minimum?: number\n  maximum?: number\n  /** For `string`, and each item of an `array`. */\n  maxLength?: number\n  /** For `array`: always a list of strings. */\n  items?: { type: 'string'; enum?: readonly string[]; maxLength?: number }\n  maxItems?: number\n}\n\n/** A flat JSON Schema object: no nesting, no extra keys. */\nexport interface PluginAiCapabilityArgsSchema {\n  type: 'object'\n  properties: Readonly<Record<string, PluginAiCapabilityArgProperty>>\n  required?: readonly string[]\n  additionalProperties: false\n}\n\n/** How the items that depend on a failed item of this capability behave. */\nexport type PluginAiCapabilityDegrade =\n  /** Dependents are built without it (a page loses the block that used it). */\n  | 'omit'\n  /** Dependents use something that already exists in its place (a site's own layout). */\n  | 'fallback'\n\n/** One planned item, as a capability sees it. */\nexport interface PluginAiCapabilityItem {\n  /** The item's name in the plan, unique within it; other items cite it as `new:<name>`. */\n  name: string\n  args: PluginAiCapabilityArgs\n}\n\n/** What a capability's `draftContent` is told beside the item. */\nexport interface PluginAiCapabilityDraftContext {\n  hostId: string\n  /**\n   * The drafts written for the items this one depends on, keyed by the\n   * reference the plan used (`new:<name>`), each with its operation and the\n   * id its own writer or runner gave it. A dependency that did not succeed is\n   * absent.\n   */\n  dependencies: Readonly<Record<string, { op: string; id: string }>>\n}\n\nexport interface PluginAiCapability {\n  /** The operation's name in a plan, stable across releases: `page`, `note`. */\n  op: string\n  /** What one is called in a sentence a person reads: \"contact form\". */\n  noun: string\n  /** Where a person finds the draft afterwards: \"Notes → Drafts\". */\n  where: string\n  /**\n   * What a person might ask for that this makes, as short phrases the chat's\n   * instructions list. True of the shipped product: never a promise the\n   * writer cannot keep.\n   */\n  intents: readonly string[]\n  /** The item's arguments, which the planner fills in. */\n  argsSchema: PluginAiCapabilityArgsSchema\n  /** How many items of this operation one plan may hold. */\n  maxPerPlan: number\n  /** Whether a workspace on the free plan may have one made. */\n  freeAllowed: boolean\n  /** The entitlement a workspace needs, checked with the platform's entitlement read. */\n  feature?: string\n  /** The site permission the member needs. */\n  permission?: string\n  /** The allowance one counts against, which the owner's writer meets. */\n  quota?: string\n  /**\n   * The resource whose writer on `plugin-resource-drafts` makes the draft.\n   * Exactly one of this and `runnerKind` is set.\n   */\n  draftResource?: string\n  /**\n   * The AI job kind whose runner makes it — the AI plugin's own operations.\n   * Exactly one of this and `draftResource` is set.\n   */\n  runnerKind?: string\n  /** The most this item can cost, in AI credits; a draft written without a model costs 0. */\n  estimateCredits(args: PluginAiCapabilityArgs): number\n  /** Operations an item of this one may depend on. */\n  dependsOnOps?: readonly string[]\n  degrade: PluginAiCapabilityDegrade\n  /**\n   * Blocks a page places when it uses an item of this operation (the block\n   * names the page palette knows). When the item fails, a dependent page is\n   * built without them, and says so.\n   */\n  pageBlocks?: readonly string[]\n  /**\n   * The writer's content for an item, from its arguments and its built\n   * dependencies. Pure. Absent means the arguments ARE the content.\n   */\n  draftContent?(\n    item: PluginAiCapabilityItem,\n    context: PluginAiCapabilityDraftContext,\n  ): Readonly<Record<string, unknown>>\n}\n\nexport const PLUGIN_AI_CAPABILITIES = definePluginServiceContract<PluginAiCapability>(\n  'core.ai-capabilities',\n  { multiple: true },\n)\n\nconst OP_PATTERN = /^[a-z][a-z0-9-]{0,39}$/\n\n/** Why a capability cannot be registered, or `null`. */\nexport function pluginAiCapabilityProblem(capability: PluginAiCapability): string | null {\n  if (!OP_PATTERN.test(capability.op)) {\n    return `ai capability op \"${capability.op}\" must be lowercase letters, digits and dashes`\n  }\n  const executors = [capability.draftResource, capability.runnerKind].filter(\n    (one) => typeof one === 'string' && one.trim(),\n  )\n  if (executors.length !== 1) {\n    return `ai capability \"${capability.op}\" needs exactly one of draftResource and runnerKind`\n  }\n  if (!Number.isInteger(capability.maxPerPlan) || capability.maxPerPlan < 1) {\n    return `ai capability \"${capability.op}\" needs a maxPerPlan of at least 1`\n  }\n  if (capability.argsSchema?.type !== 'object' || capability.argsSchema.additionalProperties !== false) {\n    return `ai capability \"${capability.op}\" needs a flat object argsSchema with additionalProperties: false`\n  }\n  for (const required of capability.argsSchema.required ?? []) {\n    if (!(required in capability.argsSchema.properties)) {\n      return `ai capability \"${capability.op}\" requires \"${required}\", which its schema does not declare`\n    }\n  }\n  if (!capability.noun.trim() || !capability.where.trim()) {\n    return `ai capability \"${capability.op}\" needs a noun and a where`\n  }\n  return null\n}\n\n/**\n * Registers what a plugin's AI builds can make. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`. An `op`\n * another plugin owns throws naming both; a malformed capability throws.\n */\nexport function registerPluginAiCapability(\n  capability: PluginAiCapability,\n  options?: { pluginId?: string },\n): void {\n  const problem = pluginAiCapabilityProblem(capability)\n  if (problem) throw new Error(problem)\n  const key = capability.op\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `ai capability \"${key}\" is already registered by \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_AI_CAPABILITIES, capability, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginAiCapability {\n  /** The plugin that owns the operation. */\n  pluginId: string\n  capability: PluginAiCapability\n}\n\n/** Every registered capability with its owner, in registration order. */\nexport function pluginAiCapabilities(): ResolvedPluginAiCapability[] {\n  return resolvePluginServices(PLUGIN_AI_CAPABILITIES).map((entry) => ({\n    pluginId: entry.pluginId,\n    capability: entry.impl,\n  }))\n}\n\n/** The capability for an operation, with its owner, or `null` when nothing registered it. */\nexport function pluginAiCapability(op: string): ResolvedPluginAiCapability | null {\n  const key = op.trim()\n  const entry = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, capability: entry.impl } : null\n}\n\n/**\n * What is wrong with an item's arguments against its schema; empty when\n * nothing is. Pure, and the same answer on both sides of the seam: the\n * planner holds the model to it, and an owner may hold its content to it.\n */\nexport function pluginAiCapabilityArgsProblems(\n  schema: PluginAiCapabilityArgsSchema,\n  args: Readonly<Record<string, unknown>>,\n): string[] {\n  const problems: string[] = []\n  for (const name of schema.required ?? []) {\n    const value = args[name]\n    if (value === undefined || value === null || value === '') problems.push(`\"${name}\" is required`)\n  }\n  for (const [name, value] of Object.entries(args)) {\n    const property = schema.properties[name]\n    if (!property) {\n      problems.push(`\"${name}\" is not an argument`)\n      continue\n    }\n    if (value === undefined || value === null) continue\n    switch (property.type) {\n      case 'string':\n        if (typeof value !== 'string') problems.push(`\"${name}\" must be text`)\n        else {\n          if (property.enum && !property.enum.includes(value)) {\n            problems.push(`\"${name}\" must be one of ${property.enum.join(', ')}`)\n          }\n          if (property.maxLength !== undefined && value.length > property.maxLength) {\n            problems.push(`\"${name}\" must be at most ${property.maxLength} characters`)\n          }\n        }\n        break\n      case 'integer':\n      case 'number':\n        if (\n          typeof value !== 'number' ||\n          !Number.isFinite(value) ||\n          (property.type === 'integer' && !Number.isInteger(value))\n        ) {\n          problems.push(`\"${name}\" must be ${property.type === 'integer' ? 'a whole number' : 'a number'}`)\n        } else {\n          if (property.minimum !== undefined && value < property.minimum) {\n            problems.push(`\"${name}\" must be at least ${property.minimum}`)\n          }\n          if (property.maximum !== undefined && value > property.maximum) {\n            problems.push(`\"${name}\" must be at most ${property.maximum}`)\n          }\n        }\n        break\n      case 'boolean':\n        if (typeof value !== 'boolean') problems.push(`\"${name}\" must be true or false`)\n        break\n      case 'array':\n        if (!Array.isArray(value) || value.some((one) => typeof one !== 'string')) {\n          problems.push(`\"${name}\" must be a list of text`)\n        } else {\n          if (property.maxItems !== undefined && value.length > property.maxItems) {\n            problems.push(`\"${name}\" must hold at most ${property.maxItems}`)\n          }\n          const items = property.items\n          for (const one of value as string[]) {\n            if (items?.enum && !items.enum.includes(one)) {\n              problems.push(`\"${name}\" holds \"${one}\", which is not one of ${items.enum.join(', ')}`)\n              break\n            }\n            if (items?.maxLength !== undefined && one.length > items.maxLength) {\n              problems.push(`\"${name}\" holds an entry longer than ${items.maxLength} characters`)\n              break\n            }\n          }\n        }\n        break\n    }\n  }\n  return problems\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_AI_CAPABILITIES","multiple","OP_PATTERN","pluginAiCapabilityProblem","capability","test","op","executors","draftResource","runnerKind","filter","one","trim","length","Number","isInteger","maxPerPlan","argsSchema","type","additionalProperties","required","properties","noun","where","registerPluginAiCapability","options","problem","Error","key","pluginId","incumbent","find","entry","pluginAiCapabilities","map","impl","pluginAiCapability","pluginAiCapabilityArgsProblems","schema","args","problems","name","value","undefined","push","Object","entries","property","enum","includes","join","maxLength","isFinite","minimum","maximum","Array","isArray","some","maxItems","items"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-checkout-extras.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @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.
+ */
+/**
+ * Optional lines a buyer may add at checkout, offered by another plugin
+ * (AGL-3635).
+ *
+ * Package protection is the first: a plugin that insures parcels quotes a
+ * premium for the basket, the seller shows it as a box the buyer ticks, and
+ * the seller charges it as one more line. The seller never learns which
+ * insurer answered and the insurer never reads the seller's documents: the
+ * offer crosses here, and what was bought is recorded on the sale, which the
+ * seller's own events then carry.
+ *
+ * ## Money
+ *
+ * Every amount is integer cents in the request's currency. An offer is
+ * advisory until the sale: the seller asks again when the buyer pays and
+ * charges THAT answer, so a stale price in a drawer is never what is
+ * charged. An offer whose amount is not a positive integer, or whose
+ * currency differs from the request's, is dropped rather than rounded.
+ *
+ * ## Nobody home is an empty list
+ *
+ * A provider that is not configured, not switched on for the site, slow or
+ * failing answers nothing, and the seller sells exactly as it did before.
+ * {@link quotePluginCheckoutExtras} never throws.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-checkout-extras`); it is not in the
+ * barrel.
+ */
+/** One line of the basket, as a provider prices it. */
+export interface PluginCheckoutExtraLine {
+    /** The seller's id for the item, when it has one. */
+    itemId?: string;
+    name: string;
+    sku?: string;
+    quantity: number;
+    /** Per unit, integer cents, before discounts. */
+    unitCents: number;
+    /** Whether the line travels in a parcel. */
+    ships: boolean;
+}
+/** What a seller asks: the basket a buyer is about to pay for. */
+export interface PluginCheckoutExtraRequest {
+    hostId: string;
+    /** ISO-4217, lower case. */
+    currency: string;
+    /** The goods' value, integer cents, before discounts and shipping. */
+    itemsCents: number;
+    lines: PluginCheckoutExtraLine[];
+    /** Where the buyer said it goes, when they said. */
+    destination?: {
+        country?: string;
+        postalCode?: string;
+    };
+    /** Aborted when the seller stops waiting; a provider passes it to its fetches. */
+    signal?: AbortSignal;
+}
+/** What a provider offers for that basket. */
+export interface PluginCheckoutExtraOffer {
+    /** Stable within the provider: `package-protection`. Lower-case words and dashes. */
+    key: string;
+    /** What the buyer reads beside the box: `Package protection`. */
+    label: string;
+    /** One sentence under it. */
+    description?: string;
+    /** Integer cents, above zero. */
+    amountCents: number;
+    /** ISO-4217, lower case; must be the request's. */
+    currency: string;
+    /** Whether the box starts ticked. The merchant decides; default unticked. */
+    defaultSelected?: boolean;
+    /** The provider's id for this quote, carried onto the sale (64 characters at most). */
+    quoteRef?: string;
+    /** A page the buyer can read about it, `https:` only. */
+    termsUrl?: string;
+}
+export interface PluginCheckoutExtraProvider {
+    /** The offer for this basket, or `null`. Throwing reads as `null`. */
+    offer(request: PluginCheckoutExtraRequest): Promise<PluginCheckoutExtraOffer | null>;
+}
+/** An offer as the seller sees it: whose it is, and the id it is chosen by. */
+export interface QuotedPluginCheckoutExtra extends Required<Pick<PluginCheckoutExtraOffer, 'defaultSelected'>> {
+    /** `{pluginId}.{key}`: what a buyer's choice names. */
+    id: string;
+    pluginId: string;
+    key: string;
+    label: string;
+    description?: string;
+    amountCents: number;
+    currency: string;
+    quoteRef?: string;
+    termsUrl?: string;
+}
+/**
+ * What a sale recorded of one extra the buyer took. The seller stores this
+ * on the sale and puts it in the events it raises about the sale, so the
+ * provider learns what was bought from the seller's own facts.
+ */
+export interface PluginCheckoutExtraSold {
+    id: string;
+    pluginId: string;
+    key: string;
+    label: string;
+    amountCents: number;
+    quoteRef?: string;
+}
+/** The most extras one checkout carries. */
+export declare const MAX_CHECKOUT_EXTRAS = 3;
+/** Joins the providers. Re-registering under the same plugin replaces its own. */
+export declare function registerPluginCheckoutExtra(provider: PluginCheckoutExtraProvider, options?: {
+    pluginId?: string;
+}): void;
+/** Whether any plugin offers extras: a seller with none skips the question. */
+export declare function hasPluginCheckoutExtras(): boolean;
+/**
+ * An offer held to the contract, or `null`: a positive integer amount in the
+ * request's currency, a key and a label, and nothing else a page would render
+ * that it should not.
+ */
+export declare function normalizePluginCheckoutExtra(pluginId: string, offer: PluginCheckoutExtraOffer | null | undefined, currency: string): QuotedPluginCheckoutExtra | null;
+/**
+ * Asks every provider at once and keeps what answered within `timeoutMs`,
+ * each one held to the contract. Never throws; a provider that throws, is
+ * late or answers nonsense is simply absent. At most
+ * {@link MAX_CHECKOUT_EXTRAS}, in the providers' resolve order.
+ */
+export declare function quotePluginCheckoutExtras(request: Omit<PluginCheckoutExtraRequest, 'signal'>, options: {
+    timeoutMs: number;
+}): Promise<QuotedPluginCheckoutExtra[]>;
+/**
+ * The buyer's choice, read from a request body: the ids of offers they took,
+ * de-duplicated and bounded. Ids only; the amounts are always asked again.
+ */
+export declare function readChosenCheckoutExtras(value: unknown): string[];
+/** The metadata keys the extras ride under: `extra0`, `extra1`, `extra2`. */
+export declare const CHECKOUT_EXTRA_METADATA_PREFIX = "extra";
+/**
+ * The extras a sale carries, packed for a payment processor's metadata: one
+ * key per extra (`extra0` …), each `[id, cents, label, quoteRef?]` as JSON,
+ * well inside a 500-character value. One key each, so a long quote id can
+ * never truncate another extra out of the record.
+ */
+export declare function encodeCheckoutExtrasMetadata(extras: readonly QuotedPluginCheckoutExtra[]): Record<string, string>;
+/**
+ * Reads {@link encodeCheckoutExtrasMetadata} back off the metadata object.
+ * Anything unreadable is dropped, never guessed.
+ */
+export declare function decodeCheckoutExtrasMetadata(metadata: Record<string, unknown> | null | undefined): PluginCheckoutExtraSold[];
+/** The cents a sale's extras add up to. */
+export declare function checkoutExtrasCents(extras: ReadonlyArray<{
+    amountCents: number;
+}> | null | undefined): number;