@opencxh/domain 1.153.0 → 1.158.0

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

@@ -1,9 +1,11 @@
 import { ActingIdentity } from '../../platform/identity';
+import { ResourceRef } from '../../platform/resource';
 import { OwnerScope } from '../contact/types';
 /**
- * Playbooks — event-driven automation with AI steps. See docs/PLAYBOOKS.md.
- * Fase 0 covers the deterministic subset; AI steps are typed here but the
- * executor rejects them until Fase 2.
+ * Playbooks — event-driven automation met AI-stappen. Zie docs/PLAYBOOKS.md.
+ *
+ * Twee uitvoeringsvormen, één contract: zie {@link Decider}. Alle staptypes in
+ * {@link Step} worden uitgevoerd; er is geen soort meer die de executor weigert.
  */
 export type Autonomy = "suggest" | "auto";
 export type PlaybookTrigger = {
@@ -29,11 +31,43 @@ export type PlaybookTrigger = {
     debounceMs?: number;
 } | {
     kind: "manual";
+}
+/**
+ * Iemand wijst werk aan de agent van deze playbook toe — de wekker van een **opdracht**.
+ *
+ * Geen nieuw mechanisme: een toewijzing is al een activity, dus dezelfde poort levert hem af.
+ * Wat deze soort toevoegt is de vraag die de engine niet zelf kan beantwoorden — *is dit aan
+ * míjn agent?* — en het antwoord staat in `Playbook.agentId`, niet hier. Eén plek die de
+ * agent benoemt, want dat veld bepaalt óók namens wie de run handelt; zou het hier nóg een
+ * keer staan, dan kon een playbook op de toewijzing aan de één reageren namens de ander.
+ *
+ * Wélke soorten werk toegewezen kunnen worden is **gedeclareerd** door de app die ze bezit
+ * (`assignment-source`-federatie, zie `./assignment.ts`) en staat daarom als losse id in
+ * `targetKind` in plaats van als union hier.
+ */
+ | {
+    kind: "assignment";
+    targetKind: string;
 };
 export interface Guardrails {
     maxSteps?: number;
     maxToolCalls?: number;
 }
+/**
+ * Grenzen voor `maxTokens` op een AI-stap. De bovengrens is dezelfde als die van
+ * `/generate`: geen enkele prompt hier heeft meer output nodig, en een op hol
+ * geslagen run mag er niet voor betalen. De ondergrens houdt een typfout ("5")
+ * tegen die elk antwoord halverwege een woord afkapt.
+ */
+export declare const STEP_MAX_TOKENS_MIN = 64;
+export declare const STEP_MAX_TOKENS_MAX = 8000;
+/**
+ * `maxTokens` van een stap naar een bruikbare waarde, of `undefined` als er niets
+ * (bruikbaars) staat. Neemt ook strings aan, want de editor levert het veld als
+ * tekst op (`<input type="number">`) en een string in `max_tokens` is bij OpenAI
+ * en Anthropic een 400.
+ */
+export declare function clampStepMaxTokens(value: unknown): number | undefined;
 export interface ConditionStep {
     type: "condition";
     /** JSONLogic expression evaluated against the run vars. */
@@ -41,11 +75,19 @@ export interface ConditionStep {
     /** Gate: what to do when the condition is false. "then" = the steps that follow. */
     onFalse: "stop" | "escalate" | "continue";
 }
-export interface ForEachStep {
+/**
+ * Generiek over wat er in de body mag staan, zodat een beperkte staptaal een **echt subtype** kan
+ * zijn in plaats van een runtime-regel. Zie `ReadStep` in `../live-lens/types`: die laat hier
+ * alleen leesbare stappen in, en dan is "een leesbaan kan niet schrijven" een typefout in plaats
+ * van een controle die iemand kan vergeten aan te roepen.
+ *
+ * De default houdt elk bestaand gebruik (`ForEachStep` zonder parameter) ongewijzigd.
+ */
+export interface ForEachStep<S = Step> {
     type: "for-each";
     in: string;
     as: string;
-    body: Step[];
+    body: S[];
 }
 export interface LookupStep {
     type: "lookup";
@@ -60,13 +102,47 @@ export interface ActionStep {
     action: string;
     params: Record<string, unknown>;
     autonomy?: Autonomy;
+    /**
+     * Var waarin het resultaat van de actie landt, als je het nodig hebt.
+     *
+     * Bestond niet, en daardoor was er geen manier om te wachten op iets dat je zelf net had
+     * aangemaakt: een `create_task` kon haar id nergens laten, dus `waitingOn: { on: "task" }` was
+     * niet in te gaan. Dezelfde vorm als `LookupStep.as`, en dezelfde parsing — twee antwoorden op
+     * "wat ís het resultaat van een tool" zou de volgende duplicatie zijn.
+     *
+     * Onder autonomie `suggest` wordt de actie vastgehouden en draait ze pas na goedkeuring; het
+     * resultaat landt dan bij het hervatten. Tot dat moment bestaat de var niet, en een stap die
+     * er dan al naar verwijst faalt luid (zie `engine/utils.ts`) in plaats van met leegte verder
+     * te gaan.
+     */
+    as?: string;
+}
+/**
+ * Wacht tot deze taak af is.
+ *
+ * De tegenhanger van `wait-for-reply`, voor het geval uit de support-procedure: "moet een
+ * collega iets doen, maak een taak en wacht tot die af is". `taskId` is een gewone verwijzing,
+ * dus `$newTask.id` na een `create_task` met een `as`.
+ */
+export interface WaitForTaskStep {
+    type: "wait-for-task";
+    /** `$ref` of letterlijk id van de taak om op te wachten. */
+    taskId: string;
 }
-/** AI steps — typed in Fase 0, executed from Fase 2. */
+/**
+ * Een enkele classificatie met gestructureerde uitvoer.
+ *
+ * **`profileId` en niet `accountId` + `model`.** Dit was de enige AI-stap die zijn eigen account
+ * en model droeg, terwijl de kernkeuze van dit systeem is dat een `AIProfile` het herbruikbare
+ * brein is en AI-stappen daarnaar verwijzen (`docs/PLAYBOOKS.md` §2). Wat die uitzondering kostte:
+ * sjablonen hadden `$default`/`$defaultModel`-placeholders nodig die de installer moest
+ * vervangen, en een modelwissel raakte elke classify-stap van elke playbook afzonderlijk.
+ */
 export interface ClassifyStep {
     type: "classify";
     as: string;
-    accountId: string;
-    model: string;
+    /** Het brein dat classificeert. Een goedkoop, snel profiel is hier de bedoeling. */
+    profileId: string;
     mode: "topics" | "question" | "extract";
     topicIds?: string[];
     question?: string;
@@ -81,6 +157,16 @@ export interface ClassifyStep {
      * eerdere `lookup` heeft opgehaald, zoals de berichten van het gesprek.
      */
     input?: string;
+    /**
+     * Plafond op de output van deze stap, per model-call. Leeg = het
+     * `providerConfig` van het account/profiel, en anders de vendor-default.
+     *
+     * Bewust naast `guardrails` en niet erin: `maxSteps`/`maxToolCalls` begrenzen de
+     * hele run, dit geldt per call. In dezelfde bak zou het lezen als "totaalbudget
+     * voor deze stap", en dat is het niet — een agent-loop van vijf turns mag vijf
+     * keer tot dit plafond komen.
+     */
+    maxTokens?: number;
 }
 export interface GenerateStep {
     type: "generate";
@@ -88,13 +174,27 @@ export interface GenerateStep {
     goal?: string;
     kind: "reply" | "compose" | "note";
     as?: string;
+    /** Plafond op de output van deze stap. Zie `ClassifyStep.maxTokens`. */
+    maxTokens?: number;
 }
+/**
+ * Een agentische beurt **binnen een flow**.
+ *
+ * Draagt een {@link Procedure} in plaats van diens velden nóg een keer: dit had
+ * `goal`/`toolsOverride`/`guardrails`/`maxTokens` als eigen velden, wat exact dezelfde vijf
+ * dingen waren onder twee namen — en `runAgentStep` was een adapter die `goal` op `text` en
+ * `toolsOverride` op `tools` afbeeldde. Compositie in plaats van een tweede naamgeving.
+ *
+ * `profileId` staat hiér en niet in de procedure: een workflow heeft geen agent, dus het brein
+ * moet uit de stap komen. Bij een **opdracht** komt het brein van de agent
+ * (`User.profileId`) en draagt de procedure er dus geen.
+ */
 export interface AgentStep {
     type: "agent";
+    /** Het brein voor deze stap. */
     profileId: string;
-    goal: string;
-    guardrails: Guardrails;
-    toolsOverride?: string[];
+    /** Wat er moet gebeuren, en waarbinnen. */
+    procedure: Procedure;
     autonomy?: Autonomy;
     as?: string;
 }
@@ -102,7 +202,122 @@ export interface WaitForReplyStep {
     type: "wait-for-reply";
     deadline?: number;
 }
-export type Step = ConditionStep | ForEachStep | LookupStep | ActionStep | ClassifyStep | GenerateStep | AgentStep | WaitForReplyStep;
+/**
+ * Meerdere takken tegelijk, en pas verder als ze allemaal klaar zijn.
+ *
+ * Bestaat voor één concreet probleem: stappen liepen strikt sequentieel, en drie lookups van
+ * elk ~1200 ms achter elkaar passen niet in een cadans van seconden (live assist). Sequentieel
+ * kost de som, parallel kost de langzaamste.
+ *
+ * **Alleen lezen.** Een tak mag niet pauzeren — geen goedkeuring, geen wachten op een antwoord.
+ * Dat is geen tijdelijke beperking maar een grens die het begrip eenvoudig houdt: een run die
+ * halverwege een fan-out pauzeert zou moeten onthouden welke takken al klaar waren en waar hij
+ * verder moet, en dat is een tweede toestandsmachine naast `waitingOn`. Wie iets wil schrijven
+ * doet dat in een stap ná de `parallel`.
+ *
+ * Elke tak schrijft naar zijn eigen `as`-namen; twee takken die dezelfde naam vullen is een
+ * fout, want wie er wint hangt dan van de timing af.
+ */
+export interface ParallelStep<S = Step> {
+    type: "parallel";
+    /** Elke tak is een eigen rijtje stappen. Zie {@link ForEachStep} over de parameter. */
+    branches: S[][];
+    /**
+     * Hoeveel takken er tegelijk mogen lopen. Leeg = alle.
+     *
+     * Een plafond bestaat omdat een tak een tool-call is: tien takken tegelijk zijn tien
+     * gelijktijdige aanroepen naar andere apps.
+     */
+    maxConcurrent?: number;
+    /**
+     * Wat een falende tak betekent. Default `"fail"`: de stap faalt.
+     *
+     * `"continue"` laat de andere takken staan en gaat door — dat is wat een leesoppervlak wil
+     * (één kapotte baan mag de andere twee niet wissen), en precies waarom het een keuze is en
+     * geen aanname.
+     */
+    onBranchError?: "fail" | "continue";
+}
+export type Step = ConditionStep | ForEachStep | ParallelStep | LookupStep | ActionStep | ClassifyStep | GenerateStep | AgentStep | WaitForReplyStep | WaitForTaskStep;
+/**
+ * Een **procedure**: hoe een scenario aangepakt wordt, als prose met guardrails.
+ *
+ * Dit is de tweede uitvoeringsvorm naast `Step[]`, en {@link AgentStep} is er de
+ * variant-binnen-een-flow van (die *bevat* er een, en herhaalt zijn velden niet).
+ *
+ * **Geen `profileId`.** Dat stond hier, en het was de tweede brein-verwijzing in het systeem:
+ * `User.profileId` bestaat al — verplicht bij het aanmaken van een agent, met als doc "het brein
+ * van een agent" — en de engine las hem nooit. Twee velden voor één feit, zonder dat iets ze aan
+ * elkaar relateerde: `agentId: Alice` met het brein van Bob werd zonder klacht opgeslagen, en de
+ * tijdlijn zei dan Alice terwijl het model, de tools en de prompt van Bob waren.
+ *
+ * Nu is er één antwoord op "met welk brein": bij een opdracht dat van de agent, bij een
+ * agent-stap in een workflow dat van de stap. De procedure beschrijft het scenario, niet wie het
+ * uitvoert.
+ *
+ * `tools` is **narrowing-only**: het moet een deelverzameling zijn van `enabledTools` van het
+ * brein dat hem uitvoert. Het profiel is de identiteit (één per agent), de procedure het scenario
+ * (veel per agent), en een scenario mag nooit méér mogen dan de identiteit die het uitvoert.
+ */
+export interface Procedure {
+    /** De prose zelf — wat er moet gebeuren, in de woorden van wie het opschreef. */
+    text: string;
+    /** Toegestane tools. Narrowing-only t.o.v. `enabledTools` van het brein. */
+    tools?: string[];
+    guardrails?: Guardrails;
+    /** Plafond per beurt. Zie `ClassifyStep.maxTokens`. */
+    maxTokens?: number;
+}
+/**
+ * Wie kiest de volgende zet.
+ *
+ * Twee uitvoeringsvormen, één contract. Beide lopen door dezelfde toolruntime en dezelfde
+ * goedkeuringspoort; alleen de manier waarop de volgende zet gekozen wordt verschilt:
+ *
+ * - **workflow** — deterministisch, `Step[]`, gebouwd op de canvas. Routing, triage,
+ *   achtergrondautomatisering. Een gratis, testbare poort in plaats van een prompt.
+ * - **procedure** — prose, een model kiest. Voor werk waarvan de stappen geen takken in een
+ *   boom zijn (antwoorden *én* een taak maken, of eerst vragen en daarna alsnog antwoorden).
+ *
+ * Verkeerd om gebruikt faalt elke vorm op zijn eigen manier: een procedure als workflow
+ * verspreidt logica over blokken tot het onbeheersbaar is, een workflow als procedure ruilt een
+ * testbare conditie voor een onbetrouwbare prompt (en kost een modelaanroep per bericht).
+ */
+export type Decider = {
+    kind: "workflow";
+    steps: Step[];
+} | {
+    kind: "procedure";
+    procedure: Procedure;
+};
+/**
+ * **Eén veld, met de soort erin.** Dit was een paar losse kolommen — `steps: Step[]` naast
+ * `procedure?: Procedure | null` — met een functie (`deciderOf`) die er een union van maakte
+ * volgens de regel "procedure aanwezig ⇒ procedure".
+ *
+ * Wat die vorm kostte:
+ *
+ * - een rij met **beide** gevuld was representeerbaar, en betekende stil "de steps zijn dood";
+ * - elk schrijfpad moest de onuitgesproken regel kennen: `crud/update.ts` moest expliciet `null`
+ *   schrijven om "de procedure eruit halen" te laten werken, en `run-playbook.ts` had een
+ *   conditionele spread om de kolom weg te laten;
+ * - de frontend had de regel nóg een keer (`!!pb.procedure` als soort-filter);
+ * - en het is al een keer stil fout gegaan: `fromView` droeg `procedure` niet mee, waardoor élke
+ *   procedure die je opende en opsloeg zichzelf tot een lege workflow maakte.
+ *
+ * Met `kind` in de kolom is de soort een feit in plaats van een gevolgtrekking, en kan er geen
+ * derde toestand bestaan. De editor houdt zijn platte vorm — dat is wat `toView`/`fromView` doen.
+ */
+export declare const EMPTY_WORKFLOW: Decider;
+/**
+ * De stappen van deze decider, of een lege lijst als het een procedure is.
+ *
+ * Twee lezers-helpers en géén `deciderOf` terug: het verschil is dat deze de soort *lezen* in
+ * plaats van hem te *raden* uit welke velden gevuld zijn.
+ */
+export declare function stepsOf(decider: Decider | undefined): Step[];
+/** De procedure van deze decider, of `undefined` als het een workflow is. */
+export declare function procedureOf(decider: Decider | undefined): Procedure | undefined;
 export interface Playbook {
     id: string;
     organizationId: string;
@@ -112,7 +327,20 @@ export interface Playbook {
     enabled: boolean;
     autonomy: Autonomy;
     trigger: PlaybookTrigger;
-    steps: Step[];
+    /** Wie de volgende zet kiest: stappen of prose. Zie {@link Decider}. */
+    decider: Decider;
+    /**
+     * De agent die dit uitvoert: het `userId` van een gebruiker met `type: "agent"`.
+     *
+     * Bepaalt **namens wie** de run handelt (`runActor`), en daarmee: wiens naam er in de tijdlijn
+     * staat, welke interacties hij mag raken, en van wiens budget het afgaat. Bewust náást
+     * `ownerScope` en niet erin — dat veld bepaalt wie de playbook mag *beheren*, en dat blijven
+     * mensen. Een agent logt nooit in, dus als beide op één veld leunden kon niemand hem meer
+     * aanpassen.
+     *
+     * Leeg = de actor volgt de scope, precies zoals voorheen.
+     */
+    agentId?: string | null;
     /** Bumped on every change; runs pin to the version they started on. */
     version: number;
     /** Actor of autonomous actions. */
@@ -129,19 +357,106 @@ export interface Playbook {
  * de `PLAYBOOK_STARTED`-activity dekt "hij is begonnen" al. (Die status bestond,
  * werd nooit geproduceerd, en had wél een label in de UI.)
  */
-export type RunStatus = "running" | "awaiting_approval" | "awaiting_reply" | "done" | "escalated" | "failed" | "timed_out" | "stopped";
+export type RunStatus = "running" | "waiting" | "done" | "escalated" | "failed" | "stopped";
+/**
+ * Waaróp een wachtende run wacht.
+ *
+ * Dit was eerder statusinformatie: `awaiting_approval`, `awaiting_reply` en `timed_out` waren
+ * drie statussen die alle drie "wacht op X" betekenden, en de reden zat in de naam. Daardoor
+ * groeide de statusset met elke nieuwe reden mee — een run die op een taak wacht zou
+ * `awaiting_task` hebben gevraagd, een run die op een moment wacht `awaiting_time`, en dan
+ * moest elke lezer van `status` opnieuw worden bijgewerkt.
+ *
+ * De reden van het wachten is **data**, geen status. `status: "waiting"` zegt dát er gewacht
+ * wordt; dit veld zegt waarop, en wie het signaal levert leest alleen dit.
+ *
+ * `timed_out` staat er niet bij: een verstreken deadline is geen manier van wachten maar een
+ * uitkomst, en landt via `decideFinalState` op een eindstand (zie {@link TerminalLifecycle}).
+ *
+ * Er is ook geen `{ on: "time" }`. Die stond hier, zonder dat iets hem schreef of las: het
+ * wachten-op-een-moment dat wél bestaat is de timeout-job die bij `{ on: "reply" }` wordt
+ * ingeplanned, en die leest de deadline uit de job en niet uit dit veld. Een lid dat door niets
+ * geproduceerd wordt is een belofte aan elke lezer die hem moet afhandelen.
+ */
+export type WaitingOn = {
+    on: "approval";
+}
+/** De klant antwoordt, of een collega beantwoordt de interne vraag van de run. */
+ | {
+    on: "reply";
+    interactionId: string;
+} | {
+    on: "task";
+    taskId: string;
+};
 /** Eindstanden: hier komt een run niet meer vanzelf uit. */
-export declare const TERMINAL_RUN_STATUSES: readonly ["done", "escalated", "failed", "timed_out", "stopped"];
-/** Wacht deze run op iets externs? */
-export declare const PAUSED_RUN_STATUSES: readonly ["awaiting_approval", "awaiting_reply"];
+export declare const TERMINAL_RUN_STATUSES: readonly ["done", "escalated", "failed", "stopped"];
+/**
+ * **Tweede vocabulaire, expliciet.** Waarom een run eindigde, zoals de tijdlijn het benoemt —
+ * niet hetzelfde als de status die op de run staat.
+ *
+ * Twee redenen zijn geen `RunStatus`, en dat is geen omissie:
+ *
+ * - **`rejected`** — een afgewezen voorstel landt als status `"stopped"`, maar de tijdlijn moet
+ *   "afgewezen" kunnen zeggen.
+ * - **`timed_out`** — een run waarvan de deadline verstreek landt als `"escalated"` (er moet een
+ *   mens iets mee), maar "geen antwoord binnen de deadline" is een andere mededeling dan
+ *   "geëscaleerd". Dit was eerder een eigen status; hij is verhuisd naar dit vocabulaire, want
+ *   het is een *reden* en geen toestand waar een run in kan verkeren.
+ *
+ * Dat dit vocabulaire rijker is dan de statusset is precies waarom het apart bestaat: de
+ * tijdlijn vertelt een mens wát er gebeurde, `status` vertelt de machine wat er nog te doen is.
+ */
+export type TerminalLifecycle = RunStatus | "rejected" | "timed_out";
+/**
+ * Is deze run klaar — en daarmee ook: mag hij opnieuw gedraaid worden?
+ *
+ * Die tweede vraag had een eigen functie (`isRetryable`) die niets anders deed dan deze
+ * aanroepen. Twee namen voor één regel betekent dat een lezer moet uitzoeken of er een verschil
+ * is; dat er geen was, was niet te zien zonder de body te openen.
+ *
+ * De regel zelf staat hier dus één keer: een retry mag op precies de eindstanden. Een lopende of
+ * mens-gepauzeerde run blijft met rust, zodat een retry nooit over live uitvoering heen loopt of
+ * een openstaand voorstel overschrijft.
+ */
 export declare function isTerminal(status: RunStatus | string): boolean;
 /**
- * Statussen waarvan een run opnieuw gestart mag worden. Een lopende of
- * mens-gepauzeerde run blijft met rust, zodat een retry nooit over live uitvoering
- * heen loopt of een openstaand voorstel overschrijft — vandaar: precies de eindstanden.
+ * Wacht deze run op iets externs?
+ *
+ * Eén statusvergelijking en niet meer een lijst: er was een `PAUSED_RUN_STATUSES` met twee
+ * leden omdat de reden van het wachten ín de status zat. Nu staat de reden in
+ * {@link WaitingOn} en is "wacht" één toestand — dus een nieuwe reden (een taak, een moment)
+ * verandert deze functie niet meer.
  */
-export declare function isRetryable(status: RunStatus | string): boolean;
 export declare function isPaused(status: RunStatus | string): boolean;
+/**
+ * Loopt deze run nog — mag `finalizeRun` er een uitkomst over schrijven?
+ *
+ * "In de lucht" is precies "niet in een eindstand": `running` of `waiting`. De lock-retry in
+ * `jobs/context.ts` herschedulet tot vijf keer, dus zonder deze check kan een late job met een
+ * verouderde uitkomst over een al afgeronde run schrijven.
+ */
+export declare function isInFlight(status: RunStatus | string): boolean;
+/**
+ * Het onderwerp van een run als één verwijzing, of `undefined` als hij er geen heeft.
+ *
+ * Zo'n run bestaat: een org-brede playbook die een rollup doet heeft geen resource om over te
+ * gaan. Dat is een geldige toestand en geen ontbrekend veld.
+ */
+export declare function subjectOf(run: {
+    subjectKind?: string;
+    subjectId?: string;
+}): ResourceRef | undefined;
+/** De scope-sleutel van het onderwerp, klaar voor `authorizeScope`. */
+export declare function subjectKeyOf(run: {
+    subjectKind?: string;
+    subjectId?: string;
+}): string | undefined;
+/** Het interactie-id van deze run, als zijn onderwerp een gesprek is. */
+export declare function runInteractionId(run: {
+    subjectKind?: string;
+    subjectId?: string;
+}): string | undefined;
 export interface RunStepTrace {
     path: string;
     type: string;
@@ -149,22 +464,83 @@ export interface RunStepTrace {
     note?: string;
     ms?: number;
 }
+/**
+ * Wat deze run in beweging zette.
+ *
+ * Was `createdBy: string`, en dat veld droeg de auteur van de **playbook** — niet wie de run
+ * startte. Dus "wie heeft dit gedaan" had geen antwoord, terwijl `run/start.ts` het userId van de
+ * mens die op start drukte al meestuurde in de job-data, waar niemand het las.
+ */
+export type StartedBy = 
+/** Een mens drukte op start (`POST /playbook-run/start`). */
+{
+    kind: "user";
+    id: string;
+}
+/** De trigger vuurde: een activity, een toewijzing, een afgeronde taak. */
+ | {
+    kind: "trigger";
+    id?: string;
+};
 export interface PlaybookRun {
     id: string;
     organizationId: string;
     playbookId: string;
     playbookVersion: number;
-    interactionId?: string;
+    /**
+     * De opdracht waarvan dit een **beurt** is, als er een is.
+     *
+     * Afwezig = een losstaande uitvoering (een automatisering die vuurt en klaar is). Aanwezig = één
+     * zet in werk dat langer leeft dan deze run, met een draad als geheugen.
+     */
+    assignmentId?: string;
+    /**
+     * Waar deze run **over gaat**, in twee platte kolommen.
+     *
+     * Dit was `interactionId?: string`, en dat leek onschuldig — het veld was immers optioneel. Maar
+     * vier paden leunden er zwijgend op alsof het verplicht was: goedkeuren gooide `400` zonder
+     * interactie, de lijst filterde op `audience` (leeg voor een org-actor, dus onvindbaar), de
+     * tijdlijn deed niets, en de taak-wekker eiste een gesprek. Precies het geval waar de
+     * toewijs-federatie voor bestaat — werk dat géén gesprek is — viel dus in dat gat.
+     *
+     * **Twee kolommen en geen genest object**, om dezelfde reden als {@link WaitingOn} zijn
+     * `waitingOnKind` heeft: de store kan niet in een genest object zoeken, en hier moet op gezocht
+     * worden (de runs van dit gesprek, de runs van deze taak). `subjectOf` maakt er een
+     * {@link ResourceRef} van waar je hem als geheel nodig hebt.
+     */
+    subjectKind?: string;
+    subjectId?: string;
     status: RunStatus;
+    /**
+     * De aanleiding: wélk signaal deze run startte, plus de invoer zoals die er tóen uitzag.
+     *
+     * **`vars` hier is niet hetzelfde als `vars.trigger` hieronder, en dat is met opzet.** Dit veld
+     * is de *onveranderlijke invoer*; `vars` is de *werkkopie* die tijdens de run muteert — stappen
+     * schrijven erin, en resume-on-reply overschrijft `vars.trigger` met het nieuwe bericht. Een
+     * retry moet schoon herrekenen vanaf het oorspronkelijke signaal, en dat kan alleen als dat
+     * signaal ergens bewaard is gebleven.
+     *
+     * Het veld heette `event`, wat suggereerde dat het de rauwe activity was; het zijn de
+     * trigger-vars. Dezelfde vorm als `vars.trigger` betekent hier dus niet dezelfde betekenis.
+     */
     trigger: {
         activityType?: string;
         activityId?: string;
-        event: Record<string, unknown>;
+        vars: Record<string, unknown>;
     };
     vars: Record<string, unknown>;
     trace: RunStepTrace[];
-    /** Snapshot of the playbook steps at run start — version-pinned resume (docs 11.4). */
-    steps?: Step[];
+    /**
+     * De uitvoeringsvorm, vastgepind bij de start: de playbook bijstellen mag een lopende of
+     * geparkeerde run niet halverwege van gedrag of opdracht laten wisselen (docs 11.4).
+     */
+    decider: Decider;
+    /**
+     * De agent die deze run uitvoert, vastgepind — en daarmee ook **met welk brein**: dat is
+     * `User.profileId` van deze agent. Afwezig bij een workflow zonder agent; dan draagt een
+     * agent-stap zijn eigen `profileId`.
+     */
+    agentId?: string | null;
     /**
      * Namens wie deze run handelt, vastgepind bij de start — net als `steps`. Anders
      * wisselt een lopende of geparkeerde run stilletjes van identiteit zodra iemand de
@@ -180,19 +556,51 @@ export interface PlaybookRun {
     pending?: {
         action: string;
         params: Record<string, unknown>;
+        as?: string;
     }[] | null;
     /** The AI_ACTION_PROPOSED activity created for the current pending batch (for resolve on approve/reject). */
     proposalActivityId?: string | null;
     /**
-     * Index van de stap waarop de flow pauzeerde — voor zowel `awaiting_approval` als
-     * `awaiting_reply`. (Was `resumeIndex` naast `pending.stepIndex`: twee velden voor
+     * Waarop deze run wacht, als `status === "waiting"`. `null` wanneer het veld gewist is (de
+     * store schrijft `null`), en afwezig bij een run die niet wacht.
+     *
+     * Vervangt de drie `awaiting_*`/`timed_out`-statussen: de reden van het wachten is data, dus
+     * een nieuwe reden kost een lid in {@link WaitingOn} en niet een status die elke lezer moet
+     * kennen.
+     */
+    waitingOn?: WaitingOn | null;
+    /**
+     * De **soort** van {@link WaitingOn}, als platte kolom — puur om op te kunnen queryen.
+     *
+     * `waitingOn` is een genest object en de store kan daar niet in zoeken, dus elke wekker deed
+     * `status: "waiting"` en filterde daarna in het geheugen op `run.waitingOn?.on`
+     * (`jobs/run-playbook.ts`, `triggers/from_tasks.ts`). Dat is goedkoop bij tien wachtende runs
+     * en niet bij tienduizend. Afgeleid en op één plek geschreven (`finalizeRun`), zodat hij niet
+     * uit de pas kan lopen met het object ernaast.
+     */
+    waitingOnKind?: WaitingOn["on"] | null;
+    /**
+     * Index van de stap waarop de flow pauzeerde — voor elke vorm van wachten.
+     * (Was `resumeIndex` naast `pending.stepIndex`: twee velden voor
      * hetzelfde feit, in twee takken geschreven en in twee takken gelezen.)
+     *
+     * Heette `pausedAt`, wat een tijdstip suggereerde tussen velden die dat écht zijn
+     * (`lastStepAt`, `lastRunAt`, `deadline`, `until`). Het is een stap-index.
      */
-    pausedAt?: number | null;
+    resumeAtStep?: number | null;
     rounds?: number;
-    /** Denormalized interaction audience for efficient list-filtering. */
-    audience?: string[];
-    createdBy: string;
+    /**
+     * Wie deze run in zijn lijst ziet — een **index**, geen autorisatie.
+     *
+     * Heette `audience`, en dat woord suggereerde een rechtenlijst; hij werd ook zo gebruikt in de
+     * losse tak van `authorizeRunScope` terwijl de interactie-tak hem juist bewust negeerde (de
+     * denormalisatie verouderd zodra een gesprek van inbox wisselt). Autorisatie komt nu van het
+     * onderwerp of van de scope van de definitie; dit veld is er alleen om "mijn runs" te kunnen
+     * queryen.
+     */
+    visibleTo?: string[];
+    /** Wie deze run in beweging zette. Zie {@link StartedBy}. */
+    startedBy: StartedBy;
     approvedBy?: string | null;
     result?: {
         ok: boolean;

package/dist/entities/read-state/types.d.ts

@@ -3,11 +3,7 @@
  * so read-state (and, later, an audit log) can attach to any resource -
  * interactions, activities, files, kb articles - without per-type schemas.
  */
-/** Polymorphic reference to any resource that can carry read-state. */
-export interface ResourceRef {
-    type: string;
-    id: string;
-}
+export type { ResourceRef } from '../../platform/resource';
 /**
  * A single user's high-water read mark on one resource. `lastReadAt` is the
  * epoch (ms) up to which this user has read the resource; whether they have

package/dist/entities/user/types.d.ts

@@ -1,8 +1,64 @@
+/**
+ * Mens of agent.
+ *
+ * Een agent is **geen apart begrip naast de gebruiker** maar een gebruiker met een ander type.
+ * Dat is een keuze met een concreet doel: hij krijgt een echt `userId`, dus hij loopt door
+ * `authorizeIdentity` op het fail-closed pad, hij tekent zijn activities met zijn eigen naam in
+ * plaats van als "system", hij kan lid van een team zijn (`getReadableTeamIds` werkt), en hij
+ * verbruikt van zijn eigen per-user-budget. Elk van die dingen zou anders een uitzondering zijn
+ * geweest, en elke uitzondering is een plek waar een audit hem kwijtraakt.
+ *
+ * Afwezig betekent `"user"`: bestaande rijen zijn mensen, en de mirror wordt niet gebackfilld.
+ */
+export type UserType = "user" | "agent";
+/**
+ * Wat een ander oppervlak van een gebruiker mag weten om hem te **tónen**.
+ *
+ * Los van {@link User}, en dat is het punt: een naam opzoeken is iets anders dan een gebruiker
+ * beheren. De beheerroute geeft het hele record plus zijn rollen (een extra RPC naar
+ * `system.rbac`) — dat is precies wat je niet wil als je alleen een auteursnaam in een tijdlijn
+ * zet: het kost een call die niemand nodig heeft en het deelt e-mail en rollen met een app die
+ * daar niets mee te maken heeft.
+ *
+ * `type` zit er wél in: een tijdlijn of een deelnemerslijst wil een agent kunnen markeren.
+ */
+export interface UserProfile {
+    id: string;
+    name: string;
+    displayName?: string;
+    avatarUrl?: string;
+    type?: UserType;
+    /**
+     * Het brein van een agent, als dit een agent is — zie {@link User.profileId}.
+     *
+     * Hoort bij dit compacte record en niet alleen bij het volledige: "is dit een agent" staat er
+     * al (`type`), en "met welk brein" is de directe vervolgvraag van elke beller die er werk aan
+     * geeft. Zonder dit veld moest de ai-app de beheerroute gebruiken — het hele record plus een
+     * RPC naar `system.rbac` — om één id te weten.
+     */
+    profileId?: string;
+}
+/** Is deze gebruiker een agent? Afwezig type = mens. */
+export declare function isAgentUser(user: {
+    type?: UserType | string;
+}): boolean;
 export interface User {
     id: string;
     name: string;
     email: string;
     availableOrganizations: string[];
+    /**
+     * Mens of agent. Zie {@link UserType}.
+     *
+     * Staat op de **lokale mirror** en niet in `system.users`: dat is het platform-record en dat
+     * kennen we niet. Alles wat "is dit een mens" moet weten leest dit veld.
+     */
+    type?: UserType;
+    /**
+     * Het brein van een agent: het `AIProfile` waarmee hij werkt. Alleen gezet als
+     * `type === "agent"`.
+     */
+    profileId?: string;
     /** Mirrored from system.users. */
     firstName?: string;
     lastName?: string;