@opencxh/domain 1.172.1 → 1.173.0

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

@@ -2,36 +2,36 @@ import { ActingIdentity } from '../../platform/identity';
 import { toActingIdentity } from '../scope/actor';
 import { OwnerScope } from '../scope/types';
 /**
- * `ownerScope` **is** de actor van een playbook: er is geen apart `runAs`-veld.
- * Zichtbaarheid, werkgebied en toeschrijving volgen dus uit hetzelfde veld.
+ * `ownerScope` **is** a playbook's actor: there is no separate `runAs` field. Visibility, working
+ * area and attribution therefore all follow from the same field.
  *
- * Aan de bewaarkant heet de persoonlijke variant `personal` (zoals bij elke andere
- * entity), aan de uitvoerkant `user` (zoals elke andere acting identity). Deze
- * functie is die vertaling, en de enige plek waar hij hoort.
+ * On the storage side the personal variant is called `personal` (as with every other entity), on
+ * the execution side `user` (as with every other acting identity). This function is that
+ * translation, and the only place it belongs.
  */
 export declare const playbookActor: typeof toActingIdentity;
 /**
- * Namens wie deze run handelt.
+ * Who this run acts for.
  *
- * **Twee verschillende vragen, en dat is de hele reden dat deze functie naast
- * {@link playbookActor} bestaat:**
+ * **Two different questions, and the whole reason this function exists next to
+ * {@link playbookActor}:**
  *
- * - *wie handelt* — de agent, als er één is aangewezen;
- * - *wie mag dit beheren* — `ownerScope`, en dat blijft van mensen.
+ * - *who acts* — the agent, when one is designated;
+ * - *who may manage this* — `ownerScope`, and that stays with humans.
  *
- * Die twee op één veld laten leunen leek aantrekkelijk, want een agent is een gebruiker en
- * `ownerScope: { kind: "personal", userId }` levert precies de juiste actor op. Maar
- * `ownerScope` bepaalt óók wie mag bewerken, en dan kon geen enkel mens de playbook van een
- * agent nog aanpassen — de agent zelf logt immers nooit in.
+ * Leaning both on one field looked attractive, because an agent is a user and
+ * `ownerScope: { kind: "personal", userId }` yields exactly the right actor. But `ownerScope` also
+ * decides who may edit, and then no human could change an agent's playbook any more — the agent
+ * itself never logs in.
  *
- * Zonder `agentId` verandert er niets: dan is de actor die van de scope, precies zoals eerst.
+ * Without an `agentId` nothing changes: the actor is the scope's, exactly as before.
  */
 export declare function runActor(playbook: {
     agentId?: string | null;
     ownerScope: OwnerScope;
 }): ActingIdentity;
 /**
- * Stabiele sleutel om actors te groeperen. Tien playbooks van hetzelfde team horen
- * één autorisatie-call te kosten, niet tien.
+ * Stable key for grouping actors. Ten playbooks of the same team should cost one authorization
+ * call, not ten.
  */
 export declare function actorKey(actor: ActingIdentity): string;

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

@@ -1,123 +1,114 @@
 import { LocaleBundle } from '../analytics/dashboard';
 import { PlaybookTrigger } from './types';
 /**
- * Toewijzen als wekker — het oppervlak waarop een **opdracht** bestaat.
+ * Assigning as the wake-up call — the surface on which an **assignment** exists.
  *
- * **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.
+ * The action that starts the work already exists in every app that knows work: **you assign
+ * something to someone.** Assign it to a user with `type: "agent"` and that is the start signal,
+ * and the engine puts an assignment there. (An assignment is an entity of its own — see
+ * {@link Assignment}.)
  *
- * 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.
+ * This is a federation and not a list in the ai app. Only comms knows a conversation can be
+ * assigned and that `INTERACTION_ASSIGNED` announces it; only a task app knows that of a task. The
+ * hub should not know — the same separation the memory catalog (`memory-source`) and the analytics
+ * catalog already make. Template: `apps/context/server/src/memory/catalog.ts`.
  *
- * 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.
+ * **No new wake mechanism.** An assignment is already an activity, so the existing `activity` gate
+ * delivers it; this module only adds the question the engine cannot answer itself: *"is this
+ * assigned to my agent?"*
  */
+/** One kind of work assignable to an agent, declared by the app that owns it. */
 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.
+     * `<app>.<thing>` — the prefix is the owner, the same convention as `memory_kind` and the file
+     * keys. Two apps can never claim the same kind this way.
      */
     id: string;
     label: string;
     description?: string;
     /**
-     * De activity-types waarmee deze app "dit is toegewezen" aankondigt.
+     * The activity types this app announces "this is assigned" with.
      *
-     * 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.
+     * Declared and not guessed: the engine only sees a type string go by, and only the source knows
+     * which type *is* an assignment. A guessed prefix would silently pick the wrong type as soon as
+     * an app brings its own kind.
      */
     activityTypes: string[];
     /**
-     * Waar op de activity het userId van de toegewezene staat, als punt-pad
-     * (`"payload.userId"`).
+     * Where on the activity the assignee's userId sits, as a dot path (`"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.
+     * A path and not a fixed key, because the payload belongs to the source. Comms sets
+     * `payload.userId`; another app may set `payload.assignee.id` without the hub changing.
      */
     assigneePath: string;
-    /** Gezet door de hub na de fan-out, niet door de bron. */
+    /** Set by the hub after the fan-out, not by the source. */
     origin?: "app";
 }
 /**
- * Bare payload van `GET /provider/assignment/describe` — niet in `ResponseFactory` verpakt
- * (mal: `MemorySourceDescription`).
+ * Bare payload of `GET /provider/assignment/describe` — not wrapped in `ResponseFactory`
+ * (template: `MemorySourceDescription`).
  */
 export interface AssignmentSourceDescription {
-    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    /** The declaring app (== `manifest.name` == `req.source.app`). */
     source: string;
     targets: AssignmentTargetKind[];
-    /** Vlakke LIJST, zoals {@link LocaleBundle}; zie daar waarom die vorm blijft. */
+    /** Flat LIST, like {@link LocaleBundle}; see there why that shape stays. */
     locales?: LocaleBundle;
 }
-/** De samengestelde catalogus die de hub aan de builder levert. */
+/** The composed catalog the hub hands to the builder. */
 export interface AssignmentCatalog {
     targets: AssignmentTargetKind[];
-    /** Bronnen die meededen aan de fan-out (voor "wie levert dit?"). */
+    /** Sources that took part in the fan-out (for "who provides this?"). */
     sources: string[];
     locales: LocaleBundle;
 }
 /**
- * De waarde op een punt-pad, of `undefined`.
+ * The value at a dot path, or `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.
+ * Its own mini reader and not `resolveRef` from the engine: that one lives in the ai app and knows
+ * the `$` convention, while a bare path from an app declaration is read here. Stops at the first
+ * non-object, so a path running through `null` yields `undefined` instead of throwing.
  */
 export declare function valueAtPath(source: unknown, path: string): unknown;
 /**
- * De doelsoort die dit activity-type aankondigt, en de doelsoort met dit id.
+ * The target kind this activity type announces, and the target kind with this 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?").
+ * Two readers, one list: the engine arrives with a type ("what is this?"), the builder and the
+ * validation with an id ("does this kind exist?").
  */
 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? */
+/** Is this a trigger waiting on an assignment? */
 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.
+ * Why this assignment does *not* start a run of this playbook, or `null` when it does.
  *
- * 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.
+ * A reason and not a boolean, for the same reason as `triggerMismatch`: a trigger that does not
+ * match leaves no run behind, so there is no trace to look into. "I gave this conversation to the
+ * agent and nothing happens" has to be answerable.
  *
- * Puur, en dat is waar de vier poorten hier staan in plaats van in de job:
+ * Pure, which is why the four gates live here instead of in the 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.
+ * 1. **No agent** ⇒ never. "Assigned to whom?" has no answer then, and without this gate such a
+ *    playbook would fire on *every* assignment by *anyone*.
+ * 2. **Unknown target kind** ⇒ never, and it says which. That is the case "the app that declared
+ *    this is disabled or not answering", and that must not be silence.
+ * 3. **Assigned to someone else** ⇒ not this playbook. This is the core comparison.
+ * 4. **The agent assigned it to itself** ⇒ not again. Without this gate a procedure that assigns
+ *    (`update_interaction`) is a loop waking itself: the lifecycle activity carries no `runId`, so
+ *    the existing loop damping does not see it.
  */
 export declare function assignmentMismatch(input: {
     trigger: PlaybookTrigger | undefined;
-    /** `Playbook.agentId` — het userId van de agent die deze playbook uitvoert. */
+    /** `Playbook.agentId` — the userId of the agent executing this playbook. */
     agentId?: string | null;
-    /** De doelsoort uit de catalogus die bij deze playbook hoort, indien gevonden. */
+    /** The target kind from the catalog belonging to this playbook, when found. */
     target?: AssignmentTargetKind;
     activityType: string;
-    /** Aan wie dit toegewezen werd, gelezen via `target.assigneePath`. */
+    /** Who this was assigned to, read via `target.assigneePath`. */
     assigneeUserId?: string;
-    /** Wie de toewijzing deed, als het een gebruiker was. */
+    /** Who did the assigning, when it was a user. */
     authorUserId?: string;
 }): string | null;

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

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

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

@@ -1,9 +1,9 @@
 /**
- * Leesbare naam van een actie/tool voor een mens: `tool:communication__update_interaction`
- * wordt `communication · update interaction`.
+ * Readable name of an action/tool for a human: `tool:communication__update_interaction` becomes
+ * `communication · update interaction`.
  *
- * Gedeeld, want de proposal-kaart in comms had deze helper al terwijl de run-timeline in
- * de AI-app de rauwe id printte — dus daar las je letterlijk
+ * Shared, because the proposal card in comms already had this helper while the run timeline in the
+ * AI app printed the raw id — so there you literally read
  * `voorstel: tool:mcp__jira__create_issue`.
  */
 export declare function humanizeAction(action: string): string;

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

@@ -1,11 +1,10 @@
 /**
- * De variabelen die de engine onder `vars.trigger` zet bij een activity-trigger.
+ * The variables the engine puts under `vars.trigger` on an activity trigger.
  *
- * Contract tussen `buildTriggerVars` (server) en de variabelen-picker (builder). Die
- * twee waren uiteengelopen: de picker bood `trigger.fromEmail` en `trigger.channel`
- * aan — die bestaan niet — en miste `subject`, `textRaw`, `direction`, `authorType` en
- * `activityId`. Elk pad dat hij aanbood leverde dus `undefined` op. Eén lijst, aan
- * beide kanten geïmporteerd, kan niet opnieuw uiteenlopen.
+ * A contract between `buildTriggerVars` (server) and the variable picker (builder). Those two had
+ * drifted apart: the picker offered `trigger.fromEmail` and `trigger.channel` — which do not
+ * exist — and lacked `subject`, `textRaw`, `direction`, `authorType` and `activityId`. Every path
+ * it offered therefore yielded `undefined`. One list, imported on both sides, cannot drift again.
  */
 export declare const TRIGGER_VARS: readonly [{
     readonly name: "text";
@@ -28,6 +27,9 @@ export declare const TRIGGER_VARS: readonly [{
 }, {
     readonly name: "interactionId";
     readonly type: "string";
+}, {
+    readonly name: "itemId";
+    readonly type: "string";
 }, {
     readonly name: "activityId";
     readonly type: "string";
@@ -57,17 +59,17 @@ export declare const TRIGGER_VARS: readonly [{
     readonly type: "string";
 }];
 /**
- * Wat een classify-stap per mode **oplevert** — het contract dat `runClassify` nakomt.
+ * What a classify step **yields** per mode — the contract `runClassify` honours.
  *
- * 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.
+ * Here as a type and not only as a list, because {@link CLASSIFY_VARS} should follow from it. That
+ * list had drifted from reality, exactly as `TRIGGER_VARS` had before: `question` offered
+ * `confidence` (does not exist, the adapter gives `answer` + `reasoning`) and `topics` lacked
+ * `topicId` and `reasoning`. A path the picker offers that yields `undefined` is silently broken —
+ * hence the adapter being held against it in `ai/classify.test.ts`.
  */
 export interface ClassifyTopicsResult {
     topicId: string;
-    /** Naam van het onderwerp, of `null` bij `"none"`. */
+    /** Name of the topic, or `null` with `"none"`. */
     topic: string | null;
     confidence: number;
     reasoning?: string;
@@ -76,9 +78,9 @@ export interface ClassifyQuestionResult {
     answer: boolean;
     reasoning?: string;
 }
-/** De zelf-gedefinieerde velden uit `ClassifyStep.fields`; de vorm is van de auteur. */
+/** The self-defined fields from `ClassifyStep.fields`; the shape belongs to the author. */
 export type ClassifyExtractResult = Record<string, unknown>;
-/** De variabelen die een classify-stap oplevert, per mode. Volgt de types hierboven. */
+/** The variables a classify step yields, per mode. Follows the types above. */
 export declare const CLASSIFY_VARS: {
     readonly topics: readonly [{
         readonly name: "topicId";