@company-semantics/contracts 62.11.0 → 63.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.11.0",
+  "version": "63.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -181,5 +181,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "2dcea336317c1136c8d94798b1cadc9c115febf574d041a173974a5f7959de0b"
+  "securityRequirementsVersion": "b5085eaa2fcf9fee09a3c8d2a9e15eab119800def73c98dc6ab6937d1c6e07b2"
 }

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '9829bca605e4' as const;
-export const SPEC_HASH_FULL = '9829bca605e4a464d73b067d1d063d2a68c5871b9fae570470a43987e481bb3a' as const;
+export const SPEC_HASH = '387045558d18' as const;
+export const SPEC_HASH_FULL = '387045558d1867722a744ddb05cf5ebb7260c54df0ff272b868bd4dd2ad2a973' as const;

package/src/api/generated.ts

@@ -4079,6 +4079,19 @@ export interface components {
                 sequenceNumber: number;
                 /** Format: date-time */
                 createdAt: string;
+                mentions: {
+                    target: {
+                        /** @constant */
+                        kind: "user";
+                        userId: string;
+                    } | {
+                        /** @constant */
+                        kind: "agent";
+                    };
+                    startOffset: number | null;
+                    endOffset: number | null;
+                    displayName: string;
+                }[];
             }[];
         };
         SuccessResponse: {
@@ -4360,6 +4373,11 @@ export interface components {
             /** @enum {string} */
             origin?: "user" | "proactive";
             launch: {
+                /** @constant */
+                kind: "structure-review";
+                /** Format: uuid */
+                proposalId: string;
+            } | {
                 /** @constant */
                 kind: "workflow";
                 /** Format: uuid */
@@ -6948,12 +6966,19 @@ export interface components {
                 insertedText?: string;
             };
             body?: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The written reply, and whether it auto-reopened a resolved thread. */
         CommentReplyResponse: {
@@ -6962,12 +6987,19 @@ export interface components {
         };
         CommentReplyRequest: {
             body: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The comment after the mutation (redacted projection after delete). */
         CommentResponse: {
@@ -6975,12 +7007,19 @@ export interface components {
         };
         EditCommentRequest: {
             body: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The thread after a resolve/reopen transition. */
         CommentThreadSummaryResponse: {
@@ -7013,7 +7052,14 @@ export interface components {
         };
         /** @description A principal who can read the document and may therefore be mentioned. */
         CompanyMdMentionableCandidate: {
-            userId: string;
+            principal: {
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            };
             displayName: string;
             avatarUrl: string | null;
         };
@@ -7094,6 +7140,29 @@ export interface components {
             /** @enum {string} */
             kind: "comment" | "suggestion";
             suggestion: components["schemas"]["Suggestion"] | null;
+            origin: {
+                /** @constant */
+                kind: "comment";
+            } | {
+                /** @constant */
+                kind: "doc_mention";
+                byUser: ({
+                    /** @constant */
+                    kind: "user";
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "agent";
+                }) | null;
+                introducedAt: string;
+            };
+            agentOutcomes: {
+                triggerId: string;
+                /** @enum {string} */
+                status: "pending" | "replied" | "unanswered";
+                reason: ("replies_off" | "mentioner_unavailable" | "delegate_unknown" | "subject_unreadable" | "rate_capped" | "turn_failed") | null;
+                replyCommentId: string | null;
+            }[];
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
@@ -7142,16 +7211,30 @@ export interface components {
         Comment: {
             id: string;
             threadId: string;
-            authorUserId: string | null;
+            author: ({
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            }) | null;
             body: string | null;
             editedAt: string | null;
             deletedAt: string | null;
             createdAt: string;
             mentions: components["schemas"]["CommentMention"][];
         };
-        /** @description One mention on a comment: the mentioned user id, its zero-based exclusive-end UTF-16 range (null until the offset columns exist), and the display name resolved at read time. */
+        /** @description One mention on a comment: the principal mentioned, its zero-based exclusive-end UTF-16 range (null until the offset columns exist), and the display name resolved at read time. */
         CommentMention: {
-            userId: string;
+            target: {
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            };
             startOffset: number | null;
             endOffset: number | null;
             displayName: string;
@@ -7178,6 +7261,29 @@ export interface components {
             /** @enum {string} */
             kind: "comment" | "suggestion";
             suggestion: components["schemas"]["Suggestion"] | null;
+            origin: {
+                /** @constant */
+                kind: "comment";
+            } | {
+                /** @constant */
+                kind: "doc_mention";
+                byUser: ({
+                    /** @constant */
+                    kind: "user";
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "agent";
+                }) | null;
+                introducedAt: string;
+            };
+            agentOutcomes: {
+                triggerId: string;
+                /** @enum {string} */
+                status: "pending" | "replied" | "unanswered";
+                reason: ("replies_off" | "mentioner_unavailable" | "delegate_unknown" | "subject_unreadable" | "rate_capped" | "turn_failed") | null;
+                replyCommentId: string | null;
+            }[];
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;

package/src/chat/README.md

@@ -24,6 +24,13 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - Page context carries NO ORG IDENTITY, though the app's org routes have one in the URL. Org scope is derived from the session; a request-supplied org identifier would be an authority claim in a field the server otherwise reads for itself
 - `compactedThroughSequence` on the chat detail is ABSENT or NULL exactly when the conversation has never been compacted. It is never coerced to `0` — sequence numbers are zero-indexed, so `0` is a boundary a chat can really have, and a zero default would make "never compacted" indistinguishable from "compacted through sequence 0". It is optional for the same reason `proactiveKind` is a bare string: a client that does not know the field renders the transcript exactly as before (ADR-CONTRACTS-154)
 - `compactedThroughSequence` is a BOUNDARY MARKER, not a context gauge. It is the one sequence number the summary covers through — never a token count, never a percentage of the context window, and never the summary text itself. The reader's question it answers is "why did it forget the beginning", not "how full is the window" (ADR-CONTRACTS-154)
+- `mentions` on a chat message is REQUIRED, and an empty array is the common value. Absent is not the same as empty — this shipped in a MAJOR precisely so no consumer keeps a second opinion about which one it holds. Contrast the proactive wire fields above, which are optional so consumer object literals survive a minor (ADR-CONTRACTS-160)
+- A mention TARGET is a `PrincipalRef`, never a user id, so the agent — which has no users row to point at — is a legal mention target on the chat surface exactly as on a comment (ADR-CONTRACTS-160)
+- Chat mention offsets are ZERO-BASED UTF-16 CODE UNITS into the exact `content` string with `endOffset` EXCLUSIVE, and no Unicode normalization happens anywhere on the path — the same convention as `CommentMention`, because a mention means the same thing on both surfaces. An astral character counts as TWO units
+- Chat mention offsets are NULLABLE and null means "mentioned somewhere in this turn, highlight nothing", never an error. A user turn carries a real range; an assistant turn's mention is a typed part with no character range, and the nullability is what lets that land with no second schema
+- Identity on a chat mention renders from the mention ROW, never from the content characters under the range. A stale range can only mis-highlight; it can never misattribute
+- `SharedChatMessage` deliberately has NO mentions. The token-only share viewer is granted the CONTENT of a shared chat and nothing else; a mention row is identity, and identity is not in that grant
+- `ChatMentionableResponse` carries `MentionableCandidate` items imported from `comments`, not a chat-flavoured copy. A candidate is a principal, a display name and an avatar on both surfaces — and on both, deliberately no email and no access level, because a picker that returned the band each candidate holds would be a way to enumerate who can do what
 - `CHAT_PAGE_VIEWS` and `CHAT_PAGE_SCOPES` are a projection of the app's `Route` union (`company-semantics-app/src/platform/route-parser.ts`), not a parallel vocabulary. A view the parser can emit but the schema rejects fails the send outright rather than degrading
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
@@ -53,7 +60,11 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatListFilters` _(type)_ — Filters for listing chats.
 - `ChatListResponse` _(type)_ — Response for GET /api/chats
 - `ChatListResponseSchema` — Response for GET /api/chats.
+- `ChatMentionableResponse` _(type)_ — Response for the chat composer's mentionable-candidate endpoint.
+- `ChatMentionableResponseSchema` — Who the chat composer may offer as a mention target.
 - `ChatMessage` _(type)_ — Individual message in a chat response (GET /api/chats/:id).
+- `ChatMessageMention` _(type)_ — One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16 code-unit range into `content`, and a…
+- `ChatMessageMentionSchema` — ONE mention on a chat turn — field-for-field `CommentMentionSchema` (`../comments/schemas`), and deliberately…
 - `ChatMessageSchema` — Individual message in a chat, as returned by GET /api/chats/:id.
 - `ChatOrigin` _(type)_ — How a chat was born: `user` or `proactive` (the system spoke first).
 - `ChatOriginSchema` — How a chat was born: by the user, or by the system speaking first (a proactive occurrence projected onto the…
@@ -117,6 +128,8 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 **Internal domains:**
 
 - `api`
+- `comments`
+- `identity`
 - `proactive`
 
 **External packages:**

package/src/chat/__tests__/message-mentions.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Mentions on a chat turn (ADR-CONTRACTS-160).
+ *
+ * INVARIANTS TESTED:
+ * - `mentions` is REQUIRED on a chat message. Absent is not the same as empty:
+ *   an empty array says "this turn named nobody", a missing key says nothing at
+ *   all, and the whole point of shipping it in a MAJOR is that no consumer gets
+ *   to keep a second opinion about which one it is holding.
+ * - A mention TARGET is a `PrincipalRef`, so the agent — which has no users row
+ *   to point at — is a legal target on the chat surface exactly as on a comment.
+ *   A bare user id is not a target, and never was: that is the shape this
+ *   vocabulary replaced.
+ * - OFFSETS ARE NULLABLE and null is not an error. A user turn carries a real
+ *   range because the composer measured it; an assistant turn's mention (the
+ *   later multi-party phase) is a typed part with no character range at all.
+ *   The nullability is what lets that land with no second schema.
+ * - OFFSETS ARE UTF-16 CODE UNITS into the exact `content` string, `endOffset`
+ *   exclusive. An astral character counts as TWO. Asserted against a real slice
+ *   rather than stated, because a client measuring code POINTS produces ranges
+ *   that look right until an emoji precedes the mention.
+ * - `SharedChatMessageSchema` did NOT gain mentions. The token-only share viewer
+ *   renders content, not identity chips, and a mention row is identity a
+ *   tokenholder was never granted.
+ * - `ChatMentionableResponseSchema` carries `MentionableCandidateSchema` items —
+ *   the comments shape imported, not a chat-flavoured copy of it.
+ */
+import { describe, expect, it } from "vitest";
+import { AGENT_PRINCIPAL, CS_AGENT, userPrincipal } from "../../identity/agent";
+import {
+  ChatMentionableResponseSchema,
+  ChatMessageMentionSchema,
+  ChatMessageSchema,
+  GetChatResponseSchema,
+  SharedChatMessageSchema,
+} from "../schemas.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures — one well-formed value per shape; every negative case spreads it
+// and changes exactly ONE field, so a failure cannot mean something else.
+// ---------------------------------------------------------------------------
+
+const makeMention = (over: Record<string, unknown> = {}) => ({
+  target: userPrincipal("user_1"),
+  startOffset: 0,
+  endOffset: 5,
+  displayName: "Ada",
+  ...over,
+});
+
+const makeMessage = (over: Record<string, unknown> = {}) => ({
+  id: "msg_1",
+  role: "user" as const,
+  content: "Hello",
+  sequenceNumber: 0,
+  createdAt: "2026-09-02T00:00:00.000Z",
+  mentions: [],
+  ...over,
+});
+
+describe("ChatMessageSchema mentions", () => {
+  it("a chat message requires a mentions array", () => {
+    const { mentions: _omitted, ...withoutMentions } = makeMessage();
+
+    const r = ChatMessageSchema.safeParse(withoutMentions);
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.error.issues[0].path).toEqual(["mentions"]);
+  });
+
+  it("an empty mentions array is the common value, not an absence", () => {
+    const parsed = ChatMessageSchema.parse(makeMessage());
+    expect(parsed.mentions).toEqual([]);
+  });
+
+  it("carries the mention rows a turn named", () => {
+    const parsed = ChatMessageSchema.parse(
+      makeMessage({ mentions: [makeMention()] }),
+    );
+
+    expect(parsed.mentions).toHaveLength(1);
+    expect(parsed.mentions[0].target).toEqual({
+      kind: "user",
+      userId: "user_1",
+    });
+  });
+
+  it("rides the transcript in GET /api/chats/:id", () => {
+    const parsed = GetChatResponseSchema.parse({
+      chat: {
+        id: "chat_1",
+        title: "A conversation",
+        interactionId: "int_1",
+        createdAt: "2026-09-02T00:00:00.000Z",
+        updatedAt: "2026-09-02T01:00:00.000Z",
+      },
+      messages: [makeMessage({ mentions: [makeMention()] })],
+    });
+
+    expect(parsed.messages[0].mentions).toHaveLength(1);
+  });
+
+  it("the share viewer's message shape did not gain mentions", () => {
+    // A token holder is granted the CONTENT of a shared chat and nothing else.
+    // Mention rows are identity, and identity is not in the grant.
+    expect(Object.keys(SharedChatMessageSchema.shape)).not.toContain(
+      "mentions",
+    );
+  });
+});
+
+describe("ChatMessageMentionSchema", () => {
+  it("the agent is a legal mention target and needs no user record", () => {
+    const parsed = ChatMessageMentionSchema.parse(
+      makeMention({
+        target: AGENT_PRINCIPAL,
+        displayName: CS_AGENT.displayName,
+      }),
+    );
+
+    expect(parsed.target).toEqual({ kind: "agent" });
+    expect(parsed.displayName).toBe("c_S");
+  });
+
+  it("a bare user id is not a target", () => {
+    // The shape this vocabulary replaced. A string where a ref belongs must
+    // refuse, or the agent silently becomes unnameable again.
+    expect(
+      ChatMessageMentionSchema.safeParse(makeMention({ target: "user_1" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("null offsets mean highlight nothing, and are never an error", () => {
+    // The assistant-turn case: a typed part with no character range.
+    const parsed = ChatMessageMentionSchema.parse(
+      makeMention({ startOffset: null, endOffset: null }),
+    );
+
+    expect(parsed.startOffset).toBeNull();
+    expect(parsed.endOffset).toBeNull();
+  });
+
+  it("offsets are UTF-16 code units, with endOffset exclusive", () => {
+    // The emoji is TWO code units, so the mention starts at 6. A client
+    // measuring code POINTS (`[...content].indexOf`) would say 5 and slice one
+    // unit early — one unit per preceding astral character.
+    const content = "hi 🎉 @Ada";
+    const startOffset = content.indexOf("@Ada");
+    const mention = ChatMessageMentionSchema.parse(
+      makeMention({ startOffset, endOffset: startOffset + "@Ada".length }),
+    );
+
+    expect(startOffset).toBe(6);
+    expect([...content].indexOf("@")).toBe(5);
+    expect(content.slice(mention.startOffset!, mention.endOffset!)).toBe(
+      "@Ada",
+    );
+  });
+
+  it("rejects a negative startOffset", () => {
+    expect(
+      ChatMessageMentionSchema.safeParse(makeMention({ startOffset: -1 }))
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatMentionableResponseSchema", () => {
+  it("offers the agent alongside people", () => {
+    const parsed = ChatMentionableResponseSchema.parse({
+      items: [
+        {
+          principal: AGENT_PRINCIPAL,
+          displayName: CS_AGENT.displayName,
+          avatarUrl: null,
+        },
+        {
+          principal: userPrincipal("user_1"),
+          displayName: "Ada",
+          avatarUrl: null,
+        },
+      ],
+    });
+
+    expect(parsed.items).toHaveLength(2);
+    expect(parsed.items[0].principal).toEqual({ kind: "agent" });
+  });
+
+  it("an empty candidate list parses", () => {
+    expect(ChatMentionableResponseSchema.parse({ items: [] }).items).toEqual(
+      [],
+    );
+  });
+
+  it("carries the comments candidate shape, not a chat copy of it", () => {
+    // No email and no access level: this is a picker, not an
+    // access-inspection surface.
+    const r = ChatMentionableResponseSchema.safeParse({
+      items: [{ userId: "user_1", displayName: "Ada", avatarUrl: null }],
+    });
+
+    expect(r.success).toBe(false);
+  });
+});

package/src/chat/index.ts

@@ -50,6 +50,10 @@ export type {
   ListSharesResponse,
   UpdateShareResponse,
   ChatMessage,
+  // Mentions on a chat turn (ADR-CONTRACTS-160): a PrincipalRef target, so the
+  // agent is a legal mention target on the chat surface too.
+  ChatMessageMention,
+  ChatMentionableResponse,
   ChatDetail,
   GetChatResponse,
   // Page context (request-side): where the reader is, as identifiers
@@ -91,6 +95,8 @@ export {
   ListSharesResponseSchema,
   UpdateShareResponseSchema,
   ChatMessageSchema,
+  ChatMessageMentionSchema,
+  ChatMentionableResponseSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
   // Page context (request-side) — the schema plus the closed vocabularies it

package/src/chat/schemas.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { IsoDateTime } from "../api/primitives";
+import { MentionableCandidateSchema } from "../comments/schemas";
+import { PrincipalRefSchema } from "../identity/agent";
 
 // =============================================================================
 // Enums
@@ -232,7 +234,65 @@ export const ChatSseEventSchema = z.discriminatedUnion("type", [
 // Message Types
 // =============================================================================
 
-/** Individual message in a chat, as returned by GET /api/chats/:id. */
+/**
+ * ONE mention on a chat turn — field-for-field `CommentMentionSchema`
+ * (`../comments/schemas`), and deliberately the same shape rather than a
+ * chat-flavoured variant: a mention means the same thing on both surfaces, and
+ * two descriptions of it would drift.
+ *
+ * The comments conventions carry over WHOLE and are restated here because a
+ * reader of this file will not necessarily open that one:
+ *
+ * - OFFSETS ARE ZERO-BASED UTF-16 CODE UNITS INTO THE EXACT `content` STRING,
+ *   `endOffset` EXCLUSIVE — plain JavaScript string coordinates, the same ones a
+ *   `textarea`'s `selectionStart` reports. An astral character counts as TWO
+ *   units, so a client measuring in code POINTS slides off the mention by one
+ *   per preceding emoji.
+ * - NO UNICODE NORMALIZATION happens anywhere on this path. Normalising the
+ *   content before measuring changes its length and desynchronises every offset
+ *   after the first composed character.
+ * - IDENTITY RENDERS FROM THIS ROW, NEVER FROM THE CONTENT UNDER THE RANGE. A
+ *   stale range can therefore only mis-HIGHLIGHT; it can never misattribute.
+ *
+ * OFFSETS ARE NULLABLE, and null means "mentioned somewhere in this turn,
+ * highlight nothing" — never an error. A USER turn always carries a real range,
+ * because the composer measured it. An ASSISTANT turn's mention arrives as a
+ * typed part with no character range at all (the later multi-party phase), and
+ * the nullability is what lets that land without a second schema.
+ *
+ * `target` is a `PrincipalRef`, so the agent — which has no users row — is a
+ * legal mention target here exactly as it is on a comment (ADR-CONTRACTS-160).
+ * `displayName` is resolved AT READ TIME and never frozen onto the row: a rename
+ * re-renders with no backfill.
+ */
+export const ChatMessageMentionSchema = z.object({
+  target: PrincipalRefSchema,
+  startOffset: z.number().int().min(0).nullable(),
+  endOffset: z.number().int().min(0).nullable(),
+  displayName: z.string(),
+});
+
+/**
+ * Individual message in a chat, as returned by GET /api/chats/:id.
+ *
+ * `mentions` is REQUIRED, not optional, and an empty array is the common value.
+ * This is the `CommentSchema` side of the choice rather than the
+ * `proactiveChatFields` side directly above: those are optional so consumer
+ * object literals keep compiling across a minor, whereas this ships in a MAJOR
+ * where the whole point is that no consumer keeps a second opinion about
+ * whether a turn has mentions. The server always projects the array; a missing
+ * one is a backend that has not adopted this release, and refusing it is the
+ * intended failure (ADR-CONTRACTS-160).
+ *
+ * MIRRORED, WITH ONE DECLARED LEAD. `mentions` lands HERE FIRST by the
+ * contracts-first protocol of ADR-CONT-029: the schema ships, the backend route
+ * registry adopts it, then `openapi/backend.yaml` and the generated
+ * `components["schemas"]` view in `../api` catch up. Until then `../api` still
+ * describes a chat message without mentions, and NOTHING IN THIS REPO CAN SEE
+ * THE DIVERGENCE — the parity guard that would catch it compares the spec to the
+ * backend, never to this file. This paragraph is the whole record of it, and it
+ * comes out when the spec agrees.
+ */
 export const ChatMessageSchema = z.object({
   id: z.string(),
   role: z.enum(["user", "assistant"]),
@@ -240,6 +300,7 @@ export const ChatMessageSchema = z.object({
   parts: z.array(z.unknown()).optional(),
   sequenceNumber: z.number().int(),
   createdAt: IsoDateTime,
+  mentions: z.array(ChatMessageMentionSchema),
 });
 
 // =============================================================================
@@ -357,6 +418,27 @@ export const GetChatResponseSchema = z.object({
   messages: z.array(ChatMessageSchema),
 });
 
+/**
+ * Who the chat composer may offer as a mention target.
+ *
+ * REUSES `MentionableCandidateSchema` from `../comments/schemas` rather than
+ * declaring a chat-shaped twin. A candidate is a principal, a display name and
+ * an avatar on both surfaces, and the reasons that shape carries no email and no
+ * access level hold here identically: it is a picker, not an
+ * access-inspection surface, so returning the band each candidate holds would
+ * turn an autocomplete into a way to enumerate who can do what.
+ *
+ * The ENVELOPE is separate from `MentionableResponseSchema` only because the two
+ * endpoints are separate and may diverge in what rides beside `items` — the item
+ * shape itself is one definition, imported, never copied.
+ *
+ * WHO IS IN THE SET is the server's decision and a client cannot widen it: the
+ * candidates are the chat's participants plus the agent, derived server-side.
+ */
+export const ChatMentionableResponseSchema = z.object({
+  items: z.array(MentionableCandidateSchema),
+});
+
 // =============================================================================
 // Page Context (request-side: where the reader is, as identifiers)
 // =============================================================================

package/src/chat/types.ts

@@ -37,6 +37,8 @@ import {
   ListSharesResponseSchema,
   UpdateShareResponseSchema,
   ChatMessageSchema,
+  ChatMessageMentionSchema,
+  ChatMentionableResponseSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
   ChatPageContextSchema,
@@ -291,6 +293,17 @@ export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>;
 /** Individual message in a chat response (GET /api/chats/:id). */
 export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
+/**
+ * One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16
+ * code-unit range into `content`, and a read-time display name.
+ */
+export type ChatMessageMention = z.infer<typeof ChatMessageMentionSchema>;
+
+/** Response for the chat composer's mentionable-candidate endpoint. */
+export type ChatMentionableResponse = z.infer<
+  typeof ChatMentionableResponseSchema
+>;
+
 /** Chat detail object in GET /api/chats/:id — includes interactionId for append-on-edit flows. */
 export type ChatDetail = z.infer<typeof ChatDetailSchema>;