@opencxh/domain 1.154.0 → 1.159.0

package/dist/entities/playbook/assignment.d.ts

@@ -0,0 +1,123 @@
+import { LocaleBundle } from '../analytics/dashboard';
+import { PlaybookTrigger } from './types';
+/**
+ * Toewijzen als wekker — het oppervlak waarop een **opdracht** bestaat.
+ *
+ * **Herzien:** een opdracht *is* wél een entiteit — zie {@link Assignment}. Hier stond "een
+ * opdracht is geen entiteit: het is een run met een procedure", en dat brak op drie punten: een
+ * procedure-run werd altijd afgekort tot één beurt, de draad ernaast deelde geen geheugen met de
+ * agent, en "wat voor ding is dit" moest uit de uitvoeringsvorm worden afgeleid.
+ *
+ * Wat deze module doet verandert daar niet door: de handeling die het werk begint bestaat al in
+ * elke app die werk kent — **je wijst iets aan iemand toe.** Wijs je het aan een gebruiker met
+ * `type: "agent"` toe, dan is dat het startsignaal, en dan zet de engine er een opdracht neer.
+ *
+ * Daarom is dit een federatie en geen lijst in de ai-app. Alleen comms weet dat een gesprek
+ * toegewezen kan worden en dat `INTERACTION_ASSIGNED` dat aankondigt; alleen een taken-app weet
+ * dat van een taak. De hub hoort dat niet te weten — precies de scheiding die de
+ * geheugen-catalogus (`memory-source`) en de analytics-catalogus al maken. Mal:
+ * `apps/context/server/src/memory/catalog.ts`.
+ *
+ * **Er komt geen nieuw wekmechanisme.** Een toewijzing is al een activity, dus de bestaande
+ * `activity`-poort levert hem af; deze module voegt alleen de vraag toe die de engine zelf niet
+ * kan beantwoorden: *"is dit aan míjn agent toegewezen?"*
+ */
+/**
+ * Eén soort werk dat aan een agent toegewezen kan worden, gedeclareerd door de app die het
+ * bezit.
+ */
+export interface AssignmentTargetKind {
+    /**
+     * `<app>.<ding>` — het voorvoegsel is de eigenaar, dezelfde conventie als `memory_kind` en
+     * de dossiersleutels. Twee apps kunnen zo nooit dezelfde soort claimen.
+     */
+    id: string;
+    label: string;
+    description?: string;
+    /**
+     * De activity-types waarmee deze app "dit is toegewezen" aankondigt.
+     *
+     * Gedeclareerd en niet geraden: de engine ziet alleen een type-string langskomen, en welk
+     * type een toewijzing ís weet alleen de bron. Een geraden voorvoegsel zou bij de eerste app
+     * die zijn eigen soort meebrengt stil het verkeerde type pakken.
+     */
+    activityTypes: string[];
+    /**
+     * Waar op de activity het userId van de toegewezene staat, als punt-pad
+     * (`"payload.userId"`).
+     *
+     * Een pad en geen vaste sleutel, omdat de payload van de bron is. Comms zet `payload.userId`;
+     * een andere app mag `payload.assignee.id` zetten zonder dat de hub verandert.
+     */
+    assigneePath: string;
+    /** Gezet door de hub na de fan-out, niet door de bron. */
+    origin?: "app";
+}
+/**
+ * Bare payload van `GET /provider/assignment/describe` — niet in `ResponseFactory` verpakt
+ * (mal: `MemorySourceDescription`).
+ */
+export interface AssignmentSourceDescription {
+    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    source: string;
+    targets: AssignmentTargetKind[];
+    /** Vlakke LIJST: keys met een punt worden gemangeld. */
+    locales?: LocaleBundle;
+}
+/** De samengestelde catalogus die de hub aan de builder levert. */
+export interface AssignmentCatalog {
+    targets: AssignmentTargetKind[];
+    /** Bronnen die meededen aan de fan-out (voor "wie levert dit?"). */
+    sources: string[];
+    locales: LocaleBundle;
+}
+/**
+ * De waarde op een punt-pad, of `undefined`.
+ *
+ * Eigen mini-lezer en niet `resolveRef` uit de engine: die woont in de ai-app en kent de
+ * `$`-conventie, terwijl hier een kaal pad uit een app-declaratie gelezen wordt. Stopt bij het
+ * eerste niet-object, zodat een pad dat langs `null` loopt `undefined` geeft en niet gooit.
+ */
+export declare function valueAtPath(source: unknown, path: string): unknown;
+/**
+ * De doelsoort die dit activity-type aankondigt, en de doelsoort met dit id.
+ *
+ * Twee lezers, één lijst: de engine komt binnen met een type ("wat is dit?"), de builder en de
+ * validatie met een id ("bestaat deze soort?").
+ */
+export declare function targetForActivityType(catalog: Pick<AssignmentCatalog, "targets">, activityType: string): AssignmentTargetKind | undefined;
+export declare function targetById(catalog: Pick<AssignmentCatalog, "targets">, id: string | undefined): AssignmentTargetKind | undefined;
+/** Is dit een trigger die op een toewijzing wacht? */
+export declare function isAssignmentTrigger(trigger: PlaybookTrigger | undefined): trigger is Extract<PlaybookTrigger, {
+    kind: "assignment";
+}>;
+/**
+ * Waarom deze toewijzing géén run van deze playbook start, of `null` als hij dat wél doet.
+ *
+ * Een reden en geen boolean, om dezelfde reden als `triggerMismatch`: een trigger die niet
+ * matcht laat geen run achter, dus er is geen trace om in te kijken. "Ik heb dit gesprek aan de
+ * agent gegeven en er gebeurt niets" moet te beantwoorden zijn.
+ *
+ * Puur, en dat is waar de vier poorten hier staan in plaats van in de job:
+ *
+ * 1. **Geen agent** ⇒ nooit. "Toegewezen aan wie?" heeft dan geen antwoord, en zonder deze
+ *    poort zou zo'n playbook op *elke* toewijzing van *iedereen* vuren.
+ * 2. **Onbekende doelsoort** ⇒ nooit, met naam en al. Dat is het geval "de app die dit
+ *    declareerde is uitgeschakeld of antwoordt niet", en dat mag geen stilte zijn.
+ * 3. **Aan iemand anders toegewezen** ⇒ niet deze playbook. Dit is de kernvergelijking.
+ * 4. **De agent wees het zichzelf toe** ⇒ niet opnieuw. Zonder deze poort is een procedure die
+ *    zelf toewijst (`update_interaction`) een lus die zichzelf blijft wekken: de
+ *    lifecycle-activity draagt geen `runId`, dus de bestaande loop-demping ziet hem niet.
+ */
+export declare function assignmentMismatch(input: {
+    trigger: PlaybookTrigger | undefined;
+    /** `Playbook.agentId` — het userId van de agent die deze playbook uitvoert. */
+    agentId?: string | null;
+    /** De doelsoort uit de catalogus die bij deze playbook hoort, indien gevonden. */
+    target?: AssignmentTargetKind;
+    activityType: string;
+    /** Aan wie dit toegewezen werd, gelezen via `target.assigneePath`. */
+    assigneeUserId?: string;
+    /** Wie de toewijzing deed, als het een gebruiker was. */
+    authorUserId?: string;
+}): string | null;

package/dist/entities/playbook/assignment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/playbook/index.d.ts

@@ -1,4 +1,5 @@
 export * from './labels';
 export * from './trigger-vars';
 export * from './actor';
+export * from './assignment';
 export * from './types';

package/dist/entities/playbook/status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/playbook/trigger-vars.d.ts

@@ -52,22 +52,53 @@ export declare const TRIGGER_VARS: readonly [{
 }, {
     readonly name: "companyId";
     readonly type: "string";
+}, {
+    readonly name: "assigneeUserId";
+    readonly type: "string";
 }];
-/** De variabelen die een classify-stap oplevert, per mode. */
+/**
+ * Wat een classify-stap per mode **oplevert** — het contract dat `runClassify` nakomt.
+ *
+ * Staat hier als type en niet alleen als lijst, omdat {@link CLASSIFY_VARS} eruit hoort te volgen.
+ * Die lijst was uiteengelopen met de werkelijkheid, precies zoals `TRIGGER_VARS` dat eerder was:
+ * `question` bood `confidence` aan (bestaat niet, de adapter geeft `answer` + `reasoning`) en
+ * `topics` miste `topicId` en `reasoning`. Een pad dat de picker aanbiedt en dat `undefined`
+ * oplevert is stil kapot — vandaar dat de adapter er in `ai/classify.test.ts` tegen wordt gehouden.
+ */
+export interface ClassifyTopicsResult {
+    topicId: string;
+    /** Naam van het onderwerp, of `null` bij `"none"`. */
+    topic: string | null;
+    confidence: number;
+    reasoning?: string;
+}
+export interface ClassifyQuestionResult {
+    answer: boolean;
+    reasoning?: string;
+}
+/** De zelf-gedefinieerde velden uit `ClassifyStep.fields`; de vorm is van de auteur. */
+export type ClassifyExtractResult = Record<string, unknown>;
+/** De variabelen die een classify-stap oplevert, per mode. Volgt de types hierboven. */
 export declare const CLASSIFY_VARS: {
     readonly topics: readonly [{
+        readonly name: "topicId";
+        readonly type: "string";
+    }, {
         readonly name: "topic";
         readonly type: "string";
     }, {
         readonly name: "confidence";
         readonly type: "number";
+    }, {
+        readonly name: "reasoning";
+        readonly type: "string";
     }];
     readonly question: readonly [{
         readonly name: "answer";
         readonly type: "boolean";
     }, {
-        readonly name: "confidence";
-        readonly type: "number";
+        readonly name: "reasoning";
+        readonly type: "string";
     }];
     readonly extract: readonly [];
 };