@opencxh/domain 1.255.0 → 1.257.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,65 @@
+import { Autonomy } from '../playbook/types';
+/**
+ * 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";
+    }[];
+    /**
+     * Does this colleague act, or propose and wait for a human?
+     *
+     * Absent = `"suggest"`, fail-closed. On the agent because it is the plainest mandate there is,
+     * and because it has to be settable for work that has no playbook: an assignment someone typed
+     * took its autonomy from the shared "Assist" playbook, which is gone. A triggered assignment
+     * still follows its playbook — that is where an organisation configured that scenario.
+     */
+    autonomy?: Autonomy;
+    /**
+     * 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-message/types.d.ts

@@ -1,5 +1,6 @@
 import { AIAttachment, RejectedAIAttachment } from '../../platform/ai-attachments';
 import { ToolTraceEntry } from '../../platform/ai-tools';
+import { UserType } from '../user/types';
 export interface AIMessageInput {
     text: string;
     type: "text";
@@ -48,6 +49,37 @@ export interface AIMessage {
     output: AIMessageOutput;
     accountId?: string;
     model?: string;
+    /**
+     * The brain that produced this turn. `accountId` + `model` said *what* answered and never
+     * *who*, so "which profile wrote this" was unanswerable after the fact — and a profile people
+     * edit is exactly the thing you want to look back at when an answer was wrong.
+     *
+     * Absent on a row nobody's brain produced: a human writing in an assignment thread.
+     */
+    profileId?: string;
+    /** The agent whose turn this was, when it was an agent's. Absent for the assistant. */
+    agentId?: string;
+    /**
+     * Who put this row in the thread, when it was somebody rather than the assistant.
+     *
+     * **The shape `getUserProfile` returns**, deliberately: `type` is the existing answer to
+     * "human or agent" ({@link UserType}) and inventing a second author vocabulary for one screen
+     * is how this codebase ended up asking "is this a message?" in six places.
+     *
+     * Why it has to be stored: an answer from a colleague-agent arrives as `sender: "user"` — it
+     * *is* the user turn of the next model call — so after a reload it read exactly like an
+     * instruction from the person who gave the assignment. The difference between material to
+     * weigh and an order to follow lived only in the wake note, which is not persisted.
+     *
+     * `type` is required here even though it is optional on a user record: every writer of this
+     * field knows which of the two it is, and "unknown" is precisely the answer that would make
+     * the field pointless.
+     */
+    author?: {
+        id: string;
+        name: string;
+        type: UserType;
+    };
     externalId?: string;
     /** Tools the assistant invoked while producing this message (final, persisted trace). */
     toolTrace?: ToolTraceEntry[];

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

@@ -49,16 +49,25 @@ export interface Assignment {
     organizationId: string;
     /** The agent doing this: the `userId` of a user with `type: "agent"`. */
     agentId: string;
-    /** The definition this assignment came from (a playbook with a procedure). */
-    jobId: string;
     /**
-     * The version it started on — purely for the audit.
+     * The playbook this assignment came from, when a trigger put it down. **Absent when someone
+     * typed it**, which is the common case in Assist.
+     *
+     * It used to be required, so a typed request had to invent a definition to be allowed to exist:
+     * one org-wide "Assist" playbook with an empty procedure, created on first use and rewritten on
+     * every start and every delegation. A shared mutable row behind a foreign key — and a turn read
+     * its agent off it, so one delegation could hand every other running assignment to a different
+     * agent. The row is gone; what a typed assignment needs, it now carries itself.
+     */
+    jobId?: string;
+    /**
+     * The version it started on — purely for the audit. Absent with {@link Assignment.jobId}.
      *
      * Every **turn** pins its own procedure (`run.decider`), so improved prose arrives on the next
      * turn without a running turn switching instructions mid-flight. Pinning forever would mean a
      * correction never arrives; not pinning would mean a turn changes halfway.
      */
-    jobVersion: number;
+    jobVersion?: number;
     /** What this assignment is about. Absent = work without a resource (a rollup, a chore). */
     subjectKind?: string;
     subjectId?: string;
@@ -79,6 +88,29 @@ export interface Assignment {
      * triggered one may not. The list needs to tell them apart, so it is stored.
      */
     origin?: "trigger" | "user";
+    /**
+     * Allowed tools for this assignment, narrowing-only against the agent's brain — the same rule
+     * `Procedure.tools` carries. Absent = whatever the brain allows.
+     *
+     * `POST assignment/start` has always accepted and validated this, and then dropped it on the
+     * floor: there was nowhere to put it, because the bounds lived on the shared playbook that
+     * every assignment in the organisation had to share.
+     */
+    tools?: string[];
+    /**
+     * 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 +255,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/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"];
@@ -428,8 +439,13 @@ export type StartedBy =
 export interface PlaybookRun {
     id: string;
     organizationId: string;
-    playbookId: string;
-    playbookVersion: number;
+    /**
+     * The definition this run is of. **Absent on a turn of a typed assignment**: that work has no
+     * playbook, and inventing one so this column could stay required is exactly what the shared
+     * "Assist" row was.
+     */
+    playbookId?: string;
+    playbookVersion?: number;
     /**
      * The assignment this is a **turn** of, if any. Absent = a standalone execution (an
      * automation that fires and is done). Present = one move in work that outlives this run,

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;