thursday-agent 0.1.2 → 0.2.0

package/hooks/use-hotkey.ts

@@ -0,0 +1,105 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+const HOLD = ["ctrl", "alt", "meta"] as const;
+
+const IS_MODIFIER = /^(Control|Alt|Shift|Meta|OS)/;
+
+const EDITABLE = /^(input|textarea|select)$/i;
+
+export const HOTKEY_CAPTURE = { "data-hotkey-capture": "" } as const;
+
+const busy = (target: EventTarget | null) => {
+  const node = target as HTMLElement | null;
+  if (!node) return false;
+  return Boolean(
+    EDITABLE.test(node.tagName) ||
+      node.isContentEditable ||
+      node.closest?.("[data-hotkey-capture]"),
+  );
+};
+
+export function comboOf(event: {
+  code: string;
+  ctrlKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+  metaKey: boolean;
+}): string | null {
+  const { code, ctrlKey, altKey, shiftKey, metaKey } = event;
+  if (!code || IS_MODIFIER.test(code)) return null;
+  if (!ctrlKey && !altKey && !metaKey) return null;
+
+  const held: string[] = [];
+  if (ctrlKey) held.push("ctrl");
+  if (altKey) held.push("alt");
+  if (shiftKey) held.push("shift");
+  if (metaKey) held.push("meta");
+  return [...held, code].join("+");
+}
+
+export const isCombo = (combo: string) => {
+  const parts = combo.split("+");
+  const code = parts.at(-1);
+  return Boolean(
+    code &&
+      !IS_MODIFIER.test(code) &&
+      parts.slice(0, -1).some((part) => HOLD.includes(part as never)),
+  );
+};
+
+const SIGN: Record<string, [plain: string, mac: string]> = {
+  ctrl: ["Ctrl", "⌃"],
+  alt: ["Alt", "⌥"],
+  shift: ["Shift", "⇧"],
+  meta: ["Meta", "⌘"],
+};
+
+const keyLabel = (code: string) =>
+  code.replace(/^(Key|Digit|Numpad)/, "").replace(/([a-z])([A-Z])/g, "$1 $2") ||
+  code;
+
+export function hotkeyLabel(combo: string, mac = false): string {
+  const parts = combo.split("+");
+  const code = parts.at(-1) ?? "";
+  const held = parts
+    .slice(0, -1)
+    .map((part) => SIGN[part]?.[mac ? 1 : 0] ?? part);
+  const key = keyLabel(code);
+  return mac ? [...held, key].join("") : [...held, key].join(" + ");
+}
+
+export function useHotkeyLabel(combo: string | null): string | null {
+  const [mac, setMac] = useState(false);
+  useEffect(() => setMac(/mac/i.test(navigator.userAgent)), []);
+  return combo ? hotkeyLabel(combo, mac) : null;
+}
+
+export function useHotkey({
+  enabled,
+  combo,
+  onPress,
+}: {
+  enabled: boolean;
+  combo: string | null;
+  onPress: () => void;
+}) {
+  const latest = useRef(onPress);
+  latest.current = onPress;
+
+  useEffect(() => {
+    if (!enabled || !combo) return;
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.repeat || busy(event.target)) return;
+      if (comboOf(event) !== combo) return;
+
+      event.preventDefault();
+      latest.current();
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [enabled, combo]);
+}

package/hooks/use-object-state.ts

@@ -0,0 +1,51 @@
+import { useMemo, useState } from "react";
+import { isFunction } from "../lib/utils";
+
+type SetPartialStateAction<T> = Partial<T> | ((prev: T) => Partial<T>);
+
+type Patch<T> = ((action: SetPartialStateAction<T>) => void) & {
+  [K in keyof T]-?: (value: T[K] | ((prev: T[K]) => T[K])) => void;
+};
+
+const hasChanged = <T extends object>(prev: T, next: Partial<T>) =>
+  (Object.keys(next) as (keyof T)[]).some(
+    (key) => !Object.is(prev[key], next[key]),
+  );
+
+export const useObjectState = <T extends object>(initial: T | (() => T)) => {
+  const [state, setState] = useState<T>(initial);
+
+  const patch = useMemo(() => {
+    const apply = (action: SetPartialStateAction<T>) => {
+      setState((prev) => {
+        const delta = isFunction(action) ? action(prev) : action;
+        return hasChanged(prev, delta) ? { ...prev, ...delta } : prev;
+      });
+    };
+
+    // Cache per-key setters so their identity is stable in deps arrays.
+    const cache = new Map<string, (value: unknown) => void>();
+
+    return new Proxy(apply, {
+      get(target, p, receiver) {
+        if (typeof p === "symbol") return Reflect.get(target, p, receiver);
+
+        let setter = cache.get(p);
+        if (!setter) {
+          setter = (value) => {
+            apply(
+              (prev) =>
+                ({
+                  [p]: isFunction(value) ? value(prev[p as keyof T]) : value,
+                }) as Partial<T>,
+            );
+          };
+          cache.set(p, setter);
+        }
+        return setter;
+      },
+    }) as Patch<T>;
+  }, []);
+
+  return [state, patch] as const;
+};

package/hooks/use-on-visible.ts

@@ -0,0 +1,72 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Calls `onVisible` when the attached element scrolls into view (infinite
+ * lists). The callback lives in a ref: rebuilding the observer on an element
+ * already in view would fire it again.
+ */
+export function useOnVisible(
+  onVisible: () => void,
+  options: {
+    /** False stops observing (nothing left, or a request in flight). */
+    enabled?: boolean;
+    /**
+     * Bump to rebuild the observer, which re-fires if the element is still in
+     * view. Observers report crossings, not states: a list shorter than the
+     * viewport would otherwise stop after one page.
+     */
+    revision?: unknown;
+    /** IntersectionObserver rootMargin; fires before the element appears. */
+    margin?: string;
+  } = {},
+) {
+  const { enabled = true, margin = "600px", revision } = options;
+
+  const callback = useRef(onVisible);
+  callback.current = onVisible;
+
+  const node = useRef<HTMLElement | null>(null);
+  const observer = useRef<IntersectionObserver | null>(null);
+
+  const attach = useCallback((next: HTMLElement | null) => {
+    node.current = next;
+  }, []);
+
+  useEffect(() => {
+    observer.current?.disconnect();
+    const target = node.current;
+    if (!target || !enabled) return;
+
+    observer.current = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) callback.current();
+      },
+      { root: scrollParent(target), rootMargin: margin },
+    );
+    observer.current.observe(target);
+    return () => observer.current?.disconnect();
+  }, [enabled, margin, revision]);
+
+  return attach;
+}
+
+/**
+ * Nearest scrolling ancestor, or null for the window. With the default root an
+ * ancestor's overflow clips the sentinel and it never intersects.
+ */
+function scrollParent(node: HTMLElement): Element | null {
+  let parent = node.parentElement;
+  while (parent) {
+    const { overflowY } = getComputedStyle(parent);
+    if (
+      (overflowY === "auto" || overflowY === "scroll") &&
+      parent.scrollHeight > parent.clientHeight
+    ) {
+      return parent;
+    }
+    parent = parent.parentElement;
+  }
+  return null;
+}

package/hooks/use-theme.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { THEME_STORAGE_KEY, THEMES, type Theme } from "@/lib/theme";
+
+/**
+ * Theme preference stored in localStorage and applied as the `dark` class on
+ * `<html>`. The boot script in app/layout reads the same key before hydration;
+ * this store only follows changes after that.
+ */
+
+const isTheme = (value: unknown): value is Theme =>
+  (THEMES as readonly unknown[]).includes(value);
+
+function read(): Theme {
+  if (typeof window === "undefined") return "system";
+  try {
+    const raw = window.localStorage.getItem(THEME_STORAGE_KEY);
+    return isTheme(raw) ? raw : "system";
+  } catch {
+    return "system";
+  }
+}
+
+let theme = read();
+const listeners = new Set<() => void>();
+
+function announce() {
+  for (const listener of listeners) listener();
+}
+
+/** Actual brightness the setting resolves to. */
+export function resolveTheme(value: Theme): "light" | "dark" {
+  if (value !== "system") return value;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+/** Applies to `<html>`; touches exactly what the boot script touches. */
+export function applyTheme(value: Theme) {
+  const dark = resolveTheme(value) === "dark";
+  document.documentElement.classList.toggle("dark", dark);
+  document.documentElement.style.colorScheme = dark ? "dark" : "light";
+}
+
+export function setTheme(next: Theme) {
+  theme = next;
+  try {
+    window.localStorage.setItem(THEME_STORAGE_KEY, next);
+  } catch {
+    // Private mode or blocked storage; the in-memory value still changes.
+  }
+  applyTheme(next);
+  announce();
+}
+
+export function useTheme(): Theme {
+  return useSyncExternalStore(
+    (listener) => {
+      listeners.add(listener);
+      // Another tab changed it.
+      const sync = (event: StorageEvent) => {
+        if (event.key !== THEME_STORAGE_KEY) return;
+        theme = read();
+        applyTheme(theme);
+        announce();
+      };
+      window.addEventListener("storage", sync);
+      return () => {
+        listeners.delete(listener);
+        window.removeEventListener("storage", sync);
+      };
+    },
+    () => theme,
+    // Server snapshot; hydration swaps in the stored value.
+    () => "system",
+  );
+}
+
+/** Resolved theme; follows the OS while the setting is "system". */
+export function useResolvedTheme(): "light" | "dark" {
+  const current = useTheme();
+  const [systemDark, setSystemDark] = useState(false);
+  useEffect(() => {
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const follow = () => setSystemDark(media.matches);
+    follow();
+    media.addEventListener("change", follow);
+    return () => media.removeEventListener("change", follow);
+  }, []);
+  if (current !== "system") return current;
+  return systemDark ? "dark" : "light";
+}
+
+/** Re-applies "system" when the OS theme changes. Mount once, in the layout. */
+export function useFollowSystemTheme() {
+  const current = useTheme();
+  useEffect(() => {
+    if (current !== "system") return;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const follow = () => applyTheme("system");
+    media.addEventListener("change", follow);
+    return () => media.removeEventListener("change", follow);
+  }, [current]);
+}

package/hooks/use-wake-word.ts

@@ -0,0 +1,262 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+/**
+ * Wake-word listener built on the browser's Web Speech API (no realtime socket
+ * while idle). It is a transcriber, not a KWS engine, so matching is fuzzy.
+ * Chrome streams idle audio to Google; Firefox has no recognizer (onError only).
+ */
+
+/** lib.dom types the result objects but not the recognizer itself. */
+type SpeechRecognitionLike = {
+  lang: string;
+  continuous: boolean;
+  interimResults: boolean;
+  maxAlternatives: number;
+  start(): void;
+  stop(): void;
+  abort(): void;
+  onresult:
+    | ((event: {
+        resultIndex: number;
+        results: SpeechRecognitionResultList;
+      }) => void)
+    | null;
+  onerror: ((event: { error: string }) => void) | null;
+  onend: (() => void) | null;
+};
+
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+/**
+ * Default recognizer language. English keeps one spelling to compare against
+ * regardless of the speaker's accent; callers with a non-English name pass
+ * `lang` and `phrases` together.
+ */
+export const WAKE_LANG = "en-US";
+
+/**
+ * Allowed edit distance per word as a fraction of its length ("hey" = 1 edit,
+ * "thursday" = 3). Lower misses accents; higher lets ordinary speech wake.
+ */
+const WAKE_TOLERANCE = 0.34;
+
+/** Alternatives per result; the second-ranked guess is often the right one. */
+const ALTERNATIVES = 3;
+
+/** Delay before restarting after `onend`, so error loops do not spin. */
+const RESTART_MS = 300;
+/** Backoff cap while the recognition service is unreachable. */
+const RESTART_MAX_MS = 10_000;
+
+/** Errors a restart cannot fix. */
+const FATAL: Record<string, string> = {
+  "not-allowed": "The microphone is not allowed",
+  "service-not-allowed": "The microphone is not allowed",
+  "audio-capture": "There is no microphone",
+  "language-not-supported": "This browser cannot listen in that language",
+};
+
+/** Case and punctuation vary per recognizer; word boundaries do not. */
+const normalize = (text: string) =>
+  text
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]/g, "")
+    .split(/\s+/)
+    .filter(Boolean);
+
+/** Plain Levenshtein distance between two words. */
+function distance(heard: string, want: string): number {
+  let previous = Array.from({ length: heard.length + 1 }, (_, index) => index);
+  let current = new Array<number>(heard.length + 1).fill(0);
+
+  for (let row = 1; row <= want.length; row++) {
+    current[0] = row;
+    for (let column = 1; column <= heard.length; column++) {
+      const substitute =
+        previous[column - 1] + (want[row - 1] === heard[column - 1] ? 0 : 1);
+      current[column] = Math.min(
+        substitute,
+        previous[column] + 1,
+        current[column - 1] + 1,
+      );
+    }
+    [previous, current] = [current, previous];
+  }
+
+  return previous[heard.length];
+}
+
+/** Within `budget` edits; the length check short-circuits most words. */
+const near = (heard: string, want: string, budget: number) =>
+  Math.abs(heard.length - want.length) <= budget &&
+  distance(heard, want) <= budget;
+
+/**
+ * Whether `want[from..]` is spoken contiguously starting at `heard[at]`.
+ * One wanted word may span two heard words ("there's day" for "thursday").
+ */
+function saidAt(
+  heard: readonly string[],
+  at: number,
+  want: readonly string[],
+  from: number,
+  tolerance: number,
+): boolean {
+  if (from === want.length) return true;
+  if (at >= heard.length) return false;
+
+  const word = want[from];
+  // Never 0, or "hay" for "hey" fails.
+  const budget = Math.max(1, Math.round(word.length * tolerance));
+
+  if (
+    near(heard[at], word, budget) &&
+    saidAt(heard, at + 1, want, from + 1, tolerance)
+  ) {
+    return true;
+  }
+  return (
+    at + 1 < heard.length &&
+    near(heard[at] + heard[at + 1], word, budget) &&
+    saidAt(heard, at + 2, want, from + 1, tolerance)
+  );
+}
+
+/**
+ * Whether `heard` contains `want` as one contiguous phrase. Scoring is per
+ * word, not over the joined string, so every word must be present and adjacent.
+ */
+function contains(
+  heard: readonly string[],
+  want: readonly string[],
+  tolerance: number,
+): boolean {
+  for (let at = 0; at < heard.length; at++) {
+    if (saidAt(heard, at, want, 0, tolerance)) return true;
+  }
+  return false;
+}
+
+type WakeOptions = {
+  /** Releases the microphone when false; must be false while a call is open. */
+  enabled: boolean;
+  /** Receives the raw transcript that matched. */
+  onWake: (heard: string) => void;
+  /** Phrases to listen for, matched fuzzily. */
+  phrases: readonly string[];
+  lang?: string;
+  /** See WAKE_TOLERANCE. */
+  tolerance?: number;
+  /** Unrecoverable failures only (denied or missing microphone). */
+  onError?: (reason: string) => void;
+};
+
+export function useWakeWord({
+  enabled,
+  onWake,
+  phrases,
+  lang = WAKE_LANG,
+  tolerance = WAKE_TOLERANCE,
+  onError,
+}: WakeOptions) {
+  // Read at result time so re-renders and phrase changes do not restart the
+  // recognizer; only `lang` must be set before start.
+  const latest = useRef({ onWake, onError, phrases, tolerance });
+  latest.current = { onWake, onError, phrases, tolerance };
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const global = window as unknown as Record<string, unknown>;
+    const Ctor = (global.SpeechRecognition ?? global.webkitSpeechRecognition) as
+      | SpeechRecognitionCtor
+      | undefined;
+
+    if (!Ctor) {
+      latest.current.onError?.("This browser cannot listen for a wake word");
+      return;
+    }
+
+    const recognition = new Ctor();
+    // Latched off on cleanup so late events cannot revive the recognizer.
+    let alive = true;
+    // Off from a match until the restart that clears the transcript.
+    let armed = true;
+    let restart: ReturnType<typeof setTimeout> | null = null;
+    let delay = RESTART_MS;
+
+    recognition.lang = lang;
+    // Interim results are enough; waiting for isFinal loses a beat.
+    recognition.continuous = true;
+    recognition.interimResults = true;
+    recognition.maxAlternatives = ALTERNATIVES;
+
+    const listen = () => {
+      if (!alive) return;
+      armed = true;
+      try {
+        recognition.start();
+      } catch {
+        // Already running (InvalidStateError).
+      }
+    };
+
+    recognition.onresult = ({ resultIndex, results }) => {
+      if (!alive || !armed) return;
+      delay = RESTART_MS;
+
+      const { phrases, tolerance, onWake } = latest.current;
+      const targets = phrases.map(normalize).filter((words) => words.length);
+
+      // Results before resultIndex are final and already seen.
+      for (let index = resultIndex; index < results.length; index++) {
+        const result = results[index];
+        for (let rank = 0; rank < result.length; rank++) {
+          const heard = result[rank].transcript;
+          const words = normalize(heard);
+          if (!targets.some((target) => contains(words, target, tolerance))) {
+            continue;
+          }
+
+          // Abort before notifying: the transcript keeps growing and would
+          // match again on the next event. `onend` restarts unless the caller
+          // has dropped `enabled` by then.
+          armed = false;
+          recognition.abort();
+          onWake(heard.trim());
+          return;
+        }
+      }
+    };
+
+    recognition.onerror = ({ error }) => {
+      const reason = FATAL[error];
+      if (reason) {
+        alive = false;
+        latest.current.onError?.(reason);
+      } else if (error === "network") {
+        delay = Math.min(delay * 2, RESTART_MAX_MS);
+      }
+      // no-speech and aborted are normal for this API.
+    };
+
+    // Chrome ends a silent session after about a minute; keep restarting.
+    recognition.onend = () => {
+      if (!alive) return;
+      restart = setTimeout(listen, delay);
+    };
+
+    listen();
+
+    return () => {
+      alive = false;
+      if (restart) clearTimeout(restart);
+      recognition.onresult = null;
+      recognition.onerror = null;
+      recognition.onend = null;
+      recognition.abort();
+    };
+  }, [enabled, lang]);
+}

package/lib/realtime/realtime.driver.ts

@@ -1,3 +1,4 @@
+import { logger } from "@/lib/logger";
 import { errorToString } from "@/lib/utils";
 import type {
   RealtimeFunctionTool,
@@ -85,6 +86,9 @@ export function realtimeSession(
     } | null = null;
     let ackTimer: ReturnType<typeof setTimeout> | null = null;
 
+    /** Event types this session has already noted as unhandled (see `default`). */
+    const seenUnhandled = new Set<string>();
+
     const turns: Turn[] = [];
     const slot = new Map<string, number>();
     const finalized = new Set<string>();
@@ -339,7 +343,25 @@ export function realtimeSession(
 
         case "conversation.item.input_audio_transcription.completed":
           write(event.item_id, "user", event.transcript ?? "", "replace");
-          finish(event.item_id);
+          // Not always the end of the turn. xAI sends this while the user is
+          // still speaking, each time with a longer transcript and `in_progress`
+          // on it; finishing on the first froze the turn at its opening words
+          // and every later transcript was written but never reported (`write`
+          // reports only what is not finalized). A provider that sends it once
+          // omits the field, so anything but `in_progress` ends the turn.
+          if (event.status !== "in_progress") finish(event.item_id);
+          break;
+
+        // A turn nobody could read. Without this the item simply never gets
+        // words, and an item with no words is not reported at all (`report`) —
+        // the turn disappears from the transcript, and every reader downstream
+        // sees a conversation the user did not have.
+        case "conversation.item.input_audio_transcription.failed":
+          on.warn(
+            event.error?.message
+              ? `That turn could not be transcribed: ${event.error.message}`
+              : "That turn could not be transcribed.",
+          );
           break;
 
         case "response.output_audio_transcript.delta":
@@ -388,6 +410,17 @@ export function realtimeSession(
           finish(event.item_id);
           onToolCall(event);
           break;
+
+        default:
+          // Providers speak this protocol with their own additions, and a case
+          // that is missing here is invisible: the event is dropped and the
+          // conversation quietly loses whatever it carried. Once per type per
+          // session, so a busy stream cannot drown the log.
+          if (!seenUnhandled.has(event.type)) {
+            seenUnhandled.add(event.type);
+            logger.debug(`realtime: no case for ${event.type}`);
+          }
+          break;
       }
       settle();
     };

package/lib/realtime/realtime.protocol.ts

@@ -308,6 +308,12 @@ export type RealtimeServerEvent =
       type: "conversation.item.input_audio_transcription.completed";
       item_id: string;
       transcript: string;
+      /**
+       * xAI sends this event repeatedly while the turn is still being
+       * transcribed, each time with more of it and `in_progress` here; only the
+       * last carries `completed`. OpenAI sends it once and omits the field.
+       */
+      status?: "in_progress" | "completed" | string;
     }
   /** OpenAI only. */
   | {

package/lib/sandbox.ts

@@ -4,6 +4,14 @@ import { join, resolve as pathResolve, relative, sep } from "node:path";
 
 export type ExecResult = { stdout: string; stderr: string; exitCode: number };
 
+/**
+ * How long one command may run before its process group is killed. Nobody is
+ * watching the shell, so a command waiting on a prompt would otherwise hang
+ * the job; anything that legitimately runs longer belongs in the background.
+ * Named because the shell guide states it to the model (ai/tools/workspace.tool).
+ */
+export const EXEC_TIMEOUT_MS = 180_000;
+
 export interface Sandbox {
   /** Absolute. Relative paths resolve from here */
   readonly cwd: string;
@@ -155,7 +163,7 @@ export const createSandBox = ({
       return out;
     },
 
-    exec(command, { cwd: c, timeoutMs = 180_000, signal, env } = {}) {
+    exec(command, { cwd: c, timeoutMs = EXEC_TIMEOUT_MS, signal, env } = {}) {
       return new Promise((resolve) => {
         const base = shellEnv();
         if (extraPath) base.PATH = `${base.PATH ?? ""}:${extraPath}`;