@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/tools/ai-insight-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/tools/ai-insight-tool.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 {\n  AI_INSIGHT_GAP_MAX_CHARS,\n  AI_INSIGHT_MAX_CHARS,\n  AI_INSIGHT_MAX_CITED_ROWS,\n  AI_INSIGHT_MAX_CITES,\n  AI_INSIGHT_MAX_INSIGHTS,\n  AI_INSIGHT_MAX_READS,\n  type AiInsightAnswer,\n} from '../model/ai-insight'\nimport type { AiTool } from '../providers/contract'\n\n/**\n * The two strict tools an insight job answers through (AGL-2915).\n *\n * `read_figures` names readers — an id, a window and the reader's own\n * parameters — and nothing else: the model never writes a query, a field\n * path or a filter of its own, only a choice among the readers the request\n * lists. `submit_insights` is the answer, each insight citing the table rows\n * its figures come from. Lengths and counts are stated in the descriptions,\n * as the platform's other strict tools state them; the step holds every one.\n */\n\nexport const AI_INSIGHT_READ_TOOL_NAME = 'read_figures'\nexport const AI_INSIGHT_ANSWER_TOOL_NAME = 'submit_insights'\n\nexport function aiInsightReadTool(): AiTool {\n  return {\n    name: AI_INSIGHT_READ_TOOL_NAME,\n    description:\n      `Choose the readers whose tables answer the question: at most ${AI_INSIGHT_MAX_READS}, ` +\n      'each from the list the request gives. Every field is required.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        reads: {\n          type: 'array',\n          description: `The readers to read, most useful first; at most ${AI_INSIGHT_MAX_READS}.`,\n          items: {\n            type: 'object',\n            properties: {\n              reader: { type: 'string', description: 'A reader id from the list, exactly as written.' },\n              days: {\n                type: 'integer',\n                description: 'One of the windows that reader lists, in days; 0 for a reader that lists none.',\n              },\n              params: {\n                type: 'array',\n                description: 'The parameters that reader lists, by name; empty when it lists none.',\n                items: {\n                  type: 'object',\n                  properties: {\n                    name: { type: 'string' },\n                    value: { type: 'string' },\n                  },\n                  required: ['name', 'value'],\n                  additionalProperties: false,\n                },\n              },\n            },\n            required: ['reader', 'days', 'params'],\n            additionalProperties: false,\n          },\n        },\n      },\n      required: ['reads'],\n      additionalProperties: false,\n    },\n  }\n}\n\nexport function aiInsightAnswerTool(): AiTool {\n  return {\n    name: AI_INSIGHT_ANSWER_TOOL_NAME,\n    description:\n      `Answer with at most ${AI_INSIGHT_MAX_INSIGHTS} insights, each citing the table rows its figures come from. ` +\n      'Every field is required.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        insights: {\n          type: 'array',\n          description: `Most useful first; at most ${AI_INSIGHT_MAX_INSIGHTS}.`,\n          items: {\n            type: 'object',\n            properties: {\n              text: {\n                type: 'string',\n                description: `One or two plain sentences; at most ${AI_INSIGHT_MAX_CHARS} characters.`,\n              },\n              cites: {\n                type: 'array',\n                description: `The tables and rows its figures come from; at most ${AI_INSIGHT_MAX_CITES} tables.`,\n                items: {\n                  type: 'object',\n                  properties: {\n                    table: { type: 'string', description: 'The table handle: t1, t2, …' },\n                    rows: {\n                      type: 'array',\n                      description: `Row numbers as the table numbers them, from 0; at most ${AI_INSIGHT_MAX_CITED_ROWS}.`,\n                      items: { type: 'integer' },\n                    },\n                  },\n                  required: ['table', 'rows'],\n                  additionalProperties: false,\n                },\n              },\n            },\n            required: ['text', 'cites'],\n            additionalProperties: false,\n          },\n        },\n        gap: {\n          anyOf: [{ type: 'string' }, { type: 'null' }],\n          description: `What the tables cannot answer, in one sentence without numbers; at most ${AI_INSIGHT_GAP_MAX_CHARS} characters. null when nothing.`,\n        },\n      },\n      required: ['insights', 'gap'],\n      additionalProperties: false,\n    },\n  }\n}\n\n/** One reader the model asked for, as it asked. */\nexport interface AiInsightReadRequest {\n  reader: string\n  days: number\n  params: Record<string, string>\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** The reads a `read_figures` call names, shape-checked and bounded; the step decides which are real. */\nexport function parseAiInsightReads(input: unknown): AiInsightReadRequest[] {\n  const reads = isRecord(input) && Array.isArray(input['reads']) ? input['reads'] : []\n  const parsed: AiInsightReadRequest[] = []\n  for (const raw of reads) {\n    if (parsed.length === AI_INSIGHT_MAX_READS) break\n    if (!isRecord(raw) || typeof raw['reader'] !== 'string') continue\n    const params: Record<string, string> = {}\n    for (const pair of Array.isArray(raw['params']) ? raw['params'] : []) {\n      if (isRecord(pair) && typeof pair['name'] === 'string' && typeof pair['value'] === 'string') {\n        params[pair['name']] = pair['value']\n      }\n    }\n    const days = Number(raw['days'])\n    parsed.push({\n      reader: raw['reader'].trim(),\n      days: Number.isInteger(days) && days >= 0 ? days : 0,\n      params,\n    })\n  }\n  return parsed\n}\n\n/**\n * A `submit_insights` call as the trace reads it, or `null` when the call is\n * not an answer at all. Values keep the types the model wrote, so the trace\n * — not this reader — decides what an unreadable citation costs.\n */\nexport function parseAiInsightAnswer(input: unknown): AiInsightAnswer | null {\n  if (!isRecord(input) || !Array.isArray(input['insights'])) return null\n  const insights = input['insights']\n    .filter(isRecord)\n    .map((raw) => ({\n      text: typeof raw['text'] === 'string' ? raw['text'] : '',\n      cites: (Array.isArray(raw['cites']) ? raw['cites'] : []).filter(isRecord).map((cite) => ({\n        table: typeof cite['table'] === 'string' ? cite['table'] : '',\n        rows: (Array.isArray(cite['rows']) ? cite['rows'] : []) as number[],\n      })),\n    }))\n  const gap = typeof input['gap'] === 'string' ? input['gap'] : null\n  return { insights, gap }\n}\n"],"names":["AI_INSIGHT_GAP_MAX_CHARS","AI_INSIGHT_MAX_CHARS","AI_INSIGHT_MAX_CITED_ROWS","AI_INSIGHT_MAX_CITES","AI_INSIGHT_MAX_INSIGHTS","AI_INSIGHT_MAX_READS","AI_INSIGHT_READ_TOOL_NAME","AI_INSIGHT_ANSWER_TOOL_NAME","aiInsightReadTool","name","description","strict","inputSchema","type","properties","reads","items","reader","days","params","value","required","additionalProperties","aiInsightAnswerTool","insights","text","cites","table","rows","gap","anyOf","isRecord","Array","isArray","parseAiInsightReads","input","parsed","raw","length","pair","Number","push","trim","isInteger","parseAiInsightAnswer","filter","map","cite"],"mappings":"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"}

package/src/lib/tools/ai-inventory-lookup-tool.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 AiInventoryKind, type AiSiteInventory } from '../model/ai-site-inventory';
+import type { AiTool } from '../providers/contract';
+/**
+ * "More on request" (AGL-2937): the strict tool a generation calls to find
+ * the records its prompt did not list.
+ *
+ * The site inventory is the one VOLATILE part of a generation prompt — it is
+ * different for every site, so it can never sit inside a cached prefix, and
+ * every character of it is billed at full input rate on every attempt and on
+ * every re-ask. That puts a hard ceiling on how much of a large site a prompt
+ * can afford to carry, and doctrine rule 7 puts a floor under it: a plan that
+ * cannot see a component reuses nothing and creates a duplicate.
+ *
+ * So the prompt lists the first `AI_SITE_INVENTORY_LISTED_PER_KIND` records of
+ * each kind and says that more exist, and this tool answers for the rest, out
+ * of the wider window the reader holds in memory. The answer costs tokens only
+ * on the requests that ask for it, where the rows would otherwise have cost
+ * them on every request that did not.
+ *
+ * ## Why it is offered on every request
+ *
+ * A tool list renders AHEAD of the system blocks and is part of what a cache
+ * entry is keyed on, so a tool offered only to the sites big enough to need it
+ * would split the platform's one cached prefix in two. It is therefore offered
+ * on every request that carries an inventory block at all, whatever the site's
+ * size, and its schema names no record: `runtime/ai-prompt-cache.spec.ts` holds
+ * it to that.
+ *
+ * ## Why it is answered from memory
+ *
+ * The reader has already read the window, under the org-and-host scope check
+ * `readSiteInventory` makes before it reads anything. Answering from that
+ * window rather than from Firestore means a lookup cannot reach a record the
+ * request was not already entitled to, needs no second scope check to be
+ * correct, and adds no read to a job step's budget.
+ */
+export declare const AI_INVENTORY_LOOKUP_TOOL_NAME = "look_up_site_inventory";
+/** Records one answer lists. Past this the model narrows its query. */
+export declare const AI_INVENTORY_LOOKUP_MAX_ROWS = 25;
+/** The longest answer one lookup returns; it rides uncached, like the block. */
+export declare const AI_INVENTORY_LOOKUP_MAX_CHARS = 2000;
+/**
+ * Lookups one generation answers before it must answer with its own tool.
+ * Each is a model call the caller pays for, so the bound is small: two is
+ * enough to check a kind and then narrow once.
+ */
+export declare const AI_INVENTORY_LOOKUP_MAX_ROUNDS = 2;
+/** What one lookup asked for, once its input has been read. */
+export interface AiInventoryLookupQuery {
+    kind: AiInventoryKind;
+    /** The text to match; `null` asks for the records the prompt did not list. */
+    query: string | null;
+}
+/**
+ * The strict tool. Its schema names a kind and a search text and nothing of
+ * the site, so it is byte-identical for every workspace and every request.
+ */
+export declare function aiInventoryLookupTool(): AiTool;
+/** A tool call's input as a query, or `null` when it named no kind of this site. */
+export declare function readAiInventoryLookup(input: Record<string, unknown>): AiInventoryLookupQuery | null;
+/**
+ * One lookup, answered out of the inventory the request was built from.
+ *
+ * The answer is plain text in the same `id · name · …` shape the prompt's own
+ * block uses, so a record found here reads exactly like a record that was
+ * listed, and a plan refers to either by id the same way. It says how many
+ * records were searched, so "nothing matched" is told apart from "nothing is
+ * there" — the distinction rule 7 turns on.
+ */
+export declare function answerAiInventoryLookup(inventory: AiSiteInventory | null, input: Record<string, unknown>): string;

package/src/lib/tools/ai-inventory-lookup-tool.js

@@ -0,0 +1,164 @@
+/**
+ * @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 { AI_INVENTORY_KINDS, AI_INVENTORY_KIND_HEADINGS, AI_SITE_INVENTORY_LISTED_PER_KIND, aiInventoryHaystack, aiInventoryLine, aiInventoryRows } from "../model/ai-site-inventory.js";
+/**
+ * "More on request" (AGL-2937): the strict tool a generation calls to find
+ * the records its prompt did not list.
+ *
+ * The site inventory is the one VOLATILE part of a generation prompt — it is
+ * different for every site, so it can never sit inside a cached prefix, and
+ * every character of it is billed at full input rate on every attempt and on
+ * every re-ask. That puts a hard ceiling on how much of a large site a prompt
+ * can afford to carry, and doctrine rule 7 puts a floor under it: a plan that
+ * cannot see a component reuses nothing and creates a duplicate.
+ *
+ * So the prompt lists the first `AI_SITE_INVENTORY_LISTED_PER_KIND` records of
+ * each kind and says that more exist, and this tool answers for the rest, out
+ * of the wider window the reader holds in memory. The answer costs tokens only
+ * on the requests that ask for it, where the rows would otherwise have cost
+ * them on every request that did not.
+ *
+ * ## Why it is offered on every request
+ *
+ * A tool list renders AHEAD of the system blocks and is part of what a cache
+ * entry is keyed on, so a tool offered only to the sites big enough to need it
+ * would split the platform's one cached prefix in two. It is therefore offered
+ * on every request that carries an inventory block at all, whatever the site's
+ * size, and its schema names no record: `runtime/ai-prompt-cache.spec.ts` holds
+ * it to that.
+ *
+ * ## Why it is answered from memory
+ *
+ * The reader has already read the window, under the org-and-host scope check
+ * `readSiteInventory` makes before it reads anything. Answering from that
+ * window rather than from Firestore means a lookup cannot reach a record the
+ * request was not already entitled to, needs no second scope check to be
+ * correct, and adds no read to a job step's budget.
+ */ export const AI_INVENTORY_LOOKUP_TOOL_NAME = 'look_up_site_inventory';
+/** Records one answer lists. Past this the model narrows its query. */ export const AI_INVENTORY_LOOKUP_MAX_ROWS = 25;
+/** The longest answer one lookup returns; it rides uncached, like the block. */ export const AI_INVENTORY_LOOKUP_MAX_CHARS = 2000;
+/**
+ * Lookups one generation answers before it must answer with its own tool.
+ * Each is a model call the caller pays for, so the bound is small: two is
+ * enough to check a kind and then narrow once.
+ */ export const AI_INVENTORY_LOOKUP_MAX_ROUNDS = 2;
+/**
+ * The strict tool. Its schema names a kind and a search text and nothing of
+ * the site, so it is byte-identical for every workspace and every request.
+ */ export function aiInventoryLookupTool() {
+    return {
+        name: AI_INVENTORY_LOOKUP_TOOL_NAME,
+        description: 'Find records of this site that the inventory above did not list. Search one kind at a ' + 'time by any word of a record: its id, its name, a prop, a field or a slug. Pass null as ' + 'the query to list the records of that kind the inventory left out. Use this before you ' + 'create anything the site may already have.',
+        strict: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: [
+                        ...AI_INVENTORY_KINDS
+                    ],
+                    description: 'The kind of record to search.'
+                },
+                query: {
+                    anyOf: [
+                        {
+                            type: 'string'
+                        },
+                        {
+                            type: 'null'
+                        }
+                    ],
+                    description: 'The text to match against a record, or null for the records that were not listed.'
+                }
+            },
+            required: [
+                'kind',
+                'query'
+            ],
+            additionalProperties: false
+        }
+    };
+}
+/** A tool call's input as a query, or `null` when it named no kind of this site. */ export function readAiInventoryLookup(input) {
+    const kind = input['kind'];
+    if (typeof kind !== 'string' || !AI_INVENTORY_KINDS.includes(kind)) {
+        return null;
+    }
+    const raw = input['query'];
+    const query = typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim() : '';
+    return {
+        kind: kind,
+        query: query || null
+    };
+}
+/** The lines an answer lists, capped by count and then by characters. */ function listed(lines) {
+    const rendered = [];
+    let used = 0;
+    for (const line of lines.slice(0, AI_INVENTORY_LOOKUP_MAX_ROWS)){
+        if (used + line.length + 3 > AI_INVENTORY_LOOKUP_MAX_CHARS) {
+            return {
+                rendered,
+                cut: true
+            };
+        }
+        rendered.push(line);
+        used += line.length + 3;
+    }
+    return {
+        rendered,
+        cut: lines.length > rendered.length
+    };
+}
+/**
+ * One lookup, answered out of the inventory the request was built from.
+ *
+ * The answer is plain text in the same `id · name · …` shape the prompt's own
+ * block uses, so a record found here reads exactly like a record that was
+ * listed, and a plan refers to either by id the same way. It says how many
+ * records were searched, so "nothing matched" is told apart from "nothing is
+ * there" — the distinction rule 7 turns on.
+ */ export function answerAiInventoryLookup(inventory, input) {
+    if (!inventory) {
+        return 'No site inventory was read for this request, so there is nothing to look up.';
+    }
+    const asked = readAiInventoryLookup(input);
+    if (!asked) {
+        return `That is not a kind of record this site has. The kinds are: ${AI_INVENTORY_KINDS.join(', ')}.`;
+    }
+    const rows = aiInventoryRows(inventory, asked.kind);
+    const needle = asked.query ? asked.query.toLowerCase() : null;
+    const matches = needle ? rows.filter((row)=>aiInventoryHaystack(asked.kind, row).includes(needle)) : rows.slice(AI_SITE_INVENTORY_LISTED_PER_KIND);
+    // "None match" and "there are none" are different answers, and rule 7 turns
+    // on the difference, so every answer says what it searched.
+    const held = `this site's ${rows.length} ${asked.kind}`;
+    if (!matches.length) {
+        const more = inventory.truncated.includes(asked.kind) ? ' More exist than were read, so this is not proof there is none.' : '';
+        return needle ? `None of ${held} matches "${asked.query}".${more}` : `Every one of ${held} was listed above.${more}`;
+    }
+    const { rendered, cut } = listed(matches.map((row)=>aiInventoryLine(asked.kind, row)));
+    const head = needle ? `${matches.length} of ${held} match "${asked.query}".` : `${matches.length} of ${held} were not listed above.`;
+    return [
+        head,
+        `${AI_INVENTORY_KIND_HEADINGS[asked.kind]}:`,
+        ...rendered.map((line)=>`- ${line}`),
+        ...cut ? [
+            'More match than are listed here. Narrow the query to see the rest.'
+        ] : []
+    ].join('\n');
+}
+
+//# sourceMappingURL=ai-inventory-lookup-tool.js.map

package/src/lib/tools/ai-inventory-lookup-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/tools/ai-inventory-lookup-tool.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 {\n  AI_INVENTORY_KINDS,\n  AI_INVENTORY_KIND_HEADINGS,\n  AI_SITE_INVENTORY_LISTED_PER_KIND,\n  aiInventoryHaystack,\n  aiInventoryLine,\n  aiInventoryRows,\n  type AiInventoryKind,\n  type AiSiteInventory,\n} from '../model/ai-site-inventory'\nimport type { AiTool } from '../providers/contract'\n\n/**\n * \"More on request\" (AGL-2937): the strict tool a generation calls to find\n * the records its prompt did not list.\n *\n * The site inventory is the one VOLATILE part of a generation prompt — it is\n * different for every site, so it can never sit inside a cached prefix, and\n * every character of it is billed at full input rate on every attempt and on\n * every re-ask. That puts a hard ceiling on how much of a large site a prompt\n * can afford to carry, and doctrine rule 7 puts a floor under it: a plan that\n * cannot see a component reuses nothing and creates a duplicate.\n *\n * So the prompt lists the first `AI_SITE_INVENTORY_LISTED_PER_KIND` records of\n * each kind and says that more exist, and this tool answers for the rest, out\n * of the wider window the reader holds in memory. The answer costs tokens only\n * on the requests that ask for it, where the rows would otherwise have cost\n * them on every request that did not.\n *\n * ## Why it is offered on every request\n *\n * A tool list renders AHEAD of the system blocks and is part of what a cache\n * entry is keyed on, so a tool offered only to the sites big enough to need it\n * would split the platform's one cached prefix in two. It is therefore offered\n * on every request that carries an inventory block at all, whatever the site's\n * size, and its schema names no record: `runtime/ai-prompt-cache.spec.ts` holds\n * it to that.\n *\n * ## Why it is answered from memory\n *\n * The reader has already read the window, under the org-and-host scope check\n * `readSiteInventory` makes before it reads anything. Answering from that\n * window rather than from Firestore means a lookup cannot reach a record the\n * request was not already entitled to, needs no second scope check to be\n * correct, and adds no read to a job step's budget.\n */\n\nexport const AI_INVENTORY_LOOKUP_TOOL_NAME = 'look_up_site_inventory'\n\n/** Records one answer lists. Past this the model narrows its query. */\nexport const AI_INVENTORY_LOOKUP_MAX_ROWS = 25\n\n/** The longest answer one lookup returns; it rides uncached, like the block. */\nexport const AI_INVENTORY_LOOKUP_MAX_CHARS = 2_000\n\n/**\n * Lookups one generation answers before it must answer with its own tool.\n * Each is a model call the caller pays for, so the bound is small: two is\n * enough to check a kind and then narrow once.\n */\nexport const AI_INVENTORY_LOOKUP_MAX_ROUNDS = 2\n\n/** What one lookup asked for, once its input has been read. */\nexport interface AiInventoryLookupQuery {\n  kind: AiInventoryKind\n  /** The text to match; `null` asks for the records the prompt did not list. */\n  query: string | null\n}\n\n/**\n * The strict tool. Its schema names a kind and a search text and nothing of\n * the site, so it is byte-identical for every workspace and every request.\n */\nexport function aiInventoryLookupTool(): AiTool {\n  return {\n    name: AI_INVENTORY_LOOKUP_TOOL_NAME,\n    description:\n      'Find records of this site that the inventory above did not list. Search one kind at a ' +\n      'time by any word of a record: its id, its name, a prop, a field or a slug. Pass null as ' +\n      'the query to list the records of that kind the inventory left out. Use this before you ' +\n      'create anything the site may already have.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        kind: {\n          type: 'string',\n          enum: [...AI_INVENTORY_KINDS],\n          description: 'The kind of record to search.',\n        },\n        query: {\n          anyOf: [{ type: 'string' }, { type: 'null' }],\n          description:\n            'The text to match against a record, or null for the records that were not listed.',\n        },\n      },\n      required: ['kind', 'query'],\n      additionalProperties: false,\n    },\n  }\n}\n\n/** A tool call's input as a query, or `null` when it named no kind of this site. */\nexport function readAiInventoryLookup(\n  input: Record<string, unknown>,\n): AiInventoryLookupQuery | null {\n  const kind = input['kind']\n  if (typeof kind !== 'string' || !(AI_INVENTORY_KINDS as readonly string[]).includes(kind)) {\n    return null\n  }\n  const raw = input['query']\n  const query = typeof raw === 'string' ? raw.replace(/\\s+/g, ' ').trim() : ''\n  return { kind: kind as AiInventoryKind, query: query || null }\n}\n\n/** The lines an answer lists, capped by count and then by characters. */\nfunction listed(lines: readonly string[]): { rendered: string[]; cut: boolean } {\n  const rendered: string[] = []\n  let used = 0\n  for (const line of lines.slice(0, AI_INVENTORY_LOOKUP_MAX_ROWS)) {\n    if (used + line.length + 3 > AI_INVENTORY_LOOKUP_MAX_CHARS) {\n      return { rendered, cut: true }\n    }\n    rendered.push(line)\n    used += line.length + 3\n  }\n  return { rendered, cut: lines.length > rendered.length }\n}\n\n/**\n * One lookup, answered out of the inventory the request was built from.\n *\n * The answer is plain text in the same `id · name · …` shape the prompt's own\n * block uses, so a record found here reads exactly like a record that was\n * listed, and a plan refers to either by id the same way. It says how many\n * records were searched, so \"nothing matched\" is told apart from \"nothing is\n * there\" — the distinction rule 7 turns on.\n */\nexport function answerAiInventoryLookup(\n  inventory: AiSiteInventory | null,\n  input: Record<string, unknown>,\n): string {\n  if (!inventory) {\n    return 'No site inventory was read for this request, so there is nothing to look up.'\n  }\n  const asked = readAiInventoryLookup(input)\n  if (!asked) {\n    return `That is not a kind of record this site has. The kinds are: ${AI_INVENTORY_KINDS.join(', ')}.`\n  }\n  const rows = aiInventoryRows(inventory, asked.kind)\n  const needle = asked.query ? asked.query.toLowerCase() : null\n  const matches = needle\n    ? rows.filter((row) => aiInventoryHaystack(asked.kind, row).includes(needle))\n    : rows.slice(AI_SITE_INVENTORY_LISTED_PER_KIND)\n  // \"None match\" and \"there are none\" are different answers, and rule 7 turns\n  // on the difference, so every answer says what it searched.\n  const held = `this site's ${rows.length} ${asked.kind}`\n  if (!matches.length) {\n    const more = inventory.truncated.includes(asked.kind)\n      ? ' More exist than were read, so this is not proof there is none.'\n      : ''\n    return needle\n      ? `None of ${held} matches \"${asked.query}\".${more}`\n      : `Every one of ${held} was listed above.${more}`\n  }\n  const { rendered, cut } = listed(matches.map((row) => aiInventoryLine(asked.kind, row)))\n  const head = needle\n    ? `${matches.length} of ${held} match \"${asked.query}\".`\n    : `${matches.length} of ${held} were not listed above.`\n  return [\n    head,\n    `${AI_INVENTORY_KIND_HEADINGS[asked.kind]}:`,\n    ...rendered.map((line) => `- ${line}`),\n    ...(cut ? ['More match than are listed here. Narrow the query to see the rest.'] : []),\n  ].join('\\n')\n}\n"],"names":["AI_INVENTORY_KINDS","AI_INVENTORY_KIND_HEADINGS","AI_SITE_INVENTORY_LISTED_PER_KIND","aiInventoryHaystack","aiInventoryLine","aiInventoryRows","AI_INVENTORY_LOOKUP_TOOL_NAME","AI_INVENTORY_LOOKUP_MAX_ROWS","AI_INVENTORY_LOOKUP_MAX_CHARS","AI_INVENTORY_LOOKUP_MAX_ROUNDS","aiInventoryLookupTool","name","description","strict","inputSchema","type","properties","kind","enum","query","anyOf","required","additionalProperties","readAiInventoryLookup","input","includes","raw","replace","trim","listed","lines","rendered","used","line","slice","length","cut","push","answerAiInventoryLookup","inventory","asked","join","rows","needle","toLowerCase","matches","filter","row","held","more","truncated","map","head"],"mappings":"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"}

package/src/lib/tools/ai-products-tool.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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 AiCatalogProduct, type AiCategoriesProposal, type AiProductCopy } from '../model/ai-products';
+import type { AiTool } from '../providers/contract';
+import type { AiGenerationCheckResult } from '../runtime/ai-doctrine';
+/**
+ * The strict tools commerce by AI answers through (AGL-2916), and the checks
+ * that hold each answer to the commerce editor it proposes for.
+ *
+ * - `propose_product_copy` — one product's description, search listing, tags,
+ *   categories and option names.
+ * - `propose_catalog` — a store's first products, from a brief.
+ * - `propose_categories_and_discounts` — store categories and a first set of
+ *   discounts, from a brief.
+ *
+ * Each schema is kept small, and no field is nullable: "none" is an empty
+ * string, an empty list or zero. A strict schema accepts no length keyword,
+ * so every bound is stated in a description and enforced here. A check
+ * returns a value only when nothing in the answer is broken, and otherwise
+ * the violations and the parts at fault, for the generation call's one
+ * re-ask.
+ */
+export declare const AI_PRODUCT_COPY_TOOL_NAME = "propose_product_copy";
+export declare const AI_CATALOG_TOOL_NAME = "propose_catalog";
+export declare const AI_CATEGORIES_TOOL_NAME = "propose_categories_and_discounts";
+export declare const AI_PRODUCT_COPY_TOOL: AiTool;
+export interface AiProductCopyCheckContext {
+    /** The ids of the site's categories the request listed. */
+    categoryIds: readonly string[];
+    /** How many options the product has. */
+    optionCount: number;
+    /** The merchant's own words about the product: its name, text and tags. */
+    merchantWords: string;
+}
+/**
+ * A product copy answer held to the editor: every field written and within
+ * its length, plain text, the categories the request listed, one distinct
+ * name per option, and no claim or price the copy may not make.
+ */
+export declare function checkAiProductCopy(answer: Record<string, unknown>, context: AiProductCopyCheckContext): AiGenerationCheckResult<AiProductCopy>;
+export declare const AI_CATALOG_TOOL: AiTool;
+/** A catalog answer held to the products editor and the storefront copy rules. */
+export declare function checkAiCatalog(answer: Record<string, unknown>, context: {
+    merchantWords: string;
+}): AiGenerationCheckResult<AiCatalogProduct[]>;
+export declare const AI_CATEGORIES_TOOL: AiTool;
+/** A categories answer held to the catalog and discount editors and the storefront copy rules. */
+export declare function checkAiCategories(answer: Record<string, unknown>, context: {
+    existingCategoryNames: readonly string[];
+    merchantWords: string;
+}): AiGenerationCheckResult<Pick<AiCategoriesProposal, 'categories' | 'discounts'>>;