@opencxh/domain 1.275.0 → 1.276.0

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

@@ -281,7 +281,7 @@ export type AIActionProposedPayload = {
     runId: string;
     playbookId?: string;
     playbookName?: string;
-    /** The held actions, e.g. { action: "tool:mcp__jira__create_issue", params }. */
+    /** The held actions, e.g. { action: "mcp__jira__create_issue", params }. */
     actions: {
         action: string;
         params?: Record<string, unknown>;
@@ -289,6 +289,10 @@ export type AIActionProposedPayload = {
     status: "pending" | "approved" | "rejected";
     /** Who the proposal was made on behalf of, so the card can show "on behalf of Finance". */
     actor?: ActingIdentity;
+    /** The approval request that decides it — the card decides through that, not through ai. */
+    approvalRequestId?: string;
+    /** Every request this proposal waits on, one per guarded act; the first is `approvalRequestId`. */
+    approvalRequestIds?: string[];
 };
 /** Playbook lifecycle marker in the interaction timeline (system-authored). */
 export type PlaybookLifecyclePayload = {

package/dist/entities/ai-account/modality.d.ts

@@ -22,5 +22,3 @@ export interface ModelModality {
  * declares, rather than silently refusing every attachment on a self-hosted or brand-new model.
  */
 export declare function modelAcceptsAttachment(modality: ModelModality | undefined, kind: string): boolean | undefined;
-/** Can this model speak? The honest question behind the `tts` flag. */
-export declare function modelProduces(modality: ModelModality | undefined, out: string): boolean;

package/dist/entities/ai-account/vendors.d.ts

@@ -1,14 +1,9 @@
 import { AiCapability } from './capabilities';
-/**
- * What a vendor can do. Was its own union of three; it is the same vocabulary the account
- * defaults and the usage rows use, so it now names {@link AiCapability} instead of repeating it.
- */
-export type AiVendorCapability = AiCapability;
 export interface AiVendor {
     id: string;
     label: string;
     /** What this vendor can do. Decides where it appears as an option in the UI. */
-    capabilities: readonly AiVendorCapability[];
+    capabilities: readonly AiCapability[];
     /** Model a call runs on when it carries none itself. Absent for vendors without a chat adapter. */
     defaultModel?: string;
     /**
@@ -38,7 +33,7 @@ export declare function aiVendorLabel(vendorId: string): string;
  */
 export declare function aiVendorDefaultModel(vendorId: string, fallback?: string): string;
 /** Vendors offering this capability — for capability-filtered pickers. */
-export declare function aiVendorsWith(capability: AiVendorCapability): AiVendor[];
+export declare function aiVendorsWith(capability: AiCapability): AiVendor[];
 /** True when the user has to fill in a host themselves (the vendor has no fixed one). */
 export declare function aiVendorNeedsBaseUrl(vendorId: string): boolean;
 /** Does this vendor accept this attachment kind? Text always works — that is prompt. */

package/dist/entities/ai-message/types.d.ts

@@ -39,6 +39,8 @@ export interface AIMessageOutput {
  * question and then having the same thread draft a reply is the normal flow.
  */
 export type AssistantMode = "ask" | "draft" | "agent";
+/** Is this one of the three modes? For request bodies, which may carry anything. */
+export declare function isAssistantMode(value: unknown): value is AssistantMode;
 export interface AIMessage {
     id: string;
     organizationId: string;

package/dist/entities/approval/decide-each.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Give one verdict on every request of a proposal that this person may decide.
+ *
+ * A park asks one request per guarded act, each with its own approvers; the person pressing the
+ * button signs the ones that are theirs. A request that is not theirs (403) or already settled
+ * (400) is counted as `waiting` rather than failing the rest — anything else is a real error.
+ */
+export declare function decideEach(requestIds: readonly string[], decideOne: (requestId: string) => Promise<unknown>): Promise<{
+    decided: number;
+    waiting: number;
+}>;
+/** The requests a proposal waits on, from the list or the single id older rows carry. */
+export declare function proposalRequestIds(source: {
+    approvalRequestIds?: readonly string[] | null;
+    approvalRequestId?: string | null;
+}): string[];

package/dist/entities/approval/decide-each.test.d.ts

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

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

@@ -1,2 +1,3 @@
+export * from './decide-each';
 export * from './policy';
 export * from './types';

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

@@ -1,20 +1,9 @@
 import { ActingIdentity } from '../../platform/identity';
-import { toActingIdentity } from '../scope/actor';
 import { OwnerScope } from '../scope/types';
-/**
- * `ownerScope` **is** a playbook's actor: there is no separate `runAs` field. Visibility, working
- * area and attribution therefore all follow from the same field.
- *
- * 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;
 /**
  * Who this run acts for.
  *
- * **Two different questions, and the whole reason this function exists next to
- * {@link playbookActor}:**
+ * **Two different questions**, which is why this is not just `toActingIdentity(ownerScope)`:
  *
  * - *who acts* — the agent, when one is designated;
  * - *who may manage this* — `ownerScope`, and that stays with humans.

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

@@ -0,0 +1,14 @@
+/**
+ * A parked run's address in the approval layer: `playbook-run:<runId>~<step>`.
+ *
+ * The park is part of the key on purpose. The approval layer de-duplicates on `(scopeKey, act)`
+ * and keeps one approved row per key, so a flow that parks, resumes and parks again on a later
+ * step needs a key per park — while a retry of the *same* park must find its open request.
+ * `~` because the key travels in paths too, where `/` and `.` already mean something.
+ */
+export declare const PLAYBOOK_RUN_SCOPE_KIND = "playbook-run";
+/** The one act a parked run asks for: "carry out what was proposed". */
+export declare const PLAYBOOK_RUN_APPROVAL_ACT = "run";
+export declare function runApprovalKey(runId: string, step?: number): string;
+/** The run behind an approval key's ref (`<runId>~<step>`), or the ref itself without a step. */
+export declare function runIdOfApprovalRef(ref: string): string;

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

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

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

@@ -0,0 +1,25 @@
+import { Autonomy } from './types';
+/** Is this one of the three settings? For request bodies, which may carry anything. */
+export declare function isAutonomy(value: unknown): value is Autonomy;
+/**
+ * How much a run may do on its own, decided **once** at its start and frozen on the run. The
+ * playbook's setting wins where there is one (that is where the organisation configured it), then
+ * the agent's, then `suggest`.
+ *
+ * `demoted`: several autonomous playbooks would act outward on the same subject at once. They
+ * keep doing internal work themselves; a human decides which one goes out.
+ */
+export declare function resolveAutonomy(input: {
+    playbook?: {
+        autonomy?: Autonomy;
+    } | null;
+    agent?: {
+        autonomy?: Autonomy;
+    } | null;
+    demoted?: boolean;
+}): Autonomy;
+/**
+ * A step's own setting may make it more careful than its run, never less: the run's value is
+ * where a demotion and the agent's mandate already landed.
+ */
+export declare function narrowAutonomy(run: Autonomy | undefined, step: Autonomy | undefined): Autonomy;

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

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

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

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

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

@@ -1,5 +1,5 @@
 /**
- * Readable name of an action/tool for a human: `tool:communication__update_interaction` becomes
+ * Readable name of an action/tool for a human: `communication__update_interaction` becomes
  * `communication · update interaction`.
  *
  * Shared, because the proposal card in comms already had this helper while the run timeline in the
@@ -7,8 +7,6 @@
  * `voorstel: tool:mcp__jira__create_issue`.
  */
 export declare function humanizeAction(action: string): string;
-/** The namespaced tool id without the step's `tool:` prefix. */
-export declare function toolName(action: string): string;
 /**
  * The tool's own name, without the namespace that says who owns it:
  * `work__create_work_item` and `mcp__jira__create_issue` become `create_work_item` and

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

@@ -1,5 +1,7 @@
 import { ActingIdentity } from '../../platform/identity';
 import { ResourceRef } from '../../platform/resource';
+import { AssignmentControl } from '../assignment/types';
+import { Trigger } from '../rule/types';
 import { OwnerScope } from '../scope/types';
 /**
  * Playbooks — event-driven automation with AI steps. See docs/PLAYBOOKS.md.
@@ -7,41 +9,18 @@ import { OwnerScope } from '../scope/types';
  * Two execution forms, one contract: see {@link Decider}. Every step type in
  * {@link Step} is executed; there is no kind the executor refuses.
  */
-export type Autonomy = "suggest" | "auto";
-export type PlaybookTrigger = {
-    kind: "activity";
-    activityTypes: string[];
-    /** Channel kinds: "mail" | "chat" | "voice" (derived from the activity type). */
-    channels?: string[];
-    /** Specific channel ids (e.g. per mailbox). Matched against activity.channelId. */
-    channelIds?: string[];
-    filter?: unknown;
-    /**
-     * Wait this many milliseconds, then run **once** for the messages in that window
-     * instead of once per message. The run executes on the **newest** message; the ones
-     * in between are already covered by the conversation lookup step.
-     *
-     * Deliberately on the trigger, not in the memory layer: coalescing is a property of
-     * "how often do I want to react", not of what you remember.
-     */
-    debounceMs?: number;
-} | {
-    kind: "manual";
-}
 /**
- * Someone assigns work to this playbook's agent — the wake-up call of an **assignment**.
- *
- * Not a new mechanism: an assignment is already an activity, so the same gate delivers it.
- * The question the engine cannot answer itself — *is this for MY agent?* — is answered by
- * `Playbook.agentId`, not here: one place names the agent, because that field also decides
- * who the run acts as. Which kinds of work can be assigned is **declared** by the app that
- * owns them (`assignment-source` federation, see `./assignment.ts`), hence a loose id in
- * `targetKind` instead of a union here.
+ * How much a run may do on its own: ask before every write, ask only before a write that leaves
+ * the organisation, or ask nothing. Ordered from most to least careful.
  */
- | {
-    kind: "assignment";
-    targetKind: string;
-};
+export type Autonomy = "suggest" | "outward" | "auto";
+/**
+ * The arms of {@link Trigger} the playbook executor runs: an activity, a person, an assignment.
+ * One vocabulary; each executor names the part it runs (rules: `event` and `schedule`).
+ */
+export type PlaybookTrigger = Extract<Trigger, {
+    kind: "activity" | "manual" | "assignment";
+}>;
 export interface Guardrails {
     maxSteps?: number;
     maxToolCalls?: number;
@@ -96,14 +75,14 @@ export interface ForEachStep<S = Step> {
 }
 export interface LookupStep {
     type: "lookup";
-    /** "tool:<namespaced>" (Fase 1) or a local source ("interactions"/"tasks"). */
+    /** The read tool, `<app>__<name>`. */
     source: string;
     filter?: unknown;
     as: string;
 }
 export interface ActionStep {
     type: "action";
-    /** Local action ("task.create"/"interaction.set"/"notify.user") or "tool:<namespaced>" (Fase 1). */
+    /** The write tool, `<app>__<name>`. */
     action: string;
     params: Record<string, unknown>;
     autonomy?: Autonomy;
@@ -120,11 +99,11 @@ export interface ActionStep {
 /**
  * Wait until this task is done. Counterpart of `wait-for-reply`, for the support-procedure
  * case "a colleague must do something: create a task and wait for it". `taskId` is an
- * ordinary reference, e.g. `$newTask.id` after a `create_task` with an `as`.
+ * ordinary reference, e.g. `{{newTask.id}}` after a `create_task` with an `as`.
  */
 export interface WaitForTaskStep {
     type: "wait-for-task";
-    /** `$ref` or literal id of the task to wait on. */
+    /** `{{ref}}` or literal id of the task to wait on. */
     taskId: string;
 }
 /**
@@ -145,7 +124,7 @@ export interface ClassifyStep {
     fields?: unknown;
     instruction?: string;
     /**
-     * Which text is classified, as a `$ref` into the run vars. Default `$trigger.text`.
+     * Which text is classified, as a `{{ref}}` into the run vars. Default `{{trigger.text}}`.
      * Needed when the trigger carries no text: an `INTERACTION_STATUS_CHANGED` activity has
      * only `{ fromStatus, toStatus }`, so `trigger.text` is empty. With `input: "$thread"` the
      * step reads what an earlier `lookup` fetched.
@@ -217,6 +196,8 @@ export interface ParallelStep<S = Step> {
     onBranchError?: "fail" | "continue";
 }
 export type Step = ConditionStep | ForEachStep | ParallelStep | LookupStep | ActionStep | ClassifyStep | GenerateStep | AgentStep | WaitForReplyStep | WaitForTaskStep;
+/** Every step type, once. The `satisfies` pair fails to compile when a type is added or dropped. */
+export declare const STEP_TYPES: readonly ["condition", "for-each", "parallel", "lookup", "action", "classify", "generate", "agent", "wait-for-reply", "wait-for-task"];
 /**
  * A **procedure**: how a scenario is handled, as prose with guardrails. The second execution
  * form next to `Step[]`; {@link AgentStep} is its inside-a-flow variant (it *contains* one).
@@ -477,6 +458,11 @@ export interface PlaybookRun {
     subjectKind?: string;
     subjectId?: string;
     status: RunStatus;
+    /**
+     * The autonomy this run started with ({@link resolveAutonomy}), frozen: a resume after an
+     * approval runs at the same setting it parked with. Absent on runs from before this field.
+     */
+    autonomy?: Autonomy;
     /**
      * The cause: which signal started this run, plus the input as it looked **then**.
      *
@@ -522,6 +508,12 @@ export interface PlaybookRun {
     }[] | null;
     /** The AI_ACTION_PROPOSED activity created for the current pending batch (for resolve on approve/reject). */
     proposalActivityId?: string | null;
+    /** The approval request a parked run waits on (`runApprovalKey`). */
+    approvalRequestId?: string | null;
+    /** Every request this park waits on, one per distinct act; resumes when all are approved. */
+    approvalRequestIds?: string[];
+    /** The move an assignment turn chose before it parked; restored when the turn resumes. */
+    turnControl?: AssignmentControl | null;
     /**
      * What this run waits for, when `status === "waiting"`. `null` when cleared (the store
      * writes `null`), absent on a run that is not waiting. A new wait reason costs a member in

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

@@ -67,9 +67,14 @@ export interface ReactionChange {
     actor: ReactionActor;
     /** `true` put it there, `false` took it away. */
     on: boolean;
+    /**
+     * The signed-in user who clicked. Absent when an app wrote it (a provider sync carrying a
+     * Teams emoji across), so a listener that syncs out never echoes a mirrored reaction back.
+     */
+    byUser?: string;
 }
 /**
- * The `reactions:changed` event, as apps receive it (`communication:reactions:changed`).
+ * The `reactions:changed` event, as apps receive it (`context:reactions:changed`).
  *
  * Carries **both** the resulting chip set and the delta, because the two consumers need
  * different things. A feed re-renders from `reactions` — a client that only got deltas and

package/dist/entities/rule/bind.d.ts

@@ -1,8 +1,23 @@
 /**
- * Fill `{{path}}` references in action params from what the rule saw (`{ event, subject }`).
+ * One variable language for rules and playbooks: `{{path}}`.
  *
- * A param that is *only* a reference keeps the referenced value's type (`"{{subject.id}}"` → the
- * id, a number stays a number); a reference inside longer text is stringified. An unresolvable
- * path becomes `""` — the same "empty is not an instruction" the tools already read.
+ * A value that is *only* a reference keeps the referenced value's type (`"{{subject.id}}"` → the
+ * id, a number stays a number); a reference inside longer text is stringified, objects as JSON.
+ * `{ "var": "path" }` in a condition is json-logic's own and not handled here.
+ *
+ * What an unknown reference becomes is the executor's call:
+ * - `"empty"` (rules): `""` — the same "empty is not an instruction" the tools already read;
+ * - `"throw"` (playbooks): an error when the path's **root** is not there (a typo, or a step that
+ *   never ran). A known root with an empty leaf stays empty: a chat message has no `subject`, and
+ *   that is not a mistake.
  */
-export declare function bindParams(params: Record<string, unknown>, context: Record<string, unknown>): Record<string, unknown>;
+export interface BindOptions {
+    onMissing?: "empty" | "throw";
+    /** Where the value sits, for the error message. */
+    where?: string;
+}
+export declare class UnresolvedRefError extends Error {
+    constructor(message: string);
+}
+export declare function bindParams(params: Record<string, unknown>, context: Record<string, unknown>, options?: BindOptions): Record<string, unknown>;
+export declare function bindValue(value: unknown, context: Record<string, unknown>, options?: BindOptions): unknown;

package/dist/entities/rule/outcome.d.ts

@@ -19,6 +19,8 @@ export interface OutcomePrior {
     params: Record<string, unknown>;
     /** Which params were content — a field the subject owns — rather than addressing. */
     fields: string[];
+    /** Fields the tool reported writing with a value it chose itself (`AiToolResult.wrote`). */
+    wrote?: Record<string, unknown>;
 }
 /**
  * Which fields no longer hold what the action put there.

package/dist/entities/rule/trigger-source.d.ts

@@ -1,4 +1,5 @@
 import { ToolCatalogEntry } from '../../platform/ai-tools';
+import { RuleTemplate } from './types';
 /**
  * What kind of value sits at a field, so the builder knows which widget to draw and the
  * comparison operators that make sense.
@@ -79,16 +80,15 @@ export interface EventDescriptor {
     name: string;
     /** What this event is, in the author's language: "Er komt een bericht binnen". */
     label: string;
-    /**
-     * What the subject is. Also the key the undo reader uses to fetch current state, so a new
-     * subject kind needs a reader there before its runs can be undone.
-     */
+    /** What the subject is, for the builder. The run itself records the subject's scope kind. */
     subjectKind: string;
     fields: EventField[];
 }
 /** What a `trigger-source` returns on `GET /provider/triggers/describe`. */
 export interface TriggerSourceDescription {
     events: EventDescriptor[];
+    /** Rules to start from, on this app's own events. */
+    templates?: RuleTemplate[];
 }
 /** An event plus the app that answered for it — the merged catalog a builder reads. */
 export interface VocabularyEvent extends EventDescriptor {

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

@@ -5,8 +5,9 @@ import { OutcomePrior, RunOutcome } from './outcome';
  *
  * There were five of these, and they had to agree without anything saying so: `PlaybookTrigger`,
  * `webhook.triggers[]` (four fixed strings), the sync tick, and twenty-one hand-rolled cron jobs.
+ * Playbooks now run a subset of this union (`PlaybookTrigger`); webhooks store `event` names.
  *
- * **Four arms, not five.** `stream` is deliberately absent. It existed once, as a field-less
+ * **No `stream` arm.** `stream` is deliberately absent. It existed once, as a field-less
  * `{ kind: "stream" }` on `PlaybookTrigger`, and was removed with a reason that generalises:
  * *"Definitions belong separated by their runtime, not by their editor."* A live read lane has no
  * run, no lock and no gate, so it is not an automation with a trigger — it is its own thing
@@ -27,18 +28,42 @@ export type Trigger =
  | {
     kind: "manual";
 }
-/** Work was handed to an agent. `targetKind` is declared by the app that owns that work. */
+/**
+ * Work was handed to an agent. `targetKind` is declared by the app that owns that work
+ * (`assignment-source` federation, see `playbook/assignment.ts`); which agent is answered by
+ * `Playbook.agentId`, not here.
+ */
  | {
     kind: "assignment";
     targetKind: string;
+}
+/**
+ * A message appears: these activity types, optionally on these channel kinds or ids, passing
+ * `filter` (JSONLogic). Its own arm rather than an `event` with a filter, so the editor keeps
+ * its pickers instead of an expression.
+ */
+ | {
+    kind: "activity";
+    activityTypes: string[];
+    /** Channel kinds: "mail" | "chat" | "voice" (derived from the activity type). */
+    channels?: string[];
+    /** Specific channel ids (e.g. per mailbox). Matched against activity.channelId. */
+    channelIds?: string[];
+    filter?: unknown;
+    /**
+     * Wait this many milliseconds, then run **once** for the messages in that window instead
+     * of once per message, on the newest one. Deliberately on the trigger: coalescing is
+     * "how often do I react", not what you remember.
+     */
+    debounceMs?: number;
 };
 /**
  * One thing a rule does.
  *
- * **`action` is always `tool:<namespaced>`.** The action library is the tool federation — the
+ * **`action` is `<app>__<tool>`** — the action library is the tool federation, the
  * same 62 descriptors the assistant uses, with the model taken out from in front. A second
  * library would duplicate what a descriptor already carries: a JSON-Schema, a scope gate, an
- * `effect` classification and an approval hook.
+ * `effect` classification and an approval hook. Playbooks spell it the same.
  */
 export interface RuleAction {
     action: string;
@@ -145,3 +170,21 @@ export interface RuleRun extends RuleRunRecord {
     outcomeAt?: number;
     createdAt?: number;
 }
+/**
+ * A rule an organisation can start from, declared by the app whose event it listens to.
+ *
+ * Data, not rows seeded on install: an organisation that never opens the builder should not
+ * acquire automation it did not ask for. Installing one is a normal create, so it lands disabled
+ * and passes the same save-time gate as anything a person writes.
+ */
+export interface RuleTemplate {
+    id: string;
+    name: string;
+    description: string;
+    /** What the author still has to fill in. Named, so the form can ask instead of guessing. */
+    blanks: {
+        path: string;
+        label: string;
+    }[];
+    rule: Pick<Rule, "trigger" | "when" | "then">;
+}

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

@@ -7,10 +7,5 @@ import { OwnerScope } from './types';
  * carries an id on one side and not on the other. This is that translation, and it is
  * meant to be the only one: a hand-rolled `kind === "personal" ? "user" : …` at a call
  * site is how two vocabularies for the same three rungs drift apart.
- *
- * It arrived as `playbookActor` in `entities/playbook/`, whose own docstring already
- * claimed to be "the only place this belongs" — correct, but it read as
- * playbook-specific while every scoped entity needs the same conversion. `playbookActor`
- * stays as a name so the playbook call sites and their tests keep working.
  */
 export declare function toActingIdentity(scope: OwnerScope): ActingIdentity;

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

@@ -50,7 +50,7 @@ export interface SlaTarget {
 }
 /**
  * A named set of service targets. Assigned to a resource explicitly — from a workflow rule
- * (`tool:context__apply_sla`) or by hand — never matched automatically. That is why there is
+ * (`context__apply_sla`) or by hand — never matched automatically. That is why there is
  * no `appliesTo` and no `order`: both only exist to drive a matcher nothing calls.
  */
 export interface SlaProfile {

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

@@ -5,7 +5,13 @@
  */
 export type WebhookMethod = "POST" | "PUT";
 export type WebhookContentType = "json" | "multipart";
-export type WebhookTrigger = "interactions:created" | "interactions:updated" | "activities:created" | "activities:updated";
+/**
+ * The bus events a webhook can listen to — full names, the same string as a rule's
+ * `Trigger.event.name`. Add one here and the automations app subscribes to it.
+ */
+export declare const WEBHOOK_EVENTS: readonly ["communication:interactions:created", "communication:interactions:updated", "communication:activities:created", "communication:activities:updated"];
+export type WebhookTrigger = (typeof WEBHOOK_EVENTS)[number];
+export declare function isWebhookEvent(value: unknown): value is WebhookTrigger;
 export interface Webhook {
     id: string;
     organizationId: string;