thursday-agent 0.1.1 → 0.2.0

package/README.md

@@ -133,7 +133,30 @@ And after every call a text model **re-reads what was actually said** and reconc
 npx thursday-agent
 ```
 
-Opens at `localhost:3000`. One OpenAI or xAI key opens the call — a voice key is also a text key, so one is enough to run everything. Data lives in `~/.thursday`.
+Opens at `localhost:3000`, or the next free port if something already has it. One OpenAI or xAI key opens the call — a voice key is also a text key, so one is enough to run everything.
+
+### Running it
+
+It runs in the terminal you started it in, like `n8n`. There is no daemon and nothing is installed into your login items.
+
+| | |
+|---|---|
+| **Stop it** | `Ctrl+C` |
+| **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 &` |
+| **Another port** | `npx thursday-agent --port 4000` |
+| **Somewhere else on disk** | `npx thursday-agent --home ~/work/thursday` |
+
+**Your data outlives all of it.** Everything you say, everything the bots write, your keys and your memory live in `~/.thursday`, never inside the package — so restarting, rebooting, or upgrading to the next version keeps every call and every file. Deleting that folder is the uninstall.
+
+```
+~/.thursday
+├── local.db          calls, memory, bots, jobs, keys
+└── .ai-workspace     what the bots wrote: artifacts, scratch, skills
+```
+
+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.
 
 <details>
 <summary><b>From source</b></summary>

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

@@ -0,0 +1,24 @@
+"use client";
+
+import { useEffect } from "react";
+import { queryKey } from "@/app/api/query-key";
+import { createEventBus, type EventHandlers } from "@/lib/protocol/events";
+import { fromEventSource, useEventFeed } from "@/lib/protocol/events.client";
+import type { AppEvent } from "./app-event";
+
+/** Browser-side bus. Only server events flow here; `emit` is not exported. */
+const bus = createEventBus<AppEvent>();
+
+/** Subscribes to server events; pass handlers for the types you care about. */
+export function useAppEvent(handlers: EventHandlers<AppEvent>) {
+  useEventFeed(bus, handlers);
+}
+
+/**
+ * Opens the one connection per tab, from the root layout. EventSource
+ * reconnects on its own and replays the on-connect events.
+ */
+export function AppEventSource() {
+  useEffect(() => fromEventSource(queryKey.events, bus), []);
+  return null;
+}

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

@@ -0,0 +1,45 @@
+import { BROWSER_GONE_MS } from "@/config";
+import { createEventBus, type EventBus } from "@/lib/protocol/events";
+import {
+  createEventStream,
+  type EventStream,
+} from "@/lib/protocol/events.server";
+import { createPresence, type Presence } from "@/lib/protocol/presence";
+import { type AppEvent, isSignal } from "./app-event";
+
+/**
+ * Server-side bus and the stream that carries it to the browser. Pinned on
+ * globalThis because next dev reloads this module while open streams still
+ * subscribe to the first bus.
+ */
+type Pinned = {
+  __appEvents?: EventBus<AppEvent>;
+  __appEventStream?: EventStream<AppEvent>;
+  __presence?: Presence;
+  __bootId?: string;
+};
+const pinned = globalThis as Pinned;
+
+export const appEvents: EventBus<AppEvent> = (pinned.__appEvents ??=
+  createEventBus<AppEvent>());
+
+/**
+ * Whether a browser is on the stream. The app stops what it is doing when the
+ * last one has been gone for BROWSER_GONE_MS; who stops what is wired at boot
+ * (instrumentation), not here.
+ */
+export const presence: Presence = (pinned.__presence ??=
+  createPresence(BROWSER_GONE_MS));
+
+/** Signals coalesce over 150ms; data events pass through. */
+export const appEventStream: EventStream<AppEvent> =
+  (pinned.__appEventStream ??= createEventStream(appEvents, {
+    coalesce: {
+      ms: 150,
+      keyOf: (event) => (isSignal(event) ? event.type : null),
+    },
+    onWatchers: presence.track,
+  }));
+
+/** Identifies this server process; changes on restart. */
+export const BOOT_ID: string = (pinned.__bootId ??= crypto.randomUUID());

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

@@ -0,0 +1,44 @@
+/**
+ * Every event the server sends the browser. Two kinds: a signal carries no data
+ * and the receiver revalidates the matching GET; a data event is the value
+ * itself. A new signal must also be added to `SIGNALS` below.
+ */
+export type AppEvent =
+  /** Sent on connect. A changed `boot` means the server restarted; re-read everything. */
+  | { type: "hello"; boot: string }
+  /** Signal: a task changed (every write in bot.query). */
+  | { type: "tasks" }
+  /** Signal: a note or fact changed. */
+  | { 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 }
+  /** Data: a finished job produced a document; `path` is workspace-relative. */
+  | { type: "artifact"; taskId: string; label: string; path: string };
+
+/** Union members carrying nothing but `type`. */
+type Signal<E = AppEvent> = E extends AppEvent
+  ? keyof E extends "type"
+    ? E["type"]
+    : never
+  : never;
+
+/**
+ * Signals are coalesced before sending (app-event.server). The `Record` type
+ * makes a signal missing here a compile error.
+ */
+export const SIGNALS: Record<Signal, true> = {
+  tasks: true,
+  memory: true,
+  mcp: true,
+  "memory-tidy": true,
+};
+
+export const isSignal = (
+  event: AppEvent,
+): event is Extract<AppEvent, { type: Signal }> => event.type in SIGNALS;

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

@@ -0,0 +1,12 @@
+import { readGatewayCatalog } from "@/features/ai/model";
+import type { GatewayModel } from "@/features/ai/model.schema";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/**
+ * Everything the gateway carries, every modality in one listing. It answers
+ * unauthenticated, so the shelf reads before a key is set; only running a model
+ * needs one. The answer is built in ai/model, where `callableRows` reads the same list.
+ */
+export const GET = serverRoute(
+  async (): Promise<GatewayModel[]> => readGatewayCatalog(),
+);

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

@@ -0,0 +1,21 @@
+import {
+  type AiProvider,
+  TEXT_MODEL_PROVIDER_LIST,
+} from "@/features/ai/model.schema";
+import { readConfig } from "@/features/config/config.query";
+import { serverRoute } from "@/lib/protocol/server-route";
+
+/** Callable providers and whether each one's key is set. */
+export const GET = serverRoute(async () =>
+  Promise.all(
+    TEXT_MODEL_PROVIDER_LIST.map(
+      async (item): Promise<AiProvider> => ({
+        id: item.id,
+        label: item.label,
+        apiKeyName: item.apiKeyName,
+        suggestModels: item.suggestModels,
+        hasKey: Boolean(await readConfig(item.apiKeyName)),
+      }),
+    ),
+  ),
+);

package/app/api/query-key.ts

@@ -0,0 +1,144 @@
+/**
+ * Every endpoint the browser reads. Keys double as SWR cache keys; `revalidate`
+ * matches by url prefix, so invalidating `queryKey.memory` also refreshes
+ * `queryKey.notePath(path)`. Writes go through server actions, not here.
+ */
+/** Encodes per segment, keeping the path's `/`. */
+const encodePath = (path: string) =>
+  path.split("/").map(encodeURIComponent).join("/");
+
+/**
+ * Inverse of encodePath for catch-all segments. No decoding: Next already
+ * decodes segments, and decoding again throws on names containing `%`.
+ */
+export const decodePath = (segments: string[]) => segments.join("/");
+
+export const queryKey = {
+  /** MemoryNote[] first page: pinned first, then by warmth */
+  memory: "/api/memory",
+  /** Next page; `offset` is the count received so far */
+  memoryPage: (offset: number) => ({
+    url: "/api/memory",
+    query: { offset: offset || null },
+  }),
+  /** 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",
+  /** MCPServer, one server with its tools */
+  mcpServer: (name: string | null) => ({
+    url: "/api/mcp",
+    pathVariable: [name],
+  }),
+
+  /** Every MCP tool across servers, flat */
+  mcpTools: "/api/mcp/tools",
+
+  /** SkillSummary[], custom first */
+  skills: "/api/skills",
+  /**
+   * SkillNode: a folder listing or a file's text inside a skill.
+   * `path` is relative to the skill folder; "" is the skill itself.
+   */
+  skillNode: (source: string | null, dir: string | null, path: string) => ({
+    url: "/api/skills",
+    pathVariable: [source, dir],
+    query: { path },
+  }),
+
+  /**
+   * Bot[]. `tasks` and `taskHistory` sit under this prefix, so editing a bot
+   * also revalidates the inbox and loaded history pages.
+   */
+  bot: "/api/bot",
+
+  /** boolean: whether bots keep their own instructions (Settings > Bots) */
+  botNotes: "/api/bot/notes",
+
+  /**
+   * Inbox: Task[] newest first with threads, everything running or asking plus
+   * the most recent finished few. Read by use-thursday only; the `tasks` signal
+   * triggers revalidation, with a 30s poll as fallback.
+   */
+  tasks: "/api/bot/task",
+  /**
+   * History page: Task[] newest first. `before` is the last page's final
+   * updatedAt (ISO), null for the first page.
+   */
+  taskHistory: (before: string | null) => ({
+    url: "/api/bot/task",
+    query: { history: 1, before },
+  }),
+  /** ResultPart[]: the full result of one tool call; lists carry only a few lines. */
+  toolResult: (taskId: string | null, callId: string | null) => ({
+    url: "/api/bot/task",
+    pathVariable: [taskId],
+    query: { call: callId },
+  }),
+  /**
+   * WorkspaceFolder: one folder's rows, and nothing below them. The bare key
+   * is the root, so invalidating it refreshes every folder.
+   */
+  workspace: "/api/workspace",
+  workspaceFolder: (path: string, rows: number) => ({
+    url: "/api/workspace",
+    query: { path: path || null, rows },
+  }),
+
+  /**
+   * ArtifactShelf: the top of `artifacts/`, one row per artifact.
+   * `artifactSet` opens one of those rows. The bare key is the menu, so
+   * invalidating it refreshes an open set too.
+   */
+  artifacts: "/api/artifact",
+  artifactShelf: (rows: number) => ({
+    url: "/api/artifact",
+    query: { rows },
+  }),
+  artifactSet: (name: string, rows: number) => ({
+    url: "/api/artifact",
+    query: { set: name, rows },
+  }),
+
+  /** Raw workspace file, no Result envelope; for iframe, img and fetch, not SWR. */
+  file: (path: string) => `/api/file/${encodePath(path)}`,
+  /** File viewer page (new tab): md rendered, html and pdf framed */
+  fileView: (path: string) => `/artifact/${encodePath(path)}`,
+
+  /**
+   * Server-sent events, not a read; only app-event.client's `AppEventSource`
+   * opens it. The payloads are the AppEvent union in app/api/events/app-event.ts.
+   */
+  events: "/api/events",
+
+  /** ConfigStatus[]: which declared config keys are set; values stay on the server */
+  config: "/api/config",
+
+  /**
+   * CallRecord[] page, newest call first, turns in speaking order; pages count
+   * calls (CALL_HISTORY_PAGE). `before` is the oldest call's `startedAt` (ISO)
+   * on the previous page, null for the first. Calls with no turns are omitted.
+   */
+  callHistory: (before: string | null) => ({
+    url: "/api/thursday/call",
+    query: { before },
+  }),
+
+  /** boolean: whether the call may read a skill itself (Settings › Thursday) */
+  callSkills: "/api/thursday/skills",
+
+  /**
+   * POST, not a read; the one endpoint here SWR never touches. Body is
+   * {toolCallId, callId, name, input}; one JSON Result per call, abortable.
+   */
+  toolCall: "/api/thursday/tool-call",
+
+  /** 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",
+} as const;

package/app/api/thursday/tool-call/route.ts

@@ -0,0 +1,67 @@
+import { asSchema } from "ai";
+import z from "zod";
+import { loadTools } from "@/features/ai/load-tools";
+import { modelErrorToString } from "@/features/ai/model";
+import { serverRoute } from "@/lib/protocol/server-route";
+import { publicError } from "@/lib/public-error";
+
+/**
+ * Executes a tool call from the voice session. The page forwards what the model
+ * asked for; bots never come through here (they call `execute` directly).
+ * A route rather than a server action because actions run serially per client
+ * and one turn may call two tools at once. One POST, one JSON, no streaming;
+ * hanging up aborts the fetch and the signal reaches the tool.
+ */
+
+const ToolCallSchema = z.object({
+  toolCallId: z.string().min(1),
+  /** The call this came from; `delegate` attaches the job to it. */
+  callId: z.string().nullish(),
+  name: z.string().min(1),
+  input: z.unknown().optional(),
+});
+
+const isAsyncIterable = (value: unknown): value is AsyncIterable<unknown> =>
+  typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+
+/** For streaming tools the last chunk is the answer. */
+async function drain(output: unknown): Promise<unknown> {
+  if (!isAsyncIterable(output)) return output;
+  let latest: unknown;
+  for await (const part of output) latest = part;
+  return latest;
+}
+
+export const POST = serverRoute(async (request) => {
+  const { toolCallId, callId, name, input } = ToolCallSchema.parse(
+    await request.json(),
+  );
+
+  // The set the voice runtime may run, not whatever the body names.
+  const tools = await loadTools({ target: "thursday", callId });
+  const tool = tools[name];
+  if (!tool) publicError(`There is no tool called "${name}".`);
+
+  // end_call has no execute by design: the page owns the call and intercepts it.
+  if (!tool.execute) publicError(`"${name}" is handled by the page, not here.`);
+
+  const parsed = await asSchema(tool.inputSchema).validate?.(input ?? {});
+  if (parsed && !parsed.success) {
+    publicError(
+      `"${name}" got arguments that do not fit: ${parsed.error.message}`,
+    );
+  }
+
+  try {
+    const output = await tool.execute(parsed?.value ?? input ?? {}, {
+      toolCallId,
+      messages: [],
+      context: undefined,
+      abortSignal: request.signal,
+    });
+    return { output: await drain(output) };
+  } catch (cause) {
+    // A tool failure is a line the model reads and recovers from, not a masked server error.
+    publicError(`"${name}" failed: ${modelErrorToString(cause)}`);
+  }
+});

package/bin/thursday.mjs

@@ -6,6 +6,7 @@
 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 { ROOT, toolPath } from "./tools.mjs";
@@ -49,7 +50,39 @@ if (has("-v", "--version")) {
   process.exit(0);
 }
 
-const port = flag("port") || process.env.PORT || "3000";
+/** 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);
 const url = `http://localhost:${port}`;
 
@@ -122,7 +155,22 @@ if (!has("--no-open")) {
   ).unref();
 }
 
+/**
+ * Ctrl+C reaches the whole process group, so the server normally hears it first
+ * and closes on its own. When it does not, it is holding a connection that does
+ * not end — the browser's event stream is one — and a second Ctrl+C is not a
+ * request to try again.
+ */
+let stopping = false;
 for (const signal of ["SIGINT", "SIGTERM"]) {
-  process.on(signal, () => child.kill(signal));
+  process.on(signal, () => {
+    if (stopping) {
+      child.kill("SIGKILL");
+      return;
+    }
+    stopping = true;
+    child.kill(signal);
+    setTimeout(() => child.kill("SIGKILL"), 4000).unref();
+  });
 }
 child.on("exit", (code) => process.exit(code ?? 0));

package/components/ui/button-group.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentProps } from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Joins plain `<Button>`s into one control (outer corners only, shared 1px
+ * seams). Nested groups get a gap between them. For a selected value use
+ * `Segmented`.
+ */
+const buttonGroupVariants = cva(
+  "flex w-fit items-stretch has-[>[data-slot=button-group]]:gap-1.5 [&>*]:relative [&>*]:focus-visible:z-10",
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          "[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none",
+        vertical:
+          "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
+      },
+    },
+    defaultVariants: {
+      orientation: "horizontal",
+    },
+  },
+);
+
+function ButtonGroup({
+  className,
+  orientation = "horizontal",
+  ...props
+}: ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
+  return (
+    <div
+      data-slot="button-group"
+      data-orientation={orientation}
+      role="group"
+      className={cn(buttonGroupVariants({ orientation }), className)}
+      {...props}
+    />
+  );
+}
+
+export { ButtonGroup, buttonGroupVariants };