thursday-agent 0.4.0 → 0.6.0

package/features/ai/tools/bot.tool.ts

@@ -1,21 +1,14 @@
-import { stat } from "node:fs/promises";
-import { tool } from "ai";
 import * as z from "zod";
+import { THREAD_STATUS_LIMIT } from "@/config";
 import { TOOL_NAMES } from "@/features/ai/tools/tool-name";
-import { pathsIn } from "@/features/workspace/file-kind";
-import { insideWorkspace } from "@/features/workspace/workspace";
-
-/**
- * Specs for the tools that move work between the voice session and bots. Only what the model
- * sees lives here; execution belongs to whoever runs the tool (load-tools, bot.run), and the
- * screen draws a call off its spec (task.query). `answer` has its own execute because what it
- * checks is a file on disk.
- */
+import { THREAD_CONTINUE } from "@/features/bot/bot.schema";
+import { RoomMessageSchema } from "@/features/bot/room.schema";
 
+/** Tools for starting a thread, sending messages, and following work from the call. */
 export const delegateSpec = {
   name: TOOL_NAMES.delegate,
   description:
-    "Hand a job to a bot. Returns immediately; the job runs in the background and its result is put in front of you later.",
+    "Hand a job to a bot. Returns a receipt at once; the job runs in the background and its updates reach the conversation on their own.",
   parameters: z.object({
     bot: z.string().describe("A name from the bot list."),
     request: z
@@ -32,166 +25,66 @@ export const delegateSpec = {
   }),
 };
 
-/**
- * `context` carries what the asking bot found, since its thread is not handed over (bot.run).
- * `request` is a brief, not a line: the borrowed bot sees nothing else.
- */
-export const askBotSpec = {
-  name: TOOL_NAMES.ask_bot,
+export const sendMessageSpec = {
   description:
-    "Hand one part of the job you are holding to another bot and wait for what they bring back. The job stays yours.",
-  parameters: z.object({
-    bot: z.string().describe("A name from the bot list."),
-    request: z
+    "Send a message to a participant or Thursday and receive a delivery receipt immediately. Mark a question for Thursday to request user input; ordinary messages to Thursday are notifications and need no answer.",
+  parameters: RoomMessageSchema.extend({
+    kind: RoomMessageSchema.shape.kind.describe(
+      "Use question only when Thursday must obtain an answer from the user: it ends your turn, and you continue when the answer arrives. Use message for bot collaboration, progress updates and reports.",
+    ),
+    options: RoomMessageSchema.shape.options.describe(
+      "With a question, offer concise answer choices when useful. Omit for an open-ended question; the user can always type their own answer.",
+    ),
+    to: z
       .string()
-      .describe(
-        "The part they take: the outcome you want, the shape to hand it back in (a path, a number, a list), and every name, path, number and limit that bears on it. It reaches them under the job and the call it came from, which are attached for you — write the part, not the job again.",
-      ),
-    context: z
+      .trim()
+      .min(1)
+      .describe("Choose a bot from the roster, or Thursday to reach the user."),
+    text: z
       .string()
+      .trim()
+      .min(1)
       .describe(
-        "What you have done on the job so far and why this part is theirs — exact values, and the paths of files you wrote for them to read. They see this, the part, the job and the call; not your thread or your tool output, so a value you leave out is one they fetch again.",
+        "Write the message and include the context the recipient needs.",
       ),
-  }),
-};
-
-/**
- * The borrowed bot's one way up. The borrowing bot answers in one model call over its own
- * context, without tools (bot.run answerBack); nothing stops. No options, since nobody reads
- * these aloud; the count is structural (bot.run MAX_ASK_BACK).
- */
-export const askBackSpec = {
-  name: TOOL_NAMES.ask_back,
-  description:
-    "Ask the bot that handed you this part. They answer from what they have — the original request, the call it came from, what they found before asking you.",
-  parameters: z.object({
-    question: z
+    replyTo: z
       .string()
+      .nullish()
       .describe(
-        "One whole question — what you need and why. They cannot take it to the user for you, so ask what they would know.",
+        "Use an incoming message ID to send an explicit reply; omit to start a new exchange. Your ordinary final text already replies to your current correspondent.",
       ),
   }),
 };
 
-/**
- * A bot stopping in front of something it cannot get on its own. No `execute` on purpose:
- * the loop halts on a tool without one (ai-sdk), the run is stored as `waiting`, and the
- * answer returns as this call's result on resume (bot.runner). Only the bot holding the job
- * may ask. Options are the one structure that works both on screen and read aloud; there is
- * no input type.
- */
-export const askThursdaySpec = {
-  name: TOOL_NAMES.ask_thursday,
-  description:
-    "Ask Thursday, who handed you this job. The job stops until an answer comes back.",
+/** The voice session's handle on a job already handed over. Run by the server, like `delegate` (load-tools). */
+export const threadSpec = {
+  name: TOOL_NAMES.thread,
+  description: `List up to ${THREAD_STATUS_LIMIT} jobs, prioritizing running and waiting work before recent endings; inspect one job, answer it, cancel it, open it on the user's screen, or mark it seen — the same as the user opening it, which takes it off the work waiting on them.`,
   parameters: z.object({
-    question: z
+    action: z.enum(["status", "answer", "cancel", "open", "seen"]),
+    recipient: z
       .string()
-      .describe(
-        "One whole question — what you need and why. One or two sentences, in the user's language: she may read it to them out loud, options and all.",
-      ),
-    // A string is accepted as well as an array: a provider may serialize the array as one
-    // joined string, and a schema rejection only loops. The reader takes arrays only (task.query optionsOf)
-    options: z
-      .union([z.string().array(), z.string()])
       .nullish()
       .describe(
-        'Only when there really are choices — two or three, each short, as an array: ["Signed in", "Not yet"]. Null for an open question.',
+        "With answer, name the participant to receive it. Words to a participant waiting on its question answer that question; omit to reach the only open question, or the coordinator when none is open.",
       ),
-  }),
-};
-
-/**
- * The one way a run ends on its own terms; the loop is stopped by it (`hasToolCall`, bot.run).
- * Whether the job is over is the runtime's to say, never an argument: an answer ends it, and a
- * run the app stopped first (bot.run `stopped`) waits to be continued.
- */
-export const answerSpec = {
-  name: TOOL_NAMES.answer,
-  description:
-    "Answer the job you were given. Calling this ends the job — nothing after it runs.",
-  parameters: z.object({
-    result: z
+    replyTo: z
       .string()
+      .nullish()
       .describe(
-        "The answer itself — what you found or did, not a replay of how. As long as the answer needs and no longer: one number is one line. In the user's language; the thread is on their screen. If you could not do it, say what stopped you.",
+        "With answer, use the message ID of the question being answered when several questions are open.",
       ),
-  }),
-};
-
-/** The voice session's handle on a job already handed over. Run by the server, like `delegate` (load-tools). */
-export const taskSpec = {
-  name: TOOL_NAMES.task,
-  description:
-    "Check a job you handed over, answer what it is asking, or cancel it.",
-  parameters: z.object({
-    action: z.enum(["status", "answer", "cancel"]),
-    task: z
+    thread: z
       .string()
       .nullish()
       .describe(
-        'The job, by its label or by the handle a past call\'s transcript carries. Leave it out with `answer` and it goes to the job that moved last — what "that one" means a moment after it answered. With `status`: null for every job in one line each — that is the list — or name one to get its answer in full.',
+        `Identify the job by label or ID. With status, omit or use null to list up to ${THREAD_STATUS_LIMIT} jobs, prioritizing open work and filling remaining places with recent endings; name one to read its full result and pending questions. With open, omit to show the job that moved last. With answer, omit only to answer the one question waiting.`,
       ),
     answer: z
       .string()
       .nullish()
       .describe(
-        "With `answer`: what to tell the bot — the answer to its question, a course correction for a job still running, or what to do next on one that finished.",
+        `With \`answer\`: what to tell the bot — the answer to its question, a course correction for a job still running, or what to do next on one that finished. \`${THREAD_CONTINUE}\` carries on a job that stopped before finishing, from where it was.`,
       ),
   }),
 };
-
-/** Deliberately no `execute` — the loop halts here. See askThursdaySpec. */
-export const askThursdayTool = tool({
-  description: askThursdaySpec.description,
-  inputSchema: askThursdaySpec.parameters,
-});
-
-/**
- * `answer` does have an execute, and it only acknowledges. The loop is stopped
- * by `hasToolCall` after the step, not by the absence of an execute — that way
- * the call and its result are both written to the thread, and a resumed run
- * reads a finished exchange rather than a call left hanging.
- */
-export const answerTool = tool({
-  description: answerSpec.description,
-  inputSchema: answerSpec.parameters,
-  execute: async ({ result }) => {
-    const missing = await missingFiles(result);
-    if (missing.length) {
-      return `${NOT_ANSWERED} these files do not exist — ${missing.join(", ")}. Write them first, or take the paths out of the answer.`;
-    }
-    return "Answered. The job is closed; nothing further runs.";
-  },
-});
-
-/**
- * An answer naming a workspace file that does not exist is refused: the path becomes a link
- * and opens by itself (bot.runner artifactIn). Paths outside the workspace are not checked.
- */
-const NOT_ANSWERED = "Not answered:";
-
-/**
- * `answer` was called `report` before it was renamed. A stored thread keeps the name the
- * call was made under, and the room draws that call as the job's prose — so the three
- * places that read messages back match either name. Nothing writes the old one.
- */
-export const isAnswerCall = (toolName: string): boolean =>
-  toolName === TOOL_NAMES.answer || toolName === "report";
-
-export const answerAccepted = (output: unknown): boolean =>
-  typeof output !== "string" || !output.startsWith(NOT_ANSWERED);
-
-async function missingFiles(result: string): Promise<string[]> {
-  const missing: string[] = [];
-  for (const rel of pathsIn(result)) {
-    const full = await insideWorkspace(rel);
-    if (!full) continue;
-    const exists = await stat(full).then(
-      (info) => info.isFile(),
-      () => false,
-    );
-    if (!exists) missing.push(rel);
-  }
-  return missing;
-}

package/features/ai/tools/call.tool.ts

@@ -11,7 +11,7 @@ export const endCallSpec = {
   name: TOOL_NAMES.end_call,
   description: `End the call.
 
-Say goodbye first — nothing said after this reaches the user.`,
+The line stays open until this runs, and drops once the goodbye being said is over.`,
   parameters: z.object({}),
 };
 

package/features/ai/tools/connected.ts

@@ -88,7 +88,8 @@ export async function callConnectedTool(
   server: string,
   name: string,
   args: Record<string, unknown> | undefined,
-  abortSignal?: AbortSignal,
+  /** `artifacts`: the calling bot's folder, where the studio saves what it makes (workspace.ts botArtifacts). */
+  { artifacts, abortSignal }: { artifacts: string; abortSignal?: AbortSignal },
 ): Promise<McpCallOutcome> {
   const deadline = AbortSignal.timeout(CONNECTED_TOOL_TIMEOUT_MS);
   const signal = abortSignal
@@ -97,7 +98,7 @@ export async function callConnectedTool(
   try {
     const text =
       server === STUDIO_SERVER
-        ? await callStudioTool(sandbox, name, args, signal)
+        ? await callStudioTool(sandbox, name, args, artifacts, signal)
         : await callMcpTool(server, name, args, signal);
     if (typeof text !== "string") return text;
     return {
@@ -126,6 +127,7 @@ async function callStudioTool(
   sandbox: Sandbox,
   name: string,
   args: Record<string, unknown> | undefined,
+  artifacts: string,
   abortSignal?: AbortSignal,
 ): Promise<string> {
   const tool = (await loadStudio()).find((one) => one.name === name);
@@ -135,7 +137,7 @@ async function callStudioTool(
       `"${name}" is not in the ${STUDIO_SERVER} right now — the key that runs it is gone.`,
     );
   }
-  return tool.execute(args ?? {}, { sandbox, abortSignal });
+  return tool.execute(args ?? {}, { sandbox, artifacts, abortSignal });
 }
 
 /** Definitions come from what the last connect stored (mcp.query); a session is opened only for a tool that runs (mcp.manager). */

package/features/ai/tools/mcp.tool.ts

@@ -2,6 +2,7 @@ import { jsonSchema, type ToolSet, tool } from "ai";
 import * as z from "zod";
 import { TOOL_NAMES } from "@/features/ai/tools/tool-name";
 import { findPinnedTools } from "@/features/connectors/mcp.query";
+import { botArtifacts } from "@/features/workspace/workspace";
 import type { Sandbox } from "@/lib/sandbox";
 import {
   callConnectedTool,
@@ -89,6 +90,7 @@ export async function createMcpTools(
     findPinnedTools(botName),
   ]);
   const tools: ToolSet = {};
+  const artifacts = botArtifacts(botName);
 
   for (const entry of pinned) {
     const key = toolNameFor(entry.server, entry.name);
@@ -110,13 +112,14 @@ export async function createMcpTools(
           entry.server,
           entry.name,
           (args ?? undefined) as Record<string, unknown> | undefined,
-          abortSignal,
+          { artifacts, abortSignal },
         ),
     });
   }
 
   // The search pair only when something is left to find; otherwise `tool_search` could only refuse
-  if (all.length > pinned.length) Object.assign(tools, searchPair(sandbox));
+  if (all.length > pinned.length)
+    Object.assign(tools, searchPair(sandbox, artifacts));
   return tools;
 }
 
@@ -132,7 +135,7 @@ async function whatExists(server: string): Promise<string> {
     : "Nothing is connected.";
 }
 
-const searchPair = (sandbox: Sandbox): ToolSet => ({
+const searchPair = (sandbox: Sandbox, artifacts: string): ToolSet => ({
   [TOOL_NAMES.tool_search]: tool({
     description: mcpToolSpec[TOOL_NAMES.tool_search].description,
     inputSchema: mcpToolSpec[TOOL_NAMES.tool_search].parameters,
@@ -179,7 +182,7 @@ const searchPair = (sandbox: Sandbox): ToolSet => ({
         server.trim(),
         name.trim(),
         args ?? undefined,
-        abortSignal,
+        { artifacts, abortSignal },
       );
     },
   }),

package/features/ai/tools/memory.tool.ts

@@ -15,16 +15,21 @@ import {
   writeNotes,
 } from "@/features/memory/memory.query";
 import {
-  APP_NAMED_NOTES,
   appNoteLine,
-  isAppNamed,
+  isAlwaysListed,
   isMemoryPath,
-  MEMORY_INBOX,
+  MEMORY_ALWAYS_LISTED,
+  MEMORY_PATHS,
   type MemoryNoteView,
   type MemorySource,
 } from "@/features/memory/memory.schema";
 import { readCallConversation } from "@/features/thursday/thursday.query";
 
+/** `profile, preferences, people/<name>, …` — the shapes a new note's path may take. */
+const PATH_SHAPES = MEMORY_PATHS.map((entry) =>
+  entry.path.endsWith("/") ? `${entry.path}<name>` : entry.path,
+).join(", ");
+
 const GONE =
   "Deleted for good. The listing in your instructions is from when this session opened and still shows it that way until the next one.";
 
@@ -107,7 +112,7 @@ export const createMemoryTools = (
       path: z
         .string()
         .describe(
-          "Exactly as the listing writes it, or a new path following the same convention.",
+          "The group this note is found by — the person, project or topic its facts are about. Exactly as the listing writes it, or a new path following the same convention. A fact goes under the one note it is about; other notes name it rather than repeat it.",
         ),
       facts: z
         .object({
@@ -121,7 +126,7 @@ export const createMemoryTools = (
             .int()
             .nullish()
             .describe(
-              "The id of the fact this replaces — from this note as handed back here or by `memory_recall`. Null if this is new. A fact that stopped being true is replaced rather than deleted, and so is a note saying the same thing twice: replacing keeps what changed on the record, deleting does not.",
+              `The id of the fact this replaces — from this note as handed back here or by \`${TOOL_NAMES.memory_recall}\`. Null if this is new. A fact that stopped being true is replaced rather than deleted, and so is a note saying the same thing twice: replacing keeps what changed on the record, deleting does not.`,
             ),
           alwaysLoad: z
             .boolean()
@@ -139,28 +144,27 @@ export const createMemoryTools = (
         .string()
         .nullish()
         .describe(
-          `One line saying what this note is about, not what it currently says. Give it for a new note, or when the line no longer fits. Null leaves it; ${APP_NAMED_NOTES.join(", ")} keep their own line.`,
+          `One line saying what this note holds, so the listing alone tells which facts are inside. Give it for a new note, and again with new facts: rewritten from the current line and the new facts together, so it covers the whole note rather than only what was added. Null leaves it; ${MEMORY_ALWAYS_LISTED.join(", ")} keep their own line.`,
         ),
       aliases: z
         .string()
         .array()
         .nullish()
         .describe(
-          'What the user calls this note out loud, in the language they say it — the words they would use to ask for it, not the facts inside. A note at people/yuri might be "Yuri" and "my wife". Replaces the set it has, so send the whole set. Null leaves it.',
+          'What the user calls this note out loud, in the language they say it — the words they would use to ask for it, not the facts inside. A note at people/partner might be "my partner" and their first name. Replaces the set it has, so send the whole set. Null leaves it.',
         ),
     }),
     execute: async (input) => {
-      // Resolve the name the way recall does (memory.query resolveNotePath), so a note opened by alias is written to itself, not inbox
+      // Resolve the name the way recall does (memory.query resolveNotePath), so a note opened by alias is written to itself
       const said = input.path.trim();
       const known = await resolveNotePath(said);
       const aliases = input.aliases ?? null;
-      // The listing line of the app-named notes is the app's (memory.schema
-      // isAppNamed); the model's description is ignored there and its own line
-      // written instead, so the inbox cannot end up described by whatever fell
-      // into it. `alwaysLoad` is not forced on them: the first-call opener
-      // (thursday.prompt) asks the model to set it.
+      // The listing line of the always-listed notes is the app's (memory.schema
+      // MEMORY_ALWAYS_LISTED); the model's description is ignored there and
+      // its own line written instead. `alwaysLoad` is not forced on them: its
+      // own schema says what it is for (what to call them, their language).
       const target = known ?? said;
-      const description = isAppNamed(target)
+      const description = isAlwaysListed(target)
         ? appNoteLine(target)
         : input.description?.trim() || null;
       const facts = input.facts ?? [];
@@ -169,31 +173,26 @@ export const createMemoryTools = (
           note: "Nothing to write: send facts, a line, names, or any of them.",
         };
       }
+      // Refused rather than filed elsewhere: a note is found by its path, line and names, and a catch-all keeps none of them
+      if (!known && !isMemoryPath(said)) {
+        return {
+          note: `Nothing was saved: "${said}" is not a path this listing can carry. Write it again under one of ${PATH_SHAPES}.`,
+        };
+      }
       // Naming amends, never creates: a note without facts is not listed (memory.query listNoteIndex)
       if (!known && !facts.length) {
         return {
           note: `Nothing on the listing called ${said}. A note comes into being with a fact — send at least one.`,
         };
       }
-      // A new path outside the convention goes to inbox, which keeps its own line and takes no aliases
-      const toInbox = !known && !isMemoryPath(said);
-      const filed = toInbox
-        ? {
-            path: MEMORY_INBOX,
-            description: appNoteLine(MEMORY_INBOX),
-            facts,
-          }
-        : { path: target, description, aliases, facts };
 
-      const write = await writeNotes([filed], source, callId);
+      const write = await writeNotes(
+        [{ path: target, description, aliases, facts }],
+        source,
+        callId,
+      );
 
       // The write already succeeded; what follows are requests, not failures.
-      // Only a path that landed in inbox is said: one reached by a name the
-      // listing carries is where it was asked for, however it was spelled.
-      const elsewhere = toInbox
-        ? ` Filed under ${filed.path}: "${said}" is not a path this listing can carry. If that is not where it belongs, write it again under one that is.`
-        : "";
-
       const unnamed = write.unnamed.length
         ? ` ${write.unnamed[0]} is new and has no line yet — the listing shows its first fact instead. Call again with \`description\` (one line about what it is) and \`aliases\` (the names they say for it).`
         : "";
@@ -206,9 +205,14 @@ export const createMemoryTools = (
             )} saved as an ordinary fact. Say which carried line you would drop for it and let them choose.`
         : "";
       const written = withCount(write.notes[0]);
+      // New facts under a line that was not resent: the listing is what a later call opens a note by
+      const stale =
+        known && facts.length && !description
+          ? ` Its line still reads "${written.description}"; if that no longer says what the note holds, send \`description\`.`
+          : "";
       return {
         ...written,
-        note: `${WROTE}${elsewhere}${unnamed}${notLoaded}${overSize(written.factCount)}`,
+        note: `${WROTE}${unnamed}${notLoaded}${stale}${overSize(written.factCount)}`,
       };
     },
   }),

package/features/ai/tools/skills.tool.ts

@@ -1,14 +1,16 @@
 import { tool } from "ai";
 import z from "zod";
 import { TOOL_NAMES } from "@/features/ai/tools/tool-name";
-import type { SkillMetadata } from "@/features/skills/skills.discover";
+import {
+  loadSkills,
+  type SkillMetadata,
+} from "@/features/skills/skills.discover";
 import { splitFrontmatter } from "@/features/skills/skills.query";
 import type { Sandbox } from "@/lib/sandbox";
 
 /**
- * A skill's full text is returned once per run; repeat loads get a pointer
- * back to the first result, since every step resends the whole context.
- * The tool set is built per run, so the `loaded` set lives in this closure.
+ * Reuse instructions only while their full text remains in this bot's context.
+ * A resume can carry them; compaction can remove them.
  */
 export const createSkillTools = ({
   skills,
@@ -17,7 +19,6 @@ export const createSkillTools = ({
   skills: SkillMetadata[];
   sandbox: Sandbox;
 }) => {
-  const loaded = new Set<string>();
   return {
     [TOOL_NAMES.load_skill]: tool({
       description:
@@ -26,25 +27,47 @@ export const createSkillTools = ({
         name: z
           .string()
           .describe(
-            "Exact name from the Skills list. Do not guess names that are not on it.",
+            "Exact name from the Skills list, or of a skill installed during this job. Do not guess names.",
           ),
       }),
-      execute: async ({ name }) => {
-        const skill = skills.find(
-          (s) => s.name.toLowerCase() === name.toLowerCase(),
-        );
+      execute: async ({ name }, { messages }) => {
+        const named = (list: SkillMetadata[]) =>
+          list.find((s) => s.name.toLowerCase() === name.toLowerCase());
+        // The list is read when the run starts; a skill installed since is only on disk
+        const listed = named(skills) ? skills : await loadSkills(sandbox);
+        const skill = named(listed);
         if (!skill) {
           return {
             error: `No skill named '${name}'.`,
-            available: skills.map((s) => s.name),
+            available: listed.map((s) => s.name),
           };
         }
 
         const skillFile = `${skill.path}/SKILL.md`;
-        if (loaded.has(skill.path)) {
+        const carried = messages.some(
+          (message) =>
+            Array.isArray(message.content) &&
+            message.content.some((part) => {
+              if (
+                part.type !== "tool-result" ||
+                part.toolName !== TOOL_NAMES.load_skill ||
+                part.output.type !== "json"
+              )
+                return false;
+              const value = part.output.value as {
+                skillDirectory?: string;
+                content?: string;
+              } | null;
+              return (
+                value?.skillDirectory === skill.path &&
+                typeof value.content === "string"
+              );
+            }),
+        );
+        if (carried) {
           return {
             skillDirectory: skill.path,
-            note: `You already loaded '${skill.name}' in this run — its instructions are above, unchanged. Scroll back to that result rather than reading it again; if you need the file itself, read ${skillFile} with the shell.`,
+            note: `Use the full '${skill.name}' instructions already in your conversation. To check for changes on disk, read ${skillFile} with the shell.`,
           };
         }
 
@@ -55,7 +78,6 @@ export const createSkillTools = ({
           path: skill.path,
           limit: 50,
         });
-        loaded.add(skill.path);
 
         return {
           skillDirectory: skill.path,