@animalabs/connectome-host 0.3.1

package/src/modules/fleet-types.ts

@@ -0,0 +1,225 @@
+/**
+ * Shared wire-protocol types for the headless daemon ↔ FleetModule IPC.
+ *
+ * Both `src/headless.ts` (child runtime) and `src/modules/fleet-module.ts`
+ * (parent module) import from here so the JSONL envelope shapes stay
+ * identical at both ends.
+ *
+ * See HEADLESS-FLEET-PLAN.md for the full protocol spec.
+ */
+
+// ---------------------------------------------------------------------------
+// Parent → Child: commands
+// ---------------------------------------------------------------------------
+
+export type IncomingCommand =
+  /** Set which event types the child emits.  Supports glob: ["tool:*", "lifecycle"]. */
+  | { type: 'subscribe'; events: string[] }
+  /** Inject a user-like message; equivalent to typing in the child's TUI. */
+  | { type: 'text'; content: string }
+  /** Run a slash command in the child's commands.ts handler. */
+  | { type: 'command'; command: string }
+  /** Graceful (default) or immediate shutdown. */
+  | { type: 'shutdown'; graceful?: boolean }
+  /** Request a state snapshot. The child responds with a single 'snapshot'
+   *  event carrying the full agent tree, exempt from subscription filtering.
+   *  Used as a recovery verb (TUI cold start, reconnect, after restart) — not
+   *  a query verb. See UNIFIED-TREE-PLAN.md §3 for the lockstep model. */
+  | { type: 'describe'; corrId?: string }
+  /** Pull the child's lesson library. Response is `lessons-snapshot`. */
+  | { type: 'request-lessons'; corrId?: string }
+  /** Pull the child's workspace mount list. Response is `workspace-mounts-snapshot`. */
+  | { type: 'request-workspace-mounts'; corrId?: string }
+  /** Pull a recursive listing of one mount in the child. Response is `workspace-tree-snapshot`. */
+  | { type: 'request-workspace-tree'; mount: string; corrId?: string }
+  /** Read a workspace file from the child. Response is `workspace-file-snapshot`. */
+  | { type: 'request-workspace-file'; path: string; corrId?: string }
+  /** Cancel a specific in-process subagent by display name. Response is
+   *  `cancel-subagent-result`. The child looks the agent up in its own
+   *  SubagentModule, so this is the only way to stop a subagent that lives
+   *  in a fleet child rather than the conductor. */
+  | { type: 'cancel-subagent'; name: string; corrId?: string };
+
+// ---------------------------------------------------------------------------
+// Child → Parent: events
+// ---------------------------------------------------------------------------
+
+/** Lifecycle events added by the headless runtime (not framework TraceEvents). */
+export type LifecycleEvent =
+  | { type: 'lifecycle'; phase: 'ready'; pid: number; dataDir: string; recipe?: string; ts?: number }
+  | { type: 'lifecycle'; phase: 'idle'; ts?: number }
+  | { type: 'lifecycle'; phase: 'exiting'; reason: string; ts?: number };
+
+/** Output line from a slash-command run, surfaced as an event. */
+export interface CommandOutputEvent {
+  type: 'command-output';
+  text: string;
+  style: string | null;
+  ts?: number;
+}
+
+/** Response to a {type:'describe'} request. Carries the child's full agent
+ *  tree as folded by AgentTreeReducer. Always emitted regardless of the
+ *  client's subscription filter. */
+export interface SnapshotEvent {
+  type: 'snapshot';
+  corrId?: string;
+  /** Wall-clock at which the child built the snapshot. Receivers should drop
+   *  events with `timestamp < asOfTs` after applying. */
+  asOfTs: number;
+  child: {
+    name: string;
+    pid: number;
+    recipe?: string;
+    startedAt: number;
+  };
+  /** Serialized AgentTreeReducer state. Shape matches AgentTreeSnapshot in
+   *  src/state/agent-tree-reducer.ts. Kept structurally typed here to avoid
+   *  cross-cutting imports. */
+  tree: {
+    nodes: Array<Record<string, unknown>>;
+    callIdIndex: Record<string, string>;
+  };
+  ts?: number;
+}
+
+/** Response to a {type:'request-lessons'} request. */
+export interface LessonsSnapshotEvent {
+  type: 'lessons-snapshot';
+  corrId?: string;
+  /** True iff the child has LessonsModule loaded. */
+  loaded: boolean;
+  lessons: Array<{
+    id: string;
+    content: string;
+    confidence: number;
+    tags: string[];
+    deprecated: boolean;
+    deprecationReason?: string;
+    created?: number;
+    updated?: number;
+  }>;
+  ts?: number;
+}
+
+/** Response to a {type:'request-workspace-mounts'} request. */
+export interface WorkspaceMountsSnapshotEvent {
+  type: 'workspace-mounts-snapshot';
+  corrId?: string;
+  loaded: boolean;
+  mounts: Array<{ name: string; path: string; mode: string }>;
+  ts?: number;
+}
+
+/** Response to a {type:'request-workspace-tree'} request. */
+export interface WorkspaceTreeSnapshotEvent {
+  type: 'workspace-tree-snapshot';
+  corrId?: string;
+  mount: string;
+  entries: Array<{ path: string; size: number }>;
+  ts?: number;
+}
+
+/** Response to a {type:'cancel-subagent'} request. */
+export interface CancelSubagentResultEvent {
+  type: 'cancel-subagent-result';
+  corrId?: string;
+  /** Subagent display name the parent asked us to cancel. */
+  name: string;
+  /** True iff a matching live subagent was found and signalled to stop. */
+  cancelled: boolean;
+  /** Set when cancelled=false to explain why (e.g. "subagent module not
+   *  loaded", "subagent not running"). */
+  reason?: string;
+  ts?: number;
+}
+
+/** Response to a {type:'request-workspace-file'} request. */
+export interface WorkspaceFileSnapshotEvent {
+  type: 'workspace-file-snapshot';
+  corrId?: string;
+  path: string;
+  totalLines: number;
+  fromLine: number;
+  toLine: number;
+  content: string;
+  truncated: boolean;
+  /** Set on lookup failure (file not found, mount unknown, etc.). */
+  error?: string;
+  ts?: number;
+}
+
+/**
+ * A wire event from the child.  In practice this is either a framework
+ * TraceEvent (typed loosely as Record<string,unknown>), or one of our
+ * lifecycle / command-output additions.
+ */
+export type WireEvent =
+  | LifecycleEvent
+  | CommandOutputEvent
+  | SnapshotEvent
+  | LessonsSnapshotEvent
+  | WorkspaceMountsSnapshotEvent
+  | WorkspaceTreeSnapshotEvent
+  | WorkspaceFileSnapshotEvent
+  | CancelSubagentResultEvent
+  // Arbitrary framework TraceEvent passthrough. The child stamps every emitted
+  // event with `ts: Date.now()` in `emit()` (see headless.ts), so ts is always
+  // present on the wire even when the underlying TraceEvent doesn't declare it.
+  | (Record<string, unknown> & { type: string; ts?: number });
+
+// ---------------------------------------------------------------------------
+// Subscription matching (used by both ends)
+// ---------------------------------------------------------------------------
+
+/**
+ * Match an event type against a subscription set.  Supports:
+ *   - exact match: "inference:completed"
+ *   - prefix wildcard: "tool:*"  (matches "tool:started", "tool:completed", ...)
+ *   - global wildcard: "*"
+ */
+export function matchesSubscription(eventType: string, subscription: Set<string>): boolean {
+  if (subscription.has('*')) return true;
+  if (subscription.has(eventType)) return true;
+  for (const pattern of subscription) {
+    if (pattern.endsWith('*') && eventType.startsWith(pattern.slice(0, -1))) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Direct-routing helper for TUI input
+// ---------------------------------------------------------------------------
+
+export interface FleetRoute {
+  /** Target child's name as parsed from the prefix. */
+  childName: string;
+  /** Message body after the prefix. */
+  content: string;
+}
+
+/**
+ * Parse a "@childname rest of message" line as a direct-route command,
+ * bypassing the conductor agent.  Returns null if the line is not an
+ * @-prefixed route (so TUI falls back to the default chat-to-conductor path).
+ *
+ * Accepted forms:
+ *   "@miner hello there"     → { childName: "miner",  content: "hello there" }
+ *   "@miner: hello"          → { childName: "miner",  content: "hello" }
+ *   "@my-bot list channels"  → { childName: "my-bot", content: "list channels" }
+ *
+ * Rejected:
+ *   "@miner"                 → null (no payload)
+ *   "no prefix"              → null
+ *   "@@escaped"              → null (literal @, e.g. paste of an email)
+ */
+export function parseFleetRoute(input: string): FleetRoute | null {
+  const trimmed = input.trimStart();
+  if (!trimmed.startsWith('@') || trimmed.startsWith('@@')) return null;
+  const match = /^@([a-zA-Z0-9_.-]+)(?::|\s)\s*(.+)$/s.exec(trimmed);
+  if (!match) return null;
+  const childName = match[1]!;
+  const content = match[2]!.trim();
+  if (!content) return null;
+  return { childName, content };
+}

package/src/modules/lessons-module.ts

@@ -0,0 +1,465 @@
+/**
+ * LessonsModule — persistent knowledge store backed by Chronicle.
+ *
+ * Lessons are units of extracted knowledge with:
+ *   - Confidence scores (0–1)
+ *   - Tags for categorization
+ *   - Evidence links (source message references)
+ *
+ * The module also implements gatherContext() to auto-inject
+ * relevant lessons into the agent's context before inference.
+ */
+
+import type {
+  Module,
+  ModuleContext,
+  ProcessState,
+  ProcessEvent,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '@animalabs/agent-framework';
+import type { ContextInjection } from '@animalabs/context-manager';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface Lesson {
+  id: string;
+  content: string;
+  confidence: number;
+  tags: string[];
+  evidence: string[];
+  created: number;
+  updated: number;
+  deprecated: boolean;
+  deprecationReason?: string;
+}
+
+interface LessonsState {
+  lessons: Lesson[];
+}
+
+interface CreateInput {
+  content: string;
+  tags: string[];
+  evidence?: string[];
+  confidence?: number;
+}
+
+interface UpdateInput {
+  id: string;
+  content?: string;
+  tags?: string[];
+  confidence?: number;
+  evidence?: string[];
+}
+
+interface DeprecateInput {
+  id: string;
+  reason: string;
+}
+
+interface QueryInput {
+  text?: string;
+  tags?: string[];
+  minConfidence?: number;
+  limit?: number;
+}
+
+interface ListInput {
+  tags?: string[];
+  sort?: 'confidence' | 'created' | 'updated';
+  limit?: number;
+  includeDeprecated?: boolean;
+}
+
+interface IdInput {
+  id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Module
+// ---------------------------------------------------------------------------
+
+export class LessonsModule implements Module {
+  readonly name = 'lessons';
+
+  private ctx: ModuleContext | null = null;
+  private state: LessonsState = { lessons: [] };
+  private globalPath: string | null;
+
+  constructor(opts?: { globalPath?: string }) {
+    this.globalPath = opts?.globalPath ?? null;
+  }
+
+  async start(ctx: ModuleContext): Promise<void> {
+    this.ctx = ctx;
+    const saved = ctx.getState<LessonsState>();
+    if (saved) {
+      this.state = saved;
+    }
+    // Merge in lessons from the global shared file
+    if (this.globalPath) {
+      this.mergeFromGlobal();
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.ctx = null;
+  }
+
+  getTools(): ToolDefinition[] {
+    return [
+      {
+        name: 'create',
+        description: 'Create a new lesson (unit of extracted knowledge).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            content: { type: 'string', description: 'The knowledge content' },
+            tags: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Categorization tags (e.g., people, process, decision, technical)',
+            },
+            evidence: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Source references (e.g., stream:topic:messageId)',
+            },
+            confidence: { type: 'number', description: 'Initial confidence 0–1 (default: 0.5)' },
+          },
+          required: ['content', 'tags'],
+        },
+      },
+      {
+        name: 'update',
+        description: 'Update an existing lesson.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Lesson ID' },
+            content: { type: 'string', description: 'Updated content' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Updated tags' },
+            confidence: { type: 'number', description: 'Updated confidence' },
+            evidence: { type: 'array', items: { type: 'string' }, description: 'Additional evidence' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'deprecate',
+        description: 'Mark a lesson as deprecated (no longer considered accurate).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Lesson ID' },
+            reason: { type: 'string', description: 'Why this lesson is being deprecated' },
+          },
+          required: ['id', 'reason'],
+        },
+      },
+      {
+        name: 'query',
+        description: 'Search lessons by text and/or tags.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            text: { type: 'string', description: 'Text to search for (keyword matching)' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags (any match)' },
+            minConfidence: { type: 'number', description: 'Minimum confidence threshold' },
+            limit: { type: 'number', description: 'Max results (default: 20)' },
+          },
+        },
+      },
+      {
+        name: 'list',
+        description: 'List all lessons, optionally filtered and sorted.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
+            sort: {
+              type: 'string',
+              description: 'Sort by: confidence, created, or updated (default: confidence)',
+            },
+            limit: { type: 'number', description: 'Max results (default: 50)' },
+            includeDeprecated: { type: 'boolean', description: 'Include deprecated lessons' },
+          },
+        },
+      },
+      {
+        name: 'boost',
+        description: 'Increase a lesson\'s confidence (it proved useful).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Lesson ID' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'demote',
+        description: 'Decrease a lesson\'s confidence (it was wrong or unhelpful).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Lesson ID' },
+          },
+          required: ['id'],
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    switch (call.name) {
+      case 'create': return this.handleCreate(call.input as CreateInput);
+      case 'update': return this.handleUpdate(call.input as UpdateInput);
+      case 'deprecate': return this.handleDeprecate(call.input as DeprecateInput);
+      case 'query': return this.handleQuery(call.input as QueryInput);
+      case 'list': return this.handleList(call.input as ListInput);
+      case 'boost': return this.handleBoost(call.input as IdInput);
+      case 'demote': return this.handleDemote(call.input as IdInput);
+      default:
+        return { success: false, error: `Unknown tool: ${call.name}`, isError: true };
+    }
+  }
+
+  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    return {};
+  }
+
+  // Lesson injection is handled solely by RetrievalModule (intelligent retrieval
+  // pipeline). LessonsModule provides storage + CRUD tools only.
+
+  // Public accessor for other modules (e.g., RetrievalModule)
+  getLessons(): Lesson[] {
+    return this.state.lessons;
+  }
+
+  // =========================================================================
+  // Tool Handlers
+  // =========================================================================
+
+  private handleCreate(input: CreateInput): ToolResult {
+    const lesson: Lesson = {
+      id: randomUUID().slice(0, 8),
+      content: input.content,
+      confidence: input.confidence ?? 0.5,
+      tags: input.tags,
+      evidence: input.evidence ?? [],
+      created: Date.now(),
+      updated: Date.now(),
+      deprecated: false,
+    };
+
+    this.state.lessons.push(lesson);
+    this.save();
+
+    return { success: true, data: { id: lesson.id, message: 'Lesson created' } };
+  }
+
+  private handleUpdate(input: UpdateInput): ToolResult {
+    const lesson = this.state.lessons.find(l => l.id === input.id);
+    if (!lesson) {
+      return { success: false, error: `Lesson not found: ${input.id}`, isError: true };
+    }
+
+    if (input.content !== undefined) lesson.content = input.content;
+    if (input.tags !== undefined) lesson.tags = input.tags;
+    if (input.confidence !== undefined) lesson.confidence = Math.max(0, Math.min(1, input.confidence));
+    if (input.evidence !== undefined) {
+      // Merge evidence, dedup
+      const existing = new Set(lesson.evidence);
+      for (const e of input.evidence) existing.add(e);
+      lesson.evidence = [...existing];
+    }
+    lesson.updated = Date.now();
+    this.save();
+
+    return { success: true, data: { id: lesson.id, message: 'Lesson updated' } };
+  }
+
+  private handleDeprecate(input: DeprecateInput): ToolResult {
+    const lesson = this.state.lessons.find(l => l.id === input.id);
+    if (!lesson) {
+      return { success: false, error: `Lesson not found: ${input.id}`, isError: true };
+    }
+
+    lesson.deprecated = true;
+    lesson.deprecationReason = input.reason;
+    lesson.updated = Date.now();
+    this.save();
+
+    return { success: true, data: { id: lesson.id, message: 'Lesson deprecated' } };
+  }
+
+  private handleQuery(input: QueryInput): ToolResult {
+    const limit = input.limit ?? 20;
+    let results = this.state.lessons.filter(l => !l.deprecated);
+
+    // Filter by minimum confidence
+    if (input.minConfidence !== undefined) {
+      results = results.filter(l => l.confidence >= input.minConfidence!);
+    }
+
+    // Filter by tags (any match)
+    if (input.tags && input.tags.length > 0) {
+      const tagSet = new Set(input.tags.map(t => t.toLowerCase()));
+      results = results.filter(l =>
+        l.tags.some(t => tagSet.has(t.toLowerCase()))
+      );
+    }
+
+    // Text search (simple keyword matching)
+    if (input.text) {
+      const keywords = input.text.toLowerCase().split(/\s+/);
+      results = results.filter(l => {
+        const text = l.content.toLowerCase();
+        return keywords.some(kw => text.includes(kw));
+      });
+    }
+
+    // Sort by relevance (confidence descending)
+    results.sort((a, b) => b.confidence - a.confidence);
+
+    return {
+      success: true,
+      data: {
+        count: results.length,
+        lessons: results.slice(0, limit).map(l => ({
+          id: l.id,
+          content: l.content,
+          confidence: l.confidence,
+          tags: l.tags,
+          evidence: l.evidence,
+        })),
+      },
+    };
+  }
+
+  private handleList(input: ListInput): ToolResult {
+    const limit = input.limit ?? 50;
+    let results = input.includeDeprecated
+      ? [...this.state.lessons]
+      : this.state.lessons.filter(l => !l.deprecated);
+
+    // Filter by tags
+    if (input.tags && input.tags.length > 0) {
+      const tagSet = new Set(input.tags.map(t => t.toLowerCase()));
+      results = results.filter(l =>
+        l.tags.some(t => tagSet.has(t.toLowerCase()))
+      );
+    }
+
+    // Sort
+    const sort = input.sort ?? 'confidence';
+    switch (sort) {
+      case 'confidence':
+        results.sort((a, b) => b.confidence - a.confidence);
+        break;
+      case 'created':
+        results.sort((a, b) => b.created - a.created);
+        break;
+      case 'updated':
+        results.sort((a, b) => b.updated - a.updated);
+        break;
+    }
+
+    return {
+      success: true,
+      data: {
+        total: results.length,
+        lessons: results.slice(0, limit).map(l => ({
+          id: l.id,
+          content: l.content,
+          confidence: l.confidence,
+          tags: l.tags,
+          deprecated: l.deprecated,
+        })),
+      },
+    };
+  }
+
+  private handleBoost(input: IdInput): ToolResult {
+    const lesson = this.state.lessons.find(l => l.id === input.id);
+    if (!lesson) {
+      return { success: false, error: `Lesson not found: ${input.id}`, isError: true };
+    }
+
+    // Diminishing returns boost
+    lesson.confidence = Math.min(1, lesson.confidence + 0.1 * (1 - lesson.confidence));
+    lesson.updated = Date.now();
+    this.save();
+
+    return { success: true, data: { id: lesson.id, confidence: lesson.confidence } };
+  }
+
+  private handleDemote(input: IdInput): ToolResult {
+    const lesson = this.state.lessons.find(l => l.id === input.id);
+    if (!lesson) {
+      return { success: false, error: `Lesson not found: ${input.id}`, isError: true };
+    }
+
+    // Diminishing returns demote
+    lesson.confidence = Math.max(0, lesson.confidence - 0.1 * lesson.confidence);
+    lesson.updated = Date.now();
+    this.save();
+
+    return { success: true, data: { id: lesson.id, confidence: lesson.confidence } };
+  }
+
+  private save(): void {
+    this.ctx?.setState(this.state);
+    if (this.globalPath) {
+      this.saveToGlobal();
+    }
+  }
+
+  /** Merge lessons from the global JSON file. Newer `updated` wins on ID conflicts. */
+  private mergeFromGlobal(): void {
+    if (!this.globalPath) return;
+    let global: LessonsState;
+    try {
+      global = JSON.parse(readFileSync(this.globalPath, 'utf-8'));
+    } catch {
+      return; // File doesn't exist yet — nothing to merge
+    }
+    if (!Array.isArray(global.lessons)) return;
+
+    const byId = new Map(this.state.lessons.map(l => [l.id, l]));
+    let merged = false;
+    for (const gl of global.lessons) {
+      const existing = byId.get(gl.id);
+      if (!existing) {
+        this.state.lessons.push(gl);
+        merged = true;
+      } else if (gl.updated > existing.updated) {
+        Object.assign(existing, gl);
+        merged = true;
+      }
+    }
+    if (merged) {
+      this.ctx?.setState(this.state);
+    }
+  }
+
+  /** Write current lessons to the global JSON file. */
+  private saveToGlobal(): void {
+    if (!this.globalPath) return;
+    try {
+      mkdirSync(dirname(this.globalPath), { recursive: true });
+      writeFileSync(this.globalPath, JSON.stringify({ lessons: this.state.lessons }, null, 2));
+    } catch {
+      // Best-effort — don't break the module if the file can't be written
+    }
+  }
+}