@animalabs/agent-framework 0.1.0 → 0.3.0

package/src/modules/workspace/watcher.ts

@@ -1,12 +1,35 @@
 /**
  * Filesystem watcher with debounce, ignore patterns, and suppression.
+ *
+ * Events are carried through with their op type (created/modified/deleted) so
+ * downstream wake policies can key on creation vs. modification vs. deletion.
  */
 
 import { watch, type FSWatcher } from 'chokidar';
+import { mkdirSync } from 'node:fs';
 import { type MountConfig } from './types.js';
 
+export type FsOp = 'created' | 'modified' | 'deleted';
+
+export interface FsChange {
+  path: string;
+  op: FsOp;
+}
+
 export interface WatcherEvents {
-  onChange(paths: string[]): void;
+  onChange(changes: FsChange[]): void;
+}
+
+/**
+ * Optional lifecycle callbacks. Without these, chokidar's `ready` and `error`
+ * events are silently dropped — which is how a failed attach can look
+ * identical to an empty directory in the recorded state.
+ */
+export interface WatcherLifecycle {
+  /** Fires once, when chokidar completes its initial scan. */
+  onReady?: () => void;
+  /** Fires on any chokidar-reported error (ENOENT, EACCES, platform faults). */
+  onError?: (err: Error) => void;
 }
 
 /**
@@ -15,21 +38,26 @@ export interface WatcherEvents {
  */
 export class MountWatcher {
   private watcher: FSWatcher | null = null;
-  private pendingChanges = new Set<string>();
+  // Most recent op seen per path within the current debounce window.
+  // create -> modify collapses to 'created' (single batch); delete always wins.
+  private pendingChanges = new Map<string, FsOp>();
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
   private suppressedPaths = new Set<string>();
   private suppressionTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private readonly debounceMs: number;
   private readonly config: MountConfig;
-  private readonly onChangeCallback: (paths: string[]) => void;
+  private readonly onChangeCallback: (changes: FsChange[]) => void;
+  private readonly lifecycle: WatcherLifecycle;
 
   constructor(
     config: MountConfig,
-    onChange: (paths: string[]) => void,
+    onChange: (changes: FsChange[]) => void,
+    lifecycle: WatcherLifecycle = {},
   ) {
     this.config = config;
     this.debounceMs = config.watchDebounceMs ?? 300;
     this.onChangeCallback = onChange;
+    this.lifecycle = lifecycle;
   }
 
   /**
@@ -38,6 +66,21 @@ export class MountWatcher {
   start(): void {
     if (this.watcher) return;
 
+    // Read-write mounts: ensure the path exists before chokidar attaches.
+    // chokidar 4's fs.watch-based backend silently fails to fire events when
+    // the watched path OR any of its parent directories don't exist at
+    // subscribe time (see case C in the WSL/Linux repro). `ready` still fires,
+    // so the failure is indistinguishable from an empty directory without
+    // this defensive mkdir. Read-only mounts are left alone — creating
+    // directories a user asked us only to read would be surprising.
+    if (this.config.mode === 'read-write') {
+      try {
+        mkdirSync(this.config.path, { recursive: true });
+      } catch (err) {
+        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+
     const ignored = this.config.ignore ?? [];
 
     this.watcher = watch(this.config.path, {
@@ -51,21 +94,31 @@ export class MountWatcher {
       },
     });
 
-    const handleEvent = (filePath: string) => {
-      // Convert absolute path to mount-relative
+    const handleEvent = (op: FsOp) => (filePath: string) => {
       const relative = this.toRelative(filePath);
       if (!relative) return;
 
-      // Skip if this path is suppressed (we just wrote it)
+      // Skip if this path is suppressed (we just wrote it).
+      // Suppression covers all ops — a materialize-then-delete by the module
+      // should not echo either the add or the unlink.
       if (this.suppressedPaths.has(relative)) return;
 
-      this.pendingChanges.add(relative);
+      this.mergeOp(relative, op);
       this.scheduleFire();
     };
 
-    this.watcher.on('add', handleEvent);
-    this.watcher.on('change', handleEvent);
-    this.watcher.on('unlink', handleEvent);
+    this.watcher.on('add', handleEvent('created'));
+    this.watcher.on('change', handleEvent('modified'));
+    this.watcher.on('unlink', handleEvent('deleted'));
+
+    if (this.lifecycle.onReady) {
+      this.watcher.once('ready', this.lifecycle.onReady);
+    }
+    if (this.lifecycle.onError) {
+      this.watcher.on('error', (err) => {
+        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+      });
+    }
   }
 
   /**
@@ -92,12 +145,10 @@ export class MountWatcher {
   /**
    * Suppress watcher events for a path temporarily.
    * Used after materializing to avoid echo events.
-   * After the cooldown, the path is re-checked via the recheckCallback.
    */
   suppress(relativePath: string, cooldownMs = 500): void {
     this.suppressedPaths.add(relativePath);
 
-    // Clear existing timer for this path
     const existing = this.suppressionTimers.get(relativePath);
     if (existing) clearTimeout(existing);
 
@@ -116,6 +167,44 @@ export class MountWatcher {
     return this.suppressedPaths.has(relativePath);
   }
 
+  /**
+   * Merge a new op for a path into the pending batch. Chokidar can fire
+   * multiple events per path inside one debounce window; collapse them to the
+   * single op that reflects the net effect at end-of-window.
+   *
+   * Transitions (prev → op → result):
+   *   ∅          → *         → op
+   *   *          → deleted   → deleted        (trailing delete wins)
+   *   deleted    → created   → modified       (atomic save: unlink+rename;
+   *                                            file exists with new contents)
+   *   created    → modified  → created        (still net-new this window)
+   *   created    → created   → created
+   *   modified   → created   → created        (shouldn't happen, but keep
+   *                                            created to avoid a false
+   *                                            delete->recreate signal)
+   *   modified   → modified  → modified
+   */
+  private mergeOp(path: string, op: FsOp): void {
+    const prev = this.pendingChanges.get(path);
+    if (!prev) {
+      this.pendingChanges.set(path, op);
+      return;
+    }
+    if (op === 'deleted') {
+      this.pendingChanges.set(path, 'deleted');
+      return;
+    }
+    if (prev === 'deleted' && op === 'created') {
+      this.pendingChanges.set(path, 'modified');
+      return;
+    }
+    if (prev === 'created') {
+      this.pendingChanges.set(path, 'created');
+      return;
+    }
+    this.pendingChanges.set(path, op);
+  }
+
   private scheduleFire(): void {
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
@@ -123,9 +212,9 @@ export class MountWatcher {
     this.debounceTimer = setTimeout(() => {
       this.debounceTimer = null;
       if (this.pendingChanges.size > 0) {
-        const paths = [...this.pendingChanges];
+        const changes: FsChange[] = [...this.pendingChanges].map(([path, op]) => ({ path, op }));
         this.pendingChanges.clear();
-        this.onChangeCallback(paths);
+        this.onChangeCallback(changes);
       }
     }, this.debounceMs);
   }

package/src/types/trace.ts

@@ -1,5 +1,6 @@
 import type { ProcessEvent } from './events.js';
 import type { ModuleProcessResponse } from './framework.js';
+import type { SessionUsage } from '../usage/types.js';
 
 /**
  * Base for all trace events.
@@ -75,7 +76,7 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'inference:usage';
       agentName: string;
-      tokenUsage: { input: number; output: number };
+      tokenUsage: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
     })
   | (TraceEventBase & {
       type: 'inference:stream_resumed';
@@ -174,6 +175,23 @@ export type TraceEvent =
       configPath: string;
       policyCount: number;
     })
+  | (TraceEventBase & {
+      type: 'gate:decision';
+      eventType: string;
+      serverId?: string;
+      channelId?: string;
+      matchedPolicy: string | null;
+      trigger: boolean;
+      behavior: string;
+    })
+
+  // Usage lifecycle
+  | (TraceEventBase & {
+      type: 'usage:updated';
+      totals: SessionUsage;
+      agentName: string;
+      inferenceCount: number;
+    })
 
   // Undo/redo lifecycle
   | (TraceEventBase & {
@@ -188,6 +206,13 @@ export type TraceEvent =
       agentName: string;
       fromBranch: string;
       toBranch: string;
+    })
+
+  // MCPL subprocess stderr (one trace per line, for receipts when things break)
+  | (TraceEventBase & {
+      type: 'mcpl:server-stderr';
+      serverId: string;
+      line: string;
     });
 
 /**

package/src/usage/index.ts

@@ -0,0 +1,2 @@
+export { UsageTracker } from './usage-tracker.js';
+export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './types.js';

package/src/usage/types.ts

@@ -0,0 +1,27 @@
+export interface SessionUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationTokens: number;
+  cacheReadTokens: number;
+  estimatedCost?: { total: number; currency: string };
+}
+
+export interface AgentUsage {
+  agentName: string;
+  usage: SessionUsage;
+  inferenceCount: number;
+}
+
+export interface SessionUsageSnapshot {
+  totals: SessionUsage;
+  byAgent: AgentUsage[];
+  inferenceCount: number;
+}
+
+/** Trace event emitted by UsageTracker after each inference completion. */
+export interface UsageUpdatedEvent {
+  type: 'usage:updated';
+  totals: SessionUsage;
+  agentName: string;
+  inferenceCount: number;
+}

package/src/usage/usage-tracker.ts

@@ -0,0 +1,141 @@
+import type { SessionUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './types.js';
+
+function snapshotUsage(usage: SessionUsage): SessionUsage {
+  return {
+    ...usage,
+    estimatedCost: usage.estimatedCost ? { ...usage.estimatedCost } : undefined,
+  };
+}
+
+function accumulateUsage(
+  target: SessionUsage,
+  tokens: { inputTokens: number; outputTokens: number; cacheCreationTokens: number; cacheReadTokens: number },
+  estimatedCost?: { total: number; currency: string }
+): void {
+  target.inputTokens += tokens.inputTokens;
+  target.outputTokens += tokens.outputTokens;
+  target.cacheCreationTokens += tokens.cacheCreationTokens;
+  target.cacheReadTokens += tokens.cacheReadTokens;
+  if (estimatedCost) {
+    if (!target.estimatedCost) {
+      target.estimatedCost = { total: 0, currency: estimatedCost.currency };
+    } else if (target.estimatedCost.currency !== estimatedCost.currency) {
+      // Mixed currencies — drop cost tracking rather than produce garbage
+      target.estimatedCost = undefined;
+      return;
+    }
+    target.estimatedCost.total += estimatedCost.total;
+  }
+}
+
+function parseUsage(raw: unknown): SessionUsage | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const o = raw as Record<string, unknown>;
+  if (typeof o.inputTokens !== 'number' || typeof o.outputTokens !== 'number') return null;
+  return {
+    inputTokens: o.inputTokens,
+    outputTokens: o.outputTokens as number,
+    cacheCreationTokens: typeof o.cacheCreationTokens === 'number' ? o.cacheCreationTokens : 0,
+    cacheReadTokens: typeof o.cacheReadTokens === 'number' ? o.cacheReadTokens : 0,
+    estimatedCost: o.estimatedCost && typeof o.estimatedCost === 'object'
+      ? { total: (o.estimatedCost as any).total, currency: (o.estimatedCost as any).currency }
+      : undefined,
+  };
+}
+
+export interface PersistedUsageState {
+  totals: SessionUsage;
+  byAgent: Array<{ agentName: string; usage: SessionUsage; inferenceCount: number }>;
+  inferenceCount: number;
+}
+
+export class UsageTracker {
+  private totals: SessionUsage = { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+  private byAgent: Map<string, { usage: SessionUsage; inferenceCount: number }> = new Map();
+  private inferenceCount = 0;
+  private emitTrace: (event: UsageUpdatedEvent) => void;
+
+  constructor(opts: {
+    emitTrace: (event: UsageUpdatedEvent) => void;
+    restored?: PersistedUsageState;
+  }) {
+    this.emitTrace = opts.emitTrace;
+    if (opts.restored) {
+      this.restoreFrom(opts.restored);
+    }
+  }
+
+  private restoreFrom(state: PersistedUsageState): void {
+    const totals = parseUsage(state.totals);
+    if (!totals) return;
+    this.totals = totals;
+    this.inferenceCount = typeof state.inferenceCount === 'number' ? state.inferenceCount : 0;
+    if (Array.isArray(state.byAgent)) {
+      for (const entry of state.byAgent) {
+        const usage = parseUsage(entry.usage);
+        if (usage && typeof entry.agentName === 'string') {
+          this.byAgent.set(entry.agentName, {
+            usage,
+            inferenceCount: typeof entry.inferenceCount === 'number' ? entry.inferenceCount : 0,
+          });
+        }
+      }
+    }
+  }
+
+  toJSON(): PersistedUsageState {
+    return {
+      totals: snapshotUsage(this.totals),
+      byAgent: [...this.byAgent.entries()].map(([name, data]) => ({
+        agentName: name,
+        usage: snapshotUsage(data.usage),
+        inferenceCount: data.inferenceCount,
+      })),
+      inferenceCount: this.inferenceCount,
+    };
+  }
+
+  onInferenceCompleted(agentName: string, usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+  }, estimatedCost?: { total: number; currency: string }): void {
+    const tokens = {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheCreationTokens: usage.cacheCreationTokens ?? 0,
+      cacheReadTokens: usage.cacheReadTokens ?? 0,
+    };
+
+    accumulateUsage(this.totals, tokens, estimatedCost);
+    this.inferenceCount++;
+
+    let agent = this.byAgent.get(agentName);
+    if (!agent) {
+      agent = { usage: { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 }, inferenceCount: 0 };
+      this.byAgent.set(agentName, agent);
+    }
+    accumulateUsage(agent.usage, tokens, estimatedCost);
+    agent.inferenceCount++;
+
+    this.emitTrace({
+      type: 'usage:updated',
+      totals: snapshotUsage(this.totals),
+      agentName,
+      inferenceCount: this.inferenceCount,
+    });
+  }
+
+  getSnapshot(): SessionUsageSnapshot {
+    return {
+      totals: snapshotUsage(this.totals),
+      byAgent: [...this.byAgent.entries()].map(([name, data]) => ({
+        agentName: name,
+        usage: snapshotUsage(data.usage),
+        inferenceCount: data.inferenceCount,
+      })),
+      inferenceCount: this.inferenceCount,
+    };
+  }
+}