thursday-agent 0.2.0 → 0.3.0

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

@@ -8,7 +8,7 @@ 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). `report` has its own execute because what it
+ * screen draws a call off its spec (task.query). `answer` has its own execute because what it
  * checks is a file on disk.
  */
 
@@ -45,12 +45,12 @@ export const askBotSpec = {
     request: z
       .string()
       .describe(
-        "The part they take, as a brief: 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. They see nothing but this and `context` — not the call, not your thread — so write it long rather than short; a brief that leaves them guessing costs a whole run.",
+        "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
       .string()
       .describe(
-        "The job you were given, quoted, and whatever you have found that bears on this part — exact values, and the paths of files you wrote for them to read. They cannot see your work, your tool output, or the call.",
+        "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.",
       ),
   }),
 };
@@ -103,41 +103,21 @@ export const askThursdaySpec = {
 
 /**
  * The one way a run ends on its own terms; the loop is stopped by it (`hasToolCall`, bot.run).
- * `complete` cannot be inferred: a run out of steps and a finished run look the same from outside.
- * `notes` is what the bot wants changed about its own instructions, in its own words — never
- * the text itself. A bot that rewrites the whole thing here edits it around the job it was on
- * and drops what that job was not about; a pass of its own writes it (features/bot/bot.notes).
+ * 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 reportSpec = (notes: boolean) => ({
-  name: TOOL_NAMES.report,
+export const answerSpec = {
+  name: TOOL_NAMES.answer,
   description:
-    "Hand back what the job produced. Calling this ends the job — nothing after it runs.",
+    "Answer the job you were given. Calling this ends the job — nothing after it runs.",
   parameters: z.object({
     result: z
       .string()
       .describe(
-        "The result itself, in a few lines — what you found or did, not a replay of how. Thursday reads this out loud, so write what a person needs to hear. If you could not do it, say what stopped you.",
+        "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.",
       ),
-    complete: z
-      .boolean()
-      .describe(
-        "True when the whole request is done. False when work is left over — the user is then asked whether to keep going, and `result` is what they decide on.",
-      ),
-    ...(notes
-      ? {
-          notes: reportNotes,
-        }
-      : {}),
   }),
-});
-
-/** Only attached while Settings > Bots keeps them (bot.schema BOT_NOTES_KEY). */
-const reportNotes = z
-  .string()
-  .nullish()
-  .describe(
-    "What should change in your own instructions before your next job here — something to add, something wrong to correct, something to drop. Your own words, any length; someone else writes it in. Nothing to say is the usual answer, and leaving it out costs nothing: they already say what they say.",
-  );
+};
 
 /** The voice session's handle on a job already handed over. Run by the server, like `delegate` (load-tools). */
 export const taskSpec = {
@@ -150,7 +130,7 @@ export const taskSpec = {
       .string()
       .nullish()
       .describe(
-        "The job, by its label or by the handle a past call's transcript carries. With `status`: null for every job in one line each — that is the list — or name one to get its report in full.",
+        '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.',
       ),
     answer: z
       .string()
@@ -168,36 +148,39 @@ export const askThursdayTool = tool({
 });
 
 /**
- * `report` does have an execute, and it only acknowledges. The loop is stopped
+ * `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 createReportTool = (notes: boolean) => {
-  const spec = reportSpec(notes);
-  return tool({
-    description: spec.description,
-    inputSchema: spec.parameters,
-    execute: async ({ result, complete }) => {
-      const missing = await missingFiles(result);
-      if (missing.length) {
-        return `${NOT_HANDED_BACK} these files do not exist — ${missing.join(", ")}. Write them first, or take the paths out of the result.`;
-      }
-      return complete
-        ? "Handed back. The job is closed; nothing further runs."
-        : "Handed back as unfinished. The user decides whether to continue.";
-    },
-  });
-};
+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.";
+  },
+});
 
 /**
- * A report naming a workspace file that does not exist is refused: the path becomes a link
+ * 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_HANDED_BACK = "Not handed back:";
+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 reportAccepted = (output: unknown): boolean =>
-  typeof output !== "string" || !output.startsWith(NOT_HANDED_BACK);
+export const answerAccepted = (output: unknown): boolean =>
+  typeof output !== "string" || !output.startsWith(NOT_ANSWERED);
 
 async function missingFiles(result: string): Promise<string[]> {
   const missing: string[] = [];

package/features/ai/tools/connected.ts

@@ -1,5 +1,5 @@
 import z from "zod";
-import { STUDIO_SERVER } from "@/config";
+import { CONNECTED_TOOL_TIMEOUT_MS, STUDIO_SERVER } from "@/config";
 import {
   McpAuthRequiredError,
   mcpManager,
@@ -80,6 +80,8 @@ export async function findConnectedSchemas(
 /**
  * Run one, wherever it lives. Long answers are folded (lib/sandbox fold). Failures are reported,
  * not thrown; a server that wants the user to sign in first comes back as its own status with the url.
+ * One deadline covers both sources (config CONNECTED_TOOL_TIMEOUT_MS): nothing behind this door
+ * bounds itself, and a tool that never answers would hold the job's step for good.
  */
 export async function callConnectedTool(
   sandbox: Sandbox,
@@ -88,11 +90,15 @@ export async function callConnectedTool(
   args: Record<string, unknown> | undefined,
   abortSignal?: AbortSignal,
 ): Promise<McpCallOutcome> {
+  const deadline = AbortSignal.timeout(CONNECTED_TOOL_TIMEOUT_MS);
+  const signal = abortSignal
+    ? AbortSignal.any([abortSignal, deadline])
+    : deadline;
   try {
     const text =
       server === STUDIO_SERVER
-        ? await callStudioTool(sandbox, name, args, abortSignal)
-        : await callMcpTool(server, name, args);
+        ? await callStudioTool(sandbox, name, args, signal)
+        : await callMcpTool(server, name, args, signal);
     if (typeof text !== "string") return text;
     return {
       status: "ok",
@@ -106,6 +112,12 @@ export async function callConnectedTool(
         authorizationUrl: error.authorizationUrl,
       };
     }
+    if (deadline.aborted && !abortSignal?.aborted) {
+      return {
+        status: "error",
+        text: `${name} on ${server} gave no answer in ${CONNECTED_TOOL_TIMEOUT_MS / 60_000} minutes and was given up on.`,
+      };
+    }
     return { status: "error", text: errorToString(error) };
   }
 }
@@ -131,9 +143,10 @@ async function callMcpTool(
   server: string,
   name: string,
   args: Record<string, unknown> | undefined,
+  signal: AbortSignal,
 ): Promise<string | McpCallOutcome> {
   const outcome = flattenToolResult(
-    await mcpManager.callTool(server, name, args),
+    await mcpManager.callTool(server, name, args, signal),
   );
   return outcome.status === "ok" ? outcome.text : outcome;
 }

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

@@ -1,22 +1,30 @@
 import { tool } from "ai";
 import * as z from "zod";
 import { appEvents } from "@/app/api/events/app-event.server";
+import { MEMORY_CONVERSATION_PAGE, MEMORY_LIMITS } from "@/config";
+import {
+  callStamp,
+  conversationLines,
+  saidStamp,
+} from "@/features/ai/prompts/prompt-helper";
 import { TOOL_NAMES } from "@/features/ai/tools/tool-name";
 import {
+  findFactCall,
   forgetFactById,
   readNotes,
   resolveNotePath,
   writeNotes,
 } from "@/features/memory/memory.query";
 import {
-  ALWAYS_LOADED_MAX,
-  isAlwaysListed,
+  APP_NAMED_NOTES,
+  appNoteLine,
+  isAppNamed,
   isMemoryPath,
-  MANY_FACTS,
-  MEMORY_ALWAYS_LISTED,
   MEMORY_INBOX,
+  type MemoryNoteView,
   type MemorySource,
 } from "@/features/memory/memory.schema";
+import { readCallConversation } from "@/features/thursday/thursday.query";
 
 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.";
@@ -24,16 +32,56 @@ const GONE =
 const WROTE =
   "Saved. The listing in your instructions is from when this session opened and will not show this until the next one — the note below is current.";
 
-/** Attached only when a note past MANY_FACTS is actually opened, instead of a standing rule in the prompt. */
-const tooMany = (path: string, count: number) =>
-  ` ${path} carries ${count} facts — enough that it is worth tidying. Put it on screen with \`${TOOL_NAMES.memory_show}\` and ask which of it they no longer need.`;
+/**
+ * A note as a model reads it: how many facts it holds now, and `said` on each
+ * fact a call wrote — the local time of that call, the same stamp its
+ * conversation opens with, so a fact from a call already in the prompt reads
+ * as that call. Never the Date itself: it would serialise as UTC.
+ */
+const withCount = (note: MemoryNoteView) => ({
+  ...note,
+  facts: note.facts.map(({ saidAt, ...fact }) =>
+    saidAt ? { ...fact, said: saidStamp(saidAt) } : fact,
+  ),
+  factCount: note.facts.length,
+});
+
+/** Why a fact has no conversation to open, by the hand that wrote it. */
+const noConversation = (source: MemorySource | null) =>
+  source === "user"
+    ? "Typed on the screen — there is no conversation behind it."
+    : source === "bot"
+      ? "Saved by a bot during a job — there is no conversation behind it."
+      : "The conversation it was saved in is not kept.";
+
+/**
+ * Said when a note has outgrown the recommended size, and only then — the write
+ * itself always goes through. It names no tool: this one answers the call and a
+ * bot, and only one of them has a screen to put a note on. How to do it is the
+ * call prompt's (prompts/thursday.prompt); the ask is the same either way,
+ * because a bot that turned up a fact can hand the same request back with it.
+ */
+const overSize = (count: number) =>
+  count > MEMORY_LIMITS.factsPerNote
+    ? ` This note now holds ${count} facts, past the ${MEMORY_LIMITS.factsPerNote} one note holds well. Ask the user which of it is no longer true and delete what they name.`
+    : "";
 
 /**
  * @param source Which hand these writes are recorded under. The runtime knows
- * it without being told — the call, the read-back pass — so no model ever
- * chooses it (load-tools, memory.schema MemorySource).
+ * it without being told, so no model ever chooses it (load-tools,
+ * memory.schema MemorySource).
+ * @param callId The call these tools serve, when there is one: recorded on
+ * what `memory_remember` writes, and the conversation `memory_conversation`
+ * does not hand back because the model is already in it.
+ * @param options.countReads Whether opening a note counts as reading it. The
+ * counts rank notes cold in the call prompt, so only a runtime that recalls on
+ * the user's behalf counts; an edit opening a note to change it does not.
  */
-export const createMemoryTools = (source: MemorySource) => ({
+export const createMemoryTools = (
+  source: MemorySource,
+  callId: string | null = null,
+  { countReads = true }: { countReads?: boolean } = {},
+) => ({
   [TOOL_NAMES.memory_recall]: tool({
     description: "Open one note from the listing, whole.",
     inputSchema: z.object({
@@ -44,14 +92,13 @@ export const createMemoryTools = (source: MemorySource) => ({
         ),
     }),
     execute: async ({ path }) => {
-      const { notes } = await readNotes([path]);
+      const { notes } = await readNotes([path], { touch: countReads });
       const note = notes[0];
       // A missing note is an answer to relay, not a reason to retry spellings
       if (!note)
         return { note: `Nothing on the listing called ${path.trim()}.` };
-      return note.facts.length > MANY_FACTS
-        ? { ...note, note: tooMany(note.path, note.facts.length).trim() }
-        : note;
+      const over = overSize(note.facts.length);
+      return over ? { ...withCount(note), note: over.trim() } : withCount(note);
     },
   }),
 
@@ -79,7 +126,7 @@ export const createMemoryTools = (source: MemorySource) => ({
             .boolean()
             .nullish()
             .describe(
-              `True carries this line into every call's instructions without opening its note — for what to call them, their language and register, a standing rule. At most ${ALWAYS_LOADED_MAX}. Null leaves it; false makes a carried line an ordinary fact.`,
+              `True carries this line into every call's instructions without opening its note — for what to call them, their language and register, a standing rule. At most ${MEMORY_LIMITS.carried}. Null leaves it; false makes a carried line an ordinary fact.`,
             ),
         })
         .array()
@@ -91,7 +138,7 @@ export const createMemoryTools = (source: MemorySource) => ({
         .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; ${MEMORY_ALWAYS_LISTED.join(" and ")} keep their own line.`,
+          `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.`,
         ),
       aliases: z
         .string()
@@ -106,11 +153,15 @@ export const createMemoryTools = (source: MemorySource) => ({
       const said = input.path.trim();
       const known = await resolveNotePath(said);
       const aliases = input.aliases ?? null;
-      // The listing line of the always-listed notes belongs to the app (memory.query ensureRootNotes);
-      // the model's description is ignored there. `alwaysLoad` is not forced on them either:
-      // the first-call opener (thursday.prompt) asks the model to set it.
-      const owned = isAlwaysListed(known ?? said);
-      const description = owned ? null : input.description?.trim() || 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.
+      const target = known ?? said;
+      const description = isAppNamed(target)
+        ? appNoteLine(target)
+        : input.description?.trim() || null;
       const facts = input.facts ?? [];
       if (!facts.length && !description && !aliases) {
         return {
@@ -126,14 +177,14 @@ export const createMemoryTools = (source: MemorySource) => ({
       // A new path outside the convention goes to inbox, which keeps its own line and takes no aliases
       const filed =
         known || isMemoryPath(said)
-          ? { path: known ?? said, description, aliases, facts }
+          ? { path: target, description, aliases, facts }
           : {
               path: MEMORY_INBOX,
-              description: "Facts with nowhere obvious to go",
+              description: appNoteLine(MEMORY_INBOX),
               facts,
             };
 
-      const write = await writeNotes([filed], source);
+      const write = await writeNotes([filed], source, callId);
 
       // The write already succeeded; what follows are requests, not failures.
       // A path filed elsewhere must be said, or the model reports it saved where it asked.
@@ -145,17 +196,71 @@ export const createMemoryTools = (source: MemorySource) => ({
       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).`
         : "";
-      // Carried lines are full: saved as an ordinary fact, and the user picks what to drop (ALWAYS_LOADED_MAX)
+      // Carried lines are full: saved as an ordinary fact, and the user picks what to drop (config MEMORY_LIMITS.carried)
       const notLoaded = write.notLoaded.length
-        ? ` All ${ALWAYS_LOADED_MAX} carried lines are taken, so ${write.notLoaded
+        ? ` All ${MEMORY_LIMITS.carried} carried lines are taken, so ${write.notLoaded
             .map((text) => `"${text}"`)
             .join(
               ", ",
             )} saved as an ordinary fact. Say which carried line you would drop for it and let them choose.`
         : "";
+      const written = withCount(write.notes[0]);
+      return {
+        ...written,
+        note: `${WROTE}${elsewhere}${unnamed}${notLoaded}${overSize(written.factCount)}`,
+      };
+    },
+  }),
+
+  [TOOL_NAMES.memory_conversation]: tool({
+    description:
+      "Open the conversation a fact was saved in, whole: what each side said, and which tools were used.",
+    inputSchema: z.object({
+      factId: z
+        .number()
+        .int()
+        .describe("The id that came with the fact when its note was opened."),
+      page: z
+        .number()
+        .int()
+        .min(1)
+        .nullish()
+        .describe(
+          `${MEMORY_CONVERSATION_PAGE} turns a page, oldest first. Null for the first.`,
+        ),
+    }),
+    execute: async ({ factId, page }) => {
+      const fact = await findFactCall(factId);
+      if (!fact) return { note: `No fact with id ${factId}.` };
+      if (!fact.callId) return { note: noConversation(fact.source) };
+      // Already in the model's context: handing it back only spends it twice
+      if (fact.callId === callId) {
+        return {
+          note: "Said in this call — it is the conversation you are in.",
+        };
+      }
+
+      const at = page ?? 1;
+      const read = await readCallConversation(
+        fact.callId,
+        at,
+        MEMORY_CONVERSATION_PAGE,
+      );
+      if (!read) return { note: noConversation(fact.source) };
+      const pages = Math.max(
+        1,
+        Math.ceil(read.total / MEMORY_CONVERSATION_PAGE),
+      );
+      if (at > pages) {
+        return {
+          note: `That conversation has ${pages} page${pages > 1 ? "s" : ""}.`,
+        };
+      }
       return {
-        ...write.notes[0],
-        note: `${WROTE}${elsewhere}${unnamed}${notLoaded}`,
+        when: callStamp(read.startedAt),
+        page: at,
+        pages,
+        conversation: conversationLines(read.turns),
       };
     },
   }),
@@ -216,47 +321,3 @@ what to drop and you drop it.`,
     },
   }),
 });
-
-/**
- * The bot's write. Same act under the same name, without what only the call can
- * do: no `replaces`, no carried lines, no naming a note — a bot has neither the
- * user in front of it nor the listing's history. Rare by nature; what the job
- * turned up belongs in the report, and only what outlives the job comes here.
- */
-export const botRememberTool = tool({
-  description:
-    "Save a lasting fact about the user. Only for what outlives this job; what the job itself turned up goes in the report.",
-  inputSchema: z.object({
-    path: z
-      .string()
-      .describe(
-        "Exactly as the listing writes it, or a new path following the same convention.",
-      ),
-    facts: z
-      .string()
-      .array()
-      .describe("One statement each, standing on its own later."),
-  }),
-  execute: async ({ path, facts }) => {
-    const said = path.trim();
-    const written = facts.map((text) => text.trim()).filter(Boolean);
-    if (!written.length) return { note: "Nothing to write: send a fact." };
-
-    const known = await resolveNotePath(said);
-    // A path outside the convention goes to inbox, as it does for the call
-    const filed = known || isMemoryPath(said) ? (known ?? said) : MEMORY_INBOX;
-
-    await writeNotes(
-      [{ path: filed, facts: written.map((text) => ({ text })) }],
-      "bot",
-    );
-
-    // A write filed elsewhere must be said, or the report claims the wrong place
-    return {
-      note:
-        filed === said
-          ? `Saved to ${filed}.`
-          : `Saved to ${filed}: "${said}" is not a path this listing can carry.`,
-    };
-  },
-});