@opencxh/domain 1.254.0 → 1.256.0

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

@@ -5,7 +5,7 @@ import { ReactionSummary } from '../reaction/types';
 export type CallStatus = "new" | "connecting" | "ringing" | "connected" | "held" | "ended" | "failed";
 export type CallDirection = "inbound" | "outbound";
 export type CallType = "audio" | "video" | "data" | "screen-share";
-export type ActivityType = "VOICE_CALL_STARTED" | "VOICE_CALL_ANSWERED" | "VOICE_CALL_HOLD" | "VOICE_CALL_UNHOLD" | "VOICE_CALL_ENDED" | "VOICE_CALL_MISSED" | "VOICE_CALL_VOICEMAIL" | "VIDEO_CALL_STARTED" | "VIDEO_CALL_ANSWERED" | "VIDEO_CALL_HOLD" | "VIDEO_CALL_UNHOLD" | "VIDEO_CALL_ENDED" | "VIDEO_CALL_MISSED" | "EMAIL_RECEIVED" | "EMAIL_SENT" | "CHAT_MESSAGE_SENT" | "CHAT_MESSAGE_RECEIVED" | "CHAT_MEMBER_JOINED" | "CHAT_MEMBER_LEFT" | "CHAT_RENAMED" | "CHAT_CALL_STARTED" | "CHAT_CALL_ENDED" | "CHAT_EVENT" | "AI_MESSAGE_ADDED" | "AI_ACTION_PROPOSED" | "PLAYBOOK_STARTED" | "PLAYBOOK_COMPLETED" | "PLAYBOOK_ESCALATED" | "MEETING_SCHEDULED" | "MEETING_STARTED" | "MEETING_ENDED" | "MEETING_PARTICIPANT_JOINED" | "MEETING_PARTICIPANT_LEFT" | "COMMENT_ADDED" | "FILE_UPLOADED" | "INTERACTION_CREATED" | "INTERACTION_STATUS_CHANGED" | "INTERACTION_ASSIGNED" | "SLA_BREACHED" | "VOICE_CALL_FAILED" | "VIDEO_CALL_FAILED" | "TRANSCRIPT_ADDED" | "WORK_COMMENT_ADDED" | "WORK_ITEM_ASSIGNED" | "WORK_ITEM_STATUS_CHANGED";
+export type ActivityType = "VOICE_CALL_STARTED" | "VOICE_CALL_ANSWERED" | "VOICE_CALL_HOLD" | "VOICE_CALL_UNHOLD" | "VOICE_CALL_ENDED" | "VOICE_CALL_MISSED" | "VOICE_CALL_VOICEMAIL" | "VIDEO_CALL_STARTED" | "VIDEO_CALL_ANSWERED" | "VIDEO_CALL_HOLD" | "VIDEO_CALL_UNHOLD" | "VIDEO_CALL_ENDED" | "VIDEO_CALL_MISSED" | "EMAIL_RECEIVED" | "EMAIL_SENT" | "CHAT_MESSAGE_SENT" | "CHAT_MESSAGE_RECEIVED" | "CHAT_MEMBER_JOINED" | "CHAT_MEMBER_LEFT" | "CHAT_RENAMED" | "CHAT_CALL_STARTED" | "CHAT_CALL_ENDED" | "CHAT_EVENT" | "AI_MESSAGE_ADDED" | "AI_ACTION_PROPOSED" | "PLAYBOOK_STARTED" | "PLAYBOOK_COMPLETED" | "PLAYBOOK_ESCALATED" | "AGENT_DELEGATED" | "AGENT_ANSWERED" | "MEETING_SCHEDULED" | "MEETING_STARTED" | "MEETING_ENDED" | "MEETING_PARTICIPANT_JOINED" | "MEETING_PARTICIPANT_LEFT" | "COMMENT_ADDED" | "FILE_UPLOADED" | "INTERACTION_CREATED" | "INTERACTION_STATUS_CHANGED" | "INTERACTION_ASSIGNED" | "SLA_BREACHED" | "VOICE_CALL_FAILED" | "VIDEO_CALL_FAILED" | "TRANSCRIPT_ADDED" | "WORK_COMMENT_ADDED" | "WORK_ITEM_ASSIGNED" | "WORK_ITEM_STATUS_CHANGED";
 export interface Attachment {
     id: string;
     filename: string;
@@ -299,6 +299,24 @@ export type PlaybookLifecyclePayload = {
     /** Who the run acted for; saves the UI from fetching the playbook again. */
     actor?: ActingIdentity;
 };
+/**
+ * One agent asking another, and the answer coming back — the two markers that make delegation
+ * visible on the timeline instead of only inside a second thread.
+ *
+ * Extends the playbook lifecycle payload rather than standing beside it, because these *are*
+ * playbook-authored markers: they carry the same `runId` that damps re-triggering, and every
+ * reader that already handles a lifecycle marker handles these unchanged.
+ */
+export type AgentDelegationPayload = PlaybookLifecyclePayload & {
+    /** The agent that asked. */
+    fromAgentName: string;
+    /** The agent that was asked. Absent on the answer, where `fromAgentName` is the answerer. */
+    toAgentName?: string;
+    /** The sub-question, as the delegating agent wrote it. Trimmed for the timeline. */
+    ask?: string;
+    /** The delegated assignment, so the UI can link to its thread. */
+    assignmentId?: string;
+};
 export type Activity = (BaseActivity & {
     type: "VOICE_CALL_STARTED";
     payload: VoiceCallPayload;
@@ -392,6 +410,12 @@ export type Activity = (BaseActivity & {
 }) | (BaseActivity & {
     type: "PLAYBOOK_ESCALATED";
     payload: PlaybookLifecyclePayload;
+}) | (BaseActivity & {
+    type: "AGENT_DELEGATED";
+    payload: AgentDelegationPayload;
+}) | (BaseActivity & {
+    type: "AGENT_ANSWERED";
+    payload: AgentDelegationPayload;
 }) | (BaseActivity & {
     type: "MEETING_SCHEDULED";
     payload: MeetingPayload;

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

@@ -0,0 +1 @@
+export * from './types';

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

@@ -0,0 +1,55 @@
+/**
+ * An **agent**: a digital colleague. A profile plus an identity plus a mandate.
+ *
+ * **Why this is its own record, next to the user row and the profile.** Those two already
+ * existed and pointed at each other: `User.profileId` said which brain, `Playbook.agentId` said
+ * which agent, and nothing related them — `agentId: Alice` running on Bob's brain was a valid
+ * configuration, and did happen (see `agent/brain.ts` in the ai app). One record ends that.
+ *
+ * **`id` is the user id.** Not a `userId` column beside a generated key: an agent *is* that user
+ * (that is what gives it a real identity — fail-closed authorization, its own name on the
+ * timeline, team membership, its own budget), so a second identifier would only be a second thing
+ * that can disagree. Every `agentId` in this codebase is therefore also this row's id.
+ *
+ * **What is deliberately not here.** The name lives on the user row, because that is what every
+ * timeline, mention list and assignee picker already reads; duplicating it would let two places
+ * disagree about what an agent is called.
+ */
+export interface Agent {
+    /** The agent's user id. See above: there is no second identifier. */
+    id: string;
+    organizationId: string;
+    /** The brain: the `AIProfile` this agent thinks with. */
+    profileId: string;
+    /**
+     * What this agent is for, in one line.
+     *
+     * **On the agent, not on the profile.** Another agent reads this line to decide whether to call
+     * this one in ({@link Agent.delegateTo}), so it has to describe *this colleague* — and two
+     * agents sharing the Support profile are two different colleagues. It used to be
+     * `AIProfile.description`, which gave them the same blurb.
+     */
+    description?: string;
+    /**
+     * Per-tool confirmation policy: which of this agent's tools count as a write.
+     *
+     * Moved off the profile because it is a mandate, not expertise: the same Support brain may be
+     * trusted to send in one agent's hands and only to propose in another's. Under autonomy
+     * "suggest" write tools are held for approval; reads run freely. A tool absent from this list
+     * defaults to "write" (safe).
+     */
+    toolPolicy?: {
+        name: string;
+        policy: "read" | "write";
+    }[];
+    /**
+     * Which colleagues this agent may call in for a sub-question (agent ids).
+     *
+     * **Opt-in**: absent and `[]` both mean none. Who you may wake is a permission, and a default
+     * of "everyone" would make every new agent reachable by every other one the moment it exists.
+     *
+     * Moved off the profile for the reason the whole record exists: this is a relation *between
+     * agents*, and storing it on a shared brain gave two agents one delegate list.
+     */
+    delegateTo?: string[];
+}

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

@@ -27,32 +27,24 @@ export interface AIProfile<T extends Record<string, any> = Record<string, any>>
     systemPrompt?: string;
     contextIds?: string[];
     predefinedPrompts?: PredefinedPrompt[];
-    /** Namespaced tool names this profile may use (default: none enabled). */
-    enabledTools?: string[];
     /**
-     * Per-tool confirmation policy, stored as a LIST (not a keyed map). It sits on existing profile
-     * rows with a form on top, and a migration to a map would only yield a nicer shape;
-     * `enabledTools` next to it is a list too.
-     *
-     * Under autonomy "suggest", write tools are held for approval; reads run freely. A tool absent
-     * from this list defaults to "write" (safe).
-     *
-     * **Where this does and does not apply.** Enforced in `playbook/ai/gate.ts`, and thereby on
-     * every autonomous run (workflow or procedure). The interactive assistant does **nothing** with
-     * it: there is no confirmation step there. So a `write` marking you expect to enforce in a chat
-     * conversation does nothing.
+     * Namespaced tool names this profile may use (default: none enabled).
      *
-     * That is an open gap and not a design choice: a confirmation step in the chat is UI plus an
-     * extra round, and should be a decision rather than a field that silently does nothing.
+     * Expertise, not mandate: *what this brain knows how to do*. Whether a given agent is trusted
+     * to actually use a write tool is `Agent.toolPolicy`, and which colleagues it may call in is
+     * `Agent.delegateTo` — both moved off this record, because two agents can share one brain and
+     * still not be trusted with the same things.
      */
-    toolPolicy?: {
-        name: string;
-        policy: "read" | "write";
-    }[];
+    enabledTools?: string[];
     /**
-     * Whether the acting user's PERSONAL MCP tools (their own per-user connections)
-     * are available on this profile, on top of the admin-curated `enabledTools`.
-     * "off" (default) = strictly the curated set; "allow" = also include personal.
+     * Whether the acting user's PERSONAL MCP tools (their own per-user connections) are available
+     * on top of the admin-curated `enabledTools`. "off" (default) = strictly the curated set.
+     *
+     * **Stays on the profile while `toolPolicy` and `delegateTo` moved to `Agent`**, because this
+     * one is only ever true of the interactive assistant: there a person is typing and the tools
+     * are their own. An autonomous run has no watching user, so borrowing someone's token is never
+     * the intent — `resolveToolset` passes `SYSTEM_TOOL_POLICY` and this field is dead on that
+     * path. Putting it on the agent would have made it a setting that cannot do anything.
      */
     personalTools?: "off" | "allow";
 }

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

@@ -79,6 +79,20 @@ export interface Assignment {
      * triggered one may not. The list needs to tell them apart, so it is stored.
      */
     origin?: "trigger" | "user";
+    /**
+     * The assignment that delegated this one, when an agent asked a colleague-agent a sub-question.
+     * The return address: `applyTurn` reports back here the moment this assignment goes terminal.
+     */
+    delegatedFrom?: string;
+    /**
+     * The agent ids from the root of the delegation chain down to and including this assignment's
+     * own agent.
+     *
+     * **One field, two gates.** Its length is the depth and `includes()` is the cycle check — see
+     * {@link delegationRefusal}. A separate `depth` counter beside a chain would be a second source
+     * of truth for the same fact.
+     */
+    delegationChain?: string[];
     status: AssignmentStatus;
     /**
      * What the **assignment** is waiting on between two turns.
@@ -223,3 +237,26 @@ export declare function decideAssignmentState(control: AssignmentControl | undef
     turns: number;
     reason?: string;
 };
+/**
+ * How many **hops** one delegation chain may make. A → B is one hop, A → B → C is two.
+ *
+ * Two, not more: "ask a colleague who asks their colleague" is the last chain that still has an
+ * owner anyone can name. Every extra level multiplies the turn ceiling by twelve for work nobody
+ * asked for.
+ */
+export declare const MAX_DELEGATION_DEPTH = 2;
+/**
+ * Why this agent may **not** delegate to that one — or `null` when it may.
+ *
+ * Pure, so the rule is testable without a Bridge, and the same shape as `decideAssignmentState`
+ * beside it.
+ *
+ * **A reason, not a boolean.** The string goes back to the model as the tool's error, so it can
+ * pick another route instead of retrying the same refused call. `toolsOutsideBrain` in the ai app
+ * does the same for the same reason.
+ *
+ * @param chain  The calling assignment's {@link Assignment.delegationChain}; absent = root.
+ * @param allowed The calling agent's `delegateTo`. `undefined` and `[]` both mean **none**:
+ *                delegation is opt-in, unlike `enabledTools` where absent means "no filter".
+ */
+export declare function delegationRefusal(chain: string[] | undefined, targetAgentId: string, callerAgentId: string, allowed: string[] | undefined): string | null;

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

@@ -45,12 +45,15 @@ export declare const TRIGGER_VARS: readonly [{
 }, {
     readonly name: "fromStatus";
     readonly type: "string";
+    readonly onlyFor: readonly ["INTERACTION_STATUS_CHANGED"];
 }, {
     readonly name: "toStatus";
     readonly type: "string";
+    readonly onlyFor: readonly ["INTERACTION_STATUS_CHANGED"];
 }, {
     readonly name: "toCategory";
     readonly type: "string";
+    readonly onlyFor: readonly ["WORK_ITEM_STATUS_CHANGED"];
 }, {
     readonly name: "contactId";
     readonly type: "string";
@@ -70,6 +73,14 @@ export declare const TRIGGER_VARS: readonly [{
     readonly name: "assigneeUserId";
     readonly type: "string";
 }];
+/**
+ * Does this trigger fill that variable? A trigger listing no activity types matches
+ * everything, which is also what the engine does with it.
+ */
+export declare function triggerFillsVar(variable: {
+    name: string;
+    onlyFor?: readonly string[];
+}, activityTypes: readonly string[] | undefined): boolean;
 /**
  * What a classify step **yields** per mode — the contract `runClassify` honours.
  *

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

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

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

@@ -355,6 +355,17 @@ export type WaitingOn = {
 } | {
     on: "task";
     taskId: string;
+}
+/**
+ * Another agent is working on a sub-question; its terminal status is the signal.
+ *
+ * Deliberately quiet: `wakesAssignment` rule 5 only lets a plain internal note through while
+ * waiting on a `"reply"`, so an assignment parked on an agent is woken by that agent's answer
+ * or by an explicit mention — not by every colleague passing by.
+ */
+ | {
+    on: "agent";
+    assignmentId: string;
 };
 /** Terminal states: a run does not leave these on its own. */
 export declare const TERMINAL_RUN_STATUSES: readonly ["done", "escalated", "failed", "stopped"];

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

@@ -9,6 +9,10 @@
  * audit loses it.
  *
  * Absent means `"user"`: existing rows are humans, and the mirror is not backfilled.
+ *
+ * This flag is all the user record knows about being an agent. The brain and the mandate live on
+ * `Agent` in the ai app, keyed by this user's id — the ai configuration used to sit here as
+ * `profileId`, which made user management carry agent behaviour and gave one fact two homes.
  */
 export type UserType = "user" | "agent";
 /**
@@ -27,15 +31,6 @@ export interface UserProfile {
     displayName?: string;
     avatarUrl?: string;
     type?: UserType;
-    /**
-     * An agent's brain, when this is an agent — see {@link User.profileId}.
-     *
-     * Belongs on this compact record and not only on the full one: "is this an agent" is already
-     * here (`type`), and "with which brain" is the immediate follow-up of every caller handing it
-     * work. Without this field the ai app had to use the admin route — the whole record plus an RPC
-     * to `system.rbac` — to learn one id.
-     */
-    profileId?: string;
 }
 /** Is this user an agent? An absent type = human. */
 export declare function isAgentUser(user: {
@@ -53,8 +48,6 @@ export interface User {
      * not own it. Everything that needs to know "is this a human" reads this field.
      */
     type?: UserType;
-    /** An agent's brain: the `AIProfile` it works with. Only set when `type === "agent"`. */
-    profileId?: string;
     /** Mirrored from system.users. */
     firstName?: string;
     lastName?: string;