tinywebui 0.1.0

package/src/store/usage.js

@@ -0,0 +1,327 @@
+import { scope } from './scope.js';
+
+/** What an aux_usage row was spent on. */
+export const AUX_KIND = { CHECKPOINT: 'checkpoint' };
+import { inputTokens, outputTokens, cacheReads, tally } from '../../public/shared/usage.js';
+
+// Token and cost statistics over stored messages.
+// One area of the Store; see index.js.
+
+/** Adds one stored attribution snapshot (see harness/attribution.js) into a running total. */
+function mergeAttribution(target, snapshot) {
+  if (!snapshot || snapshot.version !== 1) return target;
+  target ||= { requests: 0, input: { total: 0, reported: 0, buckets: [] }, output: { total: 0, reported: 0, buckets: [] }, cached: 0 };
+  target.requests++;
+  for (const side of ['input', 'output']) {
+    const value = snapshot[side];
+    if (!value) continue;
+    if (value.total !== null) { target[side].total += value.total; target[side].reported++; }
+    for (const b of value.buckets || []) {
+      let existing = target[side].buckets.find((x) => x.category === b.category && x.source === b.source && x.capability === b.capability);
+      if (!existing) target[side].buckets.push(existing = { ...b, tokens: 0 });
+      existing.tokens += b.tokens;
+    }
+  }
+  target.cached += snapshot.cached || 0;
+  return target;
+}
+
+/** Causes of a cache miss, most actionable first. */
+export const MISS = { PREFIX: 'prefix', SWITCH: 'switch', EXPIRED: 'expired', STUB: 'stub', PROVIDER: 'provider' };
+
+// How long an entry outlives its last use on most providers. Longer TTLs exist
+// (Anthropic's 1h, Gemini's explicit caches), so a gap past this is a likely
+// expiry, not a certain one.
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Why a round missed the cache, given the round before it in the same chat:
+ * null for a hit or a round that can't be judged. A miss is less than half of
+ * the previous request cached -- that request is what this one should have
+ * found, and providers cache in blocks, so "less than all" is normal.
+ * `prefix` is the fingerprint streamTurn() stores (see chat/llm.js).
+ */
+export function cacheMiss(round, prev) {
+  const { usage, at } = round;
+  const prefix = usage.prefix;
+  if (!prev || !prefix || prefix.previous == null || !tally([usage]).reported) return null;
+  if ((cacheReads(usage) ?? 0) >= prev.input / 2) return null;
+  if (prefix.matched < prefix.previous) return prefix.stubSwap ? MISS.STUB : MISS.PREFIX;
+  if (usage.provider && prev.provider && usage.provider !== prev.provider) return MISS.SWITCH;
+  if (at != null && prev.at != null && at - prev.at > CACHE_TTL_MS) return MISS.EXPIRED;
+  return MISS.PROVIDER;
+}
+
+/**
+ * What caching saved, from costs providers already report. Within one model on
+ * one upstream, every round's input cost is fresh * full + cached * cacheRate
+ * with the same two prices, so rounds at different cache ratios pin both down
+ * (least squares). The fit is trusted only if it reproduces every round to 1%:
+ * a tiered or changed price would not, and then nothing is claimed.
+ * `rounds`: [{ fresh, cached, inputCost }]. Returns null when it can't tell.
+ */
+export function derivedCacheRates(rounds) {
+  if (rounds.length < 2) return null;
+  let ff = 0, fc = 0, cc = 0, fy = 0, cy = 0;
+  for (const { fresh, cached, inputCost: y } of rounds) {
+    ff += fresh * fresh; fc += fresh * cached; cc += cached * cached; fy += fresh * y; cy += cached * y;
+  }
+  const det = ff * cc - fc * fc;
+  // All rounds at one cache ratio: the two prices can't be told apart.
+  if (!(det > 1e-9 * ff * cc)) return null;
+  const full = (fy * cc - fc * cy) / det;
+  const cacheRate = (ff * cy - fc * fy) / det;
+  if (!(full > 0) || cacheRate < -1e-12 || cacheRate >= full) return null;
+  const fits = rounds.every(({ fresh, cached, inputCost }) =>
+    Math.abs(fresh * full + cached * cacheRate - inputCost) <= 0.01 * inputCost + 1e-9);
+  return fits ? { full, cache: Math.max(cacheRate, 0) } : null;
+}
+
+/**
+ * Which rounds a statistics view covers: `model` alone is every upstream that
+ * served it; `provider` narrows to one ('' is rounds with none on record).
+ */
+const matches = (filter, model, provider) =>
+  (!filter.model || model === filter.model)
+  && (filter.provider == null || (provider ?? '') === filter.provider);
+
+/** Every model seen, with the upstreams that served it, for the filter. */
+function addTarget(targets, model, provider) {
+  if (!targets.has(model)) targets.set(model, new Set());
+  if (provider) targets.get(model).add(provider);
+}
+const listTargets = (targets) => [...targets].map(([model, providers]) => ({ model, providers: [...providers].sort() }))
+  .sort((a, b) => a.model.localeCompare(b.model));
+
+export class UsageStore {
+  constructor(db, deps = {}) {
+    this.db = db;
+    Object.assign(this, deps);
+  }
+
+  /** Usage of a request made for a chat that is not one of its turns. `kind`: AUX_KIND. */
+  addAuxiliary(chatId, { kind, model, usage }) {
+    this.db.prepare('INSERT INTO aux_usage (chat_id, kind, model, usage_json, created_at) VALUES (?, ?, ?, ?, ?)')
+      .run(chatId, kind, model ?? null, JSON.stringify(usage ?? {}), Date.now());
+  }
+
+  /** Usage of one chat's auxiliary requests, oldest first. */
+  auxiliaryFor(chatId) {
+    return this.db.prepare('SELECT usage_json FROM aux_usage WHERE chat_id = ? ORDER BY id').all(chatId)
+      .map((r) => JSON.parse(r.usage_json));
+  }
+
+  /**
+   * Rolls up token usage across every assistant round that has it, bucketed
+   * by local calendar day ('YYYY-MM-DD', via SQLite's julianday/strftime on
+   * created_at) and by model. Buckets are computed in SQL rather than in JS
+   * so a year of history doesn't have to be pulled across just to summarize
+   * it. Field-name variance across providers (prompt_tokens vs input_tokens,
+   * the several cache-token spellings) is normalized here the same way
+   * transcript.js's tally() does client-side for a single round.
+   *
+   * Rows predating model/timestamp tracking have neither column set and land
+   * in an 'unknown' day bucket instead of being dropped, so their tokens
+   * still show up here the same way their cost already does in
+   * usageStatistics() below.
+   */
+  rollup(userId, filter = {}) {
+    const s = scope(userId, 'c.user_id');
+    const rows = this.db.prepare(`
+      SELECT CASE WHEN m.created_at IS NOT NULL
+               THEN strftime('%Y-%m-%d', m.created_at / 1000, 'unixepoch')
+               ELSE 'unknown' END AS day,
+             m.model, m.usage_json
+      FROM (SELECT chat_id, created_at, model, usage_json FROM messages
+            UNION ALL SELECT chat_id, created_at, model, usage_json FROM aux_usage) m
+      JOIN chats c ON c.id=m.chat_id
+      WHERE m.usage_json IS NOT NULL AND ${s.sql}
+    `).all(...s.params);
+
+    const byDay = new Map();
+    for (const row of rows) {
+      let u;
+      try { u = JSON.parse(row.usage_json); } catch { continue; }
+      const inTok = inputTokens(u) ?? 0;
+      const outTok = outputTokens(u) ?? 0;
+      const cached = cacheReads(u) ?? 0;
+      const model = row.model || u.model || 'unknown';
+      if (!matches(filter, model, u.provider)) continue;
+
+      const cost = u.cost != null && Number.isFinite(Number(u.cost)) ? Number(u.cost) : null;
+      if (!byDay.has(row.day)) byDay.set(row.day, { day: row.day, in: 0, out: 0, cached: 0, models: new Map() });
+      const d = byDay.get(row.day);
+      d.in += inTok; d.out += outTok; d.cached += cached;
+
+      if (!d.models.has(model)) d.models.set(model, { model, in: 0, out: 0, cached: 0 });
+      const m = d.models.get(model);
+      m.in += inTok; m.out += outTok; m.cached += cached;
+      m.attribution = mergeAttribution(m.attribution, u.attribution);
+      m.requests = (m.requests || 0) + 1;
+      if (cost !== null) {
+        d.cost = (d.cost || 0) + cost;
+        m.cost = (m.cost || 0) + cost;
+        d.pricedRounds = (d.pricedRounds || 0) + 1;
+        m.pricedRounds = (m.pricedRounds || 0) + 1;
+      }
+    }
+
+    return [...byDay.values()]
+      .map((d) => ({ ...d, models: [...d.models.values()] }))
+      .sort((a, b) => a.day.localeCompare(b.day));
+  }
+
+  statistics(userId, filter = {}) {
+    const s = scope(userId, 'c.user_id');
+    const rows = this.db.prepare(`SELECT m.chat_id,m.seq,m.role,m.content,m.tool_calls_json,m.model,m.usage_json,m.created_at
+      FROM messages m JOIN chats c ON c.id=m.chat_id WHERE ${s.sql} ORDER BY m.chat_id,m.seq`).all(...s.params);
+    const models = new Map();
+    const tools = new Map();
+    const summary = { rounds: 0, pricedRounds: 0, reportedCost: 0, completedAnswers: 0,
+      pricedAnswers: 0, answerCostTotal: 0, answerTokens: 0, tokenAnswers: 0, toolCalls: 0 };
+    // Hit share counts only rounds whose provider reports cache figures: one
+    // that reports nothing would otherwise read as a 0% hit and drag it down.
+    const cache = { rounds: 0, input: 0, cached: 0, written: 0, saved: 0, savedRounds: 0, savedCost: 0,
+      judged: 0, misses: Object.fromEntries(Object.values(MISS).map((k) => [k, 0])) };
+    let prevRound = null;
+    // Per model @ upstream, for derivedCacheRates().
+    const priced = new Map();
+    const targets = new Map();
+    let chatId = null;
+    let answer = null;
+    const finishAnswer = () => {
+      if (!answer) return;
+      if (answer.complete) {
+        summary.completedAnswers++;
+        summary.answerRoundsTotal = (summary.answerRoundsTotal || 0) + answer.rounds;
+        if (answer.rounds && answer.pricedRounds === answer.rounds) {
+          summary.pricedAnswers++;
+          summary.answerCostTotal += answer.cost;
+        }
+        if (answer.rounds && answer.usageRounds === answer.rounds) { summary.tokenAnswers++; summary.answerTokens += answer.tokens; }
+      }
+    };
+    for (const row of rows) {
+      if (row.chat_id !== chatId) { finishAnswer(); chatId = row.chat_id; answer = null; prevRound = null; }
+      if (row.role === 'user') { finishAnswer(); answer = { rounds:0, usageRounds:0, pricedRounds:0, cost:0, tokens:0, complete:false }; continue; }
+      if (row.role !== 'assistant') continue;
+      let usage = null;
+      try { if (row.usage_json) usage = JSON.parse(row.usage_json); } catch { /* ignore malformed historic usage */ }
+      const model = row.model || usage?.model || 'unknown';
+      addTarget(targets, model, usage?.provider);
+      if (!matches(filter, model, usage?.provider)) {
+        // Still the round the next one is judged against: a filtered-out
+        // upstream in between is exactly what makes the next one a switch.
+        if (usage) prevRound = { input: tally([usage]).in, provider: usage.provider ?? null, at: row.created_at };
+        continue;
+      }
+      summary.rounds++;
+      if (answer) answer.rounds++;
+      if (!models.has(model)) models.set(model, { model, in:0, out:0, cached:0, rounds:0, pricedRounds:0, cost:0 });
+      const m = models.get(model);
+      m.rounds++;
+      if (row.tool_calls_json) {
+        let calls = null;
+        try { calls = JSON.parse(row.tool_calls_json); } catch { /* ignore malformed historic tool_calls */ }
+        for (const call of calls || []) {
+          const name = call?.function?.name;
+          if (!name) continue;
+          summary.toolCalls++;
+          tools.set(name, (tools.get(name) || 0) + 1);
+        }
+      }
+      if (usage) {
+        const inTok = inputTokens(usage) ?? 0;
+        const outTok = outputTokens(usage) ?? 0;
+        const cached = cacheReads(usage) ?? 0;
+        const costValue = usage.cost ?? usage.total_cost;
+        const cost = costValue !== undefined && costValue !== null && Number.isFinite(Number(costValue)) ? Number(costValue) : null;
+        m.in += inTok; m.out += outTok; m.cached += cached;
+        const t = tally([usage]);
+        if (t.reported) { cache.rounds++; cache.input += t.in; cache.cached += t.cached; cache.written += t.written; }
+        if (t.reported && usage.prefix?.previous != null && prevRound) {
+          cache.judged++;
+          const miss = cacheMiss({ usage, at: row.created_at }, prevRound);
+          if (miss) cache.misses[miss]++;
+        }
+        prevRound = { input: t.in, provider: usage.provider ?? null, at: row.created_at };
+        const inputCost = Number(usage.cost_details?.upstream_inference_prompt_cost);
+        const key = `${model}\u0000${usage.provider ?? ''}`;
+        if (!priced.has(key)) priced.set(key, { model, provider: usage.provider ?? null, rounds: [], cost: 0, discount: 0, discounted: 0 });
+        const g = priced.get(key);
+        if (t.reported && Number.isFinite(inputCost) && inputCost > 0) g.rounds.push({ fresh: t.in - t.cached, cached: t.cached, inputCost, cost });
+        if (usage.cache_discount != null && Number.isFinite(Number(usage.cache_discount))) { g.discounted++; g.discount += Number(usage.cache_discount); g.cost += cost ?? 0; }
+        if (cost !== null) { m.cost += cost; m.pricedRounds++; summary.pricedRounds++; summary.reportedCost += cost; }
+        if (answer) {
+          if (inputTokens(usage) !== null && outputTokens(usage) !== null) answer.usageRounds++;
+          answer.tokens += inTok + outTok;
+          if (cost !== null) { answer.pricedRounds++; answer.cost += cost; }
+        }
+      }
+      if (!row.tool_calls_json && String(row.content || '').trim()) {
+        if (answer) answer.complete = true;
+      }
+    }
+    finishAnswer();
+    // A provider's own figure wins; otherwise derive it from what it charged.
+    const rates = [];
+    for (const g of priced.values()) {
+      if (g.discounted) { cache.saved += g.discount; cache.savedCost += g.cost; cache.savedRounds += g.discounted; continue; }
+      const r = derivedCacheRates(g.rounds);
+      if (!r) continue;
+      const cached = g.rounds.reduce((n, x) => n + x.cached, 0);
+      cache.saved += cached * (r.full - r.cache);
+      cache.savedCost += g.rounds.reduce((n, x) => n + (x.cost ?? 0), 0);
+      cache.savedRounds += g.rounds.length;
+      rates.push({ model: g.model, provider: g.provider, full: r.full, cache: r.cache });
+    }
+    // Kept out of rounds and answers: these are not turns, but they are spent.
+    const aux = { requests: 0, pricedRequests: 0, cost: 0 };
+    for (const row of this.db.prepare(`SELECT a.model, a.usage_json FROM aux_usage a
+      JOIN chats c ON c.id=a.chat_id WHERE ${s.sql}`).all(...s.params)) {
+      let usage = null;
+      try { usage = JSON.parse(row.usage_json); } catch { continue; }
+      const model = row.model || usage.model || 'unknown';
+      addTarget(targets, model, usage.provider);
+      if (!matches(filter, model, usage.provider)) continue;
+      aux.requests++;
+      const costValue = usage.cost ?? usage.total_cost;
+      if (costValue != null && Number.isFinite(Number(costValue))) { aux.pricedRequests++; aux.cost += Number(costValue); }
+    }
+    return {
+      targets: listTargets(targets),
+      auxiliary: { requests: aux.requests, cost: aux.pricedRequests ? aux.cost : null },
+      cache: {
+        reportedRounds: cache.rounds,
+        input: cache.input,
+        cached: cache.cached,
+        written: cache.written,
+        hitShare: cache.input ? cache.cached / cache.input : null,
+        saved: cache.savedRounds ? cache.saved : null,
+        // Share of what those rounds would have cost uncached.
+        savedShare: cache.savedRounds && cache.saved + cache.savedCost > 0 ? cache.saved / (cache.saved + cache.savedCost) : null,
+        rates,
+        savedRounds: cache.savedRounds,
+        // Rounds with a previous request to compare against; the rest (a
+        // chat's first round, the first after a restart, old rows) are unknown.
+        judged: cache.judged,
+        misses: cache.misses
+      },
+      rounds: summary.rounds,
+      pricedRounds: summary.pricedRounds,
+      unpricedRounds: summary.rounds - summary.pricedRounds,
+      reportedCost: summary.pricedRounds ? summary.reportedCost : null,
+      averageRoundCost: summary.pricedRounds ? summary.reportedCost / summary.pricedRounds : null,
+      completedAnswers: summary.completedAnswers,
+      pricedAnswers: summary.pricedAnswers,
+      averageAnswerCost: summary.pricedAnswers ? summary.answerCostTotal / summary.pricedAnswers : null,
+      averageAnswerTokens: summary.tokenAnswers ? summary.answerTokens / summary.tokenAnswers : null,
+      averageRoundsPerAnswer: summary.completedAnswers ? summary.answerRoundsTotal / summary.completedAnswers : null,
+      toolCalls: summary.toolCalls,
+      models: [...models.values()].map((m) => ({ ...m, cost: m.pricedRounds ? m.cost : null }))
+        .sort((a,b) => b.in + b.out - a.in - a.out),
+      tools: [...tools.entries()].map(([name, calls]) => ({ name, calls }))
+        .sort((a, b) => b.calls - a.calls)
+    };
+  }
+}

package/src/store/users.js

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+
+// Users, their preferences, and login sessions.
+// One area of the Store; see index.js.
+
+export class UserStore {
+  constructor(db, deps = {}) {
+    this.db = db;
+    Object.assign(this, deps);
+  }
+
+  getPrefs(userId) {
+    const out = {};
+    for (const r of this.db.prepare('SELECT key, value FROM user_prefs WHERE user_id = ?').all(userId)) out[r.key] = r.value;
+    return out;
+  }
+
+  setPref(userId, key, value) {
+    if (value == null) this.db.prepare('DELETE FROM user_prefs WHERE user_id = ? AND key = ?').run(userId, key);
+    else this.db.prepare(`INSERT INTO user_prefs (user_id, key, value) VALUES (?, ?, ?)
+      ON CONFLICT(user_id, key) DO UPDATE SET value = excluded.value`).run(userId, key, String(value));
+  }
+
+  get(id) {
+    return this.db.prepare('SELECT * FROM users WHERE id = ?').get(id) || null;
+  }
+
+  list() {
+    return this.db.prepare(`
+      SELECT u.id, u.email, u.name, u.role, u.status, u.external_id, u.created_at, u.last_login_at,
+             (SELECT COUNT(*) FROM chats c WHERE c.user_id = u.id) AS chat_count
+      FROM users u ORDER BY u.created_at ASC
+    `).all();
+  }
+
+  /** Admin-side changes only: role in (admin,user), status in (pending,approved,disabled). */
+  update(id, { role, status } = {}) {
+    const sets = []; const vals = [];
+    if (role !== undefined) { sets.push('role = ?'); vals.push(role); }
+    if (status !== undefined) {
+      sets.push('status = ?'); vals.push(status);
+      if (status === 'approved') { sets.push('approved_at = COALESCE(approved_at, ?)'); vals.push(Date.now()); }
+    }
+    if (sets.length) this.db.prepare(`UPDATE users SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+    return this.get(id);
+  }
+
+  byExternalId(externalId) {
+    return this.db.prepare('SELECT * FROM users WHERE external_id = ?').get(externalId) || null;
+  }
+
+  /** Whether another account already holds this email (emails are unique). */
+  emailTaken(email, exceptId) {
+    return Boolean(this.db.prepare('SELECT 1 FROM users WHERE email = ? AND id != ?').get(email, exceptId));
+  }
+
+  /**
+   * Creates the user a gateway vouched for, unless one with that external id
+   * exists. The unique index makes this atomic: concurrent first requests race
+   * to insert, exactly one wins. Returns { user, created }.
+   */
+  provision({ externalId, role, status, now = Date.now() }) {
+    const created = this.db.prepare(`
+      INSERT INTO users (id, external_id, role, status, created_at, approved_at, last_login_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(external_id) DO NOTHING
+    `).run(randomUUID(), externalId, role, status, now, status === 'approved' ? now : null, now).changes > 0;
+    return { user: this.byExternalId(externalId), created };
+  }
+
+  /** Gateway-side sync of identity metadata; only these columns can be set. */
+  sync(id, fields) {
+    const allowed = ['email', 'name', 'role', 'status', 'last_login_at'];
+    const keys = Object.keys(fields).filter((k) => allowed.includes(k));
+    if (keys.length) this.db.prepare(`UPDATE users SET ${keys.map((k) => `${k} = ?`).join(', ')} WHERE id = ?`).run(...keys.map((k) => fields[k]), id);
+    return this.get(id);
+  }
+
+  /** The single approved admin account behind a 'single' password. */
+  ensureOwner(id) {
+    const now = Date.now();
+    this.db.prepare(`INSERT INTO users (id, role, status, created_at, approved_at)
+      VALUES (?, 'admin', 'approved', ?, ?) ON CONFLICT(id) DO NOTHING`).run(id, now, now);
+  }
+
+  addSession(tokenHash, userId, expiresAt) {
+    this.db.prepare('INSERT INTO sessions (token_hash, user_id, created_at, expires_at) VALUES (?, ?, ?, ?)')
+      .run(tokenHash, userId, Date.now(), expiresAt);
+  }
+
+  getSession(tokenHash) {
+    return this.db.prepare('SELECT * FROM sessions WHERE token_hash = ?').get(tokenHash) || null;
+  }
+
+  deleteSession(tokenHash) {
+    this.db.prepare('DELETE FROM sessions WHERE token_hash = ?').run(tokenHash);
+  }
+
+  deleteUserSessions(userId) {
+    this.db.prepare('DELETE FROM sessions WHERE user_id = ?').run(userId);
+  }
+}

package/src/store/wire.js

@@ -0,0 +1,55 @@
+/* Row <-> message shapes: what the model is sent (toWire) and what the UI shows (toView). */
+
+function base(row) {
+  const msg = { role: row.role };
+  if (row.tool_call_id) msg.tool_call_id = row.tool_call_id;
+  if (row.tool_calls_json) msg.tool_calls = JSON.parse(row.tool_calls_json);
+  if (row.reasoning_details_json) msg.reasoning_details = JSON.parse(row.reasoning_details_json);
+  if (row.images_json) msg.images = JSON.parse(row.images_json);
+  return msg;
+}
+
+/**
+ * What the model sees. A demoted tool message sends its stub; everything else
+ * sends its content verbatim. Reasoning text rides along; `buildMessages` in
+ * harness/provider.js decides whether the provider gets it back.
+ */
+export function toWire(row) {
+  const msg = base(row);
+  if (row.reasoning) msg.reasoning = row.reasoning;
+  msg.content = row.role === 'tool' ? (row.stub_text ?? row.content) : (row.content ?? null);
+  // An epoch took these images off the wire. The note is a pure function of
+  // the row, so every rebuild sends the same bytes.
+  if (row.images_dropped && msg.images?.length) {
+    const n = msg.images.length;
+    msg.content = `${msg.content ?? ''}\n\n[${n} image${n === 1 ? '' : 's'} attached here ${n === 1 ? 'was' : 'were'} removed from context to save space. Ask the user to re-attach if you need to look again.]`;
+    delete msg.images;
+  }
+  // A model that was sent images needs the OpenAI multimodal shape -- an array
+  // of parts rather than a plain string. Built only when there are images, so
+  // every text-only turn keeps sending the plain string it always has, which
+  // is what most of the caching machinery in harness/provider.js assumes.
+  if (msg.images?.length) {
+    const parts = [];
+    if (msg.content) parts.push({ type: 'text', text: msg.content });
+    for (const img of msg.images) {
+      parts.push({ type: 'image_url', image_url: { url: `data:${img.mime};base64,${img.data}` } });
+    }
+    msg.content = parts;
+  }
+  delete msg.images;
+  return msg;
+}
+
+/** What the transcript shows: always the full text, stub or not. */
+export function toView(row) {
+  const msg = base(row);
+  // The client needs a handle on each message to be able to rewind to one.
+  msg.seq = row.seq;
+  msg.content = row.content ?? null;
+  if (row.reasoning) msg.reasoning = row.reasoning;
+  if (row.usage_json) msg.usage = JSON.parse(row.usage_json);
+  if (row.stub_text) msg.compacted = true;
+  if (row.origin_json) msg.origin = JSON.parse(row.origin_json);
+  return msg;
+}

package/src/tools/ask_tool.js

@@ -0,0 +1,93 @@
+/**
+ * ask_user -- lets the model put one question to the user mid-run and carry
+ * on with the answer in the same run.
+ *
+ * The waiting itself belongs to the server, which owns the run: it persists
+ * the question, draws it, runs the timeout and takes the answer. This file
+ * only validates the call and turns the outcome into the tool result. A run
+ * with nobody to ask (an automation) never waits; it gets the fallback at once.
+ */
+
+export const ASK_USER = 'ask_user';
+
+const MAX_QUESTION = 2000;
+const MAX_CHOICES = 10;
+const MAX_CHOICE = 200;
+
+export function askToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: ASK_USER,
+      description: [
+        'Ask the user one question and wait for the answer, then continue this same task',
+        'with it. The run pauses until they answer; if they do not answer in time, you are',
+        'told so and continue on your own assumptions.',
+        '',
+        'Use it only for information that materially changes the result and that you cannot',
+        'infer or safely assume: choosing between materially different files, accounts or',
+        'environments; a missing value; a decision with real downstream effects; a manual',
+        'step the user must do first.',
+        '',
+        'Do not use it to ask "should I continue?", for preferences with a sensible default,',
+        'to confirm ordinary reversible actions, or because the request is only mildly',
+        'ambiguous -- make a reasonable assumption and state it instead. One question per',
+        'call; offer `choices` when there are a few valid answers.'
+      ].join('\n'),
+      parameters: {
+        type: 'object',
+        properties: {
+          question: { type: 'string', description: 'The question, written for the user to read.' },
+          choices: {
+            type: 'array',
+            items: { type: 'string' },
+            description: `Optional answers to pick from (up to ${MAX_CHOICES}).`
+          },
+          allow_free_text: {
+            type: 'boolean',
+            description: 'Whether the user may type their own answer instead of picking a choice. Default true.'
+          }
+        },
+        required: ['question']
+      }
+    }
+  };
+}
+
+/** The result text for each way a question can end. JSON, so it parses and reads. */
+export function askResult(outcome) {
+  if (outcome.answered) return JSON.stringify({ answered: true, answer: outcome.answer });
+  const message = {
+    timeout: 'The user did not respond within the configured timeout.',
+    skipped: 'The user chose to let you continue without answering.',
+    unattended: 'No interactive user is available for this run.'
+  }[outcome.reason] || 'The question could not be put to the user.';
+  return JSON.stringify({
+    answered: false,
+    reason: outcome.reason,
+    message: `${message} Continue the task using your own reasonable assumptions, and state any`
+      + ' important assumptions in your final answer when they materially affect the result.'
+  });
+}
+
+/**
+ * The tool handler. `ctx.askUser({ question, choices, allowFreeText })`
+ * resolves to `{ answered: true, answer }` or `{ answered: false, reason }`;
+ * without one (an unattended run) the fallback comes back at once.
+ */
+export async function callAskUser(args, ctx) {
+  const question = typeof args.question === 'string' ? args.question.trim() : '';
+  if (!question) return 'Error: "question" is required and must be a non-empty string.';
+  if (question.length > MAX_QUESTION) return `Error: "question" is over ${MAX_QUESTION} characters; ask something shorter.`;
+  if (args.choices !== undefined && !(Array.isArray(args.choices) && args.choices.every((c) => typeof c === 'string'))) {
+    return 'Error: "choices" must be a list of strings.';
+  }
+  const choices = [...new Set((args.choices || []).map((c) => c.trim()).filter(Boolean))];
+  if (choices.length > MAX_CHOICES) return `Error: at most ${MAX_CHOICES} choices.`;
+  if (choices.some((c) => c.length > MAX_CHOICE)) return `Error: each choice must be under ${MAX_CHOICE} characters.`;
+  // Nothing to pick and nothing to type would be a question nobody can answer.
+  const allowFreeText = args.allow_free_text !== false || choices.length === 0;
+
+  if (ctx.unattended || !ctx.askUser) return askResult({ answered: false, reason: 'unattended' });
+  return askResult(await ctx.askUser({ question, choices, allowFreeText }));
+}

package/src/tools/chat_search_tool.js

@@ -0,0 +1,63 @@
+import { CORPUS } from '../store/index.js';
+
+/**
+ * search_chats -- lets the model look up the user's earlier conversations:
+ * what they asked and the answer they finally got. Ranked by the same
+ * retrieval engine as read_document (retrieval.js, 'chats' corpus), so it is
+ * lexical, dense or hybrid with retrieval.mode. Only the asking chat's owner's
+ * chats are searched, and never the asking chat itself -- that one is already
+ * in context (and expand_context reads what compaction folded away).
+ */
+
+export const SEARCH_CHATS = 'search_chats';
+
+const MAX_RESULTS = 10;
+
+export function chatSearchToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: SEARCH_CHATS,
+      description: [
+        "Search the user's earlier conversations (not this one) for what they asked and the answers they got.",
+        'Use it when the user refers to something discussed before ("like last time", "what did we decide about..."),',
+        'or when an earlier answer would save redoing work. Returns the best-matching question/answer pairs,',
+        'each with the chat it came from. Phrase the query as the topic, not as a question to the user.'
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'What to look for, in plain words.' },
+          limit: { type: 'integer', description: `How many turns to return, 1-${MAX_RESULTS} (default 5).` }
+        },
+        required: ['query']
+      }
+    }
+  };
+}
+
+const day = (ms) => (ms ? new Date(ms).toISOString().slice(0, 10) : 'undated');
+
+function clip(text, max) {
+  const t = String(text || '').trim();
+  return t.length > max ? `${t.slice(0, max)}… [${(t.length - max).toLocaleString('en-US')} more chars]` : t;
+}
+
+/** Runs one search. Returns a string, like every other tool result. */
+export async function callSearchChats(args, { store, retrieval, chatId, budget = 8000 }) {
+  const query = String(args?.query || '').trim();
+  if (!query) return 'Error: query is required.';
+  const limit = Math.min(MAX_RESULTS, Math.max(1, Number.parseInt(args?.limit, 10) || 5));
+  const owner = chatId ? store.chats.byId(chatId)?.user_id ?? null : null;
+  const hits = await retrieval.search(CORPUS.CHATS, { userId: owner, excludeChatId: chatId ?? null }, query, limit);
+  if (!hits.length) return `[search_chats · no earlier conversation matches "${query}"]\nTry other words for the same topic.`;
+
+  const out = [`[search_chats · ${hits.length} turn(s) matching "${query}"]`];
+  const share = Math.max(400, Math.floor((budget - out[0].length) / hits.length) - 120);
+  for (const h of hits) {
+    const q = clip(h.question, Math.min(600, Math.floor(share / 3)));
+    const a = h.answer ? clip(h.answer, share - q.length) : '(no answer recorded)';
+    out.push(`--- "${h.chatTitle}" · ${day(h.createdAt)} · chat ${h.chatId} ---\nQ: ${q}\nA: ${a}`);
+  }
+  return out.join('\n\n');
+}