freddie 0.0.121 → 0.0.123

package/src/plugins/case/toolset.js

@@ -0,0 +1,312 @@
+// freddie case toolset -- the agent's hands on a CRM "case" system of record, plus
+// a worker ENQUIRY surface. Agentic code lives here (per the layering mandate);
+// the data lives in a thatcher-backed store the host application injects. Nothing
+// here is casey-specific: the store, the field/enum config, and the role model all
+// arrive via toolCtx + plugin config, so a different application configures the
+// same toolset differently.
+//
+// Two design rules from the re-architecture:
+//  - IDENTITY comes from toolCtx (author/role/activeCaseRef/store), never a global
+//    singleton, so the agent loop stays identity-blind and a tool answers FOR the
+//    asking worker.
+//  - ENQUIRY outputs are PROJECTED: a per-case row handed to the model is scrubbed
+//    to a whitelist that EXCLUDES external_id/contact_id (a phone number / chat id),
+//    so a worker's list -- or a mis-scoped neighbour row -- can never surface PII.
+
+const str = (description, extra = {}) => ({ type: 'string', description, ...extra })
+
+// The default report field set. An app overrides via config (plugins.case.reportKeys)
+// so the captured-field vocabulary is configuration, not code.
+const DEFAULT_REPORT_KEYS = ['species', 'symptoms', 'location', 'how_to_find', 'affected_count',
+  'dead_count', 'onset', 'suspected_disease', 'recent_movement', 'identifying_traits',
+  'access_notes', 'farmer_available', 'contact_fallback', 'photos', 'audio', 'notes']
+
+const DEFAULT_STATUS_ENUM = ['new', 'triaging', 'in_progress', 'waiting', 'resolved', 'closed']
+
+// Whitelisted fields a per-case enquiry row may expose to the agent. Deliberately
+// EXCLUDES external_id and contact_id (PII). An app may extend via config
+// (plugins.case.enquiryProjection) but the PII keys are always stripped.
+const DEFAULT_PROJECTION = ['id', 'ref', 'status', 'priority', 'subject', 'summary',
+  'case_type', 'tags', 'assignee', 'autonomy', 'species', 'location', 'last_event_at', 'created_at', 'distance_km']
+const PII_KEYS = ['external_id', 'contact_id', 'contact', 'handle', 'phone', 'from']
+
+function pick(obj, keys) {
+  const out = {}
+  for (const k of keys) if (obj[k] !== undefined) out[k] = obj[k]
+  return out
+}
+
+// Project a case row for enquiry output: keep only whitelisted keys and NEVER any
+// PII key, even if the whitelist or a slimmed report leaked one in.
+function projectCase(row, projection) {
+  if (!row || typeof row !== 'object') return row
+  const out = pick(row, projection)
+  for (const k of PII_KEYS) delete out[k]
+  return out
+}
+
+// Resolve the store from toolCtx, else the plugin-configured fallback. Throws a
+// clear error (surfaced to the agent as a tool error) when neither is present.
+function storeFrom(ctx, fallback) {
+  const s = ctx?.store || fallback?.()
+  if (!s) throw new Error('case toolset: no store in toolCtx and no configured fallback store')
+  return s
+}
+
+// Build the case toolset. Options:
+//  - resolveStore():store   -- fallback store when toolCtx carries none (e.g. tests)
+//  - config                 -- scopedCfg-like { get(k,d), all() } for reportKeys,
+//                              statusEnum, enquiryProjection, actor
+//  - slimCase/slimEvent     -- optional projectors the host provides (else identity)
+export function buildCaseToolset({ resolveStore = null, config = null, slimCase = (c) => c, slimEvent = (e) => e } = {}) {
+  const cfg = config || { get: (_k, d) => d, all: () => ({}) }
+  const reportKeys = cfg.get('reportKeys', DEFAULT_REPORT_KEYS)
+  const statusEnum = cfg.get('statusEnum', DEFAULT_STATUS_ENUM)
+  const projection = cfg.get('enquiryProjection', DEFAULT_PROJECTION)
+  const actor = cfg.get('actor', 'agent')
+  const terminalStatuses = cfg.get('terminalStatuses', ['resolved', 'closed'])
+  // The field that identifies the REPORTER of a case (who messaged it in). A worker's
+  // "my cases" itinerary must scope by who REPORTED the case, not who it is assigned
+  // to -- the reporter is the channel author (external_id), never an operator assignee,
+  // so an assignee-scoped "my cases" returned nothing for the asking worker. Default
+  // external_id; a host keys it via plugins.case.reporterField.
+  const reporterField = cfg.get('reporterField', 'external_id')
+
+  // A case row scrubbed for enquiry output -- slim first (structured report), then
+  // project to the PII-free whitelist.
+  const enquiryRow = (c) => projectCase({ ...c, ...slimCase(c) }, projection)
+
+  const tools = []
+  const T = (name, schema, handler) => tools.push({ name, toolset: 'cases', schema: { name, ...schema }, handler })
+
+  // ---- core case_* tools (relocated from the host app; store from ctx) ----
+  T('case_get',
+    { description: 'Fetch a case by id, including its recent timeline events. Use to refresh your view before acting.',
+      parameters: { type: 'object', properties: { id: str('Case id') }, required: ['id'] } },
+    async ({ id }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const c = await store.getCase(id)
+      if (!c) return { error: `no case ${id}` }
+      const events = await store.listEvents(id, { limit: 30 })
+      // PII projection by caller: a worker-facing status read gets the enquiryRow
+      // whitelist (no external_id/contact_id/phone) so a model-narrated status answer
+      // can never echo a contact identifier; an operator/dashboard read keeps the full
+      // slimCase. Default to the safe (worker) projection when the role is unknown.
+      const operator = ctx?.role === 'operator' || ctx?.principal?.role === 'operator' || ctx?.role === 'dashboard'
+      return { case: operator ? slimCase(c) : enquiryRow(c), events: events.map(slimEvent) }
+    })
+
+  T('case_list',
+    { description: 'List cases, optionally filtered by status/channel/assignee/location. Use `location` (a town, area, or province name the person mentions) to find reports in a place -- this is the place-enquiry tool (case_near needs GPS the worker rarely has). Returns most-recently-active first, PII-free.',
+      parameters: { type: 'object', properties: {
+        status: str('Filter by workflow status', { enum: statusEnum }),
+        channel: str('Filter by channel'), assignee: str('Filter by assignee'),
+        location: str('A place name (town/area/province) to match reports whose location contains it'),
+        limit: { type: 'number', default: 25 },
+      } } },
+    async ({ status, channel, assignee, location, limit = 25 }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const where = {}
+      if (status) where.status = status
+      if (channel) where.channel = channel
+      if (assignee) where.assignee = assignee
+      // A place-name enquiry: match reports whose location contains the token. Rides
+      // thatcher's $ilike operator-where (no gazetteer regex -- the model supplies the
+      // place). The store's feature-detect shim falls back to a JS contains filter.
+      if (location) where.location = { $ilike: `%${String(location).toLowerCase()}%` }
+      const rows = await store.listCases(where, { limit })
+      // enquiryRow (PII-free) not slimCase -- a worker-facing list must never carry
+      // external_id/contact_id/phone.
+      return { count: rows.length, cases: rows.map(enquiryRow) }
+    })
+
+  T('case_update',
+    { description: 'Update editable case fields (subject, summary, priority, tags, assignee). Keep `summary` current -- it is your working memory of the case.',
+      parameters: { type: 'object', properties: {
+        id: str('Case id'), subject: str('Short human title'),
+        summary: str('One-paragraph rolling summary of the case state'),
+        priority: str('Priority', { enum: ['low', 'normal', 'high', 'urgent'] }),
+        tags: str('Comma-separated tags'), assignee: str('Operator handle, or "agent"'),
+      }, required: ['id'] } },
+    async ({ id, ...patch }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const clean = pick(patch, ['subject', 'summary', 'priority', 'tags', 'assignee'])
+      if (!Object.keys(clean).length) return { error: 'no editable fields supplied' }
+      const c = await store.getCase(id)
+      if (!c) return { error: `no case ${id}` }
+      // Observe mode is operator control: the agent may only observe.
+      if (c.autonomy === 'observe') return { error: 'case autonomy is "observe"; agent edits are disabled. Use case_observe to record notes.' }
+      const updated = await store.updateCase(id, clean, actor)
+      await store.appendEvent(id, { kind: 'action', actor: 'agent', text: `updated ${Object.keys(clean).join(', ')}`, data: clean })
+      return { ok: true, case: slimCase(updated) }
+    })
+
+  T('case_report',
+    { description: 'Record what you have learned about the report, one field at a time, as the person gives it. Pass ONLY the fields you actually learned this turn -- they merge into the running report, so you never lose earlier facts and never repeat a field already given.',
+      parameters: { type: 'object', properties: Object.fromEntries([['id', str('Case id')], ...reportKeys.map(k => [k, str(`Report field: ${k}`)])]), required: ['id'] } },
+    async ({ id, ...fields }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const incoming = pick(fields, reportKeys)
+      if (!Object.keys(incoming).length) return { error: 'no report fields supplied' }
+      const res = await store.mergeReport(id, incoming, actor)
+      if (res.error === 'observe') return { error: 'case autonomy is "observe"; agent edits are disabled. Use case_observe to record notes.' }
+      if (res.error) return { error: res.error }
+      await store.appendEvent(id, { kind: 'action', actor: 'agent', text: `recorded report fields: ${Object.keys(incoming).join(', ')}`, data: incoming })
+      return { ok: true, report: res.report, fieldsRecorded: Object.keys(incoming) }
+    })
+
+  T('case_observe',
+    { description: 'Record an observation or internal note on the case timeline WITHOUT replying to the contact.',
+      parameters: { type: 'object', properties: { id: str('Case id'), text: str('The observation') }, required: ['id', 'text'] } },
+    async ({ id, text }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      await store.appendEvent(id, { kind: 'observation', actor: 'agent', text })
+      return { ok: true }
+    })
+
+  // ---- ENQUIRY surface (the new worker-facing retrieval, role-scoped, PII-free) ----
+
+  T('case_mine',
+    { description: 'List the cases assigned to or claimed by the CURRENT worker. Use when the worker asks about "my cases" or "what am I working on". Returns PII-free rows, most recent first.',
+      parameters: { type: 'object', properties: { status: str('Optional status filter', { enum: statusEnum }), limit: { type: 'number', default: 20 } } } },
+    async ({ status, limit = 20 }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      // Scope by REPORTER (the channel author), not assignee -- a worker's own cases
+      // are the ones they reported. The equality filter already isolates the worker,
+      // so no row_access user scope is needed (and external_id is stripped by
+      // enquiryRow, so filtering on it never leaks it).
+      const where = ctx?.author ? { [reporterField]: ctx.author } : {}
+      if (status) where.status = status
+      const rows = await store.listCases(where, { limit })
+      return { count: rows.length, cases: rows.map(enquiryRow) }
+    })
+
+  T('case_today',
+    { description: 'List cases created or last active TODAY (the worker\'s "today\'s list"). Returns PII-free rows.',
+      parameters: { type: 'object', properties: { mineOnly: { type: 'boolean', default: true, description: 'restrict to the current worker' }, limit: { type: 'number', default: 20 } } } },
+    async ({ mineOnly = true, limit = 20 }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const dayStart = ctx?.now ? new Date(ctx.now) : new Date()
+      dayStart.setHours(0, 0, 0, 0)
+      const since = String(Math.floor(dayStart.getTime() / 1000))   // case timestamps are unix seconds
+      const where = { last_event_at: { $gte: since } }
+      if (mineOnly && ctx?.author) where[reporterField] = ctx.author   // reporter scope, not assignee
+      const rows = await store.listCases(where, { limit: mineOnly ? limit : limit, ...(mineOnly ? {} : { user: ctx?.principal }) })
+      return { count: rows.length, cases: rows.map(enquiryRow) }
+    })
+
+  T('case_near',
+    { description: 'List cases NEAR the worker, by a lat/lon bounding box. Provide the worker\'s lat/lon and a radius (km). Returns PII-free rows.',
+      parameters: { type: 'object', properties: {
+        lat: { type: 'number', description: 'worker latitude' }, lon: { type: 'number', description: 'worker longitude' },
+        radiusKm: { type: 'number', default: 25 }, limit: { type: 'number', default: 20 },
+      }, required: ['lat', 'lon'] } },
+    async ({ lat, lon, radiusKm = 25, limit = 20 }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      // Bounding box: ~111km per degree latitude; longitude scaled by cos(lat).
+      const dLat = radiusKm / 111
+      const dLon = radiusKm / (111 * Math.max(0.01, Math.cos(lat * Math.PI / 180)))
+      const where = { lat: { $gte: lat - dLat, $lte: lat + dLat }, lon: { $gte: lon - dLon, $lte: lon + dLon } }
+      const rows = await store.listCases(where, { limit, user: ctx?.principal })
+      const withDist = rows.map(r => ({ ...r, distance_km: haversineKm(lat, lon, Number(r.lat), Number(r.lon)) }))
+        .filter(r => !Number.isFinite(r.distance_km) || r.distance_km <= radiusKm)
+        .sort((a, b) => (a.distance_km ?? 1e9) - (b.distance_km ?? 1e9))
+      return { count: withDist.length, cases: withDist.map(enquiryRow) }
+    })
+
+  T('case_today_open',
+    { description: 'List OPEN, available work the current worker could help with -- unassigned or unresolved cases ("anything I can help with"). Returns PII-free rows.',
+      parameters: { type: 'object', properties: { limit: { type: 'number', default: 20 } } } },
+    async ({ limit = 20 }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      // Open = status NOT in the terminal set; available = no assignee or 'agent'.
+      const where = { status: { $in: statusEnum.filter(s => !terminalStatuses.includes(s)) } }
+      const rows = await store.listCases(where, { limit: limit * 3, user: ctx?.principal })
+      const available = rows.filter(r => !r.assignee || r.assignee === 'agent' || r.assignee === actor).slice(0, limit)
+      return { count: available.length, cases: available.map(enquiryRow) }
+    })
+
+  // ---- active-case binding: select / new (explicit) ----
+
+  T('case_select',
+    { description: 'Bind the worker\'s ACTIVE case to an existing case (by id or ref), so their subsequent field updates go into THIS case. Use when the worker says which case they are working on. Does NOT create a case.',
+      parameters: { type: 'object', properties: { id: str('Case id'), ref: str('Case reference (e.g. CASE-1042-x)') } } },
+    async ({ id, ref }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      let c = id ? await store.getCase(id) : null
+      if (!c && ref && store.findCaseByRef) c = await store.findCaseByRef(ref)
+      if (!c) return { error: `no case found for ${id || ref || '(nothing given)'}` }
+      if (store.setActiveCase && ctx?.author) await store.setActiveCase(ctx.author, c.id)
+      await store.appendEvent(c.id, { kind: 'observation', actor: 'system', text: `worker ${ctx?.author || 'unknown'} selected this case as active` })
+      return { ok: true, activeCase: enquiryRow(c) }
+    })
+
+  T('case_new',
+    { description: 'Explicitly CREATE a new case and bind it active to the worker. Use ONLY when the worker explicitly asks to start a new case/report -- never to auto-open one. Optionally seed a subject.',
+      parameters: { type: 'object', properties: { subject: str('Optional short subject') } } },
+    async ({ subject }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      if (!store.createCase) return { error: 'store does not support explicit case creation' }
+      const c = await store.createCase({ subject: subject || '', assignee: ctx?.author || actor, channel: ctx?.channel || 'enquiry' })
+      if (store.setActiveCase && ctx?.author) await store.setActiveCase(ctx.author, c.id)
+      await store.appendEvent(c.id, { kind: 'note', actor: 'system', text: `case explicitly opened by worker ${ctx?.author || 'unknown'}` })
+      return { ok: true, activeCase: enquiryRow(c) }
+    })
+
+  // ---- service controls the agent can ACT on (opt-out / human handoff) ----
+  T('case_stop',
+    { description: 'The person asked to STOP receiving messages (opt out). Records the opt-out so no more automatic replies go to them. Use ONLY on a clear opt-out.',
+      parameters: { type: 'object', properties: { id: str('Case id') }, required: ['id'] } },
+    async ({ id }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const c = await store.getCase(id)
+      if (!c) return { error: `no case ${id}` }
+      const tags = String(c.tags || '').split(',').map(s => s.trim()).filter(Boolean)
+      if (!tags.includes('opted-out')) tags.push('opted-out')
+      await store.updateCase(id, { tags: tags.join(',') }, ctx?.principal || undefined)
+      await store.appendEvent(id, { kind: 'observation', actor: 'agent', text: 'OPT-OUT: the person asked to stop; no more automatic replies.' })
+      return { ok: true }
+    })
+
+  T('case_handoff',
+    { description: 'The person wants a real person / operator to help. Flags the case for a human and records the request. Use on a clear ask for a person.',
+      parameters: { type: 'object', properties: { id: str('Case id') }, required: ['id'] } },
+    async ({ id }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const c = await store.getCase(id)
+      if (!c) return { error: `no case ${id}` }
+      const tags = String(c.tags || '').split(',').map(s => s.trim()).filter(Boolean)
+      if (!tags.includes('needs-human')) tags.push('needs-human')
+      await store.updateCase(id, { tags: tags.join(',') }, ctx?.principal || undefined)
+      await store.appendEvent(id, { kind: 'observation', actor: 'agent', text: 'HANDOFF REQUESTED: the person asked for a real person.' })
+      return { ok: true }
+    })
+
+  // The agent DECLARES which phase the conversation is now in; the host reads this
+  // observation back and applies the durable state transition (dstate). Append-only,
+  // like case_intent -- keeps the state I/O in the host, not the tool.
+  T('case_stage',
+    { description: 'Declare which phase the conversation is now in: greeting (a warm opener), gathering (collecting the report), enquiring (the worker asked about their work), answering (a general question), complete (the report is on record), handoff (a person is needed), or closed (they asked to stop). Call this when the phase changes so you keep your place and never repeat a question.',
+      parameters: { type: 'object', properties: {
+        to: str('Conversation phase', { enum: ['greeting', 'gathering', 'enquiring', 'answering', 'complete', 'handoff', 'closed'] }),
+      }, required: ['to'] } },
+    async ({ to }, ctx) => {
+      const store = storeFrom(ctx, resolveStore)
+      const id = ctx?.activeCaseId
+      if (!id) return { error: 'no active case' }
+      await store.appendEvent(id, { kind: 'observation', actor: 'agent', text: `STAGE-DECLARED ${to}` })
+      return { ok: true, stage: to }
+    })
+
+  return tools
+}
+
+function haversineKm(lat1, lon1, lat2, lon2) {
+  if (![lat1, lon1, lat2, lon2].every(Number.isFinite)) return NaN
+  const R = 6371, toRad = (d) => d * Math.PI / 180
+  const dLat = toRad(lat2 - lat1), dLon = toRad(lon2 - lon1)
+  const a = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2
+  return 2 * R * Math.asin(Math.sqrt(a))
+}
+
+export { projectCase, DEFAULT_PROJECTION, DEFAULT_REPORT_KEYS, PII_KEYS }

package/src/sessions.js

@@ -59,13 +59,28 @@ export async function appendMessage(sessionId, { role, content = '', toolCalls =
     const info = await d.prepare(`INSERT INTO messages (session_id, role, content, tool_calls, tool_call_id, ts) VALUES (?, ?, ?, ?, ?, ?)`)
         .run(sessionId, role, content, toolCalls ? JSON.stringify(toolCalls) : null, toolCallId, now)
     await d.prepare(`UPDATE sessions SET updated_at = ? WHERE id = ?`).run(now, sessionId)
+    // Auto-derive a scannable title from the first user prompt so `session list`
+    // shows readable rows instead of bare uuids. Only sets when title is null/empty.
+    if (role === 'user' && content) {
+        const title = content.replace(/\s+/g, ' ').trim().slice(0, 60)
+        if (title) await d.prepare(`UPDATE sessions SET title = ? WHERE id = ? AND (title IS NULL OR title = '')`).run(title, sessionId)
+    }
     return info.lastInsertRowid
 }
 
 export async function getMessages(sessionId) {
     const d = await db()
     const rows = await d.prepare(`SELECT id, role, content, tool_calls, tool_call_id, ts FROM messages WHERE session_id = ? ORDER BY ts ASC, id ASC`).all(sessionId)
-    return rows.map(r => ({ ...r, tool_calls: r.tool_calls ? JSON.parse(r.tool_calls) : null }))
+    return rows.map(r => {
+        let tool_calls = null
+        if (r.tool_calls) {
+            // A corrupted tool_calls cell (manual DB edit, a crash mid-serialize)
+            // must not crash every reader of this session -- degrade to null.
+            try { tool_calls = JSON.parse(r.tool_calls) }
+            catch (e) { console.error('sessions.js: corrupted tool_calls, treating as null', { id: r.id, error: String(e) }) }
+        }
+        return { ...r, tool_calls }
+    })
 }
 
 export async function listSessions(limit = 50) {
@@ -73,6 +88,28 @@ export async function listSessions(limit = 50) {
     return await d.prepare(`SELECT id, platform, title, created_at, updated_at, model, cwd, skill FROM sessions ORDER BY updated_at DESC LIMIT ?`).all(limit)
 }
 
+export async function getSession(id) {
+    const d = await db()
+    return await d.prepare(`SELECT id, platform, title, created_at, updated_at, model, cwd, skill FROM sessions WHERE id = ?`).get(id) || null
+}
+
+export async function deleteSession(id) {
+    const d = await db()
+    // messages_fts is an external-content FTS5 table (content='messages'); its
+    // 'ai' trigger only fires on INSERT, so deleting the messages does not purge
+    // the index. Rebuild the FTS index after the message rows are gone.
+    await d.prepare(`DELETE FROM messages WHERE session_id = ?`).run(id)
+    try { await d.prepare(`INSERT INTO messages_fts(messages_fts) VALUES('rebuild')`).run() } catch {}
+    const info = await d.prepare(`DELETE FROM sessions WHERE id = ?`).run(id)
+    return { id, deleted: (info.changes ?? info.rowsAffected ?? 0) > 0 }
+}
+
+export async function setSessionTitle(id, title) {
+    const d = await db()
+    await d.prepare(`UPDATE sessions SET title = ? WHERE id = ?`).run(title, id)
+    return { id, title }
+}
+
 export async function search(query, limit = 20) {
     const d = await db()
     const likePattern = `%${query}%`

package/src/toolset_distributions.js

@@ -6,6 +6,9 @@ export const DEFAULT_DISTRIBUTIONS = {
     ops: { enabledToolsets: ['core'], disabledToolsets: ['creative', 'browse'] },
     minimal: { enabledToolsets: ['core'], disabledToolsets: ['browse', 'creative'] },
     full: { enabledToolsets: ['core', 'browse', 'creative'], disabledToolsets: [] },
+    // A field worker on a CRM "case" surface: the core tools plus the case/enquiry
+    // toolset (case_* + case_mine/today/near/select/new). No browse/creative.
+    'field-worker': { enabledToolsets: ['core', 'cases'], disabledToolsets: ['browse', 'creative'] },
 }
 export function listDistributions() { return Object.keys(DEFAULT_DISTRIBUTIONS) }
 export function getDistribution(name) { return DEFAULT_DISTRIBUTIONS[name] || null }

package/src/toolsets.js

@@ -20,5 +20,5 @@ export async function getEnabledToolNames(enabled = ['core'], disabled = []) {
 
 export async function getAvailableToolsets() {
     const h = await bootHost()
-    return [...new Set(h.pi.tools.list().map(t => t.toolset || 'core'))]
+    return [...new Set(available(h).map(t => t.toolset || 'core'))]
 }

package/src/web/app.js

@@ -2,35 +2,53 @@ import { h, applyDiff, installStyles, components } from 'anentrypoint-design';
 import { fetchHost, ROUTES } from './state.js';
 import { PAGES } from './routes.js';
 
-const { AppShell, Topbar, Side, Crumb, Status, EmptyState, Chip } = components;
+const { AppShell, Topbar, Side, Crumb, Status, EmptyState, Chip, ThemeToggle, Icon } = components;
 
 await installStyles();
+// Styles installed — lift the FOUC visibility guard (see index.html reset).
+document.body.setAttribute('data-ready', '');
 
 const root = document.getElementById('app');
 root.textContent = 'loading…';
 const host0 = await fetchHost();
 root.innerHTML = '';
 
+// Lightweight transient error surface for mutation failures (config.saveValue,
+// chat.send, cron.create, …). state.js's mutators reject; the catch handler in
+// each callsite — or state.js's wrapMutation — routes the message here so a
+// thrown error is shown to the user instead of vanishing into the console.
+let _toastTimer = null;
+function notify(msg, tone = 'error') {
+    let el = document.getElementById('fd-toast');
+    if (!el) { el = document.createElement('div'); el.id = 'fd-toast'; el.className = 'fd-toast'; el.setAttribute('role', 'alert'); document.body.appendChild(el); }
+    el.textContent = String(msg || '').slice(0, 300);
+    el.dataset.tone = tone;
+    el.style.display = 'block';
+    if (_toastTimer) clearTimeout(_toastTimer);
+    _toastTimer = setTimeout(() => { el.style.display = 'none'; }, 6000);
+}
+if (typeof window !== 'undefined') window.__fd_notify = notify;
+
 function routeFromHash() {
     const m = String(location.hash || '').match(/^#(?:fd-)?([a-z]+)/i);
     const p = m && m[1];
     return ROUTES.find(r => r.path === p) ? p : 'home';
 }
-const state = { active: routeFromHash(), ts: new Date().toLocaleTimeString(), body: null, error: null, sampler: { ok: 0, bad: 0, total: 0 } };
+const state = { active: routeFromHash(), ts: new Date().toLocaleTimeString(), body: null, error: null, sampler: { ok: 0, bad: 0, total: 0, error: false } };
 
 async function refreshSampler() {
     try {
         const j = await fetch('/api/models/sampler').then(r => r.json());
         const ents = Object.values(j.status || {});
-        state.sampler = { total: ents.length, ok: ents.filter(s => s && s.available !== false).length, bad: ents.filter(s => s && s.available === false).length };
-    } catch { state.sampler = { ok: 0, bad: 0, total: 0 }; }
+        state.sampler = { total: ents.length, ok: ents.filter(s => s && s.available !== false).length, bad: ents.filter(s => s && s.available === false).length, error: false };
+    } catch { state.sampler = { ok: 0, bad: 0, total: 0, error: true }; }
 }
 await refreshSampler();
 setInterval(() => { refreshSampler().then(rerender); }, 15000);
 
 function buildSide() {
     return Side({ sections: [{ group: 'freddie', items: ROUTES.map(r => ({
-        glyph: r.glyph, label: r.label, href: '#fd-' + r.path,
+        glyph: Icon ? Icon(r.icon) : null, label: r.label, href: '#fd-' + r.path,
         active: state.active === r.path,
         onClick: ev => { ev.preventDefault(); setActive(r.path); },
     })) }] });
@@ -38,27 +56,48 @@ function buildSide() {
 
 function view() {
     const route = ROUTES.find(r => r.path === state.active) || ROUTES[0];
-    const body = state.body || EmptyState({ text: 'loading…', glyph: '◌' });
+    const body = state.body || EmptyState({ text: 'loading…' });
     const main = h('div', { key: state.active, class: 'fd-page' }, ...(Array.isArray(body) ? body : [body]));
-    const samplerPill = state.sampler.total > 0
-        ? Chip({ tone: state.sampler.bad > 0 ? 'miss' : 'ok', children: 'sampler ' + state.sampler.ok + '/' + state.sampler.total })
-        : Chip({ tone: 'neutral', children: 'sampler —' });
+    const samplerPill = state.sampler.error
+        ? Chip({ tone: 'miss', children: 'sampler err' })
+        : state.sampler.total > 0
+            ? Chip({ tone: state.sampler.bad > 0 ? 'miss' : 'ok', children: 'sampler ' + state.sampler.ok + '/' + state.sampler.total })
+            : Chip({ tone: 'neutral', children: 'sampler —' });
+    // Layout lives in .fd-topbar-leaf (index.html reset block) — zero inline CSS.
+    const leaf = h('span', { class: 'fd-topbar-leaf' },
+        samplerPill, ThemeToggle ? ThemeToggle({ compact: true }) : null);
     return AppShell({
-        topbar: Topbar({ brand: 'freddie', leaf: samplerPill, items: [], active: '' }),
-        crumb: Crumb({ trail: ['freddie'], leaf: route.path, right: state.error ? Chip({ tone: 'miss', children: 'error' }) : Chip({ tone: 'ok', children: 'live' }) }),
+        topbar: Topbar({ brand: 'freddie', leaf, items: [], active: '' }),
+        crumb: Crumb({ trail: ['freddie'], leaf: route.label || route.path, right: state.error ? Chip({ tone: 'miss', children: 'error' }) : Chip({ tone: 'ok', children: 'live' }) }),
         side: buildSide(),
         main,
         status: Status({ left: ['ds-247420 · webjsx · ' + ROUTES.length + ' routes'], right: [state.ts] }),
     });
 }
 
-function rerender() { applyDiff(root, view()); }
+function rerender() {
+    // LIVE-ROUTE RECOMPUTE HOOK: rerender() reuses the cached state.body. No
+    // freddie route currently streams (SSE/live updates) — pages are computed
+    // once per nav in loadActive(). If a live route is added (e.g. 'chat' with
+    // SSE), recompute its body here before applyDiff, per AGENTS.md:
+    //   if (state.active === 'chat') { Promise.resolve(PAGES.chat(host0)).then(b => { state.body = b; applyDiff(root, view()); }); return; }
+    applyDiff(root, view());
+}
 
+function setDocTitle(p) {
+    const r = ROUTES.find(x => x.path === p);
+    document.title = 'freddie · ' + (r ? (r.label || r.path) : p);
+}
+function focusMain() {
+    const main = root.querySelector('#app-main');
+    if (main) { main.setAttribute('tabindex', '-1'); main.focus({ preventScroll: false }); }
+}
 function setActive(p) {
     if (state.active === p) return;
     state.active = p; state.body = null;
     const want = '#fd-' + p;
     if (location.hash !== want) { try { history.replaceState(null, '', want); } catch { location.hash = want; } }
+    setDocTitle(p);
     rerender(); loadActive();
 }
 if (typeof window !== 'undefined') {
@@ -77,13 +116,17 @@ async function loadActive() {
     } catch (e) {
         if (state.active !== active) return;
         state.error = String(e && e.stack || e);
+        // Reflect the error in the tab title (success path sets it in setActive).
+        document.title = 'freddie · ' + active + ' (error)';
         const { Panel } = components;
         state.body = Panel({ title: 'page error', children: h('pre', { class: 'fd-pre fd-page-error' }, state.error) });
     }
     state.ts = new Date().toLocaleTimeString();
     applyDiff(root, view());
+    focusMain();
 }
 
+setDocTitle(state.active);
 applyDiff(root, view());
 loadActive();
 

package/src/web/index.html

@@ -4,16 +4,43 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Freddie Dashboard</title>
-<link rel="stylesheet" href="/vendor/anentrypoint-design/247420.css">
+<link rel="stylesheet" href="/vendor/anentrypoint-design/sdk.css">
 <script type="importmap">
-{ "imports": { "anentrypoint-design": "/vendor/anentrypoint-design/247420.js" } }
+{ "imports": { "anentrypoint-design": "/vendor/anentrypoint-design/sdk.js" } }
+</script>
+<!-- Theme: the SDK ThemeToggle controller is the single source of truth and
+     persists to <html data-theme> (verified in browser). Pre-paint the saved or
+     system theme onto <html> here, BEFORE the module loads, so first paint
+     matches the controller and there is no wrong-theme flash. -->
+<script>
+(function () {
+  var t;
+  try { t = localStorage.getItem('247420:theme'); } catch (e) {}
+  if (!t) t = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  document.documentElement.setAttribute('data-theme', t);
+})();
 </script>
 <style>
 html, body { margin: 0; padding: 0; height: 100%; }
 #app { height: 100%; }
+/* FOUC guard: hide the document until app.js signals ready (after installStyles)
+   so #app never paints raw unstyled 'loading…' text. */
+body { visibility: hidden; }
+body[data-ready] { visibility: visible; }
+/* Cap raw-JSON/code dumps so unbounded payloads scroll instead of blowing
+   the page layout. Ideally belongs in the anentrypoint-design SDK CSS. */
+.fd-pre { max-height: 60vh; overflow: auto; }
+/* Topbar leaf layout (sampler pill + theme toggle). One utility class so app.js
+   carries no inline style string. Ideally belongs in the SDK CSS. */
+.fd-topbar-leaf { display: inline-flex; gap: 8px; align-items: center; }
+/* Transient mutation-error toast (see app.js notify()). */
+.fd-toast { position: fixed; bottom: 16px; left: 50%; transform: translateX(-50%);
+  z-index: 1000; max-width: 90vw; padding: 8px 14px; border-radius: 8px;
+  background: #b3261e; color: #fff; font: 13px/1.4 system-ui, sans-serif;
+  box-shadow: 0 4px 16px rgba(0,0,0,.3); }
 </style>
 </head>
-<body data-theme="light">
+<body>
 <div id="app"></div>
 <script type="module" src="./app.js"></script>
 </body>

package/src/web/server.js

@@ -1,10 +1,29 @@
 import express from 'express'
 import path from 'node:path'
+import fs from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { bootHost } from '../host/index.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+// Resolve the real hashed SDK bundle filenames (247420.js / 247420.css today).
+// index.html pins stable aliases (sdk.js / sdk.css); we map them to whatever
+// hashed file is actually present so a version bump can't 404 silently.
+function resolveSdkBundle(distDir) {
+    let js = '247420.js', css = '247420.css'
+    try {
+        const files = fs.readdirSync(distDir)
+        const jsHit = files.find(f => /^247420.*\.js$/.test(f))
+        const cssHit = files.find(f => /^247420.*\.css$/.test(f))
+        if (jsHit) js = jsHit
+        if (cssHit) css = cssHit
+        if (!jsHit || !cssHit) console.error(`[dashboard] SDK bundle missing in ${distDir} (js=${jsHit || 'NONE'}, css=${cssHit || 'NONE'}) — dashboard will fail to mount. Run: node scripts/build.mjs in anentrypoint-design`)
+    } catch (e) {
+        console.error(`[dashboard] cannot read SDK dist dir ${distDir}: ${e.message}`)
+    }
+    return { js, css }
+}
+
 export async function createDashboard({ port = 0 } = {}) {
     const host = await bootHost()
     // Rehydrate any interrupted machines (agent turns, batches) from their
@@ -12,8 +31,30 @@ export async function createDashboard({ port = 0 } = {}) {
     try { const { resumeAll } = await import('../machines/resume.js'); await resumeAll() } catch (_) {}
     const app = express()
     app.use(express.json())
-    app.use(express.static(__dirname))
+    // Baseline security headers for the local dashboard. No CSP (the SDK uses
+    // inline styles/SVG); these are the cheap, no-false-positive defaults.
+    app.use((req, res, next) => {
+        res.set('X-Content-Type-Options', 'nosniff')
+        res.set('X-Frame-Options', 'SAMEORIGIN')
+        res.set('Referrer-Policy', 'same-origin')
+        next()
+    })
     const fromNodeModules = path.join(__dirname, '..', '..', 'node_modules', 'anentrypoint-design', 'dist')
+    const sdk = resolveSdkBundle(fromNodeModules)
+
+    // Stable aliases -> real hashed bundle. Immutable cache (hashed content).
+    const sendImmutable = file => (req, res) => res.set('Cache-Control', 'public, max-age=31536000, immutable').sendFile(path.join(fromNodeModules, file))
+    app.get('/vendor/anentrypoint-design/sdk.js', sendImmutable(sdk.js))
+    app.get('/vendor/anentrypoint-design/sdk.css', sendImmutable(sdk.css))
+
+    // index.html / app.js are mutable entry points — never cache.
+    app.use((req, res, next) => {
+        if (req.method === 'GET' && (req.path === '/' || req.path === '/index.html' || req.path === '/app.js')) {
+            res.set('Cache-Control', 'no-cache')
+        }
+        next()
+    })
+    app.use(express.static(__dirname))
     app.use('/vendor/anentrypoint-design', express.static(fromNodeModules))
     const nmKitsOs = path.join(__dirname, '..', '..', 'node_modules', 'anentrypoint-design', 'src', 'kits', 'os')
     app.use('/vendor/anentrypoint-design/kits/os', express.static(nmKitsOs))
@@ -23,6 +64,14 @@ export async function createDashboard({ port = 0 } = {}) {
     }
     const debugApi = host.gui._state.apis.get('debug')
     if (debugApi?.attach) debugApi.attach(app)
-    const { server, actualPort } = await new Promise((res, rej) => { const s = app.listen(port, () => res({ server: s, actualPort: s.address().port })); s.once('error', rej) })
+
+    // SPA fallback: unknown non-API GET routes serve index.html so deep links
+    // (and client-side hash routes) don't return Express's default 404 HTML.
+    // /api/* and /vendor/* are excluded — those 404 legitimately as data/assets.
+    app.get(/.*/, (req, res, next) => {
+        if (req.path.startsWith('/api/') || req.path.startsWith('/vendor/')) return next()
+        res.set('Cache-Control', 'no-cache').sendFile(path.join(__dirname, 'index.html'))
+    })
+    const { server, actualPort } = await new Promise((res, rej) => { const s = app.listen(port, () => { const a = s.address(); res({ server: s, actualPort: a && typeof a === 'object' ? a.port : port }) }); s.once('error', rej) })
     return { server, port: actualPort, url: `http://127.0.0.1:${actualPort}/`, stop: () => new Promise(r => server.close(() => r())) }
 }