@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-crm.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @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 { ConsoleImportColumn, ConsoleImportColumnShape } from '@aglyn/aglyn/plugin-manager/record-zone-props';
+import type { AiJobSummary } from './ai-jobs.types';
+/**
+ * CRM by AI (AGL-2917): what a `crm` job is asked, and the proposals it
+ * answers with, in the shape the job step keeps and the console widgets read.
+ * Pure data and readers, with no server import.
+ *
+ * ## Three questions, all proposals
+ *
+ * - `record` — a contact, company, deal or lead: a short summary of where the
+ *   relationship stands, the next step as a task (never for a lead, which no
+ *   task can link to), a stage for a deal, and a lead's standing. The member
+ *   saves the task in the CRM's task form and confirms a stage move there.
+ * - `email` — a subject and a plain-text message for the CRM composer, greeted
+ *   and signed with merge fields. The member edits it and presses Send; a job
+ *   never sends anything.
+ * - `mapping` — which of a file's columns fill which fields of an import. The
+ *   import drawer shows it in its own table and preview before anything is
+ *   imported.
+ *
+ * ## What the model is given
+ *
+ * The CRM decides it: the facts its readers report on the core's record-facts
+ * seam, never a document the AI plugin read itself. For an import, the
+ * columns' headers and shapes — never a cell of the file.
+ *
+ * ## Where an answer is kept
+ *
+ * Not on the job: every member of a workspace may read its jobs, and a
+ * summary of a contact is the contact's to show. The job's output names the
+ * question ({@link AiCrmOutputRef}); the answer is kept apart, and the answer
+ * door serves it only to a member the CRM still lets read the record.
+ */
+/** The plugin that owns every record a `crm` job reads, as `plugins.config.json` names it. */
+export declare const AI_CRM_PLUGIN_ID = "crm";
+/** What the site's plugin list calls it, for the sentence a person reads. */
+export declare const AI_CRM_PLUGIN_LABEL = "CRM";
+export type AiCrmTask = 'record' | 'email' | 'mapping';
+export declare const AI_CRM_TASKS: readonly AiCrmTask[];
+export type AiCrmRecordKind = 'contact' | 'company' | 'deal' | 'lead';
+export declare const AI_CRM_RECORD_KINDS: readonly AiCrmRecordKind[];
+/** The records an email is written from: a person, a deal (its person) or a lead. */
+export declare const AI_CRM_EMAIL_RECORD_KINDS: readonly AiCrmRecordKind[];
+export type AiCrmImportCollection = 'contacts' | 'companies' | 'deals' | 'leads';
+export declare const AI_CRM_IMPORT_COLLECTIONS: readonly AiCrmImportCollection[];
+/** The resource names the CRM's readers are registered under on the record-facts seam. */
+export declare const AI_CRM_FACTS_RESOURCES: Readonly<Record<AiCrmRecordKind, string>>;
+/** The import catalogs' resource name; the collection is the record id. */
+export declare const AI_CRM_IMPORT_FACTS_RESOURCE = "crm.import";
+export declare const AI_CRM_COLUMN_SHAPES: readonly ConsoleImportColumnShape[];
+/** The most columns one mapping request sends. */
+export declare const AI_CRM_MAX_COLUMNS = 60;
+/** How much of a column header is sent. */
+export declare const AI_CRM_HEADER_MAX_CHARS = 60;
+/** How much of the member's request an email draft carries. */
+export declare const AI_CRM_EMAIL_REQUEST_MAX_CHARS = 600;
+/** Lengths the CRM tools hold an answer to. */
+export declare const AI_CRM_LIMITS: {
+    readonly summary: 320;
+    readonly standing: 280;
+    readonly taskTitle: 80;
+    readonly reason: 160;
+    readonly subject: 100;
+    readonly body: 1200;
+    /** The latest a proposed next step may be due, in days from today. */
+    readonly dueInDays: 30;
+};
+/** A task the job proposes as the record's next step. */
+export interface AiCrmNextStep {
+    title: string;
+    kind: 'call' | 'email' | 'meeting' | 'todo';
+    priority: 'low' | 'normal' | 'high';
+    dueInDays: number;
+    /** Why, pointing at the fact behind it. */
+    reason: string;
+}
+/** A stage the job proposes a deal move to. */
+export interface AiCrmStageMove {
+    stageId: string;
+    stageName: string;
+    reason: string;
+}
+export interface AiCrmRecordProposal {
+    kind: 'record';
+    record: {
+        kind: AiCrmRecordKind;
+        id: string;
+    };
+    summary: string;
+    nextStep: AiCrmNextStep | null;
+    stage: AiCrmStageMove | null;
+    /** Why a lead stands where it does; `null` for any other record. */
+    standing: string | null;
+    /** The UTC day the facts were read. */
+    asOf: string;
+    /** The job the answer was reused from, when it was not asked for again. */
+    reusedFrom?: string;
+}
+export interface AiCrmEmailProposal {
+    kind: 'email';
+    record: {
+        kind: AiCrmRecordKind;
+        id: string;
+    };
+    subject: string;
+    body: string;
+}
+/** One column the job matched to a field. */
+export interface AiCrmColumnMatch {
+    column: number;
+    header: string;
+    field: string;
+    label: string;
+}
+export interface AiCrmMappingProposal {
+    kind: 'mapping';
+    collection: AiCrmImportCollection;
+    matches: AiCrmColumnMatch[];
+    /** How many columns the request sent. */
+    columns: number;
+}
+export type AiCrmProposal = AiCrmRecordProposal | AiCrmEmailProposal | AiCrmMappingProposal;
+/** The output ids a `crm` job writes: one per question. */
+export declare const AI_CRM_OUTPUT_IDS: {
+    readonly record: (kind: AiCrmRecordKind, id: string) => string;
+    readonly email: (kind: AiCrmRecordKind, id: string) => string;
+    readonly mapping: (collection: AiCrmImportCollection) => string;
+};
+/** What a `crm` job's inputs say it is asked, read and bounded. */
+export type AiCrmRequest = {
+    task: 'record';
+    record: {
+        kind: AiCrmRecordKind;
+        id: string;
+    };
+} | {
+    task: 'email';
+    record: {
+        kind: AiCrmRecordKind;
+        id: string;
+    };
+} | {
+    task: 'mapping';
+    collection: AiCrmImportCollection;
+    columns: ConsoleImportColumn[];
+};
+/** The columns a mapping request sends, as the job's inputs carry them (a JSON string). */
+export declare function aiCrmColumnsInput(columns: readonly ConsoleImportColumn[]): string;
+/** What a `crm` job is asked, or the sentence naming what its inputs lack. */
+export declare function parseAiCrmRequest(inputs: Readonly<Record<string, unknown>> | null | undefined): AiCrmRequest | string;
+/** A stored proposal read back, or `null` when it is not one a `crm` job writes. */
+export declare function readAiCrmProposal(raw: unknown): AiCrmProposal | null;
+/**
+ * What a `crm` job's output says about its answer (AGL-2917): which question,
+ * about which record or import. The answer itself is not on the job — every
+ * member of a workspace may read a job, and not every member may read the
+ * record — so it is kept in {@link AI_CRM_ANSWERS_COLLECTION} and read through
+ * the answer door, which asks the CRM again whether this member may read it.
+ */
+export type AiCrmOutputRef = {
+    kind: 'record' | 'email';
+    record: {
+        kind: AiCrmRecordKind;
+        id: string;
+    };
+} | {
+    kind: 'mapping';
+    collection: AiCrmImportCollection;
+};
+/** An output's reference read back, or `null` when it is not one a `crm` job writes. */
+export declare function readAiCrmOutputRef(raw: unknown): AiCrmOutputRef | null;
+/** What a widget looks for among a workspace's jobs: one question about one record, or one import. */
+export type AiCrmAnswerWanted = {
+    kind: 'record' | 'email';
+    record: {
+        kind: string;
+        id: string;
+    };
+} | {
+    kind: 'mapping';
+    collection: string;
+};
+/** Whether a job answered the question a widget asks. */
+export declare function aiCrmJobAnswers(job: Pick<AiJobSummary, 'kind' | 'outputs'> | null | undefined, wanted: AiCrmAnswerWanted): boolean;
+/** The org collection a `crm` job's answer is kept in, which no client may read. */
+export declare const AI_CRM_ANSWERS_COLLECTION = "aiCrmAnswers";
+/**
+ * How long an answer is kept: two weeks, far shorter than the job's own clock.
+ * An answer is written from a person's record, and erasing a person from a
+ * workspace does not sweep this collection, so the copy has to be gone on its
+ * own well inside the month an erasure request is answered in. The answer
+ * door stops serving it at once, because the CRM no longer finds the record.
+ */
+export declare const AI_CRM_ANSWER_RETENTION_DAYS = 14;
+/** When an answer written at `now` expires: a `Date`, which a TTL policy keys on. */
+export declare function aiCrmAnswerExpiry(now?: Date): Date;
+/** An answer as it is kept at `orgs/{orgId}/aiCrmAnswers/{jobId}`. */
+export interface AiCrmAnswerRecord {
+    jobId: string;
+    orgId: string;
+    /** The site the record was read on, or `null` at the organization level. */
+    hostId: string | null;
+    /** The member who asked. */
+    createdBy: string;
+    task: AiCrmTask;
+    /** The record an answer is about, by the resource its facts were read from; `null` for a mapping. */
+    resource: string;
+    recordId: string;
+    proposal: AiCrmProposal;
+    /** A record answer's request key, which a later job reuses it by; `null` for any other. */
+    key: string | null;
+    createdAt: unknown;
+    expiresAt?: unknown;
+}
+/** What the answer door serves. */
+export interface AiCrmAnswerWire {
+    jobId: string;
+    hostId: string | null;
+    createdBy: string;
+    proposal: AiCrmProposal;
+}

package/src/lib/model/ai-crm.js

@@ -0,0 +1,225 @@
+/**
+ * @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.
+ */ /**
+ * CRM by AI (AGL-2917): what a `crm` job is asked, and the proposals it
+ * answers with, in the shape the job step keeps and the console widgets read.
+ * Pure data and readers, with no server import.
+ *
+ * ## Three questions, all proposals
+ *
+ * - `record` — a contact, company, deal or lead: a short summary of where the
+ *   relationship stands, the next step as a task (never for a lead, which no
+ *   task can link to), a stage for a deal, and a lead's standing. The member
+ *   saves the task in the CRM's task form and confirms a stage move there.
+ * - `email` — a subject and a plain-text message for the CRM composer, greeted
+ *   and signed with merge fields. The member edits it and presses Send; a job
+ *   never sends anything.
+ * - `mapping` — which of a file's columns fill which fields of an import. The
+ *   import drawer shows it in its own table and preview before anything is
+ *   imported.
+ *
+ * ## What the model is given
+ *
+ * The CRM decides it: the facts its readers report on the core's record-facts
+ * seam, never a document the AI plugin read itself. For an import, the
+ * columns' headers and shapes — never a cell of the file.
+ *
+ * ## Where an answer is kept
+ *
+ * Not on the job: every member of a workspace may read its jobs, and a
+ * summary of a contact is the contact's to show. The job's output names the
+ * question ({@link AiCrmOutputRef}); the answer is kept apart, and the answer
+ * door serves it only to a member the CRM still lets read the record.
+ */ /** The plugin that owns every record a `crm` job reads, as `plugins.config.json` names it. */ export const AI_CRM_PLUGIN_ID = 'crm';
+/** What the site's plugin list calls it, for the sentence a person reads. */ export const AI_CRM_PLUGIN_LABEL = 'CRM';
+export const AI_CRM_TASKS = [
+    'record',
+    'email',
+    'mapping'
+];
+export const AI_CRM_RECORD_KINDS = [
+    'contact',
+    'company',
+    'deal',
+    'lead'
+];
+/** The records an email is written from: a person, a deal (its person) or a lead. */ export const AI_CRM_EMAIL_RECORD_KINDS = [
+    'contact',
+    'deal',
+    'lead'
+];
+export const AI_CRM_IMPORT_COLLECTIONS = [
+    'contacts',
+    'companies',
+    'deals',
+    'leads'
+];
+/** The resource names the CRM's readers are registered under on the record-facts seam. */ export const AI_CRM_FACTS_RESOURCES = {
+    contact: 'crm.contact',
+    company: 'crm.company',
+    deal: 'crm.deal',
+    lead: 'crm.lead'
+};
+/** The import catalogs' resource name; the collection is the record id. */ export const AI_CRM_IMPORT_FACTS_RESOURCE = 'crm.import';
+export const AI_CRM_COLUMN_SHAPES = [
+    'empty',
+    'email',
+    'phone',
+    'number',
+    'date',
+    'yes-no',
+    'url',
+    'text'
+];
+/** The most columns one mapping request sends. */ export const AI_CRM_MAX_COLUMNS = 60;
+/** How much of a column header is sent. */ export const AI_CRM_HEADER_MAX_CHARS = 60;
+/** How much of the member's request an email draft carries. */ export const AI_CRM_EMAIL_REQUEST_MAX_CHARS = 600;
+/** Lengths the CRM tools hold an answer to. */ export const AI_CRM_LIMITS = {
+    summary: 320,
+    standing: 280,
+    taskTitle: 80,
+    reason: 160,
+    subject: 100,
+    body: 1200,
+    /** The latest a proposed next step may be due, in days from today. */ dueInDays: 30
+};
+/** The output ids a `crm` job writes: one per question. */ export const AI_CRM_OUTPUT_IDS = {
+    record: (kind, id)=>`record:${kind}:${id}`,
+    email: (kind, id)=>`email:${kind}:${id}`,
+    mapping: (collection)=>`mapping:${collection}`
+};
+const RECORD_ID = /^[A-Za-z0-9_.:@+-]{1,128}$/;
+const oneOf = (list, value)=>typeof value === 'string' && list.includes(value);
+/** The columns a mapping request sends, as the job's inputs carry them (a JSON string). */ export function aiCrmColumnsInput(columns) {
+    return JSON.stringify(columns.slice(0, AI_CRM_MAX_COLUMNS).map((column)=>{
+        var _column_header;
+        return {
+            header: String((_column_header = column.header) != null ? _column_header : '').replace(/\s+/g, ' ').trim().slice(0, AI_CRM_HEADER_MAX_CHARS),
+            shape: column.shape
+        };
+    }));
+}
+function readColumns(raw) {
+    if (typeof raw !== 'string') return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (unused) {
+        return null;
+    }
+    if (!Array.isArray(parsed) || !parsed.length || parsed.length > AI_CRM_MAX_COLUMNS) return null;
+    const columns = [];
+    for (const entry of parsed){
+        const column = entry;
+        if (!column || typeof column['header'] !== 'string' || !oneOf(AI_CRM_COLUMN_SHAPES, column['shape'])) return null;
+        columns.push({
+            header: column['header'].replace(/\s+/g, ' ').trim().slice(0, AI_CRM_HEADER_MAX_CHARS),
+            shape: column['shape']
+        });
+    }
+    return columns;
+}
+/** What a `crm` job is asked, or the sentence naming what its inputs lack. */ export function parseAiCrmRequest(inputs) {
+    const task = inputs == null ? void 0 : inputs['task'];
+    if (task === 'record' || task === 'email') {
+        var _ref;
+        const kind = inputs == null ? void 0 : inputs['record'];
+        const id = String((_ref = inputs == null ? void 0 : inputs['recordId']) != null ? _ref : '').trim();
+        const kinds = task === 'email' ? AI_CRM_EMAIL_RECORD_KINDS : AI_CRM_RECORD_KINDS;
+        if (!oneOf(kinds, kind) || !RECORD_ID.test(id)) return 'Open the CRM record this is about first';
+        return {
+            task,
+            record: {
+                kind,
+                id
+            }
+        };
+    }
+    if (task === 'mapping') {
+        const collection = inputs == null ? void 0 : inputs['collection'];
+        if (!oneOf(AI_CRM_IMPORT_COLLECTIONS, collection)) return 'Open the import this is for first';
+        const columns = readColumns(inputs == null ? void 0 : inputs['columns']);
+        if (!columns) return `Choose a file with between 1 and ${AI_CRM_MAX_COLUMNS} columns first`;
+        return {
+            task,
+            collection,
+            columns
+        };
+    }
+    return 'This CRM request does not say what it is for';
+}
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A stored proposal read back, or `null` when it is not one a `crm` job writes. */ export function readAiCrmProposal(raw) {
+    if (!isRecord(raw)) return null;
+    if (raw['kind'] === 'record' || raw['kind'] === 'email') {
+        const record = raw['record'];
+        if (!isRecord(record) || !oneOf(AI_CRM_RECORD_KINDS, record['kind']) || typeof record['id'] !== 'string') {
+            return null;
+        }
+        if (raw['kind'] === 'email') {
+            return typeof raw['subject'] === 'string' && typeof raw['body'] === 'string' ? raw : null;
+        }
+        return typeof raw['summary'] === 'string' ? raw : null;
+    }
+    if (raw['kind'] === 'mapping') {
+        return oneOf(AI_CRM_IMPORT_COLLECTIONS, raw['collection']) && Array.isArray(raw['matches']) ? raw : null;
+    }
+    return null;
+}
+/** An output's reference read back, or `null` when it is not one a `crm` job writes. */ export function readAiCrmOutputRef(raw) {
+    if (!isRecord(raw)) return null;
+    if (raw['kind'] === 'record' || raw['kind'] === 'email') {
+        const record = raw['record'];
+        return isRecord(record) && oneOf(AI_CRM_RECORD_KINDS, record['kind']) && typeof record['id'] === 'string' ? {
+            kind: raw['kind'],
+            record: {
+                kind: record['kind'],
+                id: record['id']
+            }
+        } : null;
+    }
+    if (raw['kind'] === 'mapping') {
+        return oneOf(AI_CRM_IMPORT_COLLECTIONS, raw['collection']) ? {
+            kind: 'mapping',
+            collection: raw['collection']
+        } : null;
+    }
+    return null;
+}
+/** Whether a job answered the question a widget asks. */ export function aiCrmJobAnswers(job, wanted) {
+    var _job_outputs;
+    if ((job == null ? void 0 : job.kind) !== 'crm') return false;
+    return ((_job_outputs = job.outputs) != null ? _job_outputs : []).some((output)=>{
+        if (output.resource !== 'crm') return false;
+        const ref = readAiCrmOutputRef(output.proposal);
+        if (!ref || ref.kind !== wanted.kind) return false;
+        if (ref.kind === 'mapping') return wanted.kind === 'mapping' && ref.collection === wanted.collection;
+        return wanted.kind !== 'mapping' && ref.record.kind === wanted.record.kind && ref.record.id === wanted.record.id;
+    });
+}
+/** The org collection a `crm` job's answer is kept in, which no client may read. */ export const AI_CRM_ANSWERS_COLLECTION = 'aiCrmAnswers';
+/**
+ * How long an answer is kept: two weeks, far shorter than the job's own clock.
+ * An answer is written from a person's record, and erasing a person from a
+ * workspace does not sweep this collection, so the copy has to be gone on its
+ * own well inside the month an erasure request is answered in. The answer
+ * door stops serving it at once, because the CRM no longer finds the record.
+ */ export const AI_CRM_ANSWER_RETENTION_DAYS = 14;
+/** When an answer written at `now` expires: a `Date`, which a TTL policy keys on. */ export function aiCrmAnswerExpiry(now = new Date()) {
+    return new Date(now.getTime() + AI_CRM_ANSWER_RETENTION_DAYS * 86400000);
+}
+
+//# sourceMappingURL=ai-crm.js.map

package/src/lib/model/ai-crm.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-crm.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 type {\n  ConsoleImportColumn,\n  ConsoleImportColumnShape,\n} from '@aglyn/aglyn/plugin-manager/record-zone-props'\nimport type { AiJobOutput, AiJobSummary } from './ai-jobs.types'\n\n/**\n * CRM by AI (AGL-2917): what a `crm` job is asked, and the proposals it\n * answers with, in the shape the job step keeps and the console widgets read.\n * Pure data and readers, with no server import.\n *\n * ## Three questions, all proposals\n *\n * - `record` — a contact, company, deal or lead: a short summary of where the\n *   relationship stands, the next step as a task (never for a lead, which no\n *   task can link to), a stage for a deal, and a lead's standing. The member\n *   saves the task in the CRM's task form and confirms a stage move there.\n * - `email` — a subject and a plain-text message for the CRM composer, greeted\n *   and signed with merge fields. The member edits it and presses Send; a job\n *   never sends anything.\n * - `mapping` — which of a file's columns fill which fields of an import. The\n *   import drawer shows it in its own table and preview before anything is\n *   imported.\n *\n * ## What the model is given\n *\n * The CRM decides it: the facts its readers report on the core's record-facts\n * seam, never a document the AI plugin read itself. For an import, the\n * columns' headers and shapes — never a cell of the file.\n *\n * ## Where an answer is kept\n *\n * Not on the job: every member of a workspace may read its jobs, and a\n * summary of a contact is the contact's to show. The job's output names the\n * question ({@link AiCrmOutputRef}); the answer is kept apart, and the answer\n * door serves it only to a member the CRM still lets read the record.\n */\n\n/** The plugin that owns every record a `crm` job reads, as `plugins.config.json` names it. */\nexport const AI_CRM_PLUGIN_ID = 'crm'\n\n/** What the site's plugin list calls it, for the sentence a person reads. */\nexport const AI_CRM_PLUGIN_LABEL = 'CRM'\n\nexport type AiCrmTask = 'record' | 'email' | 'mapping'\n\nexport const AI_CRM_TASKS: readonly AiCrmTask[] = ['record', 'email', 'mapping']\n\nexport type AiCrmRecordKind = 'contact' | 'company' | 'deal' | 'lead'\n\nexport const AI_CRM_RECORD_KINDS: readonly AiCrmRecordKind[] = ['contact', 'company', 'deal', 'lead']\n\n/** The records an email is written from: a person, a deal (its person) or a lead. */\nexport const AI_CRM_EMAIL_RECORD_KINDS: readonly AiCrmRecordKind[] = ['contact', 'deal', 'lead']\n\nexport type AiCrmImportCollection = 'contacts' | 'companies' | 'deals' | 'leads'\n\nexport const AI_CRM_IMPORT_COLLECTIONS: readonly AiCrmImportCollection[] = [\n  'contacts',\n  'companies',\n  'deals',\n  'leads',\n]\n\n/** The resource names the CRM's readers are registered under on the record-facts seam. */\nexport const AI_CRM_FACTS_RESOURCES: Readonly<Record<AiCrmRecordKind, string>> = {\n  contact: 'crm.contact',\n  company: 'crm.company',\n  deal: 'crm.deal',\n  lead: 'crm.lead',\n}\n\n/** The import catalogs' resource name; the collection is the record id. */\nexport const AI_CRM_IMPORT_FACTS_RESOURCE = 'crm.import'\n\nexport const AI_CRM_COLUMN_SHAPES: readonly ConsoleImportColumnShape[] = [\n  'empty',\n  'email',\n  'phone',\n  'number',\n  'date',\n  'yes-no',\n  'url',\n  'text',\n]\n\n/** The most columns one mapping request sends. */\nexport const AI_CRM_MAX_COLUMNS = 60\n\n/** How much of a column header is sent. */\nexport const AI_CRM_HEADER_MAX_CHARS = 60\n\n/** How much of the member's request an email draft carries. */\nexport const AI_CRM_EMAIL_REQUEST_MAX_CHARS = 600\n\n/** Lengths the CRM tools hold an answer to. */\nexport const AI_CRM_LIMITS = {\n  summary: 320,\n  standing: 280,\n  taskTitle: 80,\n  reason: 160,\n  subject: 100,\n  body: 1_200,\n  /** The latest a proposed next step may be due, in days from today. */\n  dueInDays: 30,\n} as const\n\n/** A task the job proposes as the record's next step. */\nexport interface AiCrmNextStep {\n  title: string\n  kind: 'call' | 'email' | 'meeting' | 'todo'\n  priority: 'low' | 'normal' | 'high'\n  dueInDays: number\n  /** Why, pointing at the fact behind it. */\n  reason: string\n}\n\n/** A stage the job proposes a deal move to. */\nexport interface AiCrmStageMove {\n  stageId: string\n  stageName: string\n  reason: string\n}\n\nexport interface AiCrmRecordProposal {\n  kind: 'record'\n  record: { kind: AiCrmRecordKind; id: string }\n  summary: string\n  nextStep: AiCrmNextStep | null\n  stage: AiCrmStageMove | null\n  /** Why a lead stands where it does; `null` for any other record. */\n  standing: string | null\n  /** The UTC day the facts were read. */\n  asOf: string\n  /** The job the answer was reused from, when it was not asked for again. */\n  reusedFrom?: string\n}\n\nexport interface AiCrmEmailProposal {\n  kind: 'email'\n  record: { kind: AiCrmRecordKind; id: string }\n  subject: string\n  body: string\n}\n\n/** One column the job matched to a field. */\nexport interface AiCrmColumnMatch {\n  column: number\n  header: string\n  field: string\n  label: string\n}\n\nexport interface AiCrmMappingProposal {\n  kind: 'mapping'\n  collection: AiCrmImportCollection\n  matches: AiCrmColumnMatch[]\n  /** How many columns the request sent. */\n  columns: number\n}\n\nexport type AiCrmProposal = AiCrmRecordProposal | AiCrmEmailProposal | AiCrmMappingProposal\n\n/** The output ids a `crm` job writes: one per question. */\nexport const AI_CRM_OUTPUT_IDS = {\n  record: (kind: AiCrmRecordKind, id: string) => `record:${kind}:${id}`,\n  email: (kind: AiCrmRecordKind, id: string) => `email:${kind}:${id}`,\n  mapping: (collection: AiCrmImportCollection) => `mapping:${collection}`,\n} as const\n\n/** What a `crm` job's inputs say it is asked, read and bounded. */\nexport type AiCrmRequest =\n  | { task: 'record'; record: { kind: AiCrmRecordKind; id: string } }\n  | { task: 'email'; record: { kind: AiCrmRecordKind; id: string } }\n  | { task: 'mapping'; collection: AiCrmImportCollection; columns: ConsoleImportColumn[] }\n\nconst RECORD_ID = /^[A-Za-z0-9_.:@+-]{1,128}$/\n\nconst oneOf = <T extends string>(list: readonly T[], value: unknown): value is T =>\n  typeof value === 'string' && (list as readonly string[]).includes(value)\n\n/** The columns a mapping request sends, as the job's inputs carry them (a JSON string). */\nexport function aiCrmColumnsInput(columns: readonly ConsoleImportColumn[]): string {\n  return JSON.stringify(\n    columns.slice(0, AI_CRM_MAX_COLUMNS).map((column) => ({\n      header: String(column.header ?? '').replace(/\\s+/g, ' ').trim().slice(0, AI_CRM_HEADER_MAX_CHARS),\n      shape: column.shape,\n    })),\n  )\n}\n\nfunction readColumns(raw: unknown): ConsoleImportColumn[] | null {\n  if (typeof raw !== 'string') return null\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch {\n    return null\n  }\n  if (!Array.isArray(parsed) || !parsed.length || parsed.length > AI_CRM_MAX_COLUMNS) return null\n  const columns: ConsoleImportColumn[] = []\n  for (const entry of parsed) {\n    const column = entry as Record<string, unknown> | null\n    if (!column || typeof column['header'] !== 'string' || !oneOf(AI_CRM_COLUMN_SHAPES, column['shape'])) return null\n    columns.push({\n      header: column['header'].replace(/\\s+/g, ' ').trim().slice(0, AI_CRM_HEADER_MAX_CHARS),\n      shape: column['shape'],\n    })\n  }\n  return columns\n}\n\n/** What a `crm` job is asked, or the sentence naming what its inputs lack. */\nexport function parseAiCrmRequest(inputs: Readonly<Record<string, unknown>> | null | undefined): AiCrmRequest | string {\n  const task = inputs?.['task']\n  if (task === 'record' || task === 'email') {\n    const kind = inputs?.['record']\n    const id = String(inputs?.['recordId'] ?? '').trim()\n    const kinds = task === 'email' ? AI_CRM_EMAIL_RECORD_KINDS : AI_CRM_RECORD_KINDS\n    if (!oneOf(kinds, kind) || !RECORD_ID.test(id)) return 'Open the CRM record this is about first'\n    return { task, record: { kind, id } }\n  }\n  if (task === 'mapping') {\n    const collection = inputs?.['collection']\n    if (!oneOf(AI_CRM_IMPORT_COLLECTIONS, collection)) return 'Open the import this is for first'\n    const columns = readColumns(inputs?.['columns'])\n    if (!columns) return `Choose a file with between 1 and ${AI_CRM_MAX_COLUMNS} columns first`\n    return { task, collection, columns }\n  }\n  return 'This CRM request does not say what it is for'\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** A stored proposal read back, or `null` when it is not one a `crm` job writes. */\nexport function readAiCrmProposal(raw: unknown): AiCrmProposal | null {\n  if (!isRecord(raw)) return null\n  if (raw['kind'] === 'record' || raw['kind'] === 'email') {\n    const record = raw['record']\n    if (!isRecord(record) || !oneOf(AI_CRM_RECORD_KINDS, record['kind']) || typeof record['id'] !== 'string') {\n      return null\n    }\n    if (raw['kind'] === 'email') {\n      return typeof raw['subject'] === 'string' && typeof raw['body'] === 'string'\n        ? (raw as unknown as AiCrmEmailProposal)\n        : null\n    }\n    return typeof raw['summary'] === 'string' ? (raw as unknown as AiCrmRecordProposal) : null\n  }\n  if (raw['kind'] === 'mapping') {\n    return oneOf(AI_CRM_IMPORT_COLLECTIONS, raw['collection']) && Array.isArray(raw['matches'])\n      ? (raw as unknown as AiCrmMappingProposal)\n      : null\n  }\n  return null\n}\n\n/**\n * What a `crm` job's output says about its answer (AGL-2917): which question,\n * about which record or import. The answer itself is not on the job — every\n * member of a workspace may read a job, and not every member may read the\n * record — so it is kept in {@link AI_CRM_ANSWERS_COLLECTION} and read through\n * the answer door, which asks the CRM again whether this member may read it.\n */\nexport type AiCrmOutputRef =\n  | { kind: 'record' | 'email'; record: { kind: AiCrmRecordKind; id: string } }\n  | { kind: 'mapping'; collection: AiCrmImportCollection }\n\n/** An output's reference read back, or `null` when it is not one a `crm` job writes. */\nexport function readAiCrmOutputRef(raw: unknown): AiCrmOutputRef | null {\n  if (!isRecord(raw)) return null\n  if (raw['kind'] === 'record' || raw['kind'] === 'email') {\n    const record = raw['record']\n    return isRecord(record) && oneOf(AI_CRM_RECORD_KINDS, record['kind']) && typeof record['id'] === 'string'\n      ? { kind: raw['kind'], record: { kind: record['kind'], id: record['id'] } }\n      : null\n  }\n  if (raw['kind'] === 'mapping') {\n    return oneOf(AI_CRM_IMPORT_COLLECTIONS, raw['collection']) ? { kind: 'mapping', collection: raw['collection'] } : null\n  }\n  return null\n}\n\n/** What a widget looks for among a workspace's jobs: one question about one record, or one import. */\nexport type AiCrmAnswerWanted =\n  | { kind: 'record' | 'email'; record: { kind: string; id: string } }\n  | { kind: 'mapping'; collection: string }\n\n/** Whether a job answered the question a widget asks. */\nexport function aiCrmJobAnswers(job: Pick<AiJobSummary, 'kind' | 'outputs'> | null | undefined, wanted: AiCrmAnswerWanted): boolean {\n  if (job?.kind !== 'crm') return false\n  return (job.outputs ?? []).some((output: AiJobOutput) => {\n    if (output.resource !== 'crm') return false\n    const ref = readAiCrmOutputRef(output.proposal)\n    if (!ref || ref.kind !== wanted.kind) return false\n    if (ref.kind === 'mapping') return wanted.kind === 'mapping' && ref.collection === wanted.collection\n    return wanted.kind !== 'mapping' && ref.record.kind === wanted.record.kind && ref.record.id === wanted.record.id\n  })\n}\n\n/** The org collection a `crm` job's answer is kept in, which no client may read. */\nexport const AI_CRM_ANSWERS_COLLECTION = 'aiCrmAnswers'\n\n/**\n * How long an answer is kept: two weeks, far shorter than the job's own clock.\n * An answer is written from a person's record, and erasing a person from a\n * workspace does not sweep this collection, so the copy has to be gone on its\n * own well inside the month an erasure request is answered in. The answer\n * door stops serving it at once, because the CRM no longer finds the record.\n */\nexport const AI_CRM_ANSWER_RETENTION_DAYS = 14\n\n/** When an answer written at `now` expires: a `Date`, which a TTL policy keys on. */\nexport function aiCrmAnswerExpiry(now = new Date()): Date {\n  return new Date(now.getTime() + AI_CRM_ANSWER_RETENTION_DAYS * 86_400_000)\n}\n\n/** An answer as it is kept at `orgs/{orgId}/aiCrmAnswers/{jobId}`. */\nexport interface AiCrmAnswerRecord {\n  jobId: string\n  orgId: string\n  /** The site the record was read on, or `null` at the organization level. */\n  hostId: string | null\n  /** The member who asked. */\n  createdBy: string\n  task: AiCrmTask\n  /** The record an answer is about, by the resource its facts were read from; `null` for a mapping. */\n  resource: string\n  recordId: string\n  proposal: AiCrmProposal\n  /** A record answer's request key, which a later job reuses it by; `null` for any other. */\n  key: string | null\n  createdAt: unknown\n  expiresAt?: unknown\n}\n\n/** What the answer door serves. */\nexport interface AiCrmAnswerWire {\n  jobId: string\n  hostId: string | null\n  createdBy: string\n  proposal: AiCrmProposal\n}\n"],"names":["AI_CRM_PLUGIN_ID","AI_CRM_PLUGIN_LABEL","AI_CRM_TASKS","AI_CRM_RECORD_KINDS","AI_CRM_EMAIL_RECORD_KINDS","AI_CRM_IMPORT_COLLECTIONS","AI_CRM_FACTS_RESOURCES","contact","company","deal","lead","AI_CRM_IMPORT_FACTS_RESOURCE","AI_CRM_COLUMN_SHAPES","AI_CRM_MAX_COLUMNS","AI_CRM_HEADER_MAX_CHARS","AI_CRM_EMAIL_REQUEST_MAX_CHARS","AI_CRM_LIMITS","summary","standing","taskTitle","reason","subject","body","dueInDays","AI_CRM_OUTPUT_IDS","record","kind","id","email","mapping","collection","RECORD_ID","oneOf","list","value","includes","aiCrmColumnsInput","columns","JSON","stringify","slice","map","column","header","String","replace","trim","shape","readColumns","raw","parsed","parse","Array","isArray","length","entry","push","parseAiCrmRequest","inputs","task","kinds","test","isRecord","readAiCrmProposal","readAiCrmOutputRef","aiCrmJobAnswers","job","wanted","outputs","some","output","resource","ref","proposal","AI_CRM_ANSWERS_COLLECTION","AI_CRM_ANSWER_RETENTION_DAYS","aiCrmAnswerExpiry","now","Date","getTime"],"mappings":"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"}

package/src/lib/model/ai-experiment-proposal.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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 AiExperimentArm, type AiExperimentTarget, type AiExperimentVariantProposal, type AiExperimentVerdict } from './ai-experiment';
+/** An explanation as a console surface reads it back. */
+export interface AiExperimentExplanationProposal {
+    verdict: AiExperimentVerdict;
+    test: string;
+    headline: string;
+    points: string[];
+    /** The arm the FIGURES named, and only ever on a verdict that names one. */
+    winnerId: string | null;
+    next: string;
+    /** The confidence one comparison had to clear, as a percentage. */
+    threshold: number;
+    arms: AiExperimentArm[];
+}
+/** A variants answer as a console surface reads it back. */
+export interface AiExperimentVariantsProposalView {
+    target: AiExperimentTarget;
+    goal: string;
+    variants: AiExperimentVariantProposal[];
+}
+/**
+ * How a verdict is drawn.
+ *
+ * `namesAnArm` is the one a surface must ask before it marks a row, a chip or
+ * a heading: on `too-early`, `inconclusive` and `unreadable` there is no arm
+ * to mark, and marking the one with the best rate anyway is the claim the
+ * step refused to let the model make.
+ *
+ * `tone` is a MUI severity/color word rather than a color: `success` only
+ * where the figures decided something, and the neutral `default` everywhere
+ * else — an undecided result drawn in a color that reads as good or as bad
+ * says something the figures did not.
+ */
+export interface AiExperimentVerdictDisplay {
+    namesAnArm: boolean;
+    tone: 'success' | 'default';
+    /** The verdict in a reader's words, short enough for a chip. */
+    status: string;
+    /** What the result does not settle, or empty where it settles something. */
+    caveat: string;
+}
+/** How a verdict is drawn; an unknown verdict is drawn as the most careful one. */
+export declare function aiExperimentVerdictDisplay(verdict: AiExperimentVerdict | string): AiExperimentVerdictDisplay;
+/**
+ * Whether a surface may mark this arm. The verdict decides first, so an arm
+ * cannot be marked on a result that named none, whatever `winnerId` holds.
+ */
+export declare function aiExperimentArmIsNamed(explanation: Pick<AiExperimentExplanationProposal, 'verdict' | 'winnerId'>, armId: string): boolean;
+/** An explanation output's proposal, or `null` when it is not one. */
+export declare function readAiExperimentExplanation(value: unknown): AiExperimentExplanationProposal | null;
+/** A variants output's proposal, or `null` when it is not one. */
+export declare function readAiExperimentVariants(value: unknown): AiExperimentVariantsProposalView | null;