synabun 1.3.0 → 2.0.0-beta

package/neural-interface/public/shared/assistant/asst-hosts.js

@@ -0,0 +1,262 @@
+// ═══════════════════════════════════════════
+// SynaBun Assistant — hosts (terminal tab + sidepanel)
+// ═══════════════════════════════════════════
+// One Assistant component (asst-panel.js mountAssistant) is mounted by two
+// hosts: the terminal tab (ui-terminal.js) and the sidepanel
+// (asst-sidepanel.js). Each host keeps its own window chrome; this module owns
+// what they share, so they cannot drift apart:
+//   - server create/resume (once, here)
+//   - one session lives in one host (resume/focus goes to where it is open)
+//   - the last-used session (Apps → Assistant, `a`, Ctrl+A)
+//   - the guest gate
+// DOM-free on purpose: node:test suites import it. The app wiring with real
+// dependencies lives in ../ui-assistant.js.
+//
+// Adapter contract (registered by each host):
+//   { id,
+//     has(sessionId) → bool,
+//     sessions() → sessionId[]            (preferred first: the active tab)
+//     focus(sessionId, { prompt })        (show + focus; send prompt if given)
+//     mount({ sessionId, meta, brain, label, floating, prompt, reattach })
+//     close(sessionId, { closeServer })
+//     toggle(sessionId|null)              (hide if visible, else show/focus)
+//     toast?(text) }                      (errors shown in the host; else deps.toast)
+
+import { normalizeBrain } from './asst-state.js';
+
+export const ASSISTANT_CLOSED_STATUSES = new Set(['closed', 'ended', 'deleted', 'archived', 'destroyed']);
+export const ASSISTANT_GONE_STATUSES = new Set(['deleted', 'destroyed']);
+
+/** A session still open on the server (not closed, ended, deleted…): boot restores saved tabs only to these. */
+export function isAssistantSessionLive(meta) {
+  if (!meta || typeof meta !== 'object') return false;
+  if (meta.closedAt || meta.endedAt || meta.deletedAt) return false;
+  return !ASSISTANT_CLOSED_STATUSES.has(String(meta.status || '').toLowerCase());
+}
+
+/**
+ * A session the user can reopen (Sessions menu, /resume, a notification): any
+ * record the server still has, an ended one included — attaching revives it on
+ * its own brain, which resumes the stored Claude session / Codex thread.
+ */
+export function isAssistantSessionRestorable(meta) {
+  if (!meta || typeof meta !== 'object' || meta.deletedAt) return false;
+  return !ASSISTANT_GONE_STATUSES.has(String(meta.status || '').toLowerCase());
+}
+
+/** English note for a session the server started on another model (session.fallback). */
+export function describeBrainFallback(fallback) {
+  if (!fallback || typeof fallback !== 'object') return '';
+  const to = fallback.label || fallback.to || 'another model';
+  return fallback.reason === 'provider'
+    ? `Every ${fallback.fromProvider || fallback.from} model is disabled in the Assistant's Models list — started on ${to}.`
+    : `${fallback.from} is disabled in the Assistant's Models list — started on ${to}.`;
+}
+
+/**
+ * deps: { api: { list(), get(id), create({brain,label,fallback}) },
+ *         isBlocked() → bool, toast(text), storedBrain() → brain|null,
+ *         fallbackText(session.fallback) → text, defaultHost: 'terminal' }
+ */
+export function createAssistantHosts({
+  api,
+  isBlocked = () => false,
+  toast = () => {},
+  storedBrain = () => null,
+  fallbackText = describeBrainFallback,
+  defaultHost = 'terminal',
+} = {}) {
+  const adapters = new Map(); // id → adapter; registration order breaks ties
+  let last = null;            // { hostId, sessionId } — the last-used session
+
+  function register(adapter) {
+    if (!adapter?.id) throw new Error('Assistant host adapter needs an id');
+    adapters.set(adapter.id, adapter);
+    return () => {
+      if (adapters.get(adapter.id) !== adapter) return;
+      adapters.delete(adapter.id);
+      if (last?.hostId === adapter.id) last = null;
+    };
+  }
+
+  function ownerOf(sessionId) {
+    if (!sessionId) return null;
+    for (const adapter of adapters.values()) {
+      try { if (adapter.has(sessionId)) return adapter.id; } catch { /* a broken host owns nothing */ }
+    }
+    return null;
+  }
+
+  function sessionsOf(hostId) {
+    try { return (adapters.get(hostId)?.sessions?.() || []).filter(Boolean); } catch { return []; }
+  }
+
+  function noteFocus(sessionId, hostId) {
+    if (sessionId && hostId && adapters.has(hostId)) last = { hostId, sessionId };
+  }
+
+  /** The requested host, else the default, else whichever registered first. */
+  function hostFor(hostId) {
+    return adapters.get(hostId) || adapters.get(defaultHost) || adapters.values().next().value || null;
+  }
+
+  function focusIn(hostId, sessionId, prompt = '') {
+    const adapter = adapters.get(hostId);
+    if (!adapter) return null;
+    adapter.focus(sessionId, { prompt: prompt || '' });
+    noteFocus(sessionId, hostId);
+    return { host: hostId, sessionId, focused: true };
+  }
+
+  /** Map(id → session) of the sessions still open on the server (boot's saved-tab restore). */
+  async function fetchLive() {
+    try {
+      const list = await api.list();
+      return new Map((Array.isArray(list) ? list : [])
+        .filter(s => s?.id && isAssistantSessionLive(s))
+        .map(s => [s.id, s]));
+    } catch { return new Map(); }
+  }
+
+  /**
+   * Open a session in a host. `resume` names an existing session: if a host
+   * already has it, it is focused there; an ended one is reopened as it was;
+   * only one the server no longer has is replaced by a fresh one. Ownership is
+   * re-checked after every await, so a session mounted meanwhile by the other
+   * host is focused, never doubled.
+   */
+  async function open({ host = null, brain = null, resume = null, label = '', floating = false, prompt = '' } = {}) {
+    if (isBlocked()) return null;
+    let sessionId = resume ? String(resume) : null;
+    let meta = null;
+    if (sessionId) {
+      const owner = ownerOf(sessionId);
+      if (owner) return focusIn(owner, sessionId, prompt);
+      try {
+        const data = await api.get(sessionId);
+        meta = data?.session || data;
+        if (!isAssistantSessionRestorable(meta)) { meta = null; sessionId = null; }
+      } catch { meta = null; sessionId = null; }
+      const owned = ownerOf(sessionId);
+      if (owned) return focusIn(owned, sessionId, prompt);
+    }
+    const target = hostFor(host);
+    const say = (text) => { if (target?.toast) target.toast(text); else toast(text); };
+    if (!target) { toast('Assistant unavailable'); return null; }
+    if (!sessionId) {
+      const b = normalizeBrain(brain || storedBrain());
+      let res;
+      try {
+        // A model disabled since it was picked (Assistant → Models) must not
+        // lock the Assistant out: the server starts on its enabled stand-in.
+        res = await api.create({ brain: b, label: label || undefined, fallback: true });
+      } catch (err) {
+        say(`Assistant unavailable: ${err?.message || err}`);
+        return null;
+      }
+      meta = res?.session || res;
+      sessionId = meta?.id || res?.sessionId || res?.id || null;
+      if (!sessionId) { say('Assistant session could not be created'); return null; }
+      if (!meta?.brain) meta = { ...(meta || {}), brain: b };
+      if (meta?.fallback) say(fallbackText(meta.fallback) || describeBrainFallback(meta.fallback));
+    }
+    const owner = ownerOf(sessionId);
+    if (owner) return focusIn(owner, sessionId, prompt);
+    const adapter = hostFor(host);
+    if (!adapter) { say('Assistant unavailable'); return null; }
+    adapter.mount({
+      sessionId,
+      meta,
+      // A substituted model is what the tab shows (and saves as the last used brain).
+      brain: meta?.fallback ? meta.brain : (brain || meta?.brain || null),
+      label: label || '',
+      floating: floating === true,
+      prompt: prompt || '',
+      reattach: !!resume,
+    });
+    noteFocus(sessionId, adapter.id);
+    return { host: adapter.id, sessionId, mounted: true };
+  }
+
+  /** The last-used live session, if its host still has it. */
+  function lastOpen() {
+    return last && ownerOf(last.sessionId) === last.hostId ? last : null;
+  }
+
+  /** Hosts in preference order: the requested one, the default, then the rest. */
+  function hostOrder(preferred) {
+    return [...new Set([preferred, defaultHost, ...adapters.keys()].filter(id => id && adapters.has(id)))];
+  }
+
+  /**
+   * Apps → Assistant / `a`: focus an open session (the named one, else the
+   * last used, else any), otherwise open a new one in the default host.
+   */
+  async function openOrFocus(opts = {}) {
+    if (isBlocked()) return null;
+    if (opts.sessionId) {
+      const owner = ownerOf(opts.sessionId);
+      if (owner) return focusIn(owner, opts.sessionId, opts.prompt);
+    }
+    if (!opts.fresh) {
+      const recent = lastOpen();
+      if (recent) return focusIn(recent.hostId, recent.sessionId, opts.prompt);
+      for (const hostId of hostOrder(opts.host)) {
+        const [sessionId] = sessionsOf(hostId);
+        if (sessionId) return focusIn(hostId, sessionId, opts.prompt);
+      }
+    }
+    return open({ ...opts, resume: null, host: opts.host || defaultHost });
+  }
+
+  /** Ctrl+A: hide or show the last-used session in its host; open one if none. */
+  function toggle() {
+    if (isBlocked()) return null;
+    const recent = lastOpen();
+    if (recent) {
+      adapters.get(recent.hostId).toggle(recent.sessionId);
+      return { host: recent.hostId, sessionId: recent.sessionId, toggled: true };
+    }
+    for (const hostId of hostOrder(null)) {
+      const [sessionId] = sessionsOf(hostId);
+      if (sessionId) {
+        adapters.get(hostId).toggle(sessionId);
+        return { host: hostId, sessionId, toggled: true };
+      }
+    }
+    return open({ host: defaultHost });
+  }
+
+  /** Notification click: focus the session where it lives, or resume it. */
+  async function show(sessionId, { host = null } = {}) {
+    if (!sessionId) return openOrFocus({});
+    if (isBlocked()) return null;
+    const owner = ownerOf(sessionId);
+    if (owner) return focusIn(owner, sessionId);
+    return open({ resume: sessionId, host: host || lastOpen()?.hostId || defaultHost });
+  }
+
+  /** Another client ended the session: drop it where it is open, without re-closing it server-side. */
+  function ended(sessionId) {
+    const owner = ownerOf(sessionId);
+    if (last?.sessionId === sessionId) last = null;
+    if (!owner) return false;
+    adapters.get(owner).close(sessionId, { closeServer: false });
+    return true;
+  }
+
+  return {
+    register,
+    ownerOf,
+    open,
+    openOrFocus,
+    toggle,
+    show,
+    ended,
+    noteFocus,
+    fetchLive,
+    isLive: isAssistantSessionLive,
+    lastUsed: () => lastOpen(),
+    hosts: () => [...adapters.keys()],
+  };
+}

package/neural-interface/public/shared/assistant/asst-mascot.js

@@ -0,0 +1,311 @@
+// ═══════════════════════════════════════════
+// SynaBun Assistant — the panel's mascot director
+// ═══════════════════════════════════════════
+// The renderer (asst-render.js) owns the rigs and says which one is on screen:
+// the hero (the empty state's character, parked after a send until the first
+// stage takes it over) or the live rack's stage. This module dresses that one
+// in the panel's own state, above the pose the renderer gives it:
+//
+//   offline         the socket dropped (the Reconnecting banner); one startle on reconnect
+//   blocked         a card waits on you: eyes on it, two pulses, then still
+//   success, error  once, when a turn that did real work ends (then idle)
+//   watch           while you type: eyes on the caret column, look() at most
+//                   every 120 ms; back 1.5 s after the last key, at once on send
+//   sleep           the hero only, after 90 s with no input while nothing runs;
+//                   the rig wakes itself on a pointer move or a key
+//
+// Anything else is the renderer's pose: the hero idles (thinks once parked),
+// the stage acts out its call. A pose the director sets is held: the renderer
+// leaves it alone until the director lets go and asks it to restore its own.
+// Only one panel animates its rigs: the visible one used last (typing, focus,
+// a new stage). Pure logic: the clock, timers and page input come in through
+// `env`, so node:test drives it with fakes (tests/assistant-mascot.test.mjs).
+
+export const MASCOT_TIMING = Object.freeze({
+  watchEveryMs: 120,
+  watchIdleMs: 1500,
+  sleepAfterMs: 90_000,
+  realWorkMs: 3000,
+  oneShotMs: Object.freeze({ success: 1000, error: 900 }),
+});
+
+const unit = (v) => (v < -1 ? -1 : v > 1 ? 1 : v);
+
+/**
+ * The pose a turn ends with: error when it failed or its last call did,
+ * success after real work (a tool call, or longer than 3 s), else none. A
+ * turn the user stopped ends with nothing.
+ */
+export function turnEndPose({ aborted = false, errored = false, lastFailed = false, calls = 0, elapsedMs = 0 } = {}) {
+  if (aborted) return null;
+  if (errored || lastFailed) return 'error';
+  if (Number(calls) > 0 || Number(elapsedMs) > MASCOT_TIMING.realWorkMs) return 'success';
+  return null;
+}
+
+/**
+ * Where a rig in `box` looks to see `point` (client px): the rig's own cursor
+ * mapping, d / (d + 140) × 1.25 along the direction. `horizontal` keeps the
+ * column only (watch looks along the line being typed).
+ */
+export function lookToward(box, point, { horizontal = false } = {}) {
+  if (!box || !point || !(box.width > 0) || !Number.isFinite(point.x)) return { x: 0, y: 0 };
+  const vx = point.x - (box.left + box.width / 2);
+  const vy = horizontal || !Number.isFinite(point.y) ? 0 : point.y - (box.top + box.height / 2);
+  const d = Math.hypot(vx, vy);
+  if (d < 1) return { x: 0, y: 0 };
+  const m = (d / (d + 140)) * 1.25;
+  return { x: unit((vx / d) * m), y: unit((vy / d) * m) };
+}
+
+// ── One panel animates: the visible one used last ──
+const directors = new Set();
+let lead = null;
+let seq = 0;
+
+function elect() {
+  let best = null;
+  for (const d of directors) if (d.visible() && (!best || d.activeAt() > best.activeAt())) best = d;
+  if (!best) for (const d of directors) if (!best || d.activeAt() > best.activeAt()) best = d;
+  if (best === lead) return;
+  const prev = lead;
+  lead = best;
+  prev?.leadChanged();
+  best?.leadChanged();
+}
+
+/**
+ * createMascotDirector({ getTarget, caret, setEnabled, isVisible, env })
+ * getTarget() → the renderer's visible mascot { kind: 'hero'|'stage', rig, el,
+ *   parked?(), hold(on), restore() } or null; caret() → the caret's client
+ *   point or null; setEnabled(on) → whether this panel's rigs animate;
+ *   isVisible() → the panel is on screen.
+ * env: { now, setTimeout, clearTimeout, input(fn) → unsubscribe (page pointer
+ *   and key input), lastInputAt() }.
+ */
+export function createMascotDirector({ getTarget = () => null, caret = () => null, setEnabled = () => {}, isVisible = () => true, env = {} } = {}) {
+  const now = env.now || (() => Date.now());
+  const later = env.setTimeout || ((fn, ms) => setTimeout(fn, ms));
+  const cancel = env.clearTimeout || ((id) => clearTimeout(id));
+  const pageInput = typeof env.input === 'function' ? env.input : null;
+  const pageInputAt = typeof env.lastInputAt === 'function' ? env.lastInputAt : () => -Infinity;
+
+  let destroyed = false;
+  let target = null; // the rig on screen the director last dressed
+  let holding = false; // hold(true) is in force on `target`
+  let shown = ''; // the pose (and then) set on `target`
+  let typing = false;
+  let typingTimer = 0;
+  let lookTimer = 0;
+  let lookedAt = -Infinity;
+  let blocked = null; // () → the waiting card's rect
+  let offline = false;
+  let oneShot = null; // { pose, target, timer }
+  let turnActive = false;
+  let sleeping = false;
+  let sleepTimer = 0;
+  let lastInput = now();
+  let stopInput = null;
+  let activeAt = (seq += 1);
+
+  const safe = (fn) => { try { return fn(); } catch { return undefined; } };
+  const boxOf = (t) => safe(() => t.el?.getBoundingClientRect?.()) || null;
+
+  function desired(t) {
+    if (offline) return { pose: 'offline' };
+    if (blocked) {
+      // The card's head (its title and command sit top left), not its centre.
+      const card = safe(blocked);
+      const point = card && card.width ? { x: card.left + Math.min(card.width * 0.3, 160), y: card.top + Math.min(card.height / 2, 28) } : null;
+      return { pose: 'blocked', look: lookToward(boxOf(t), point) };
+    }
+    if (oneShot && oneShot.target === t) return { pose: oneShot.pose, opts: { then: 'idle' } };
+    if (typing) return { pose: 'watch', look: lookToward(boxOf(t), safe(caret), { horizontal: true }) };
+    if (sleeping && t.kind === 'hero' && !safe(() => t.parked?.())) return { pose: 'sleep' };
+    return null;
+  }
+
+  /** Dress the rig on screen for the current state (or hand it back to the renderer). */
+  function apply() {
+    if (destroyed) return;
+    const t = safe(getTarget) || null;
+    if (t !== target) {
+      if (target && holding) safe(() => target.hold(false));
+      target = t;
+      holding = false;
+      shown = '';
+      if (oneShot && oneShot.target !== t) dropOneShot();
+      listenInput();
+      armSleep();
+    }
+    if (!t) return;
+    const want = desired(t);
+    if (!want) {
+      if (!holding) return;
+      holding = false;
+      shown = '';
+      safe(() => t.hold(false));
+      safe(() => t.restore());
+      return;
+    }
+    if (!holding) { holding = true; safe(() => t.hold(true)); }
+    const key = `${want.pose}|${want.opts?.then || ''}`;
+    if (key !== shown) { shown = key; safe(() => t.rig.setPose(want.pose, want.opts)); }
+    if (want.look) safe(() => t.rig.look(want.look.x, want.look.y));
+  }
+
+  // ── Page input: the hero sleeps after 90 s of quiet and wakes on the next input ──
+  function noteInput() {
+    lastInput = now();
+    if (sleeping) { sleeping = false; apply(); armSleep(); }
+  }
+
+  function listenInput() {
+    const want = !!target && target.kind === 'hero' && !!pageInput;
+    if (want && !stopInput) stopInput = safe(() => pageInput(noteInput)) || null;
+    if (!want && stopInput) { safe(stopInput); stopInput = null; }
+  }
+
+  function canSleep() {
+    const t = target;
+    return !destroyed && !!t && t.kind === 'hero' && !safe(() => t.parked?.()) && !turnActive && !typing && !blocked && !offline && !oneShot;
+  }
+
+  function armSleep() {
+    if (sleepTimer) { cancel(sleepTimer); sleepTimer = 0; }
+    if (sleeping || !canSleep()) return;
+    const quiet = now() - Math.max(lastInput, pageInputAt());
+    sleepTimer = later(() => {
+      sleepTimer = 0;
+      if (!canSleep()) return;
+      if (now() - Math.max(lastInput, pageInputAt()) < MASCOT_TIMING.sleepAfterMs) { armSleep(); return; }
+      sleeping = true;
+      apply();
+    }, Math.max(0, MASCOT_TIMING.sleepAfterMs - quiet));
+  }
+
+  // ── Typing ──
+  function stopTyping() {
+    if (typingTimer) { cancel(typingTimer); typingTimer = 0; }
+    if (lookTimer) { cancel(lookTimer); lookTimer = 0; }
+    if (!typing) return;
+    typing = false;
+    apply();
+    armSleep();
+  }
+
+  /** The draft changed: `present` false (an empty draft) ends the watch. */
+  function type(present = true) {
+    if (destroyed) return;
+    touch();
+    noteInput();
+    if (!present) { stopTyping(); return; }
+    const first = !typing;
+    typing = true;
+    if (sleepTimer) { cancel(sleepTimer); sleepTimer = 0; }
+    if (typingTimer) cancel(typingTimer);
+    typingTimer = later(() => { typingTimer = 0; stopTyping(); }, MASCOT_TIMING.watchIdleMs);
+    const at = now();
+    if (first || at - lookedAt >= MASCOT_TIMING.watchEveryMs) {
+      if (lookTimer) { cancel(lookTimer); lookTimer = 0; }
+      lookedAt = at;
+      apply();
+    } else if (!lookTimer) {
+      lookTimer = later(() => { lookTimer = 0; if (!typing) return; lookedAt = now(); apply(); }, lookedAt + MASCOT_TIMING.watchEveryMs - at);
+    }
+  }
+
+  // ── One-shots ──
+  function dropOneShot() {
+    if (!oneShot) return;
+    cancel(oneShot.timer);
+    oneShot = null;
+  }
+
+  function turnEnded(pose) {
+    turnActive = false;
+    dropOneShot();
+    const t = safe(getTarget) || null;
+    if (pose && t && (pose === 'success' || pose === 'error')) {
+      const shot = { pose, target: t, timer: 0 };
+      shot.timer = later(() => { if (oneShot !== shot) return; oneShot = null; apply(); armSleep(); }, MASCOT_TIMING.oneShotMs[pose]);
+      oneShot = shot;
+    }
+    apply();
+    armSleep();
+  }
+
+  function touch() {
+    activeAt = (seq += 1);
+    elect();
+  }
+
+  const self = {
+    visible: () => !destroyed && safe(isVisible) !== false,
+    activeAt: () => activeAt,
+    leadChanged() { if (!destroyed) safe(() => setEnabled(lead === self)); },
+  };
+  directors.add(self);
+  touch();
+  if (lead !== self) self.leadChanged();
+
+  return {
+    /** The draft changed (typing): the mascot watches the caret column. */
+    type,
+    /** Blur, or the draft went away. */
+    stopTyping,
+    /** A prompt went out: the watch hands over at once (the renderer parks the hero thinking). */
+    sent() { touch(); stopTyping(); },
+    /** A card waits on the user (`rectOf()` → its box), or none (null). */
+    setBlocked(rectOf) {
+      blocked = typeof rectOf === 'function' ? rectOf : null;
+      apply();
+      armSleep();
+    },
+    /** The socket is down (true) or back (false); coming back startles the rig once. */
+    setOffline(on) {
+      const next = !!on;
+      if (next === offline) return;
+      offline = next;
+      apply();
+      if (!offline) {
+        const t = target;
+        if (t) safe(() => t.rig.react?.('startle'));
+      }
+      armSleep();
+    },
+    turnStarted() {
+      turnActive = true;
+      dropOneShot();
+      if (sleeping) sleeping = false;
+      apply();
+      armSleep();
+    },
+    /** The turn ended with `pose` ('success' | 'error' | null): played once on the rig on screen. */
+    turnEnded,
+    /** The renderer's visible mascot changed; a new stage makes this panel the one that animates. */
+    retarget() {
+      if (destroyed) return;
+      const t = safe(getTarget) || null;
+      if (t && t !== target && t.kind === 'stage') touch();
+      apply();
+    },
+    /** The user is here (focus, a click): this panel animates. */
+    touch() { touch(); noteInput(); },
+    /** The host showed or hid the panel. */
+    visibilityChanged() { elect(); },
+    isLead: () => lead === self,
+    /** For tests and devtools: what the director holds right now. */
+    state: () => ({ target: target?.kind || null, pose: shown.split('|')[0] || null, typing, blocked: !!blocked, offline, sleeping, oneShot: oneShot?.pose || null, lead: lead === self }),
+    destroy() {
+      if (destroyed) return;
+      if (target && holding) safe(() => target.hold(false));
+      destroyed = true;
+      for (const id of [typingTimer, lookTimer, sleepTimer]) if (id) cancel(id);
+      dropOneShot();
+      if (stopInput) { safe(stopInput); stopInput = null; }
+      directors.delete(self);
+      if (lead === self) { lead = null; elect(); }
+    },
+  };
+}