thursday-agent 0.4.0 → 0.6.0

package/features/bot/bot.schema.ts

@@ -1,5 +1,4 @@
 import z from "zod";
-import { PAGE_SIZE } from "@/config";
 import {
   type TextModelProviderId,
   textModelProviderSchema,
@@ -7,9 +6,10 @@ import {
 import { DateLikeSchema } from "@/lib/date-like";
 import { COMMON_VALIDATE } from "@/lib/limits";
 import { clip } from "@/lib/utils";
-import { MARK_SHAPES, randomMarkColors } from "./mark.const";
+import { MARK_PAINT_IDS, MARK_SHAPES, randomMarkFills } from "./mark.const";
+import { ROOM_THURSDAY, RoomViewSchema } from "./room.schema";
 
-/** How a bot's mark is drawn. Both fields are optional; the seed alone gives every bot a distinct face. */
+/** How a bot's mark is drawn. Every field is optional; the seed alone gives every bot a distinct face. */
 export const botIconSchema = z.object({
   /** A hex colour, or MARK_SYSTEM to follow the theme. Stored so a chosen "system" differs from no choice. */
   color: z
@@ -19,18 +19,27 @@ export const botIconSchema = z.object({
   shape: z.enum(MARK_SHAPES).optional(),
   /** Draw as an outline instead of a fill. */
   outline: z.boolean().optional(),
+  /** A paint (MARK_PAINTS) worn in place of the colour; the colour stays for when it comes off. */
+  paint: z.enum(MARK_PAINT_IDS).optional(),
 });
 
 export const botSystemPromptSchema = z.string().max(COMMON_VALIDATE.prompt.max);
 
-/** Face for a bot nobody drew. Random rather than name-derived so two bots made in one call differ at a glance. */
-export function randomBotIcon(): BotIcon {
-  return {
-    color: randomMarkColors(1)[0],
+/**
+ * Faces for bots nobody drew, distinct from one another: the whole vocabulary is
+ * rolled, shape and paints included, so a face the app hands out and a face
+ * somebody picked are drawn from the same range. Random rather than name-derived
+ * so two bots made in one call differ at a glance.
+ */
+export function randomBotIcons(count: number): BotIcon[] {
+  return randomMarkFills(count).map((fill) => ({
+    ...fill,
     shape: MARK_SHAPES[Math.floor(Math.random() * MARK_SHAPES.length)],
-  };
+  }));
 }
 
+export const randomBotIcon = (): BotIcon => randomBotIcons(1)[0];
+
 /** Pinned MCP tools skip the in-call tool search. 10 is a prompt-size budget, not a DB limit. */
 export const MAX_PINNED_TOOLS = 10;
 
@@ -49,6 +58,10 @@ export const botNameSchema = z
   .string()
   .trim()
   .transform((name) => name.replace(/\s+/g, " "))
+  .refine(
+    (name) => name.toLowerCase() !== ROOM_THURSDAY.toLowerCase(),
+    "Thursday is reserved for the voice assistant.",
+  )
   .pipe(
     z.string().min(1, "A name is required").max(COMMON_VALIDATE.name.max),
     // .regex(/^\p{L}+(?: \p{L}+)*$/u, "Letters and single spaces only"),
@@ -62,8 +75,6 @@ export const TokenUsageSchema = z.object({
 
 export type TokenUsage = z.infer<typeof TokenUsageSchema>;
 
-export const NO_TOKENS: TokenUsage = { input: 0, output: 0 };
-
 /** A budget under this leaves no room for the opening message, so it is refused rather than stored. */
 export const COMPACT_AT_MIN = 8_000;
 
@@ -147,7 +158,8 @@ export type JobBot = {
 /**
  * Worker that exists when no bot row does, so a fresh install can delegate.
  * Has no prompt: the base persona (ai/prompts/bot.prompt) says everything it needs.
- * No seed may reuse this name, or the row shadows the fallback.
+ * The Jarvis seed takes the same name on purpose (bot.seed): installed, its row
+ * stands in for the fallback.
  */
 export const DEFAULT_BOT: JobBot = {
   name: "Jarvis",
@@ -192,35 +204,39 @@ export type BotMemory = {
 };
 
 /**
- * `waiting`: the bot stopped on a question only the user can answer; the answer
- * resumes the same thread. `done` and `failed` can be resumed as well.
+ * `waiting`: a bot asked the user something, or the app stopped the work; the
+ * answer resumes the same thread. `cancelled`: the user stopped it. A model that
+ * breaks pauses the job as `waiting` rather than ending it, so nothing ends as a
+ * failure. `done` and `cancelled` can be picked back up with a follow-up.
  */
-export const TASK_STATUSES = ["running", "waiting", "done", "failed"] as const;
+export const THREAD_STATUSES = [
+  "running",
+  "waiting",
+  "done",
+  "cancelled",
+] as const;
 
-export type TaskStatus = (typeof TASK_STATUSES)[number];
-
-/** One page of history (config PAGE_SIZE). */
-export const TASK_HISTORY_PAGE = PAGE_SIZE;
+export type ThreadStatus = (typeof THREAD_STATUSES)[number];
 
 /** The single option offered when the app stopped a job and asks whether to go on. Button text and spoken word alike. */
-export const TASK_CONTINUE = "Continue";
+export const THREAD_CONTINUE = "Continue";
 
 /**
- * Who a person's words to a job came from (bot.runner answerTask). Thursday
+ * Who a person's words to a job came from (bot.runner answerThread). Thursday
  * passing something on from a call and the user typing on screen reach a bot
  * down one pipe, so the words carry it in front of them.
  */
-export type TaskSpeaker = "thursday" | "user";
+export type ThreadSpeaker = "thursday" | "user";
 
-const SPEAKER_TAGS: Record<TaskSpeaker, string> = {
+const SPEAKER_TAGS: Record<ThreadSpeaker, string> = {
   thursday: "Thursday, on the call:",
   user: "The user, on screen:",
 };
 
-export const tagSpeaker = (from: TaskSpeaker, text: string): string =>
+export const tagSpeaker = (from: ThreadSpeaker, text: string): string =>
   `${SPEAKER_TAGS[from]} ${text}`;
 
-/** The words without their tag, as the screen draws a person's line (task.query linesOf). */
+/** The words without their tag, as the screen draws a person's line (thread.query linesOf). */
 export const untagSpeaker = (text: string): string => {
   for (const tag of Object.values(SPEAKER_TAGS)) {
     if (text.startsWith(`${tag} `)) return text.slice(tag.length + 1);
@@ -229,29 +245,33 @@ export const untagSpeaker = (text: string): string => {
 };
 
 /**
- * What a `waiting` job waits on (database task.pending). `toolCallId` is the
- * `ask_thursday` call the answer resolves, null when the app stopped the run and
- * offers to continue. `auto` marks a stop the app picks back up by itself once a
- * browser is on the app, not before `retryAt` (epoch ms) (bot.runner parkTask).
+ * What a waiting thread waits on: a bot's question (`messageId`, the asker `bot`)
+ * or a stop the app made, which offers only Continue. `auto` is a stop the app
+ * picks back up by itself (browser absence).
  */
-export type TaskPending = {
-  toolCallId: string | null;
+export type ThreadPending = {
   options: string[];
   auto?: boolean;
-  retryAt?: number;
+  messageId?: string;
+  bot?: string;
 };
 
 /**
- * True when the app stopped the job (step cap, closed browser, restart) rather
- * than the bot asking something. Why it stopped is in the outcome text; every
- * list calls it waiting on you, because the answer is the same click.
+ * True when the app stopped the job (step cap, closed browser, restart, idle room)
+ * rather than a bot asking something. Why it stopped is in the outcome text; every
+ * list calls it waiting on you, because the answer is the same click. A question
+ * carries its message id, so a bot offering Continue as a choice is still asking.
  */
-export const isAppStop = (ask: { options: string[] } | null | undefined) => {
+export const isAppStop = (
+  ask: { options: string[]; messageId?: string } | null | undefined,
+) => {
   const options = ask?.options ?? [];
-  return options.length === 1 && options[0] === TASK_CONTINUE;
+  return (
+    !ask?.messageId && options.length === 1 && options[0] === THREAD_CONTINUE
+  );
 };
 
-/** One piece of a tool result as the screen draws it. Full output stays in the server thread. */
+/** One piece of a tool result as the screen draws it. Full output stays in the stored messages. */
 export const ResultPartSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("text"), text: z.string() }),
   /** data: or http(s) url usable in an <img>. */
@@ -260,24 +280,25 @@ export const ResultPartSchema = z.discriminatedUnion("type", [
 
 export type ResultPart = z.infer<typeof ResultPartSchema>;
 
-/** One thread line as the screen sees it. `bot` is null on the user side; `parent` is the ask_bot call it happened under. */
+/** One thread line as the screen sees it. `bot` is null on the user side; `parent` is the exchange (thread_work) it was written under. */
 const LineBase = z.object({
   /** Row id plus part index; one message may hold several lines. */
   id: z.string(),
   seq: z.number(),
   bot: z.string().nullable(),
   parent: z.string().nullable(),
+  to: z.string().nullish(),
   at: DateLikeSchema,
 });
 
-export const TaskLineSchema = z.discriminatedUnion("kind", [
+export const ThreadLineSchema = z.discriminatedUnion("kind", [
   /** What the user said (via Thursday): request, answer. */
   LineBase.extend({ kind: z.literal("user"), text: z.string() }),
   /** Bot text; the last one is the answer. */
   LineBase.extend({ kind: z.literal("text"), text: z.string() }),
   /** Compaction summary (bot.run compact). The model resumes from here; the screen draws it as a divider. */
   LineBase.extend({ kind: z.literal("note"), text: z.string() }),
-  /** Why the app stopped the run (bot.runner parkTask, a run that broke), without what the resumed run is told to check. */
+  /** Why the app stopped the run (room.query pauseRoom, or a break the runner retries), without what the resumed run is told to check. */
   LineBase.extend({ kind: z.literal("stop"), text: z.string() }),
   LineBase.extend({
     kind: z.literal("tool"),
@@ -294,38 +315,25 @@ export const TaskLineSchema = z.discriminatedUnion("kind", [
     kind: z.literal("tool-result"),
     callId: z.string(),
     name: z.string(),
-    /** A glance's worth; the rest is behind `queryKey.toolResult`. */
+    /** A glance: a few text lines, each clipped. The whole output is behind `queryKey.toolResult`. */
     results: ResultPartSchema.array(),
-    /** Something was clipped. */
+    /** The output holds more than the glance: more lines, a clipped line, or an image. */
     more: z.boolean(),
   }),
-  /**
-  /** Bot to bot: `ask_bot` (`to` is the borrowed bot) or `ask_back` (`to` is the job's bot, `parent` set). Both answer as `ask-result`. */
+  /** A message sent to another participant or to Thursday (send_message); `question` asks the user. */
   LineBase.extend({
     kind: z.literal("ask"),
     callId: z.string(),
     to: z.string(),
     text: z.string(),
-  }),
-  LineBase.extend({
-    kind: z.literal("ask-result"),
-    callId: z.string(),
-    text: z.string(),
-  }),
-  /** Asked Thursday; she or the user through her answers. */
-  LineBase.extend({
-    kind: z.literal("waiting"),
-    callId: z.string(),
-    question: z.string(),
-    /** Only real options. Buttons on screen, read aloud in the call. */
-    options: z.string().array(),
+    question: z.boolean().optional(),
   }),
 ]);
 
-export type TaskLine = z.infer<typeof TaskLineSchema>;
+export type ThreadLine = z.infer<typeof ThreadLineSchema>;
 
 /** One line of where a job is: the bot's last text plus the tool it reached for after. Stops at a user-side line. */
-export function taskActivity(lines: TaskLine[], max = 120): string | null {
+export function threadActivity(lines: ThreadLine[], max = 120): string | null {
   let doing: string | null = null;
   for (let at = lines.length - 1; at >= 0; at--) {
     const line = lines[at];
@@ -334,14 +342,8 @@ export function taskActivity(lines: TaskLine[], max = 120): string | null {
     } else if (line.kind === "text") {
       return clip(doing ? `${line.text} → ${doing}` : line.text, max);
     } else if (line.kind === "ask") {
-      // ask_bot reads as "for"; ask_back (has parent) reads as a plain question
-      return clip(
-        line.parent
-          ? `asked ${line.to}: ${line.text}`
-          : `asked ${line.to} for: ${line.text}`,
-        max,
-      );
-    } else if (line.kind === "user" || line.kind === "waiting") {
+      return clip(`asked ${line.to}: ${line.text}`, max);
+    } else if (line.kind === "user") {
       break;
     }
   }
@@ -349,43 +351,52 @@ export function taskActivity(lines: TaskLine[], max = 120): string | null {
 }
 
 /**
- * What a `waiting` task asks: question from the row's `outcome`, options from
- * `pending`. `auto` is a stop the app picks back up by itself (TaskPending), so
+ * What a `waiting` thread asks: question from the row's `outcome`, options from
+ * `pending`. `auto` is a stop the app picks back up by itself (ThreadPending), so
  * nobody is told about it and nobody is rung for it.
  */
-export const TaskAskSchema = z.object({
+export const ThreadAskSchema = z.object({
   question: z.string(),
+  messageId: z.string().optional(),
+  bot: z.string().optional(),
   options: z.string().array(),
   auto: z.boolean(),
 });
 
-export type TaskAsk = z.infer<typeof TaskAskSchema>;
+export type ThreadAsk = z.infer<typeof ThreadAskSchema>;
 
-/** Task as the screen and voice tools see it. */
-export const TaskSchema = z.object({
+/** Thread as the screen and voice tools see it. */
+export const ThreadSchema = z.object({
   id: z.string(),
   bot: z.string(),
   label: z.string(),
   request: z.string(),
-  status: z.enum(TASK_STATUSES),
+  status: z.enum(THREAD_STATUSES),
   outcome: z.string().nullable(),
   /** Set only while `waiting`. */
-  ask: TaskAskSchema.nullable(),
+  ask: ThreadAskSchema.nullable(),
   /**
-   * Whether the user has had the ending: Thursday said it on a call, or a task
-   * list was on screen while it sat there. A cancel is seen by whoever cancelled.
-   * A highlight and a count, never a filter.
+   * Whether the user has had the ending: they opened the thread, or Thursday marked
+   * it once she had told them (`thread` `seen`). A cancel is seen by whoever
+   * cancelled. A highlight and a count, never a filter.
    */
   seen: z.boolean(),
-  /** Burned so far, across every segment including borrowed bots. */
+  /** Burned so far, across every participant. */
   tokens: TokenUsageSchema,
   /** Context size the model read on the last step (not a sum) and the compaction threshold (BOT_RUN.compactAt). 0 means no step ran yet. */
   contextTokens: z.number(),
   contextBudget: z.number(),
   createdAt: DateLikeSchema,
   updatedAt: DateLikeSchema,
-  /** Thread reduced for drawing; the model's messages stay on the server. */
-  lines: TaskLineSchema.array(),
+  /** Lines to draw; the model's messages stay on the server. */
+  lines: ThreadLineSchema.array(),
+  room: RoomViewSchema,
 });
 
-export type Task = z.infer<typeof TaskSchema>;
+export type Thread = z.infer<typeof ThreadSchema>;
+
+/** A participant can ask the user while other participants keep working. */
+export const needsThreadReply = (thread: {
+  status: string;
+  room: Thread["room"];
+}) => thread.status === "waiting" || thread.room.questions.length > 0;