@animalabs/agent-framework 0.1.0 → 0.2.0

package/src/modules/workspace/index.ts

@@ -5,8 +5,8 @@
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
 
-import { readFile, stat, access } from 'node:fs/promises';
-import { join, resolve, relative } from 'node:path';
+import { readFile, stat, access, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, resolve, relative, dirname } from 'node:path';
 import type { JsStore } from '@animalabs/chronicle';
 import type { Module, ModuleContext, ProcessState, EventResponse } from '../../types/module.js';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from '../../types/events.js';
@@ -25,9 +25,13 @@ import type {
   StatusInput,
   MaterializeInput,
   SyncInput,
-  WorkspaceChangedEvent,
+  WorkspaceCreatedEvent,
+  WorkspaceModifiedEvent,
+  WorkspaceDeletedEvent,
+  WorkspaceFsOp,
 } from './types.js';
-import { MountWatcher } from './watcher.js';
+import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
+import { MountWatcher, type FsChange } from './watcher.js';
 import { syncFromFs, materializeToFs, hashContent, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
 
 export type {
@@ -85,6 +89,12 @@ export class WorkspaceModule implements Module {
 
   /**
    * Inject the Chronicle store. Must be called after framework creation.
+   *
+   * Host ordering is: `AgentFramework.create()` calls `module.start(ctx)`
+   * before the framework is fully returned, and the host (e.g. conhost) wires
+   * the store via `initStore(store)` afterwards. Neither half has everything
+   * it needs on its own, so watcher setup runs in whichever callback fires
+   * second. `ensureRunning()` gates on `ctx && mounts-populated`.
    */
   initStore(store: JsStore): void {
     this.store = store;
@@ -114,6 +124,8 @@ export class WorkspaceModule implements Module {
       };
       this.mounts.set(mount.name, mountState);
     }
+
+    this.ensureRunning();
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -133,19 +145,38 @@ export class WorkspaceModule implements Module {
       }
     }
 
-    // Start watchers for 'always' mode mounts
+    this.ensureRunning();
+  }
+
+  /**
+   * Start chokidar watchers and emit workspace:mounted events.
+   * Idempotent: safe to call from both start() and initStore(), fires once
+   * per mount regardless of which runs second.
+   */
+  private ensureRunning(): void {
+    if (!this.ctx || this.mounts.size === 0) return;
+
     for (const [name, mount] of this.mounts) {
+      if (this.watchers.has(name)) continue;
+
       const watchMode = mount.config.watch ?? 'always';
       if (watchMode === 'always') {
-        const watcher = new MountWatcher(mount.config, (paths) => {
-          this.handleFsChanges(name, paths);
+        const watcher = new MountWatcher(mount.config, (changes) => {
+          this.handleFsChanges(name, changes);
         });
         watcher.start();
         this.watchers.set(name, watcher);
+
+        // Chokidar is started with ignoreInitial:true, so files already on
+        // disk at session start would be invisible. Trigger one syncFromFs
+        // pass — syncFromFs diffs disk against the tree state, so only files
+        // new-to-this-session's-tree fire workspace:created events. Fresh
+        // sessions see the existing catalog; restarts only see what appeared
+        // while the session was down.
+        void this.initialScan(name);
       }
 
-      // Emit mounted event
-      this.ctx?.pushEvent({
+      this.ctx.pushEvent({
         type: 'workspace:mounted',
         mount: name,
         path: mount.config.path,
@@ -153,6 +184,25 @@ export class WorkspaceModule implements Module {
     }
   }
 
+  private async initialScan(mountName: string): Promise<void> {
+    const store = this.store;
+    const mount = this.mounts.get(mountName);
+    if (!store || !mount) return;
+
+    try {
+      const result = await syncFromFs(store, mount);
+      mount.initialSyncDone = true;
+      this.emitFsEvents(mountName, result.synced, result.conflicts);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.ctx?.pushEvent({
+        type: 'workspace:initial-scan-failed',
+        mount: mountName,
+        error: msg,
+      } as ProcessEvent);
+    }
+  }
+
   async stop(): Promise<void> {
     // Persist state
     if (this.ctx) {
@@ -330,8 +380,26 @@ export class WorkspaceModule implements Module {
     }
   }
 
-  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
-    return {};
+  async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    // Wake agents on filesystem events when the originating mount opted in.
+    // The EventGate still has final say — gate policies can further filter by
+    // mount name, path glob, or op type without requiring a recipe change.
+    if (!(WORKSPACE_FS_EVENT_TYPES as readonly string[]).includes(event.type)) {
+      return {};
+    }
+    const mountName = (event as { mount?: string }).mount;
+    if (!mountName) return {};
+    const mount = this.mounts.get(mountName);
+    if (!mount) return {};
+
+    const flag = mount.config.wakeOnChange;
+    if (!flag) return {};
+
+    const op = event.type.slice('workspace:'.length) as WorkspaceFsOp;
+    const opAllowed = flag === true || (Array.isArray(flag) && flag.includes(op));
+    if (!opAllowed) return {};
+
+    return { requestInference: true };
   }
 
   // ==========================================================================
@@ -366,6 +434,58 @@ export class WorkspaceModule implements Module {
     return this.store;
   }
 
+  /**
+   * Persist a single write/edit/delete to disk when the mount opts in via
+   * `autoMaterialize`. Required for cross-agent pipelines — another agent's
+   * chokidar watcher on the same directory only sees real filesystem events.
+   * The local watcher's `suppress()` absorbs the echo so we don't self-wake.
+   *
+   * Returns an error string on failure so callers can surface it in the tool
+   * result. The autoMaterialize contract is specifically "disk is the source
+   * of truth for downstream agents", so a silent disk-write failure with a
+   * Chronicle commit would defeat the whole purpose. No-op cases (flag off,
+   * read-only mount) return null (success).
+   */
+  private async autoMaterialize(
+    mount: MountState,
+    relativePath: string,
+    op: 'write' | 'delete',
+    content?: Buffer,
+  ): Promise<string | null> {
+    if (!mount.config.autoMaterialize) return null;
+    if (mount.config.mode === 'read-only') return null;
+
+    const absolutePath = join(mount.config.path, relativePath);
+    const watcher = this.watchers.get(mount.config.name);
+    watcher?.suppress(relativePath);
+
+    try {
+      if (op === 'write' && content) {
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, content);
+        mount.materializedHashes.set(relativePath, hashContent(content));
+      } else if (op === 'delete') {
+        try {
+          await unlink(absolutePath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+        }
+        mount.materializedHashes.delete(relativePath);
+      }
+      return null;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.ctx?.pushEvent({
+        type: 'workspace:materialize-failed',
+        mount: mount.config.name,
+        path: relativePath,
+        op,
+        error: msg,
+      } as ProcessEvent);
+      return msg;
+    }
+  }
+
   // ==========================================================================
   // Lazy Sync
   // ==========================================================================
@@ -456,12 +576,21 @@ export class WorkspaceModule implements Module {
       return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
     }
 
-    const blobHash = store.storeBlob(Buffer.from(input.content, 'utf-8'), 'text/plain');
+    const buffer = Buffer.from(input.content, 'utf-8');
+    const blobHash = store.storeBlob(buffer, 'text/plain');
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash,
       size: Buffer.byteLength(input.content),
       mode: 0o644,
     });
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'write', buffer);
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Wrote to Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
+        isError: true,
+      };
+    }
 
     return {
       success: true,
@@ -513,12 +642,21 @@ export class WorkspaceModule implements Module {
       ? content.replaceAll(input.oldString, input.newString)
       : content.replace(input.oldString, input.newString);
 
-    const newBlobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
+    const newBuffer = Buffer.from(content, 'utf-8');
+    const newBlobHash = store.storeBlob(newBuffer, 'text/plain');
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash: newBlobHash,
       size: Buffer.byteLength(content),
       mode: entry.mode,
     });
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'write', newBuffer);
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Edited Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
+        isError: true,
+      };
+    }
 
     return {
       success: true,
@@ -542,6 +680,14 @@ export class WorkspaceModule implements Module {
     }
 
     store.treeRemove(mount.treeStateId, relativePath);
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'delete');
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Removed from Chronicle but failed to unlink "${input.path}" from disk: ${materializeError}. Downstream agents will still see the stale file until manual cleanup.`,
+        isError: true,
+      };
+    }
 
     return { success: true, data: { path: input.path, deleted: true } };
   }
@@ -869,20 +1015,12 @@ export class WorkspaceModule implements Module {
       mount.initialSyncDone = true;
 
       if (result.synced.length > 0 || result.conflicts.length > 0) {
-        allResults.push({ mount: name, synced: result.synced, conflicts: result.conflicts });
-
-        // Emit workspace:changed event
-        if (this.ctx) {
-          const event: WorkspaceChangedEvent = {
-            type: 'workspace:changed',
-            paths: result.synced.map(p => `${name}/${p}`),
-            mount: name,
-            conflicts: result.conflicts.length > 0
-              ? result.conflicts.map(c => `${name}/${c.path}`)
-              : undefined,
-          };
-          this.ctx.pushEvent(event as ProcessEvent);
-        }
+        allResults.push({
+          mount: name,
+          synced: result.synced.map(s => s.path),
+          conflicts: result.conflicts,
+        });
+        this.emitFsEvents(name, result.synced, result.conflicts);
       }
     }
 
@@ -902,23 +1040,76 @@ export class WorkspaceModule implements Module {
 
   /**
    * Handle filesystem changes detected by watcher (watch: 'always' mode).
+   *
+   * The watcher carries the op per path. For created/modified we call
+   * syncFromFs to pull content into the tree; for deleted we strip the tree
+   * entry directly (the file is gone, nothing to read). We emit one event per
+   * op type.
    */
-  private async handleFsChanges(mountName: string, paths: string[]): Promise<void> {
+  private async handleFsChanges(mountName: string, changes: FsChange[]): Promise<void> {
     const store = this.store;
     const mount = this.mounts.get(mountName);
     if (!store || !mount) return;
 
-    const result = await syncFromFs(store, mount, paths);
+    const touchedPaths = changes.filter(c => c.op !== 'deleted').map(c => c.path);
+    const deletedPaths = changes.filter(c => c.op === 'deleted').map(c => c.path);
+
+    const syncResult = touchedPaths.length > 0
+      ? await syncFromFs(store, mount, touchedPaths)
+      : { synced: [], conflicts: [], skipped: [] };
+
+    // Strip deleted entries from the tree so downstream consumers see a
+    // coherent state. syncFromFs would also do this if we passed the paths in,
+    // but the op from the watcher is authoritative — skip the access() probe.
+    for (const p of deletedPaths) {
+      const existing = store.treeGet(mount.treeStateId, p);
+      if (existing) {
+        store.treeRemove(mount.treeStateId, p);
+        syncResult.synced.push({ path: p, op: 'deleted' });
+      }
+    }
 
-    if ((result.synced.length > 0 || result.conflicts.length > 0) && this.ctx) {
-      const event: WorkspaceChangedEvent = {
-        type: 'workspace:changed',
-        paths: result.synced.map(p => `${mountName}/${p}`),
+    this.emitFsEvents(mountName, syncResult.synced, syncResult.conflicts);
+  }
+
+  /**
+   * Group synced paths by op and push one ProcessEvent per non-empty op.
+   */
+  private emitFsEvents(
+    mountName: string,
+    synced: Array<{ path: string; op: WorkspaceFsOp }>,
+    conflicts: ConflictInfo[],
+  ): void {
+    if (!this.ctx || synced.length === 0) return;
+
+    const byOp = new Map<WorkspaceFsOp, string[]>();
+    for (const { path, op } of synced) {
+      const list = byOp.get(op) ?? [];
+      list.push(`${mountName}/${path}`);
+      byOp.set(op, list);
+    }
+
+    // Conflicts by definition require a prior tree entry (sync detected that
+    // the agent-side version diverged from the filesystem baseline), which
+    // means the path is being re-synced as a modification. Attach conflicts
+    // only to the workspace:modified event, intersected with its paths — a
+    // created/deleted batch can't carry a meaningful conflict.
+    const conflictsByPath = new Map<string, ConflictInfo>();
+    for (const c of conflicts) conflictsByPath.set(c.path, c);
+
+    for (const [op, paths] of byOp) {
+      const type = opToEventType(op);
+      let eventConflicts: string[] | undefined;
+      if (op === 'modified' && conflictsByPath.size > 0) {
+        const matched = paths.filter(p => conflictsByPath.has(p.slice(mountName.length + 1)));
+        if (matched.length > 0) eventConflicts = matched;
+      }
+      const event = {
+        type,
+        paths,
         mount: mountName,
-        conflicts: result.conflicts.length > 0
-          ? result.conflicts.map(c => `${mountName}/${c.path}`)
-          : undefined,
-      };
+        ...(eventConflicts ? { conflicts: eventConflicts } : {}),
+      } as WorkspaceCreatedEvent | WorkspaceModifiedEvent | WorkspaceDeletedEvent;
       this.ctx.pushEvent(event as ProcessEvent);
     }
   }

package/src/modules/workspace/sync.ts

@@ -56,9 +56,16 @@ export interface ConflictInfo {
   agentBlobHash: string;
 }
 
+export type SyncOp = 'created' | 'modified' | 'deleted';
+
+export interface SyncedPath {
+  path: string;
+  op: SyncOp;
+}
+
 export interface SyncResult {
-  /** Paths that were synced */
-  synced: string[];
+  /** Paths that were synced, tagged with the op detected against tree state */
+  synced: SyncedPath[];
   /** Paths that conflicted (both agent and user modified) — filesystem wins */
   conflicts: ConflictInfo[];
   /** Paths that were skipped (binary, too large, etc.) */
@@ -97,7 +104,7 @@ export async function syncFromFs(
       const existing = store.treeGet(mount.treeStateId, relativePath);
       if (existing) {
         store.treeRemove(mount.treeStateId, relativePath);
-        result.synced.push(relativePath);
+        result.synced.push({ path: relativePath, op: 'deleted' });
       }
       continue;
     }
@@ -151,7 +158,7 @@ export async function syncFromFs(
       }
 
       store.treeSet(mount.treeStateId, relativePath, entry);
-      result.synced.push(relativePath);
+      result.synced.push({ path: relativePath, op: existing ? 'modified' : 'created' });
     } catch {
       result.skipped.push(relativePath);
     }

package/src/modules/workspace/types.ts

@@ -36,6 +36,26 @@ export interface MountConfig {
   followSymlinks?: boolean;
   /** Maximum file size in bytes (default: 5MB) */
   maxFileSize?: number;
+  /**
+   * If set, filesystem changes on this mount request inference.
+   * - `true` — wake on any op (created | modified | deleted)
+   * - array — wake only for the listed ops
+   *
+   * Self-writes through the module's own tools are already suppressed by the
+   * watcher, so a mount shared between agents only wakes on external writes.
+   * The EventGate still has final say — use gate policies for path-glob
+   * filtering or to disable wake temporarily via hot-reload.
+   */
+  wakeOnChange?: boolean | Array<'created' | 'modified' | 'deleted'>;
+
+  /**
+   * If true, writes/edits/deletes via the module's tools materialize to the
+   * filesystem immediately (not just into Chronicle tree state). Required for
+   * any mount shared across agents as a communication channel — without it,
+   * another agent's watcher on the same directory sees nothing. The watcher
+   * suppresses its own echoes, so this doesn't cause self-wake loops.
+   */
+  autoMaterialize?: boolean;
 }
 
 /**
@@ -175,14 +195,36 @@ export interface SyncInput {
 // Events
 // ============================================================================
 
-export interface WorkspaceChangedEvent {
-  type: 'workspace:changed';
+export type WorkspaceFsOp = 'created' | 'modified' | 'deleted';
+
+/**
+ * Fired when files in a mount are created. `paths` are mount-prefixed
+ * (e.g. "tickets/2026-04-20-foo.md"). Conflicts are reported when Chronicle
+ * sync detected divergence between the filesystem and the tree state.
+ */
+export interface WorkspaceCreatedEvent {
+  type: 'workspace:created';
   paths: string[];
   mount: string;
   conflicts?: string[];
   [key: string]: unknown;
 }
 
+export interface WorkspaceModifiedEvent {
+  type: 'workspace:modified';
+  paths: string[];
+  mount: string;
+  conflicts?: string[];
+  [key: string]: unknown;
+}
+
+export interface WorkspaceDeletedEvent {
+  type: 'workspace:deleted';
+  paths: string[];
+  mount: string;
+  [key: string]: unknown;
+}
+
 export interface WorkspaceMountedEvent {
   type: 'workspace:mounted';
   mount: string;
@@ -197,6 +239,20 @@ export interface WorkspaceUnmountedEvent {
 }
 
 export type WorkspaceEvent =
-  | WorkspaceChangedEvent
+  | WorkspaceCreatedEvent
+  | WorkspaceModifiedEvent
+  | WorkspaceDeletedEvent
   | WorkspaceMountedEvent
   | WorkspaceUnmountedEvent;
+
+export const WORKSPACE_FS_EVENT_TYPES = [
+  'workspace:created',
+  'workspace:modified',
+  'workspace:deleted',
+] as const;
+
+export type WorkspaceFsEventType = typeof WORKSPACE_FS_EVENT_TYPES[number];
+
+export function opToEventType(op: WorkspaceFsOp): WorkspaceFsEventType {
+  return `workspace:${op}` as WorkspaceFsEventType;
+}

package/src/modules/workspace/watcher.ts

@@ -1,12 +1,22 @@
 /**
  * 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 { 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;
 }
 
 /**
@@ -15,17 +25,19 @@ 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;
 
   constructor(
     config: MountConfig,
-    onChange: (paths: string[]) => void,
+    onChange: (changes: FsChange[]) => void,
   ) {
     this.config = config;
     this.debounceMs = config.watchDebounceMs ?? 300;
@@ -51,21 +63,22 @@ 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'));
   }
 
   /**
@@ -92,12 +105,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 +127,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 +172,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 & {

package/src/usage/index.ts

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