@animalabs/agent-framework 0.5.6 → 0.6.0

package/src/runtime/liveness-watchdog-worker.ts

@@ -0,0 +1,66 @@
+/**
+ * Liveness watchdog worker — runs on its own thread, so it keeps ticking even
+ * when the main thread is wedged. Watches the shared heartbeat; if it goes stale
+ * past the threshold, writes a diagnostic and kills the whole process.
+ *
+ * Killing from a worker: process.kill(process.pid, signal) signals the whole
+ * process. SIGABRT → core dump (if enabled) + terminate; SIGKILL → immediate.
+ * Catchable signals (SIGTERM) are avoided — their handler would run on the
+ * wedged main thread and never fire.
+ */
+import { workerData } from 'node:worker_threads';
+import { writeFileSync } from 'node:fs';
+
+interface Data {
+  sab: SharedArrayBuffer;
+  thresholdMs: number;
+  checkMs: number;
+  action: 'abort' | 'exit';
+  reportPath: string | null;
+}
+const { sab, thresholdMs, checkMs, action, reportPath } = workerData as Data;
+
+const hb = new Float64Array(sab, 0, 1);
+const phaseBuf = new Uint8Array(sab, 16, 48);
+const dec = new TextDecoder();
+
+function currentPhase(): string {
+  return dec.decode(phaseBuf).replace(/\0+$/, '') || 'unknown';
+}
+
+function check(): void {
+  const last = hb[0];
+  const age = Date.now() - last;
+  if (last > 0 && age > thresholdMs) {
+    const phase = currentPhase();
+    const report = {
+      ts: new Date().toISOString(),
+      event: 'main-thread-wedged',
+      ageMs: Math.round(age),
+      thresholdMs,
+      phase,
+      action,
+      pid: process.pid,
+    };
+    const line = `[liveness-watchdog] main thread unresponsive ${Math.round(age)}ms ` +
+      `(phase=${phase}) — failing hard via ${action}`;
+    try {
+      console.error(line);
+    } catch {
+      /* ignore */
+    }
+    if (reportPath) {
+      try {
+        writeFileSync(reportPath, JSON.stringify(report) + '\n', { flag: 'a' });
+      } catch {
+        /* best effort */
+      }
+    }
+    // Kill the whole process. The supervisor restarts a fresh one.
+    process.kill(process.pid, action === 'abort' ? 'SIGABRT' : 'SIGKILL');
+    return; // process is dying
+  }
+  setTimeout(check, checkMs);
+}
+
+setTimeout(check, checkMs);

package/src/runtime/liveness-watchdog.ts

@@ -0,0 +1,122 @@
+/**
+ * LivenessWatchdog — detects a wedged (unresponsive) main thread and fails hard.
+ *
+ * The agent's event loop is single-threaded. A synchronous infinite loop or a
+ * self-rescheduling microtask flood (e.g. a pathological compression drain) can
+ * peg the thread for minutes: no events, no heartbeat, no recovery — the agent
+ * goes silently deaf. A same-thread timer can't catch this (it can't fire while
+ * the loop is blocked), so detection must live off-thread.
+ *
+ * Mechanism: the main thread stamps a heartbeat (and an optional phase label)
+ * into shared memory on a timer. A worker thread — which keeps running even when
+ * main is wedged — watches the heartbeat; if it goes stale past a threshold it
+ * writes a diagnostic and kills the whole process:
+ *   - 'abort' → SIGABRT (core dump if enabled, for an offline stack) then dies
+ *   - 'exit'  → SIGKILL (clean, quiet; rely on the supervisor to restart)
+ * Either way the supervisor (launchd/systemd) restarts a fresh process instead
+ * of leaving a deaf one running.
+ */
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { phaseChannel } from '@animalabs/context-manager';
+
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'liveness-watchdog-worker.js');
+
+const HEARTBEAT_OFFSET = 0; // Float64: last heartbeat (ms since epoch)
+const PHASE_OFFSET = 16; // Uint8[48]: current phase label (UTF-8)
+const PHASE_LEN = 48;
+const SAB_SIZE = 64;
+
+export interface WatchdogOptions {
+  /** Wedge threshold: kill if no heartbeat for this long. Default 30000ms. */
+  thresholdMs?: number;
+  /** Heartbeat cadence. Default 1000ms. */
+  heartbeatMs?: number;
+  /** 'abort' → SIGABRT (core dump for debugging); 'exit' → SIGKILL. Default 'abort'. */
+  action?: 'abort' | 'exit';
+  /** Optional file the worker writes a JSON wedge report to before killing. */
+  reportPath?: string;
+  /** Disable entirely. */
+  enabled?: boolean;
+}
+
+export class LivenessWatchdog {
+  private readonly sab = new SharedArrayBuffer(SAB_SIZE);
+  private readonly hb = new Float64Array(this.sab, HEARTBEAT_OFFSET, 1);
+  private readonly phaseBuf = new Uint8Array(this.sab, PHASE_OFFSET, PHASE_LEN);
+  private readonly enc = new TextEncoder();
+  private timer?: ReturnType<typeof setInterval>;
+  private worker?: Worker;
+  private started = false;
+
+  constructor(private readonly opts: WatchdogOptions = {}) {}
+
+  start(): void {
+    if (this.started || this.opts.enabled === false) return;
+    this.started = true;
+    const heartbeatMs = this.opts.heartbeatMs ?? 1000;
+    this.setPhase('starting');
+    this.beat();
+    this.timer = setInterval(() => this.beat(), heartbeatMs);
+    this.timer.unref?.();
+    try {
+      this.worker = new Worker(WORKER_PATH, {
+        workerData: {
+          sab: this.sab,
+          thresholdMs: this.opts.thresholdMs ?? 30_000,
+          checkMs: Math.min(heartbeatMs, 2000),
+          action: this.opts.action ?? 'abort',
+          reportPath: this.opts.reportPath ?? null,
+        },
+      });
+      this.worker.unref();
+      this.worker.on('error', (e) => console.error('[liveness-watchdog] worker error:', e.message));
+      // Wire the phase channel so labelled synchronous spans (compression,
+      // context-build, merge-graph walks) name themselves in a wedge report.
+      phaseChannel.report = (label: string) => this.setPhase(label);
+      console.error(
+        `[liveness-watchdog] armed: threshold=${this.opts.thresholdMs ?? 30_000}ms ` +
+          `action=${this.opts.action ?? 'abort'}`,
+      );
+    } catch (e) {
+      console.error('[liveness-watchdog] failed to start:', (e as Error).message);
+    }
+    this.setPhase('idle');
+  }
+
+  /** Stamp liveness. Called on a timer; the worker watches for staleness. */
+  private beat(): void {
+    this.hb[0] = Date.now();
+  }
+
+  /**
+   * Label the operation the main thread is about to run synchronously, so a
+   * wedge report names it (e.g. 'compression-tick', 'context-build'). Keep it
+   * short (truncated to 48 bytes). Reset to 'idle' when done.
+   */
+  setPhase(label: string): void {
+    this.phaseBuf.fill(0);
+    const bytes = this.enc.encode(label);
+    this.phaseBuf.set(bytes.subarray(0, PHASE_LEN));
+  }
+
+  /** Run a synchronous section under a named phase, restoring the prior phase. */
+  withPhase<T>(label: string, fn: () => T): T {
+    this.setPhase(label);
+    try {
+      return fn();
+    } finally {
+      this.setPhase('idle');
+    }
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    phaseChannel.report = () => {};
+    void this.worker?.terminate();
+    this.worker = undefined;
+    this.started = false;
+  }
+}

package/src/tool-result-history.ts

@@ -0,0 +1,57 @@
+/**
+ * Convert an AF `ToolResult.data` value into the string form that lives in
+ * the agent's conversation history.
+ *
+ * The live path (`toMembraneToolResult` in framework.ts) preserves MCP image
+ * blocks natively so the model sees the bytes on the current turn. The
+ * *persisted* copy needs to survive recompilation, compression, and
+ * `/restore` — storing megabytes of base64 there gets corrupted on the next
+ * `maxChars` slice and re-introduces, one turn deferred, exactly the silent
+ * hallucination this feature exists to kill.
+ *
+ * For MCP-shaped content arrays, this helper keeps text blocks verbatim and
+ * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
+ * For anything else it falls back to JSON.
+ */
+
+import { safeSlice } from './safe-slice.js';
+
+export function toolResultDataToHistoryString(data: unknown, maxChars?: number): string {
+  const fromArray = tryHistoryStringFromContentArray(data);
+  const str = fromArray ?? JSON.stringify(data);
+  if (maxChars && str.length > maxChars) {
+    return safeSlice(str, 0, maxChars)
+      + '\n\n[truncated — original was ' + str.length + ' chars]';
+  }
+  return str;
+}
+
+/**
+ * If `data` is an MCP content array whose every block has a shape we
+ * recognize, return a history-safe string (images → placeholders). Otherwise
+ * return `null` to defer to the caller's fallback (JSON, usually).
+ */
+function tryHistoryStringFromContentArray(data: unknown): string | null {
+  if (!Array.isArray(data)) return null;
+  const parts: string[] = [];
+  for (const raw of data) {
+    if (!raw || typeof raw !== 'object') return null;
+    const b = raw as { type?: unknown; text?: unknown; data?: unknown; mimeType?: unknown };
+    if (b.type === 'text' && typeof b.text === 'string') {
+      parts.push(b.text);
+    } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
+      // Decoded byte estimate from base64 length (3/4 ratio, rounded).
+      const approxBytes = Math.floor(b.data.length * 3 / 4);
+      parts.push(`[image: ${b.mimeType}, ${formatSize(approxBytes)}]`);
+    } else {
+      return null;
+    }
+  }
+  return parts.join('\n');
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `~${Math.round(bytes / 1024)}KB`;
+  return `~${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/types/agent.ts

@@ -42,6 +42,9 @@ export interface AgentConfig {
    *  restarts with recompiled (compressed) context. Default: 150000. */
   maxStreamTokens?: number;
 
+  /** Per-agent context compile budget (input tokens). When unset, the
+   *  ContextManager's built-in default (100k) applies. */
+  contextBudgetTokens?: number;
   /**
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks
@@ -51,6 +54,14 @@ export interface AgentConfig {
   thinking?: {
     enabled: boolean;
     budgetTokens?: number;
+    /** 'enabled' (explicit budget, default) or 'adaptive' (model-managed) */
+    type?: 'enabled' | 'adaptive';
+    /**
+     * How thinking content is returned: 'summarized' (readable summary) or
+     * 'omitted' (empty thinking field, signature only). Fable 5 / Opus 4.7+
+     * default to 'omitted' — set 'summarized' to receive thinking text.
+     */
+    display?: 'summarized' | 'omitted';
   };
 }
 
@@ -127,4 +138,14 @@ export interface InferenceRequest {
   reason: string;
   source: string;
   timestamp: number;
+  /**
+   * The MCPL channel whose message triggered this inference, if any (composite
+   * id, e.g. `discord:guild:channel` / `discord:dm:id`). The framework routes
+   * the turn's auto-published plain-text speech here so a single TRUNK agent
+   * replies in the channel it is answering — not the process-global most-recent-
+   * inbound locus, which a concurrent message elsewhere can hijack (item-3
+   * redux). Undefined for non-channel wakes (heartbeat, timers, module events),
+   * which correctly fall back to the global default channel.
+   */
+  channelId?: string;
 }

package/src/types/framework.ts

@@ -4,6 +4,7 @@ import type { Module, EventResponse } from './module.js';
 import type { AgentConfig, InferenceRequest } from './agent.js';
 import type { ProcessEvent } from './events.js';
 import type { McplServerConfig, InferenceRoutingPolicy } from '../mcpl/types.js';
+import type { ConversationRouterConfig } from '../mcpl/conversation-router.js';
 import type { GateOptions } from '../gate/types.js';
 
 // Re-export trace types
@@ -66,6 +67,29 @@ export interface FrameworkConfig {
 
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */
   gate?: GateOptions;
+
+  /**
+   * Liveness watchdog: fail hard (and let the supervisor restart) if the main
+   * thread wedges — a synchronous infinite loop or microtask flood that would
+   * otherwise leave the agent silently deaf. Off unless `enabled` is set.
+   */
+  watchdog?: {
+    enabled?: boolean;
+    /** Kill if no heartbeat for this long (ms). Default 30000. */
+    thresholdMs?: number;
+    /** 'abort' → SIGABRT (core dump for debugging); 'exit' → SIGKILL. Default 'abort'. */
+    action?: 'abort' | 'exit';
+    /** Optional path for a JSON wedge report written before the kill. */
+    reportPath?: string;
+  };
+
+  /**
+   * Per-channel conversation routing. When set, incoming MCPL channel
+   * messages route to per-channel fork agents spawned from the template
+   * agent instead of the primary conversation. If omitted, behavior is
+   * unchanged (all messages go to the primary agent).
+   */
+  conversations?: ConversationRouterConfig;
 }
 
 /**

package/src/types/module.ts

@@ -6,6 +6,7 @@ import type {
   ContextInjection,
 } from '@animalabs/context-manager';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from './events.js';
+import type { TraceEventListener } from './trace.js';
 
 /**
  * Filter criteria for querying messages.
@@ -184,6 +185,34 @@ export interface ModuleContext {
    * Unregister this module as a speech handler.
    */
   unregisterSpeechHandler(): void;
+
+  /**
+   * Execute a tool call autonomously, without agent mediation.
+   *
+   * Routes through the framework's normal tool dispatch — MCPL-prefixed names
+   * (e.g. `mcpl--discord--unsubscribe_channel`) hit the MCPL subsystem; module
+   * names hit the owning module. Unlike pushing a `tool-call` event, this does
+   * NOT record tool_use/tool_result into any agent's context — it's a pure
+   * side-effecting call whose result is returned to the caller. Used by modules
+   * that need to act on their own (e.g. subscription GC unsubscribing a noisy
+   * channel) rather than asking the agent to call the tool.
+   */
+  callTool(call: ToolCall): Promise<ToolResult>;
+
+  /**
+   * Subscribe to the framework's trace event stream for observability.
+   *
+   * Modules use this to react to agent lifecycle without polling — e.g. an
+   * adapter that wants to show a "typing" indicator can bracket it between
+   * `inference:started` and the terminal events (`inference:turn_ended`,
+   * `inference:aborted`, `inference:failed`, `inference:exhausted`), all of
+   * which carry `agentName`. The terminal events fire once per turn, after any
+   * tool-call cycles, so a single start/stop bracket spans the whole turn.
+   *
+   * Returns an unsubscribe function. Call it in the module's `stop()` to avoid
+   * leaking listeners across teardown/recreate (e.g. session switch).
+   */
+  onTrace(listener: TraceEventListener): () => void;
 }
 
 /**

package/src/types/trace.ts

@@ -234,6 +234,42 @@ export type TraceEvent =
       type: 'mcpl:server-stderr';
       serverId: string;
       line: string;
+    })
+
+  // Per-channel conversation routing lifecycle
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-spawned';
+      channelId: string;
+      agentName: string;
+      generation: number;
+      template: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-spawn-failed';
+      channelId: string;
+      agentName: string;
+      error: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-unrouted';
+      channelId: string;
+      messageId: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-binding-orphaned';
+      channelId: string;
+      agentName: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-closed';
+      channelId: string;
+      agentName: string;
+      reason: 'idle-ttl';
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:conversation-disposed';
+      agentName: string;
+      channelId?: string;
     });
 
 /**