@animalabs/connectome-host 0.3.1

package/src/state/fleet-tree-aggregator.ts

@@ -0,0 +1,195 @@
+/**
+ * FleetTreeAggregator — owns one AgentTreeReducer per fleet child and
+ * orchestrates `describe` requests at sync points (cold start,
+ * lifecycle:ready, post-restart).
+ *
+ * Lockstep model (see UNIFIED-TREE-PLAN.md §3):
+ *   - Live event stream is the primary path. Each child's events are folded
+ *     into its reducer as they arrive.
+ *   - `describe` is a *recovery* verb, requested rarely:
+ *       * once per child on first lifecycle:ready (cold start / reattach)
+ *       * once per child after a restart (process:exited → new lifecycle:ready)
+ *   - When a `snapshot` arrives, applySnapshot wipes the child's reducer and
+ *     reseeds from ground truth. Subsequent events resume the fold.
+ *   - Events with `ts < asOfTs` are dropped after a snapshot — they're already
+ *     reflected in the snapshot's state (no double-application).
+ *
+ * The aggregator exposes a clean read API for the TUI (Phase 5) without the
+ * TUI needing to know about IPC, describe handshakes, or stale-event dedup.
+ *
+ * Local-process state is NOT mirrored here. The TUI's existing inline fold
+ * (subagentPhase / agentContextTokens / agentParent in tui.ts) is the
+ * canonical local store; running a parallel local reducer that nothing reads
+ * from would be paid-for-but-unused complexity. If a future pass migrates
+ * local rendering off those inline maps, instantiate a local reducer at
+ * that point.
+ */
+
+import type { FleetModule, FleetEventCallback } from '../modules/fleet-module.js';
+import type { WireEvent } from '../modules/fleet-types.js';
+import { AgentTreeReducer, type AgentTreeSnapshot, type AgentNode } from './agent-tree-reducer.js';
+
+interface ChildState {
+  reducer: AgentTreeReducer;
+  /** asOfTs of the last applied snapshot; events older than this are dropped. */
+  lastSnapshotTs: number;
+  /** True once we've requested a describe and are awaiting a snapshot. */
+  describeInFlight: boolean;
+  /** Set once we've ever received a snapshot — used to detect post-restart. */
+  hasInitialSnapshot: boolean;
+  /** Unsubscribe handle for the per-child event subscription. */
+  unsubscribe: () => void;
+}
+
+export type TreeUpdateListener = (childName: string | 'local') => void;
+
+export class FleetTreeAggregator {
+  private fleet: FleetModule;
+  private childStates = new Map<string, ChildState>();
+  private listeners = new Set<TreeUpdateListener>();
+  /** Generation counter for corrIds; debugging convenience. */
+  private corrIdSeq = 0;
+
+  constructor(fleet: FleetModule) {
+    this.fleet = fleet;
+  }
+
+  /** Register a child. Idempotent — re-registering with the same name is a noop
+   *  unless the prior subscription was torn down (in which case it re-subscribes). */
+  registerChild(name: string): void {
+    if (this.childStates.has(name)) return;
+
+    const reducer = new AgentTreeReducer();
+    const callback: FleetEventCallback = (childName, event) => {
+      if (childName !== name) return;
+      this.handleChildEvent(name, event);
+    };
+    const unsubscribe = this.fleet.onChildEvent(name, callback);
+
+    this.childStates.set(name, {
+      reducer,
+      lastSnapshotTs: 0,
+      describeInFlight: false,
+      hasInitialSnapshot: false,
+      unsubscribe,
+    });
+
+    // If the child is already ready when we register, request describe right away.
+    // (lifecycle:ready already fired before we subscribed.)
+    const fleetChild = this.fleet.getChildren().get(name);
+    if (fleetChild?.status === 'ready') {
+      this.requestDescribe(name);
+    }
+  }
+
+  /** Stop tracking a child and tear down its subscription. */
+  unregisterChild(name: string): void {
+    const state = this.childStates.get(name);
+    if (!state) return;
+    state.unsubscribe();
+    this.childStates.delete(name);
+  }
+
+  // ----- read API ---------------------------------------------------------
+
+  getChildNodes(name: string): AgentNode[] {
+    const state = this.childStates.get(name);
+    return state ? state.reducer.getNodes() : [];
+  }
+
+  getAllChildNames(): string[] {
+    return [...this.childStates.keys()];
+  }
+
+  /** Subscribe to tree-updated notifications. Returns an unsubscribe function.
+   *  Listener fires for any change to local or any child's tree. */
+  onTreeUpdate(listener: TreeUpdateListener): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Tear down all subscriptions. Call on TUI shutdown. */
+  dispose(): void {
+    for (const [, state] of this.childStates) {
+      state.unsubscribe();
+    }
+    this.childStates.clear();
+    this.listeners.clear();
+  }
+
+  // ----- internals --------------------------------------------------------
+
+  private handleChildEvent(name: string, event: WireEvent): void {
+    const state = this.childStates.get(name);
+    if (!state) return;
+
+    const eventTs = event.ts;
+
+    // Snapshot response: reseed from ground truth.
+    if (event.type === 'snapshot') {
+      const snapshotEvent = event as unknown as {
+        asOfTs?: number;
+        tree?: { nodes?: unknown[]; callIdIndex?: Record<string, string> };
+      };
+      const asOfTs = snapshotEvent.asOfTs ?? Date.now();
+      const treeNodes = (snapshotEvent.tree?.nodes ?? []) as AgentNode[];
+      const callIdIndex = snapshotEvent.tree?.callIdIndex ?? {};
+      const snap: AgentTreeSnapshot = {
+        asOfTs,
+        nodes: treeNodes,
+        callIdIndex,
+      };
+      state.reducer.applySnapshot(snap);
+      state.lastSnapshotTs = asOfTs;
+      state.describeInFlight = false;
+      state.hasInitialSnapshot = true;
+      this.notify(name);
+      return;
+    }
+
+    // Lifecycle: ready fires on initial connect AND after parent reconnect to
+    // a still-running child AND when adopt-on-restart re-establishes a socket
+    // post-spawn-restart. Request describe in all those cases.
+    if (event.type === 'lifecycle') {
+      const phase = (event as { phase?: string }).phase;
+      if (phase === 'ready') {
+        // Always request describe on ready — covers cold-start, reconnect, restart.
+        // The reducer's applySnapshot wipes prior state, so re-requesting is safe
+        // even if we have current data.
+        this.requestDescribe(name);
+        return;
+      }
+      // 'exiting' is purely informational here. There's no reset code below;
+      // the implicit recovery is: when the child restarts and emits a fresh
+      // lifecycle:ready, the branch above triggers a describe, and
+      // applySnapshot wipes the stale reducer state at that point. The
+      // hasInitialSnapshot flag below is what gates stale-event filtering
+      // through the gap.
+    }
+
+    // Drop events older than the most recent snapshot — they're already
+    // reflected in the snapshot's state. This handles the in-flight window
+    // between describe-send and snapshot-receive.
+    if (state.hasInitialSnapshot && typeof eventTs === 'number' && eventTs < state.lastSnapshotTs) {
+      return;
+    }
+
+    state.reducer.applyEvent(event);
+    this.notify(name);
+  }
+
+  private requestDescribe(name: string): void {
+    const state = this.childStates.get(name);
+    if (!state) return;
+    if (state.describeInFlight) return;
+    const corrId = `agg-${++this.corrIdSeq}`;
+    const ok = this.fleet.requestDescribe(name, corrId);
+    if (ok) state.describeInFlight = true;
+  }
+
+  private notify(scope: string | 'local'): void {
+    for (const l of this.listeners) {
+      try { l(scope); } catch { /* one bad listener doesn't kill the others */ }
+    }
+  }
+}

package/src/strategies/frontdesk-strategy.ts

@@ -0,0 +1,364 @@
+import { AutobiographicalStrategy } from '@animalabs/context-manager';
+import type {
+  AutobiographicalConfig,
+  ContextEntry,
+  MessageStoreView,
+  ContextLogView,
+  TokenBudget,
+  StoredMessage,
+  SummaryEntry,
+} from '@animalabs/context-manager';
+import type { ContentBlock } from '@animalabs/membrane';
+
+// Structural mirror of AutobiographicalStrategy's internal Chunk.
+// Kept inline because @animalabs/context-manager does not currently export it.
+interface Chunk {
+  index: number;
+  startIndex: number;
+  endIndex: number;
+  messages: StoredMessage[];
+  tokens: number;
+  compressed: boolean;
+  diary?: string;
+  summaryId?: string;
+  phaseType?: string;
+}
+
+export type FrontdeskStrategyOptions = Partial<AutobiographicalConfig>;
+
+/**
+ * Chatbot-flavoured context strategy for agents that receive messages via
+ * MCPL channels (Zulip, Discord, etc.) and reply back through them.
+ *
+ * Extends AutobiographicalStrategy with three features:
+ *  1. Provenance wrapping — prepends a `[zulip · #channel · topic · @user · HH:MM · msg-id]`
+ *     header to each MCPL-originated entry so the agent knows the message came from a
+ *     channel and which reply path to use.
+ *  2. Topic-aware compression — chunk boundaries prefer Zulip-topic transitions and the
+ *     compression prompt instructs per-topic structure.
+ *  3. Question/mention salience — unanswered user questions and @mentions are preserved
+ *     verbatim longer (both during compression and during L1 selection under budget).
+ */
+export class FrontdeskStrategy extends AutobiographicalStrategy {
+  override readonly name: string = 'frontdesk';
+
+  private salientSourceIds: Set<string> = new Set();
+
+  override select(
+    store: MessageStoreView,
+    log: ContextLogView,
+    budget: TokenBudget,
+  ): ContextEntry[] {
+    this.updateSalience(store);
+    const entries = super.select(store, log, budget);
+    return entries.map((e) => this.wrapProvenance(e, store));
+  }
+
+  // ==========================================================================
+  // Feature 1: Provenance wrapping
+  // ==========================================================================
+
+  protected wrapProvenance(entry: ContextEntry, store: MessageStoreView): ContextEntry {
+    if (!entry.sourceMessageId || entry.sourceRelation !== 'copy') return entry;
+    const msg = store.get(entry.sourceMessageId);
+    if (!msg) return entry;
+    const header = this.buildProvenanceHeader(msg);
+    if (!header) return entry;
+
+    // Prepend a text block. If the first block is already text, merge the header
+    // into it so tool_use/tool_result blocks stay paired with their neighbours.
+    const first = entry.content[0];
+    if (first && first.type === 'text') {
+      return {
+        ...entry,
+        content: [
+          { type: 'text', text: `${header}${first.text}` } as ContentBlock,
+          ...entry.content.slice(1),
+        ],
+      };
+    }
+    return {
+      ...entry,
+      content: [{ type: 'text', text: header } as ContentBlock, ...entry.content],
+    };
+  }
+
+  protected buildProvenanceHeader(msg: StoredMessage): string | null {
+    const meta = (msg.metadata ?? {}) as Record<string, unknown>;
+    if (meta.serverId === undefined || meta.serverId === null || meta.serverId === '') {
+      return null;
+    }
+
+    const parts: string[] = [];
+    const serverId = String(meta.serverId);
+    const channelId = meta.channelId !== undefined && meta.channelId !== null ? String(meta.channelId) : '';
+
+    const protocol = this.deriveProtocol(serverId, channelId);
+    if (protocol) parts.push(protocol);
+
+    if (channelId) {
+      const stripped = channelId.replace(/^[a-z][a-z0-9_-]*:/, '');
+      if (stripped) parts.push(`#${stripped}`);
+    }
+
+    const topicRaw = meta.topic ?? meta.subject;
+    const topic = topicRaw !== undefined && topicRaw !== null ? String(topicRaw) : '';
+    if (topic) parts.push(`topic "${topic}"`);
+
+    const author = meta.author as { id?: string; name?: string } | undefined;
+    if (author && typeof author === 'object') {
+      const display = author.name || author.id || '';
+      if (display) parts.push(`@${display}`);
+    }
+
+    const ts = this.formatTimestamp(meta.timestamp, msg.timestamp);
+    if (ts) parts.push(ts);
+
+    if (meta.messageId !== undefined && meta.messageId !== null && meta.messageId !== '') {
+      const mid = String(meta.messageId);
+      const short = mid.length > 12 ? mid.slice(0, 12) : mid;
+      parts.push(`msg ${short}`);
+    }
+
+    const threadId = meta.threadId !== undefined && meta.threadId !== null ? String(meta.threadId) : '';
+    if (threadId && threadId !== topic) {
+      const short = threadId.length > 12 ? threadId.slice(0, 12) : threadId;
+      parts.push(`thread ${short}`);
+    }
+
+    if (parts.length === 0) return null;
+    return `[${parts.join(' · ')}]\n`;
+  }
+
+  protected deriveProtocol(serverId: string, channelId: string): string {
+    if (channelId) {
+      const match = channelId.match(/^([a-z][a-z0-9_-]*):/);
+      if (match) return match[1];
+    }
+    return serverId;
+  }
+
+  protected formatTimestamp(metaTs: unknown, msgTs: Date): string | null {
+    let d: Date | null = null;
+    if (typeof metaTs === 'string' || typeof metaTs === 'number') {
+      const parsed = new Date(metaTs);
+      if (!isNaN(parsed.getTime())) d = parsed;
+    }
+    if (!d && msgTs instanceof Date && !isNaN(msgTs.getTime())) d = msgTs;
+    if (!d) return null;
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${hh}:${mm}`;
+  }
+
+  // ==========================================================================
+  // Feature 2: Topic-aware chunking
+  // ==========================================================================
+
+  /**
+   * Override rebuildChunks to additionally close chunk boundaries at Zulip-topic
+   * transitions. Falls back to base size/count behaviour when topic metadata is absent.
+   */
+  protected override rebuildChunks(store: MessageStoreView): void {
+    const messagesToChunk = this.getCompressibleMessages(store);
+
+    const existingCompressed = new Map<string, Chunk>();
+    for (const chunk of this.chunks as unknown as Chunk[]) {
+      if (chunk.compressed) {
+        existingCompressed.set(this.chunkKey(chunk as never), chunk);
+      }
+    }
+
+    this.chunks = [];
+    this.compressionQueue = [];
+
+    let currentChunk: StoredMessage[] = [];
+    let currentTokens = 0;
+    let chunkFilteredStart = 0;
+    const MIN_CHUNK = 4;
+
+    const push = (startIdx: number, endIdx: number, msgs: StoredMessage[], tokens: number) => {
+      const chunk = this.createChunk(
+        this.chunks.length,
+        startIdx,
+        endIdx,
+        msgs,
+        tokens,
+        existingCompressed as never,
+      );
+      this.chunks.push(chunk);
+      if (!chunk.compressed) this.compressionQueue.push(chunk.index);
+    };
+
+    for (let i = 0; i < messagesToChunk.length; i++) {
+      const msg = messagesToChunk[i];
+      let msgTokens = store.estimateTokens(msg);
+      if (this.config.attachmentsIgnoreSize) {
+        msgTokens = this.estimateTextOnlyTokens(msg);
+      }
+
+      // Topic boundary: close current chunk BEFORE adding msg when topic changes
+      // and the chunk has at least MIN_CHUNK messages. This keeps summaries of
+      // unrelated topics from being merged.
+      if (
+        currentChunk.length >= MIN_CHUNK &&
+        this.isTopicBoundary(currentChunk[currentChunk.length - 1], msg)
+      ) {
+        push(chunkFilteredStart, i, currentChunk, currentTokens);
+        currentChunk = [];
+        currentTokens = 0;
+        chunkFilteredStart = i;
+      }
+
+      currentChunk.push(msg);
+      currentTokens += msgTokens;
+
+      const shouldClose =
+        currentTokens >= this.config.targetChunkTokens && currentChunk.length >= MIN_CHUNK;
+
+      if (shouldClose) {
+        push(chunkFilteredStart, i + 1, currentChunk, currentTokens);
+        currentChunk = [];
+        currentTokens = 0;
+        chunkFilteredStart = i + 1;
+      }
+    }
+
+    if (currentChunk.length >= MIN_CHUNK) {
+      push(chunkFilteredStart, messagesToChunk.length, currentChunk, currentTokens);
+    }
+  }
+
+  protected isTopicBoundary(prev: StoredMessage, curr: StoredMessage): boolean {
+    const a = this.extractTopicKey(prev);
+    const b = this.extractTopicKey(curr);
+    if (!a || !b) return false;
+    return a !== b;
+  }
+
+  protected extractTopicKey(msg: StoredMessage): string | null {
+    const meta = (msg.metadata ?? {}) as Record<string, unknown>;
+    const topicRaw = meta.topic ?? meta.subject;
+    if (topicRaw === undefined || topicRaw === null || topicRaw === '') return null;
+    const channelId = meta.channelId !== undefined && meta.channelId !== null ? String(meta.channelId) : '';
+    return `${channelId}::${String(topicRaw)}`;
+  }
+
+  // ==========================================================================
+  // Feature 3a: Compression instruction with topic + open-question clauses
+  // ==========================================================================
+
+  protected override getCompressionInstruction(chunk: Chunk, targetTokens: number): string {
+    const topics = new Set<string>();
+    for (const m of chunk.messages) {
+      const t = this.extractTopicKey(m);
+      if (t) topics.add(t);
+    }
+
+    const openQuestions: string[] = [];
+    for (const m of chunk.messages) {
+      if (this.salientSourceIds.has(m.id)) {
+        const text = this.extractText(m.content).trim().replace(/\s+/g, ' ');
+        if (text) {
+          openQuestions.push(text.length > 200 ? `${text.slice(0, 200)}…` : text);
+        }
+      }
+    }
+
+    const base = `Starting from my last message, please describe everything that has happened. Aim for about ${targetTokens} tokens. Describe it as you would to yourself, as if you are remembering what has happened.`;
+
+    const clauses: string[] = [];
+    if (topics.size > 1) {
+      clauses.push(
+        'This window spans multiple Zulip topics — structure the memory with one short section per topic, keeping topic names verbatim.',
+      );
+    }
+    if (openQuestions.length > 0) {
+      clauses.push(
+        `Preserve verbatim any user question that was asked in this window and has not yet been answered, including @mentions of the agent. Questions to preserve: ${openQuestions.map((q) => `"${q}"`).join('; ')}.`,
+      );
+    }
+
+    return clauses.length === 0 ? base : `${base}\n\n${clauses.join(' ')}`;
+  }
+
+  // ==========================================================================
+  // Feature 3b: Salience-biased L1 selection
+  // ==========================================================================
+
+  protected override selectL1Summaries(
+    shownL1: SummaryEntry[],
+    budget: number,
+    maxTokens: number,
+  ): { selected: SummaryEntry[]; tokensUsed: number } {
+    if (shownL1.length === 0) return { selected: [], tokensUsed: 0 };
+
+    const isSalient = (s: SummaryEntry): boolean =>
+      s.sourceIds.some((id) => this.salientSourceIds.has(id));
+
+    const salient: SummaryEntry[] = [];
+    const routine: SummaryEntry[] = [];
+    for (const s of shownL1) {
+      (isSalient(s) ? salient : routine).push(s);
+    }
+
+    const selected: SummaryEntry[] = [];
+    let used = 0;
+
+    for (const group of [salient, routine]) {
+      for (const s of group) {
+        if (used + s.tokens > budget) break;
+        if (used + s.tokens > maxTokens) break;
+        selected.push(s);
+        used += s.tokens;
+      }
+    }
+
+    return { selected, tokensUsed: used };
+  }
+
+  // ==========================================================================
+  // Salience tracking (shared by 3a and 3b)
+  // ==========================================================================
+
+  /**
+   * Recompute which user messages are "unanswered questions or mentions":
+   * a user message that contains `?` or an @mention and has no assistant
+   * message within the following WINDOW messages.
+   */
+  protected updateSalience(store: MessageStoreView): void {
+    const messages = store.getAll();
+    const assistant = this.config.summaryParticipant ?? 'Claude';
+    const salient = new Set<string>();
+    const WINDOW = 8;
+
+    for (let i = 0; i < messages.length; i++) {
+      const m = messages[i];
+      if (m.participant === assistant) continue;
+      if (!this.messageIsQuestionOrMention(m)) continue;
+
+      let answered = false;
+      const end = Math.min(i + 1 + WINDOW, messages.length);
+      for (let j = i + 1; j < end; j++) {
+        if (messages[j].participant === assistant) {
+          answered = true;
+          break;
+        }
+      }
+      if (!answered) salient.add(m.id);
+    }
+
+    this.salientSourceIds = salient;
+  }
+
+  protected messageIsQuestionOrMention(msg: StoredMessage): boolean {
+    for (const b of msg.content) {
+      if (b.type !== 'text') continue;
+      const text = b.text;
+      if (text.includes('?')) return true;
+      if (/@\*\*[^*]+\*\*/.test(text)) return true; // Zulip-style mention
+      if (/(^|\s)@[A-Za-z][\w-]*/.test(text)) return true; // Discord/Slack-style
+    }
+    return false;
+  }
+}

package/src/synesthete.ts

@@ -0,0 +1,68 @@
+/**
+ * Synesthete — auto-generates evocative session names via a quick Haiku call.
+ *
+ * Called after a few user messages in an auto-named session. Produces a
+ * 2–4 word name that captures the session's topic/mood.
+ */
+
+import type { Membrane } from '@animalabs/membrane';
+
+const DEFAULT_EXAMPLES = [
+  'Context Window Budgeting',
+  'Agent Memory Architecture',
+  'Pipeline Debug Session',
+  'Schema Migration Plan',
+  'API Integration Review',
+];
+
+function buildNamingPrompt(examples?: string[]): string {
+  const exampleList = (examples ?? DEFAULT_EXAMPLES)
+    .map(e => `- "${e}"`)
+    .join('\n');
+
+  return `You are a session naming assistant. Given a brief summary of a conversation, generate a short, evocative name (2-4 words) that captures its essence. The name should be memorable and descriptive, like a chapter title.
+
+Examples of good names:
+${exampleList}
+
+Respond with ONLY the name, nothing else. No quotes, no explanation.`;
+}
+
+/**
+ * Generate a session name from conversation content.
+ * Returns the generated name, or null if the call fails.
+ */
+export async function generateSessionName(
+  membrane: Membrane,
+  conversationSummary: string,
+  examples?: string[],
+): Promise<string | null> {
+  try {
+    const response = await membrane.complete({
+      messages: [
+        {
+          participant: 'user',
+          content: [{ type: 'text', text: conversationSummary }],
+        },
+      ],
+      system: buildNamingPrompt(examples),
+      config: {
+        model: 'claude-haiku-4-5-20251001',
+        maxTokens: 30,
+        temperature: 0.8,
+      },
+    });
+
+    const text = response.content
+      .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+      .map(b => b.text)
+      .join('')
+      .trim();
+
+    // Sanity check: should be short and non-empty
+    if (!text || text.length > 60 || text.includes('\n')) return null;
+    return text;
+  } catch {
+    return null;
+  }
+}