@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,166 @@
+/**
+ * @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 TriggerCombinator, type TriggerConditionOp } from '@aglyn/aglyn/app-utils/actions';
+import { type ContactLifecycleStage, type CrmActivityKind, type CrmTaskKind } from '@aglyn/aglyn/app-utils/crm';
+import { type HostEventType } from '@aglyn/aglyn/app-utils/workflows';
+import { type AiAutomationCapabilities, type AiAutomationStepType, type AiAutomationUnsupported } from '../model/ai-workflow-job';
+import type { AiTool } from '../providers/contract';
+import type { AiGenerationCheckResult } from '../runtime/ai-doctrine';
+/**
+ * The two tools a `workflow` job answers through (AGL-2919).
+ *
+ * `submit_automation` carries one automation in the Actions editor's own
+ * vocabulary — a trigger from the host events, conditions over the fields the
+ * trigger carries, and steps from the automation step types — with every
+ * record it names written as WORDS. The step resolves those words against the
+ * site after the answer, so the model is never shown the site's lists,
+ * campaigns, workflows, webhooks or pipeline stages, and never writes an id it
+ * could only have invented.
+ *
+ * `submit_explanation` carries a plain-words account of one automation, or of
+ * why one of its runs failed.
+ *
+ * Both schemas are strict: every object forbids extra keys and requires every
+ * key it has, and nothing in either is a `null`. Where a step may go without
+ * something, the absence is an empty list or an empty string: a step that
+ * always runs has an empty `when`, a notEmpty condition compares against
+ * nothing, and an answer that builds an automation leaves `unsupported`
+ * empty. Bounds a strict schema cannot state are stated in the descriptions
+ * and held by the readers below, whose refusals name the field so the one
+ * re-ask can fix it.
+ *
+ * A provider that constrains decoding compiles every strict schema of a
+ * request into a grammar, and refuses one whose grammar grows past its size
+ * (`AiToolSchemaLimits`). So the steps' union carries as little repetition as
+ * a grammar can be made to hold:
+ *
+ *  - a step is its guard and its action, `{ when, action }`, so the condition
+ *    is compiled once for the whole union instead of once per variant;
+ *  - a variant serves every step type that carries the same fields, named for
+ *    what they hold: the six steps that name a record share `reference`, and
+ *    the three that carry one line share `text`;
+ *  - every field stays required and every vocabulary stays an enum, so the
+ *    model is still decoded into the Actions editor's words.
+ *
+ * Ten variants carry all seventeen step types, and the reader below maps the
+ * shared fields back onto the step's own key.
+ */
+export declare const AI_AUTOMATION_TOOL_NAME = "submit_automation";
+export declare const AI_WORKFLOW_EXPLANATION_TOOL_NAME = "submit_explanation";
+/** The longest automation name the Actions editor stores. */
+export declare const AI_AUTOMATION_NAME_MAX_CHARS = 60;
+/** The longest subject the executor sends. */
+export declare const AI_AUTOMATION_SUBJECT_MAX_CHARS = 200;
+/** The longest email text the executor sends. */
+export declare const AI_AUTOMATION_BODY_MAX_CHARS = 5000;
+/** The longest title, message or record name a step carries. */
+export declare const AI_AUTOMATION_TEXT_MAX_CHARS = 300;
+/** The longest words naming a record. */
+export declare const AI_AUTOMATION_REFERENCE_MAX_CHARS = 100;
+/** The longest condition value. */
+export declare const AI_AUTOMATION_VALUE_MAX_CHARS = 200;
+/** The most notes an answer keeps, and the longest. */
+export declare const AI_AUTOMATION_NOTES_MAX = 3;
+export declare const AI_AUTOMATION_NOTE_MAX_CHARS = 300;
+/**
+ * The longest a whole answer may be, written out as JSON: what the routing
+ * ceiling for `job.workflow` holds at three characters a token with as much
+ * again to think in (`ai-job-workflow-step.spec.ts` measures it). Ten steps
+ * with two emails of a paragraph or two each come to about 2,400, each step
+ * carrying only its own fields.
+ */
+export declare const AI_AUTOMATION_ANSWER_MAX_CHARS = 6000;
+/** The explanation's bounds. */
+export declare const AI_WORKFLOW_SUMMARY_MAX_CHARS = 400;
+export declare const AI_WORKFLOW_POINTS_MAX = 8;
+export declare const AI_WORKFLOW_SUGGESTIONS_MAX = 4;
+export declare const AI_WORKFLOW_LINE_MAX_CHARS = 300;
+declare const SEVERITIES: readonly ["info", "success", "warning", "error"];
+type Severity = (typeof SEVERITIES)[number];
+type Schema = Record<string, unknown>;
+/** Every step type an automation may carry, grouped by the fields it needs. */
+export declare const AI_AUTOMATION_STEP_VARIANTS: readonly Schema[];
+/** The automation tool. The same bytes on every request, so it sits inside the cached prefix. */
+export declare function aiAutomationTool(): AiTool;
+/** The explanation tool. */
+export declare function aiWorkflowExplanationTool(): AiTool;
+export interface AiAutomationCondition {
+    field: string;
+    op: TriggerConditionOp;
+    /** `null` for `notEmpty`. */
+    value: string | null;
+}
+/** One step as the reader gives it back, every field the step does not use `null`. */
+export interface AiAutomationAnswerStep {
+    type: AiAutomationStepType;
+    when: AiAutomationCondition | null;
+    list: string | null;
+    campaign: string | null;
+    workflow: string | null;
+    webhook: string | null;
+    dataset: string | null;
+    subject: string | null;
+    body: string | null;
+    toField: string | null;
+    title: string | null;
+    message: string | null;
+    severity: Severity | null;
+    minutes: number | null;
+    event: HostEventType | null;
+    stage: ContactLifecycleStage | null;
+    tag: string | null;
+    owner: string | null;
+    taskKind: CrmTaskKind | null;
+    dueInDays: number | null;
+    activityKind: CrmActivityKind | null;
+}
+export interface AiAutomationAnswer {
+    name: string;
+    trigger: {
+        event: HostEventType;
+        conditions: AiAutomationCondition[];
+        combinator: TriggerCombinator;
+    };
+    steps: AiAutomationAnswerStep[];
+    notes: string[];
+    unsupported: AiAutomationUnsupported | null;
+}
+/** The codes that say an answer could not be read as an automation at all. */
+export declare const AI_AUTOMATION_UNREADABLE_CODES: readonly string[];
+/** The codes that say an answer is larger than an automation may be. */
+export declare const AI_AUTOMATION_OVERSIZE_CODES: readonly string[];
+/** A lifecycle stage by its id or its label, case aside. */
+export declare function lifecycleStageOf(value: string): ContactLifecycleStage | null;
+/**
+ * The automation tool's answer read and held to the vocabulary and to what
+ * this workspace can run — the check the doctrine's loop runs on each answer,
+ * beside rule 13. `value` is the automation when nothing is refused.
+ */
+export declare function readAiAutomationAnswer(answer: Record<string, unknown>, capabilities: AiAutomationCapabilities): AiGenerationCheckResult<AiAutomationAnswer>;
+export interface AiWorkflowExplanation {
+    summary: string;
+    points: string[];
+    suggestions: string[];
+}
+/**
+ * The explanation tool's answer: a summary, and at most so many points and
+ * suggestions, each cut to a line. Refused when it has no summary, or carries
+ * markup or an address — plain words for a person, about a record whose
+ * personal details were removed before the model saw it.
+ */
+export declare function readAiWorkflowExplanation(answer: Record<string, unknown>): AiGenerationCheckResult<AiWorkflowExplanation>;
+export {};