thursday-agent 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-<img src="docs/images/hero.png" alt="Thursday" width="760">
+<img src="docs/images/hero.png" alt="Thursday — an open-source voice agent with a face made of emoji" width="760">
 
 ### Everyone wanted Friday. This is Thursday.
 
-**A voice agent that lives on your machine.** You talk. It works. You keep talking.
+**An open-source voice agent that lives on your machine.** You talk. It works. You keep talking.
 
 [![npm](https://img.shields.io/npm/v/thursday-agent?style=flat-square&color=111&label=npm)](https://www.npmjs.com/package/thursday-agent)
 [![CI](https://img.shields.io/github/actions/workflow/status/cgoinglove/thursday/ci.yml?style=flat-square&label=ci)](https://github.com/cgoinglove/thursday/actions/workflows/ci.yml)
@@ -21,7 +21,7 @@
 npx thursday-agent
 ```
 
-One API key, typed into the first screen. No `.env`, no account, no cloud. That is the whole setup.
+One API key, typed into the first screen. Then say **"hey thursday."** No `.env`, no account, no cloud. That is the whole setup.
 
 <br>
 
@@ -35,6 +35,21 @@ You never watched a spinner. You never stopped talking.
 
 <br>
 
+## She has a face, and it is made of emoji
+
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/face-dark.png">
+  <img src="docs/images/face-light.png" alt="Thursday's face: an orb of emoji that swells when she speaks" width="280">
+</picture>
+</div>
+
+Hundreds of them, packed into one orb. When she talks, the rim swells with her voice and every syllable shakes a few loose — you can tell she is speaking with the sound off.
+
+Rather have letters, a sprinkle, or a plain mark with two eyes? Settings › Thursday.
+
+<br>
+
 ## A harness you talk to
 
 A **harness** is the layer around a model that decides what it sees, which tools it may call, where its commands run, and what survives the session. Claude Code, [OpenClaw](https://github.com/openclaw/openclaw) and [Hermes](https://github.com/NousResearch/hermes-agent) are harnesses, and they got very good this year.
@@ -64,7 +79,7 @@ The split is not new. OpenAI's own [realtime-agents](https://github.com/openai/o
 
 They are frameworks and demonstrations: excellent parts for building a voice agent. What they hand the supervisor is a tool list.
 
-Thursday hands it a machine — a shell, the Chrome you are already signed into, skills, connectors, a workspace, and jobs that keep running after you hang up. It is a harness first, and speech is how you operate it. That is the whole difference, and it is the half that takes the work.
+Thursday hands it a machine — a shell, a real browser, skills, connectors, a workspace, and jobs that keep running after you hang up. It is a harness first, and speech is how you operate it. That is the whole difference, and it is the half that takes the work.
 
 </details>
 
@@ -72,18 +87,19 @@ Thursday hands it a machine — a shell, the Chrome you are already signed into,
 
 ## What a bot actually has
 
-Not an API sandbox. **Your computer.**
+Not an API sandbox. **Your computer** — down to the Chrome you are already signed into, which no agent in someone else's cloud can borrow.
 
 - **A shell** — real commands on your real files
-- **A real browser** — and it attaches to the Chrome you are *already signed into*. Your email, your accounts, your 2FA already done. **A cloud agent physically cannot do this.**
+- **A real browser** — its own, or attached to your Chrome. When there is something for you to see — a checkout, a map, a sign-in — it opens a window on your screen and leaves it there
 - **Skills** — the browser, this Mac, building a page; `npx skills add` for the rest
 - **46 connectors** — Notion, GitHub, Linear, Slack, Figma, Stripe, Supabase… one click each
 - **A studio** — image, video, speech, transcription
+- **Its own memory** — what it learned doing the job, kept as files you can open on its page
 - **Each other** — a bot hands a part of its job to the bot that exists for it
 
-![A bot gets your shell, your skills, and the Chrome you are already signed into](docs/images/machine.png)
+![A bot gets your shell, your skills and a real browser — and leaves the checkout for you](docs/images/machine.png)
 
-It signs in where it has to, in a window you can watch, and stops at exactly one thing: **the password.** That half is yours. Everything else it finishes.
+It signs in the way you would let it: a session it kept, your own Chrome, you in the window it opened, or the login you gave it — after asking. And there is one button it never presses: **pay.** It takes the order to the last screen, leaves it open in front of you, and tells you what it buys and for how much.
 
 <br>
 
@@ -93,23 +109,25 @@ It signs in where it has to, in a window you can watch, and stops at exactly one
 
 Jarvis holds the job and decides neither half is his. Navigator opens six shops and reads them. Scribe builds the page out of what came back. It reaches you as one line, out loud — and the room is there to read if you ever want to know how.
 
+Those three come with her. Two more are ready-made in Settings — **Insta** draws the post, writes the caption and puts it up once you say so; **Voyage** plans the trip with a map for each day — and one of your own takes a name and a sentence.
+
 <br>
 
 ## Hang up. It keeps going.
 
-The job is not in the call. It runs on the server and the screen is a projection of it — so hang up mid-sentence, open a new tab, come back in ten minutes. She tells you what came in, or rings you, if you let her.
+The job is not in the call. It runs on the server and the screen is a projection of it — so hang up mid-sentence, open a new tab, come back in ten minutes. She tells you what came in, or rings you, if you let her. The tab says it too: `(2) Thursday` means two things are waiting on you.
 
 ![The call ends at 0:12; the job runs to 2:41](docs/images/keeps-going.png)
 
-Close the app entirely and it does the honest thing instead: ten seconds with no browser on it and every running job stops where it stands, keeps its thread, and waits for you to pick it back up. **Nothing spends your keys while you are not looking.**
+Close the app and it does the honest thing: ten seconds with no browser on it and every running job stops where it stands. **Nothing spends your keys while you are not looking.** Open it again and they pick themselves back up — the same after a restart, a `Ctrl+C`, or a model that went quiet for a minute.
 
 <br>
 
 ## It remembers you, and you can read it
 
-Plain notes on your disk. One fact per line. Open them in any editor; delete any of them.
+One fact per line, in the database on your disk. Open the Memory screen and read every one — where it came from, when it landed, whether it rides in every call — and delete any of them. Or type what changed, *"I moved to Busan"*, and watch the edit land.
 
-And after every call a text model **re-reads what was actually said** and reconciles the notes with it — so what she keeps is not only what she thought to write down mid-sentence.
+Every fact remembers the call it was said in, so when one line is not enough she can go back and read the conversation.
 
 <br>
 
@@ -117,10 +135,10 @@ And after every call a text model **re-reads what was actually said** and reconc
 
 | | |
 |---|---|
-| **Your browser** | Bots attach to the Chrome already open on your desk — your sessions, your logins |
+| **Your browser** | Bots drive a real browser on your machine — and can attach to the Chrome already open on your desk |
 | **Your machine** | Real commands on real files. Not a VM with a copy |
 | **Your keys** | A SQLite file on your disk, stripped from the shell a bot runs in |
-| **Your memory** | Plain text notes you can open, edit and delete |
+| **Your memory** | Facts in a database on your disk. Read, edit and delete them on the screen |
 | **No account** | Nothing to sign up for. The "server" is a Node process on `127.0.0.1` |
 
 **Honest caveat:** the *intelligence* is remote. There is no local realtime speech model worth putting a call on yet, so the audio goes to OpenAI or xAI. Everything else never leaves the machine. When a local voice model lands, this is the app that is ready for it.
@@ -141,7 +159,7 @@ It runs in the terminal you started it in, like `n8n`. There is no daemon and no
 
 | | |
 |---|---|
-| **Stop it** | `Ctrl+C` |
+| **Stop it** | `Ctrl+C` — running jobs are parked and pick up at the next start |
 | **Start it again** | the same `npx thursday-agent` |
 | **Close the terminal** | it stops with the terminal — nothing is left running |
 | **Keep it up while you work** | run it in its own tab, or `npx thursday-agent &` |
@@ -153,7 +171,12 @@ It runs in the terminal you started it in, like `n8n`. There is no daemon and no
 ```
 ~/.thursday
 ├── local.db          calls, memory, bots, jobs, keys
-└── .ai-workspace     what the bots wrote: artifacts, scratch, skills
+└── .ai-workspace
+    ├── artifacts/    what the bots made for you
+    ├── projects/     code they build
+    ├── bots/         each bot's own memory and kept sign-ins
+    ├── .agents/      skills you installed
+    └── scratch/      one folder per job, cleared three days after it ends
 ```
 
 The first run also fetches the browser bots drive (~280 MB) in the background, once. That one lands in Playwright's own cache — `~/Library/Caches/ms-playwright`, or `~/.cache/ms-playwright` on Linux — so every run after it, and every upgrade, skips the download.
@@ -178,7 +201,7 @@ Node 22.18+ and pnpm 10+. The first run fetches the browser bots drive (~280 MB)
 | | Providers |
 |---|---|
 | **Voice** (the call) | OpenAI Realtime · xAI Grok Voice |
-| **Text** (the bots) | OpenAI · Anthropic · Google · xAI · Vercel AI Gateway — every model it carries, live |
+| **Text** (the bots) | OpenAI · Anthropic · Google · xAI · Vercel AI Gateway — every model it carries, live · your ChatGPT plan, by signing in |
 | **Studio** | OpenAI · Google · xAI · Vercel AI Gateway |
 
 Every bot can run on its own model. Give the errand-runner something cheap and the planner something good.
@@ -190,12 +213,12 @@ Every bot can run on its own model. Give the errand-runner something cheap and t
 
 - "What did I download this week?" — one command, run while you talk
 - "Remember my sister's birthday is March 3rd." — saved the moment it lands
-- "Anything from my landlord in my email?" — attaches to the Chrome you are signed into
-- "Set up a Google account just for my bots." — stops at the password, then carries on
+- "Anything from my landlord in my email?" — read in the Chrome you are signed into
+- "Find the cheapest flight to Osaka on the 14th." — left at the pay button, on your screen
+- "Plan three days in Kyoto, with a map for each day." — Voyage
+- "Make a post about Friday's gig and put it on Instagram." — Insta, once you say so
 - "Write up what we decided today as a one-pager." — opens as a document, not a chat bubble
-- "Draw me a logo for a bakery called Crumb."
 - "Go through my card statements and list every subscription I am paying for."
-- "Book a table for four on Friday, somewhere my sister can actually eat."
 - "Watch this page and tell me when the price drops."
 - "Build me a page of thirty wedding pose photos."
 
@@ -215,7 +238,9 @@ Tell me what you said to her and where it stopped. That is the roadmap.
 
 ## The part where I am honest with you
 
-She is a language model with a shell, a browser and your API keys. **That is the product, not an accident.** Keys never reach the shell. Writes are fenced to a workspace. The server is localhost-only. Passwords, one-time codes and passkeys stay yours to type.
+She is a language model with a shell, a browser and your API keys. **That is the product, not an accident.** Keys are stripped from the environment the shell runs in. The server is localhost-only. A login you gave a bot is asked about before it is used, and a payment is left for you to press — instructions a skill carries, not a lock the code holds.
+
+The shell is not fenced, and it is not meant to be — a bot that cannot look around cannot do the job, and a command writes wherever you can. That includes the database your keys sit in.
 
 It is not a sandbox and it does not pretend to be. → [SECURITY.md](SECURITY.md)
 

package/app/api/bot/memory/files/route.ts

@@ -0,0 +1,14 @@
+import { WORKSPACE_VIEW } from "@/config";
+import { listBotMemory } from "@/features/bot/bot.memory";
+import { serverRoute } from "@/lib/protocol/server-route";
+import { publicError } from "@/lib/public-error";
+
+/**
+ * One bot's own memory, newest first. `?bot=` names it; read only — a file is
+ * deleted through workspace.action, like any file a bot wrote.
+ */
+export const GET = serverRoute(async (request) => {
+  const bot = new URL(request.url).searchParams.get("bot")?.trim();
+  if (!bot) publicError("Which bot?");
+  return listBotMemory(bot, WORKSPACE_VIEW.rows);
+});

package/app/api/bot/memory/route.ts

@@ -0,0 +1,5 @@
+import { readBotMemoryOn } from "@/features/bot/bot.query";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/** Whether bots keep their own memory at all. Read only; the write is bot.action. */
+export const GET = serverRoute(() => readBotMemoryOn());

package/app/api/events/app-event.ts

@@ -12,12 +12,8 @@ export type AppEvent =
   | { type: "memory" }
   /** Signal: a server was registered, removed, synced, or finished OAuth. */
   | { type: "mcp" }
-  /** Signal: a read-back started or ended (memory/tidy.query). */
-  | { type: "memory-tidy" }
-  /** Data: a read-back ended on its own. `tally` is one line of what changed, or why it failed. */
-  | { type: "memory-tidied"; failed: boolean; tally: string }
-  /** Data: show this note on screen, or hide it when null (memory.tool). */
-  | { type: "memory-view"; path: string | null }
+  /** Signal: a sign-in was written away from the settings screen (ai/chatgpt's sign-in answer). */
+  | { type: "config" }
   /** Data: a finished job produced a document; `path` is workspace-relative. */
   | { type: "artifact"; taskId: string; label: string; path: string };
 
@@ -36,7 +32,7 @@ export const SIGNALS: Record<Signal, true> = {
   tasks: true,
   memory: true,
   mcp: true,
-  "memory-tidy": true,
+  config: true,
 };
 
 export const isSignal = (

package/app/api/llm-model/credits/route.ts

@@ -0,0 +1,11 @@
+import { readGatewayCredits } from "@/features/ai/model";
+import type { GatewayCredits } from "@/features/ai/model.schema";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/**
+ * What is left on the gateway key, null when none is set. Read by the gateway's
+ * row in Settings › Keys and its key dialog; the answer is built in ai/model.
+ */
+export const GET = serverRoute(
+  async (): Promise<GatewayCredits | null> => readGatewayCredits(),
+);

package/app/api/llm-model/route.ts

@@ -1,3 +1,4 @@
+import { readChatGptPlan } from "@/features/ai/chatgpt";
 import {
   type AiProvider,
   TEXT_MODEL_PROVIDER_LIST,
@@ -5,7 +6,7 @@ import {
 import { readConfig } from "@/features/config/config.query";
 import { serverRoute } from "@/lib/protocol/server-route";
 
-/** Callable providers and whether each one's key is set. */
+/** Callable providers, whether each one's key is set, and the plan a sign-in is on. */
 export const GET = serverRoute(async () =>
   Promise.all(
     TEXT_MODEL_PROVIDER_LIST.map(
@@ -15,6 +16,10 @@ export const GET = serverRoute(async () =>
         apiKeyName: item.apiKeyName,
         suggestModels: item.suggestModels,
         hasKey: Boolean(await readConfig(item.apiKeyName)),
+        ...(item.signIn && {
+          signIn: true as const,
+          plan: await readChatGptPlan(),
+        }),
       }),
     ),
   ),

package/app/api/llm-model/subscription/route.ts

@@ -0,0 +1,11 @@
+import { readChatGptUsage } from "@/features/ai/chatgpt";
+import type { SubscriptionUsage } from "@/features/ai/model.schema";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/**
+ * How much of the GPT Subscription plan is used, null when nobody is signed in. Read by its
+ * row in Settings › Keys and its sign-in dialog; the answer is built in ai/chatgpt.
+ */
+export const GET = serverRoute(
+  async (): Promise<SubscriptionUsage | null> => readChatGptUsage(),
+);

package/app/api/memory/edit/route.ts

@@ -0,0 +1,7 @@
+import { streamMemoryEdit } from "@/features/memory/memory.edit";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/** An edit from the memory screen, streamed as it runs (memory.edit). */
+export const POST = serverRoute(async (request) =>
+  streamMemoryEdit(await request.json(), request.signal),
+);

package/app/api/memory/route.ts

@@ -0,0 +1,21 @@
+import { findAllNotes, findNoteByPath } from "@/features/memory/memory.query";
+import { serverRoute } from "@/lib/protocol/server-route";
+import { publicError } from "@/lib/public-error";
+
+/**
+ * Read only; writes go through memory.action. One MemoryNote[] page, `?offset=`
+ * for the next. `?path=` returns one note: paths contain `/`, so not a segment.
+ */
+export const GET = serverRoute(async (request) => {
+  const params = new URL(request.url).searchParams;
+
+  const path = params.get("path");
+  if (path) {
+    const note = await findNoteByPath(path);
+    if (!note) publicError("Note not found");
+    return note;
+  }
+
+  const offset = Number(params.get("offset") ?? 0);
+  return findAllNotes({ offset: Number.isFinite(offset) ? offset : 0 });
+});

package/app/api/query-key.ts

@@ -24,8 +24,6 @@ export const queryKey = {
   /** One note with all facts, by path. Paths contain `/`, so it is a query, not a
    *  segment: pass the hook null instead of building this key when closed. */
   notePath: (path: string) => ({ url: "/api/memory", query: { path } }),
-  /** MemoryTidyStatusView: settings, what is pending, the pass in progress and the last one. Under the memory prefix on purpose: a fact changing moves it too. */
-  memoryTidy: "/api/memory/tidy",
 
   /** MCPServerSummary[] with tool counts, no tools */
   mcp: "/api/mcp",
@@ -56,8 +54,13 @@ export const queryKey = {
    */
   bot: "/api/bot",
 
-  /** boolean: whether bots keep their own instructions (Settings > Bots) */
-  botNotes: "/api/bot/notes",
+  /** boolean: whether bots keep their own memory (Settings > Bots) */
+  botMemory: "/api/bot/memory",
+  /** BotMemory: one bot's own memory files, newest first (Settings > Bots) */
+  botMemoryFiles: (bot: string) => ({
+    url: "/api/bot/memory/files",
+    query: { bot },
+  }),
 
   /**
    * Inbox: Task[] newest first with threads, everything running or asking plus
@@ -136,9 +139,21 @@ export const queryKey = {
    * {toolCallId, callId, name, input}; one JSON Result per call, abortable.
    */
   toolCall: "/api/thursday/tool-call",
+  /** POST, an edit from the memory screen, streamed as it runs (memory.edit). */
+  memoryEdit: "/api/memory/edit",
 
   /** Providers this app can call and whether each key is set */
   llmModel: "/api/llm-model",
   /** Models reachable with the AI Gateway key; gateway only */
   modelCatalog: "/api/llm-model/catalog",
+  /**
+   * GatewayCredits | null: what is left on the gateway key, null without one.
+   * Under `llmModel`, so the key dialog's revalidate re-reads it after a save.
+   */
+  gatewayCredits: "/api/llm-model/credits",
+  /**
+   * SubscriptionUsage | null: how much of the GPT Subscription plan is used, null when
+   * signed out. Under `llmModel`, so signing in or out re-reads it.
+   */
+  subscriptionUsage: "/api/llm-model/subscription",
 } as const;

package/bin/port.mjs

@@ -0,0 +1,65 @@
+// Which port the app serves on. Plain JavaScript and no app imports: both
+// starters run it before anything is built — `thursday` (bin/thursday.mjs) and
+// `pnpm dev` (scripts/dev.mts).
+
+import { createServer } from "node:net";
+
+/** The port when none is asked for. */
+const DEFAULT_PORT = 3000;
+/** How far past it to look before giving up. */
+const SEARCH = 20;
+
+/**
+ * Every address a holder of the port may have bound. No single probe sees them
+ * all: on macOS a socket on 127.0.0.1 does not block `::`, and one on `::` does
+ * not block 127.0.0.1 — yet `localhost` reaches whichever answers first, so two
+ * servers "on 3000" each serve some of the page. Probed one at a time, since
+ * `0.0.0.0` and `::` block each other.
+ */
+const ADDRESSES = ["127.0.0.1", "::1", "0.0.0.0", "::"];
+
+/** No IPv6 on this machine: nobody can hold that address either. */
+const UNBINDABLE = new Set(["EADDRNOTAVAIL", "EAFNOSUPPORT"]);
+
+const heldAt = (port, host) =>
+  new Promise((resolve) => {
+    const probe = createServer()
+      .once("error", (cause) => resolve(!UNBINDABLE.has(cause.code)))
+      .once("listening", () => probe.close(() => resolve(false)));
+    probe.listen(port, host);
+  });
+
+/** Whether something already holds the port, on any address. */
+async function taken(port) {
+  for (const host of ADDRESSES) {
+    if (await heldAt(port, host)) return true;
+  }
+  return false;
+}
+
+/**
+ * 3000 is the most occupied port on a developer's machine. A port nobody asked
+ * for is ours to move; a port that was asked for (`--port`, `PORT`) is not, and
+ * saying so is more use than moving it quietly. Exits with the reason when no
+ * port will do.
+ */
+export async function freePort(asked) {
+  const wanted = asked?.trim() || undefined;
+  const from = Number(wanted ?? DEFAULT_PORT);
+  if (!Number.isInteger(from) || from < 1 || from > 65535) {
+    console.error(`\n  Not a port: ${wanted}\n`);
+    process.exit(1);
+  }
+  if (!(await taken(from))) return from;
+  if (wanted !== undefined) {
+    console.error(
+      `\n  Port ${from} is already in use.\n  Try another: --port ${from + 1}\n`,
+    );
+    process.exit(1);
+  }
+  for (let port = from + 1; port < from + SEARCH; port++) {
+    if (!(await taken(port))) return port;
+  }
+  console.error(`\n  Nothing free between ${from} and ${from + SEARCH}.\n`);
+  process.exit(1);
+}

package/bin/thursday.mjs

@@ -6,9 +6,9 @@
 import { spawn } from "node:child_process";
 import { existsSync, symlinkSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { createServer } from "node:net";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { freePort } from "./port.mjs";
 import { ROOT, toolPath } from "./tools.mjs";
 
 const { version, name } = JSON.parse(
@@ -34,7 +34,7 @@ if (has("-h", "--help")) {
     $ thursday [options]
 
   Options
-    --port <n>     Port to serve on (default 3000)
+    --port <n>     Port to serve on (default 3000, or the next free one)
     --home <dir>   Where your data lives (default ~/.thursday)
     --no-open      Do not open a browser
     -v, --version  Print the version
@@ -50,37 +50,6 @@ if (has("-v", "--version")) {
   process.exit(0);
 }
 
-/** Whether something already holds the port we are about to bind. */
-const taken = (port) =>
-  new Promise((resolve) => {
-    const probe = createServer()
-      .once("error", () => resolve(true))
-      .once("listening", () => probe.close(() => resolve(false)))
-      .listen(port, "127.0.0.1");
-  });
-
-/**
- * 3000 is the most occupied port on a developer's machine, and the first thing
- * `npx thursday-agent` does is bind it — so an untouched install used to end in
- * an EADDRINUSE stack trace. A port nobody asked for is ours to move; a port
- * that was asked for is not, and saying so is more use than moving it quietly.
- */
-async function freePort(asked) {
-  const from = Number(asked ?? 3000);
-  if (!(await taken(from))) return from;
-  if (asked !== undefined) {
-    console.error(
-      `\n  Port ${from} is already in use.\n  Try another: thursday --port ${from + 1}\n`,
-    );
-    process.exit(1);
-  }
-  for (let port = from + 1; port < from + 20; port++) {
-    if (!(await taken(port))) return port;
-  }
-  console.error(`\n  Nothing free between ${from} and ${from + 20}.\n`);
-  process.exit(1);
-}
-
 const asked = flag("port") ?? process.env.PORT;
 const port = String(await freePort(asked));
 const home = resolve(flag("home") || process.env.THURSDAY_HOME || DEFAULT_HOME);
@@ -138,6 +107,9 @@ const child = spawn(process.execPath, [join(APP, "server.js")], {
     // This machine only. A voice agent with a shell is not a thing to expose.
     HOSTNAME: process.env.HOSTNAME || "127.0.0.1",
     NODE_ENV: "production",
+    // The server parks running jobs on a stop before it exits (instrumentation);
+    // without this, Next exits on the signal first
+    NEXT_MANUAL_SIG_HANDLE: "true",
   },
 });