@pithy-sh/support 0.5.0 → 0.6.0

package/src/http/responses.ts

@@ -3,6 +3,7 @@
 
 import { asRead } from "@pithy-sh/core/src/projection/asRead";
 import { z } from "zod";
+import { SupportAssignmentActorType } from "../data/assignment";
 import { SUPPORT_BILLING_SCOPE } from "../data/billingScope";
 import {
   SupportAccountLinkSource,
@@ -109,6 +110,34 @@ export const SupportThreadView = z
       .describe(
         "The control-plane subject that archived it, for convenience only — the answer to 'who marked this done' comes from the audit trail.",
       ),
+    // Optional as well as nullable (#450, #816): absent says *this Worker predates assignment*, which a client
+    // must not read as *nobody has it*.
+    assigneeRef: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "Who has this conversation, as the opaque reference it was assigned to, or null when nobody has it. Absent from a Worker that predates assignment. The listing's `assignee` filter matches it.",
+      ),
+    assigneeName: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "How the assignee is shown, as the assigner named them; null when nobody has it. A label, never an identity — `assigneeRef` is that. Untrusted text; render it escaped.",
+      ),
+    assignedAt: z.iso
+      .datetime()
+      .nullable()
+      .optional()
+      .describe("When the current assignment was made, ISO-8601; null when nobody has it."),
+    assignedBy: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "Who made the current assignment — a control-plane subject, or a user of the app's id; null when nobody has it. Every earlier change is in the thread's `assignments`.",
+      ),
     messageCount: z.number().int().describe("How many messages the thread holds, inbound and outbound together."),
     firstMessageAt: z.iso.datetime().describe("When the thread opened, ISO-8601."),
     lastMessageAt: z.iso.datetime().describe("When the thread last moved, ISO-8601. The inbox sorts on this."),
@@ -281,6 +310,98 @@ export const SupportThreadsResponse = z
   .describe("A page of the inbox, as one viewer sees it.");
 export type SupportThreadsResponse = z.output<typeof SupportThreadsResponse>;
 
+/** A search backend, by name. */
+const SupportSearchBackend = z
+  .enum(["fts", "like", "semantic"])
+  .describe("A search backend: `fts` (the FTS5 index), `like` (the keyword scan), or `semantic` (the message index).");
+
+/** One search result. */
+export const SupportSearchResultView = z
+  .object({
+    thread: SupportListedThreadView.describe("The thread, carrying the calling viewer's own read and snooze state."),
+    messageId: z
+      .string()
+      .describe(
+        "The message in the thread that matched best — the one the scores below belong to. Open the thread at it.",
+      ),
+    bm25: z
+      .number()
+      .optional()
+      .describe(
+        "That message's FTS5 `bm25`, raw: lower is better, and comparable only within one search. Absent when FTS5 did not run or did not match it — including on the `LIKE` scan, which has no score.",
+      ),
+    similarity: z
+      .number()
+      .optional()
+      .describe(
+        "That message's similarity to the query in the semantic index, raw: higher is closer. Absent when semantic search did not run or did not match it. Never normalized against `bm25` — the two are reported as they are.",
+      ),
+  })
+  .describe("One thread a search found, named by its best-matching message, with that message's raw scores.");
+export type SupportSearchResultView = z.output<typeof SupportSearchResultView>;
+
+/** `GET {base}/threads/search`. */
+export const SupportSearchResponse = z
+  .object({
+    mode: z
+      .enum(["keyword", "semantic", "hybrid"])
+      .describe("The mode that ran: the one asked for, or `hybrid` when none was."),
+    backends: z
+      .object({
+        ran: z.array(SupportSearchBackend).describe("The backends that answered."),
+        skipped: z
+          .array(
+            z
+              .object({
+                backend: SupportSearchBackend,
+                reason: z
+                  .enum(["unprovisioned", "failed"])
+                  .describe(
+                    "`unprovisioned` — on in config, and its index or binding is not there until `pithy support provision` runs. `failed` — it was there and did not answer.",
+                  ),
+              })
+              .describe("A backend that was on and did not answer."),
+          )
+          .describe(
+            "The backends that were on and did not answer. Empty when every one did. A skip degrades the search, never fails it.",
+          ),
+      })
+      .describe("Which backends ran, and which were skipped."),
+    count: z
+      .number()
+      .int()
+      .min(0)
+      .describe(
+        "How many results came back. Under the limit when the filters left fewer — that is the true count, not a page.",
+      ),
+    results: z
+      .array(SupportSearchResultView)
+      .describe("The threads, best first: fused by rank, newest first on a tie."),
+  })
+  .describe("A ranked search over the inbox. No cursor: a ranked list has a top, not pages.");
+export type SupportSearchResponse = z.output<typeof SupportSearchResponse>;
+
+/** One change of a thread's assignee, as its history shows it. */
+export const SupportAssignmentView = z
+  .object({
+    id: z.string().describe("The history row's id."),
+    assigneeRef: z
+      .string()
+      .nullable()
+      .describe("Who had the thread after this change, or null when it was unassigned."),
+    assigneeName: z.string().nullable().describe("How that assignee was shown at the time, or null."),
+    previousRef: z.string().nullable().describe("Who had it before, or null when nobody did."),
+    previousName: z.string().nullable().describe("How the previous assignee was shown, or null."),
+    actorType: SupportAssignmentActorType.describe(
+      "How whoever made the change was verified: `control-plane` for a management client, `user` for a signed-in user of the app.",
+    ),
+    assignedBy: z.string().describe("Who made the change — a control-plane subject, or a user of the app's id."),
+    note: z.string().nullable().describe("Why, in the assigner's words, or null. Untrusted text; render it escaped."),
+    createdAt: z.iso.datetime().describe("When the change was made, ISO-8601."),
+  })
+  .describe("One append-only change of a conversation's assignee.");
+export type SupportAssignmentView = z.output<typeof SupportAssignmentView>;
+
 /** `GET {base}/threads/:id`. */
 export const SupportThreadResponse = z
   .object({
@@ -289,6 +410,13 @@ export const SupportThreadResponse = z
     attachments: z.array(SupportAttachmentView).describe("Its attachments, across every message."),
     sender: SenderContextView.describe("What the app already knows about the sender."),
     replies: z.array(SupportReplyView).describe("The canned replies, ordered for this thread's category."),
+    // Optional (#450): absent from a Worker that predates assignment.
+    assignments: z
+      .array(SupportAssignmentView)
+      .optional()
+      .describe(
+        "Every change of the assignee, oldest first. Empty when nobody was ever assigned; absent from a Worker that predates assignment.",
+      ),
   })
   .describe("A whole conversation, with the customer context and the replies worth offering on it.");
 export type SupportThreadResponse = z.output<typeof SupportThreadResponse>;
@@ -333,6 +461,24 @@ export const SupportReplySentResponse = z
   .describe("The reply that was filed, and which of the two ways it reaches the customer.");
 export type SupportReplySentResponse = z.output<typeof SupportReplySentResponse>;
 
+/**
+ * `POST {base}/threads/:id/assign` and `POST {base}/staff/threads/:id/assign`.
+ *
+ * The thread as the assignment left it, and whether anything changed: assigning the current assignee again
+ * is a success that wrote nothing, and a pane that re-renders from it should know not to say *reassigned*.
+ */
+export const SupportAssignResponse = z
+  .object({
+    thread: SupportThreadView.describe("The conversation, as the assignment left it."),
+    changed: z
+      .boolean()
+      .describe(
+        "Whether the assignee changed. False when the thread already had that assignee, or had none and was unassigned — nothing was recorded and nothing was audited.",
+      ),
+  })
+  .describe("The conversation after an assignment, and whether it changed anything.");
+export type SupportAssignResponse = z.output<typeof SupportAssignResponse>;
+
 /** `POST {base}/threads/:id/reclassify`. */
 export const SupportReclassifiedResponse = z
   .object({
@@ -399,6 +545,10 @@ export type SupportMessageViewAsRead = z.output<typeof SupportMessageViewAsRead>
 export const SupportThreadsResponseAsRead = asRead(SupportThreadsResponse);
 export type SupportThreadsResponseAsRead = z.output<typeof SupportThreadsResponseAsRead>;
 
+/** `GET {base}/threads/search`, as a client that does not control the Worker must read it. */
+export const SupportSearchResponseAsRead = asRead(SupportSearchResponse);
+export type SupportSearchResponseAsRead = z.output<typeof SupportSearchResponseAsRead>;
+
 /** `GET {base}/threads/:id`, as a client that does not control the Worker must read it. */
 export const SupportThreadResponseAsRead = asRead(SupportThreadResponse);
 export type SupportThreadResponseAsRead = z.output<typeof SupportThreadResponseAsRead>;
@@ -407,6 +557,10 @@ export type SupportThreadResponseAsRead = z.output<typeof SupportThreadResponseA
 export const SupportArchiveResponseAsRead = asRead(SupportArchiveResponse);
 export type SupportArchiveResponseAsRead = z.output<typeof SupportArchiveResponseAsRead>;
 
+/** `POST {base}/threads/:id/assign`, as a client that does not control the Worker must read it. */
+export const SupportAssignResponseAsRead = asRead(SupportAssignResponse);
+export type SupportAssignResponseAsRead = z.output<typeof SupportAssignResponseAsRead>;
+
 /**
  * ## The submitter's own view, and what it deliberately omits
  *

package/src/http/routes.ts

@@ -8,9 +8,11 @@ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
 import { requireSameOrigin } from "@pithy-sh/core/src/http/sameOrigin";
 import { validate } from "@pithy-sh/core/src/http/validation";
 import type { Context, Hono } from "hono";
-import { requireAuth } from "./guards";
+import type { SupportStaffConfig } from "../config/config";
+import { requireAuth, requireStaff } from "./guards";
 import {
   archiveConversation,
+  assignConversation,
   type HandlerDeps,
   listInbox,
   listMyThreads,
@@ -19,33 +21,39 @@ import {
   readMyThread,
   reclassifyConversation,
   replyToConversation,
+  searchInbox,
   submitFeedbackRequest,
   updateFlags,
 } from "./handlers";
 import {
   SupportArchiveResponse,
+  SupportAssignResponse,
   SupportFlagsResponse,
   SupportMyThreadResponse,
   SupportMyThreadsResponse,
   SupportReclassifiedResponse,
   SupportRepliesResponse,
   SupportReplySentResponse,
+  SupportSearchResponse,
   SupportSubmissionResponse,
   SupportThreadResponse,
   SupportThreadsResponse,
 } from "./responses";
 import {
   ArchiveThreadInput,
+  AssignThreadInput,
   FlagsInput,
   ListThreadsQuery,
   MyThreadsQuery,
   RepliesQuery,
   ReplyInput,
+  SearchThreadsQuery,
   SubmitFeedbackInput,
   ThreadIdParam,
 } from "./schemas";
 import {
   SUPPORT_THREADS_ARCHIVE_SCOPE,
+  SUPPORT_THREADS_ASSIGN_SCOPE,
   SUPPORT_THREADS_FLAG_SCOPE,
   SUPPORT_THREADS_READ_SCOPE,
   SUPPORT_THREADS_RECLASSIFY_SCOPE,
@@ -56,8 +64,10 @@ import {
  * The support routes, their verification strategies, and what each accepts:
  *
  *   GET  /support/threads               → the inbox     (control-plane: support:threads:read)       query: ListThreadsQuery
+ *   GET  /support/threads/search        → search        (control-plane: support:threads:read)       query: SearchThreadsQuery
  *   GET  /support/threads/:id           → one thread    (control-plane: support:threads:read)       param: ThreadIdParam
  *   POST /support/threads/:id/archive   → done/reopen   (control-plane: support:threads:archive)    param + json
+ *   POST /support/threads/:id/assign    → who has it    (control-plane: support:threads:assign)     param + json
  *   POST /support/threads/:id/reply     → answer        (control-plane: support:threads:reply)      param + json
  *   POST /support/threads/:id/reclassify→ re-run model  (control-plane: support:threads:reclassify) param
  *   POST /support/threads/:id/flags     → read/snooze   (control-plane: support:threads:flag)       param + json
@@ -67,20 +77,26 @@ import {
  *   GET  /support/feedback              → my requests   (bearer/session)                            query: MyThreadsQuery
  *   GET  /support/feedback/:id          → one of mine   (bearer/session)                            param: ThreadIdParam
  *
- * **Two surfaces, two gates, and they never stack.** The management routes answer to a control-plane
- * credential the adopter issued, and with the seam uncomposed every one denies with
- * `controlplane/not_connected` — the correct failure for an inbox holding other people's private
+ *   POST /support/staff/threads/:id/assign → who has it (bearer/session + same-origin + staff assignPower) param + json
+ *
+ * **Three doors, three gates, and the control plane never stacks with a session.** The management routes
+ * answer to a control-plane credential the adopter issued, and with the seam uncomposed every one denies
+ * with `controlplane/not_connected` — the correct failure for an inbox holding other people's private
  * correspondence. The `feedback` routes answer to the adopter's own signed-in user, and with no auth
- * capability composed `c.var.auth` is null and every one denies. A control-plane caller holds no
- * session by design and can never satisfy `requireAuth()`; a user's session confers no scope. See
+ * capability composed `c.var.auth` is null and every one denies. The `staff` route answers to a signed-in
+ * user too, and then to `requireStaff()`: a staff power from `support({ staff })`, held in the organization
+ * the request acts for, and with no `staff` configured every caller is refused. A control-plane caller
+ * holds no session by design and can never satisfy `requireAuth()`; a user's session confers no scope —
+ * which is why staff assignment is its own route rather than a second gate on the control-plane one. See
  * `guards.ts`.
  *
- * **`requireSameOrigin()` is on the submission route and on neither read.** Cookie-mode sessions make a
- * mutating route CSRF-reachable, and this one writes into a support inbox under a real customer's name
- * — a forged submission is somebody else's words attributed to them, in the one place an operator
- * treats attribution as proven. The reads are GETs and carry no such risk. A bearer caller is
- * CSRF-exempt, and that exemption belongs to the gate `@pithy-sh/auth` publishes rather than to
- * anything decided here.
+ * **`requireSameOrigin()` is on the two session routes that write, and on no read.** Cookie-mode sessions
+ * make a mutating route CSRF-reachable. The submission route writes into a support inbox under a real
+ * customer's name — a forged submission is somebody else's words attributed to them, in the one place an
+ * operator treats attribution as proven — and the staff assign route hands a customer's conversation to
+ * somebody on a staff member's say-so. The reads are GETs and carry no such risk. A bearer caller is
+ * CSRF-exempt, and that exemption belongs to the gate `@pithy-sh/auth` publishes rather than to anything
+ * decided here.
  *
  * **Every response has an exported schema**, in `responses.ts`. Each handler's return type is
  * `z.output` of its envelope, so `c.json(await handler(...))` carries the contract without a cast — and
@@ -158,6 +174,11 @@ export interface SupportRoutesOptions {
   submission?: boolean;
   /** Resolve handler deps from the request context. */
   resolveDeps: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
+  /**
+   * Who of the app's signed-in users works the inbox. Absent, the staff route is still mounted and refuses
+   * every caller with 403 — it is not a feature this deployment lacks, it is a door nobody holds a key to.
+   */
+  staff?: SupportStaffConfig;
 }
 
 /**
@@ -217,6 +238,20 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
       async (c) => c.json(await listInbox(await resolve(c), c.req.valid("query"), viewer(c))),
     );
 
+    // Before `/threads/:id`, so `search` is never read as a thread id.
+    app.get(
+      `${base}/threads/search`,
+      describeRoute({
+        summary: "Search the inbox, by words and by meaning, ranked as one.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_READ_SCOPE],
+        responses: { 200: SupportSearchResponse },
+      }),
+      requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
+      validate("query", SearchThreadsQuery),
+      async (c) => c.json(await searchInbox(await resolve(c), c.req.valid("query"), viewer(c))),
+    );
+
     app.get(
       `${base}/replies`,
       describeRoute({
@@ -259,6 +294,51 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
         c.json(await archiveConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c))),
     );
 
+    app.post(
+      `${base}/threads/:id/assign`,
+      describeRoute({
+        summary: "Assign a conversation to somebody, or to nobody.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_ASSIGN_SCOPE],
+        responses: { 200: SupportAssignResponse },
+      }),
+      requireControlPlane(SUPPORT_THREADS_ASSIGN_SCOPE),
+      validate("param", ThreadIdParam),
+      validate("json", AssignThreadInput),
+      async (c) =>
+        c.json(
+          await assignConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), {
+            type: "control-plane",
+            id: viewer(c),
+          }),
+        ),
+    );
+
+    // The same act for a signed-in user of the app who works the inbox: their session, the CSRF gate a
+    // cookie-mode session needs on any write, and support's staff power in the organization they act for
+    // (`staff.ts`). A control-plane caller holds no session and can never pass `requireAuth()`, so the two
+    // doors never stack.
+    app.post(
+      `${base}/staff/threads/:id/assign`,
+      describeRoute({
+        summary: "Assign a conversation as a signed-in member of the support staff.",
+        verification: ["bearer", "session"],
+        responses: { 200: SupportAssignResponse },
+      }),
+      requireAuth(),
+      requireSameOrigin(),
+      requireStaff(options.staff, "assignPower"),
+      validate("param", ThreadIdParam),
+      validate("json", AssignThreadInput),
+      async (c) =>
+        c.json(
+          await assignConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), {
+            type: "user",
+            id: submitter(c),
+          }),
+        ),
+    );
+
     app.post(
       `${base}/threads/:id/reply`,
       describeRoute({
@@ -313,6 +393,8 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
       `${base}/feedback`,
       describeRoute({
         summary: "Write in to support from the app.",
+        operation: "feedback.write",
+        tool: { effect: "sends" },
         verification: ["bearer", "session"],
         responses: { 201: SupportSubmissionResponse },
       }),
@@ -326,6 +408,8 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
       `${base}/feedback`,
       describeRoute({
         summary: "List the caller's own support requests.",
+        operation: "feedback.list",
+        tool: true,
         verification: ["bearer", "session"],
         responses: { 200: SupportMyThreadsResponse },
       }),
@@ -338,6 +422,8 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
       `${base}/feedback/:id`,
       describeRoute({
         summary: "Read one of the caller's own support requests.",
+        operation: "feedback.read",
+        tool: true,
         verification: ["bearer", "session"],
         responses: { 200: SupportMyThreadResponse },
       }),

package/src/http/schemas.ts

@@ -1,11 +1,20 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { PresenceParticipantName, PresenceParticipantRef } from "@pithy-sh/core/src/presence/frames";
 import { z } from "zod";
 import { MAX_SUBMISSION_ATTACHMENTS, MAX_SUBMISSION_BODY_CHARS, MAX_SUBMISSION_SUBJECT_CHARS } from "../config/config";
+import { UNASSIGNED } from "../data/assignment";
 import { SupportChannel, SupportPriority, SupportSentiment } from "../data/enums";
 import { SupportSubmissionContext } from "../data/message";
-import { MAX_PAGE_SIZE } from "../store/paging";
+import { DEFAULT_SEARCH_LIMIT, MAX_PAGE_SIZE, MAX_SEARCH_LIMIT, MAX_SEARCH_TERM } from "../store/paging";
+
+/** An assignee reference, as the listing filters on it and an assignment names it. */
+const AssigneeRef = PresenceParticipantRef.refine((ref) => ref !== UNASSIGNED, {
+  message: `"${UNASSIGNED}" is reserved: it is the filter for threads nobody has`,
+}).describe(
+  "Who the thread is assigned to: an opaque reference, the participant shape presence rooms use. A management client's own reference, which it chose; or a user of the app's id. Never `none`, which is the listing's filter for threads nobody has.",
+);
 
 /**
  * The request contracts every support route declares (CLAUDE.md §HTTP).
@@ -41,34 +50,45 @@ const CategoryFilter = z
     "One category key from this project's effective taxonomy. A key an adopter removed simply matches nothing.",
   );
 
-/** The inbox listing query. */
+/** The filters the inbox listing and the search route share, applied in D1 either way. */
+const threadFilterFields = {
+  archived: z
+    .enum(["true", "false"])
+    .optional()
+    .describe("`true` for the done pile, `false` or absent for the open inbox — which is the default on purpose."),
+  category: CategoryFilter.optional().describe("Filter to one category — what the classifier made of it."),
+  declaredCategory: CategoryFilter.optional().describe(
+    "Filter to one category **the submitter chose**, which is a different question from `category` and answers it about different threads. Combining the two is how an operator finds the disagreements; asking for this one alone is how they triage a project with `ai.enabled: false`, where nothing ever writes the other.",
+  ),
+  priority: SupportPriority.optional().describe("Filter to one priority."),
+  sentiment: SupportSentiment.optional().describe("Filter to one sentiment."),
+  channel: SupportChannel.optional().describe(
+    "Filter to one channel — `email` for mail, `app` for what signed-in users filed from inside the app. Absent shows both, which is the right default for an inbox that is one queue however things arrived.",
+  ),
+  inbox: z
+    .string()
+    .min(3)
+    .max(256)
+    .optional()
+    .describe("Filter to one configured inbox address, for a Worker serving several."),
+  assignee: z
+    .union([z.literal(UNASSIGNED), AssigneeRef])
+    .optional()
+    .describe(
+      "Filter to the threads one assignee has, by their `assigneeRef`, or `none` for the threads nobody has. Absent shows every thread, assigned or not.",
+    ),
+};
+
+/**
+ * The inbox listing query.
+ *
+ * **Strict, and there is no `q`.** Listing lists; `GET {basePath}/threads/search` searches. An unknown
+ * key is refused as `validation/invalid_input` rather than ignored, so a client sending `q` is told so
+ * instead of getting the unfiltered inbox back as though it were the answer.
+ */
 export const ListThreadsQuery = z
   .object({
-    archived: z
-      .enum(["true", "false"])
-      .optional()
-      .describe("`true` for the done pile, `false` or absent for the open inbox — which is the default on purpose."),
-    category: CategoryFilter.optional().describe("Filter to one category — what the classifier made of it."),
-    declaredCategory: CategoryFilter.optional().describe(
-      "Filter to one category **the submitter chose**, which is a different question from `category` and answers it about different threads. Combining the two is how an operator finds the disagreements; asking for this one alone is how they triage a project with `ai.enabled: false`, where nothing ever writes the other.",
-    ),
-    priority: SupportPriority.optional().describe("Filter to one priority."),
-    sentiment: SupportSentiment.optional().describe("Filter to one sentiment."),
-    channel: SupportChannel.optional().describe(
-      "Filter to one channel — `email` for mail, `app` for what signed-in users filed from inside the app. Absent shows both, which is the right default for an inbox that is one queue however things arrived.",
-    ),
-    inbox: z
-      .string()
-      .min(3)
-      .max(256)
-      .optional()
-      .describe("Filter to one configured inbox address, for a Worker serving several."),
-    q: z
-      .string()
-      .min(1)
-      .max(200)
-      .optional()
-      .describe("Free text over subjects and bodies. Keyword search — the words people actually remember."),
+    ...threadFilterFields,
     cursor: z
       .string()
       .max(512)
@@ -82,9 +102,45 @@ export const ListThreadsQuery = z
       .optional()
       .describe("How many threads to return. Bounded, because a verified client can still have a bug."),
   })
-  .describe("The inbox query: what to filter by, what to search for, and where to resume.");
+  .strict()
+  .describe("The inbox query: what to filter by, and where to resume. Search is its own route.");
 export type ListThreadsQuery = z.infer<typeof ListThreadsQuery>;
 
+/** How a search runs. */
+export const SupportSearchMode = z
+  .enum(["keyword", "semantic", "hybrid"])
+  .describe(
+    "`keyword` finds the exact words — FTS5 when `search.fts` is on, the `LIKE` scan otherwise. `semantic` finds the meaning, through the message index. `hybrid` runs both and ranks them as one.",
+  );
+export type SupportSearchMode = z.infer<typeof SupportSearchMode>;
+
+/** The search query. */
+export const SearchThreadsQuery = z
+  .object({
+    q: z
+      .string()
+      .trim()
+      .min(1)
+      .max(MAX_SEARCH_TERM)
+      .describe("What to search for, in the customer's words or yours. An order number, an error, or a description."),
+    mode: SupportSearchMode.optional().describe(
+      "Which backends to run. Absent runs every one that is on, as `hybrid`. `semantic` or `hybrid` while `search.semantic` is off is refused, naming the flag.",
+    ),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_SEARCH_LIMIT)
+      .optional()
+      .describe(
+        `How many threads to return, best first. Default ${DEFAULT_SEARCH_LIMIT}, at most ${MAX_SEARCH_LIMIT}. No cursor: a ranked list has a top, not pages.`,
+      ),
+    ...threadFilterFields,
+  })
+  .strict()
+  .describe("A search over the inbox: the words, the mode, how many, and the same filters the inbox listing takes.");
+export type SearchThreadsQuery = z.infer<typeof SearchThreadsQuery>;
+
 /** The archive/unarchive body. */
 export const ArchiveThreadInput = z
   .object({
@@ -97,6 +153,39 @@ export const ArchiveThreadInput = z
   .describe("Mark a conversation done, or reopen it.");
 export type ArchiveThreadInput = z.infer<typeof ArchiveThreadInput>;
 
+/** Who a thread is assigned to. */
+export const AssigneeInput = z
+  .object({
+    ref: AssigneeRef,
+    name: PresenceParticipantName.describe(
+      "How the assignee is shown in the inbox and in the history. A label, never an identity — `ref` is that.",
+    ),
+  })
+  .describe("Somebody a thread may be assigned to: an opaque reference and the name to show.");
+export type AssigneeInput = z.infer<typeof AssigneeInput>;
+
+/** The longest assignment note, in UTF-16 code units. */
+export const MAX_ASSIGNMENT_NOTE_CHARS = 500;
+
+/** The assign/unassign body, the same on the control-plane route and the staff session route. */
+export const AssignThreadInput = z
+  .object({
+    assignee: AssigneeInput.nullable().describe(
+      "Who should have this conversation, or `null` to unassign it. Assigning the current assignee again changes nothing and records nothing.",
+    ),
+    note: z
+      .string()
+      .trim()
+      .min(1)
+      .max(MAX_ASSIGNMENT_NOTE_CHARS)
+      .optional()
+      .describe(
+        "Why, in your own words. Kept in the thread's assignment history and on the audit event, and shown to anybody who can read the thread — so it is a note to colleagues, never a place for the customer's details.",
+      ),
+  })
+  .describe("Assign a conversation to somebody, or to nobody.");
+export type AssignThreadInput = z.infer<typeof AssignThreadInput>;
+
 /** The reply body. */
 export const ReplyInput = z
   .object({