@animalabs/agent-framework 0.1.0 → 0.2.0

package/src/framework.ts

@@ -52,6 +52,8 @@ import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { safeSlice } from './safe-slice.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { EventGate } from './gate/event-gate.js';
+import { UsageTracker, type PersistedUsageState } from './usage/usage-tracker.js';
+import type { SessionUsageSnapshot, UsageUpdatedEvent } from './usage/types.js';
 import type { McplServerConnection } from './mcpl/server-connection.js';
 import type {
   McplServerConfig,
@@ -120,6 +122,44 @@ class DefaultErrorPolicy implements ErrorPolicy {
 /** Default sync interval in milliseconds */
 const DEFAULT_SYNC_INTERVAL_MS = 1000;
 
+/**
+ * Extract fields the EventGate cares about from a ProcessEvent. The set of
+ * event variants that carry `content`/`mount`/`paths`/`metadata` is open-ended
+ * (modules can define CustomEvents), so we read by name rather than match the
+ * discriminant. Centralizing this lets new gate-visible fields be added in one
+ * place instead of retyping the narrowing at every call site.
+ */
+function extractGateFields(event: ProcessEvent): {
+  content: string;
+  metadata: Record<string, unknown>;
+  mount?: string;
+  paths?: string[];
+} {
+  const rec = event as unknown as Record<string, unknown>;
+  const rawContent = rec.content;
+  let content = '';
+  if (typeof rawContent === 'string') {
+    content = rawContent;
+  } else if (Array.isArray(rawContent)) {
+    // ContentBlock[] — concatenate text blocks so gate content filters match
+    content = rawContent
+      .filter((b): b is { type: 'text'; text: string } =>
+        !!b && typeof b === 'object' && (b as { type?: unknown }).type === 'text'
+        && typeof (b as { text?: unknown }).text === 'string'
+      )
+      .map(b => b.text)
+      .join('\n');
+  }
+  const metadata = (rec.metadata && typeof rec.metadata === 'object')
+    ? rec.metadata as Record<string, unknown>
+    : {};
+  const mount = typeof rec.mount === 'string' ? rec.mount : undefined;
+  const paths = Array.isArray(rec.paths)
+    ? rec.paths.filter((p): p is string => typeof p === 'string')
+    : undefined;
+  return { content, metadata, mount, paths };
+}
+
 /**
  * The main agent framework.
  */
@@ -173,6 +213,9 @@ export class AgentFramework {
   // EventGate (null when FrameworkConfig.gate is omitted)
   private eventGate: EventGate | null = null;
 
+  // Session-level token usage tracking (always-on)
+  private usageTracker: UsageTracker;
+
   private constructor(
     store: JsStore,
     ownsStore: boolean,
@@ -192,6 +235,9 @@ export class AgentFramework {
     this.processLoggingPersist = processLoggingPersist;
     this.processLoggingBroadcast = processLoggingBroadcast;
     this.queue = new ProcessQueueImpl();
+    this.usageTracker = new UsageTracker({
+      emitTrace: (e: UsageUpdatedEvent) => this.emitTrace({ ...e }),
+    });
 
     // Initialize module registry with callbacks
     this.moduleRegistry = new ModuleRegistry(store, this.queue, {
@@ -276,6 +322,9 @@ export class AgentFramework {
       processLoggingBroadcast
     );
 
+    // Restore persisted usage data (if any) from prior session
+    framework.restoreUsageState();
+
     // Create agents
     for (const agentConfig of config.agents) {
       await framework.createAgent(agentConfig);
@@ -530,6 +579,36 @@ export class AgentFramework {
     return this.membrane;
   }
 
+  getSessionUsage(): SessionUsageSnapshot {
+    return this.usageTracker.getSnapshot();
+  }
+
+  private restoreUsageState(): void {
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+      if (data && typeof data === 'object' && (data as any).usage) {
+        const restored = (data as any).usage as PersistedUsageState;
+        this.usageTracker = new UsageTracker({
+          emitTrace: (e: UsageUpdatedEvent) => this.emitTrace({ ...e }),
+          restored,
+        });
+      }
+    } catch {
+      // No prior state or corrupt — start fresh (already initialized in constructor)
+    }
+  }
+
+  private persistUsageState(): void {
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+      const state = (data && typeof data === 'object' ? data : {}) as Record<string, unknown>;
+      state.usage = this.usageTracker.toJSON();
+      this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+    } catch {
+      // Non-fatal — usage tracking is best-effort
+    }
+  }
+
   /**
    * Create an ephemeral agent that is NOT registered in the main event loop.
    *
@@ -1422,13 +1501,11 @@ export class AgentFramework {
 
       // Gate non-MCPL events (MCPL events are already gated in PushHandler/ChannelRegistry)
       if (this.eventGate && event.type !== 'mcpl:push-event' && event.type !== 'mcpl:channel-incoming') {
-        const content = 'content' in event ? String((event as { content: unknown }).content) : '';
         const decision = this.eventGate.evaluate({
-          content,
+          ...extractGateFields(event),
           eventType: event.type,
           serverId: source,
           channelId: '',
-          metadata: 'metadata' in event ? (event as { metadata: Record<string, unknown> }).metadata : {},
         });
         if (!decision.trigger) return;
       }
@@ -1823,12 +1900,13 @@ export class AgentFramework {
             const speechContent = hadToolCalls ? [] : allText;
             const thoughts = hadToolCalls ? allText : [];
 
-            const tokenUsage = response.usage
+            const du = response.details?.usage;
+            const tokenUsage = du
               ? {
-                  input: response.usage.inputTokens,
-                  output: response.usage.outputTokens,
-                  cacheCreation: response.details?.usage?.cacheCreationTokens,
-                  cacheRead: response.details?.usage?.cacheReadTokens,
+                  input: du.inputTokens,
+                  output: du.outputTokens,
+                  cacheCreation: du.cacheCreationTokens,
+                  cacheRead: du.cacheReadTokens,
                 }
               : undefined;
             this.emitTrace({
@@ -1838,6 +1916,16 @@ export class AgentFramework {
               tokenUsage,
             });
 
+            if (du) {
+              this.usageTracker.onInferenceCompleted(agent.name, {
+                inputTokens: du.inputTokens,
+                outputTokens: du.outputTokens,
+                cacheCreationTokens: du.cacheCreationTokens,
+                cacheReadTokens: du.cacheReadTokens,
+              }, du.estimatedCost ? { total: du.estimatedCost.total, currency: du.estimatedCost.currency } : undefined);
+              this.persistUsageState();
+            }
+
             // Log inference
             this.logInference({
               timestamp: startTime,
@@ -1942,6 +2030,8 @@ export class AgentFramework {
               tokenUsage: {
                 input: event.usage.inputTokens,
                 output: event.usage.outputTokens,
+                cacheCreation: event.usage.cacheCreationTokens,
+                cacheRead: event.usage.cacheReadTokens,
               },
             });
             break;
@@ -2390,6 +2480,12 @@ export class AgentFramework {
 
     for (const config of serverConfigs) {
       try {
+        // Record per-server channel subscription policy before the server
+        // registers channels — handleRegister fires during the handshake.
+        if (config.channelSubscription !== undefined && this.channelRegistry) {
+          this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription);
+        }
+
         const connection = await this.mcplServerRegistry.addServer(config, hostCapabilities);
 
         // Wire event listeners then flush any events that arrived during the

package/src/gate/event-gate.ts

@@ -76,6 +76,8 @@ interface CompiledPolicy {
   filterRegex?: RegExp;
   sourceRegex?: RegExp;
   channelRegex?: RegExp;
+  mountRegex?: RegExp;
+  pathRegex?: RegExp;
 }
 
 interface PolicyStats {
@@ -170,6 +172,8 @@ function validatePolicy(raw: unknown): GatePolicy {
     if (Array.isArray(m.scope)) match.scope = m.scope.filter(s => typeof s === 'string');
     if (typeof m.source === 'string') match.source = m.source;
     if (typeof m.channel === 'string') match.channel = m.channel;
+    if (typeof m.mount === 'string') match.mount = m.mount;
+    if (typeof m.pathGlob === 'string') match.pathGlob = m.pathGlob;
     if (m.filter && typeof m.filter === 'object') {
       const f = m.filter as Record<string, unknown>;
       if ((f.type === 'text' || f.type === 'regex') && typeof f.pattern === 'string') {
@@ -210,6 +214,12 @@ export class EventGate {
   // Per-policy stats
   private stats = new Map<string, PolicyStats>();
 
+  // Observability counters for events that didn't match any policy
+  private totalEvaluations = 0;
+  private defaultTriggered = 0;
+  private defaultSkipped = 0;
+  private defaultByEventType = new Map<string, { triggered: number; skipped: number }>();
+
   // Dependency-injected callbacks
   private emitTrace: (event: TraceEventLike) => void;
   private addMessageFn: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
@@ -230,13 +240,44 @@ export class EventGate {
     this.requestInferenceFn = opts.requestInference;
     this.getAgentNamesFn = opts.getAgentNames;
 
-    // Seed config file if it doesn't exist
-    if (opts.initialConfig && !existsSync(this.configPath)) {
+    // Seed or reconcile the on-disk config.
+    //
+    // First start: write `initialConfig` verbatim.
+    // Subsequent starts: if the recipe/config source declares policies that
+    // aren't yet in gate.json (e.g. the user edited the recipe between
+    // sessions), append them by name. Existing policies are left alone so
+    // user edits via `workspace--edit _config/gate.json` survive.
+    // The `default` field is not reconciled — it's an explicit operator
+    // choice and a recipe change shouldn't silently flip live wake
+    // behavior for a session that's already been running.
+    if (opts.initialConfig) {
       try {
         mkdirSync(dirname(this.configPath), { recursive: true });
-        writeFileSync(this.configPath, JSON.stringify(opts.initialConfig, null, 2) + '\n');
+        if (!existsSync(this.configPath)) {
+          writeFileSync(this.configPath, JSON.stringify(opts.initialConfig, null, 2) + '\n');
+        } else {
+          const existing = this.loadConfig();
+          if (existing) {
+            const existingNames = new Set(existing.policies.map(p => p.name));
+            const missing = opts.initialConfig.policies.filter(p => !existingNames.has(p.name));
+            if (missing.length > 0) {
+              const reconciled: GateConfig = {
+                ...existing,
+                policies: [...existing.policies, ...missing],
+              };
+              writeFileSync(this.configPath, JSON.stringify(reconciled, null, 2) + '\n');
+              opts.emitTrace({
+                type: 'gate:config-reconciled',
+                configPath: this.configPath,
+                addedPolicies: missing.map(p => p.name),
+                timestamp: Date.now(),
+              });
+            }
+          }
+        }
       } catch (err) {
-        this.configErrors.push(`Failed to seed gate.json: ${err}`);
+        const msg = err instanceof Error ? err.message : String(err);
+        this.configErrors.push(`Failed to seed/reconcile gate.json: ${msg}`);
       }
     }
 
@@ -286,6 +327,12 @@ export class EventGate {
       if (policy.match.channel) {
         compiled.channelRegex = compileGlob(policy.match.channel);
       }
+      if (policy.match.mount) {
+        compiled.mountRegex = compileGlob(policy.match.mount);
+      }
+      if (policy.match.pathGlob) {
+        compiled.pathRegex = compileGlob(policy.match.pathGlob);
+      }
       return compiled;
     });
   }
@@ -368,6 +415,21 @@ export class EventGate {
       return false;
     }
 
+    // Mount check (workspace fs events)
+    if (compiled.mountRegex) {
+      if (!info.mount || !compiled.mountRegex.test(info.mount)) {
+        return false;
+      }
+    }
+
+    // Path glob check — matches if ANY path matches
+    if (compiled.pathRegex) {
+      const paths = info.paths;
+      if (!paths || paths.length === 0) return false;
+      const anyMatch = paths.some(p => compiled.pathRegex!.test(p));
+      if (!anyMatch) return false;
+    }
+
     // Content filter check
     if (match.filter) {
       if (match.filter.type === 'text') {
@@ -394,9 +456,38 @@ export class EventGate {
     this.reloadIfChanged();
 
     const policy = this.matchPolicy(info);
+    const decision = this.computeDecision(policy, info);
+
+    this.totalEvaluations++;
+    if (!policy) {
+      const bucket = this.defaultByEventType.get(info.eventType)
+        ?? { triggered: 0, skipped: 0 };
+      if (decision.trigger) {
+        this.defaultTriggered++;
+        bucket.triggered++;
+      } else {
+        this.defaultSkipped++;
+        bucket.skipped++;
+      }
+      this.defaultByEventType.set(info.eventType, bucket);
+    }
+
+    this.emitTrace({
+      type: 'gate:decision',
+      eventType: info.eventType,
+      serverId: info.serverId || undefined,
+      channelId: info.channelId || undefined,
+      matchedPolicy: decision.policyName,
+      trigger: decision.trigger,
+      behavior: typeof decision.behavior === 'object' ? `debounce:${decision.behavior.debounce}` : decision.behavior,
+      timestamp: Date.now(),
+    });
+
+    return decision;
+  }
 
+  private computeDecision(policy: GatePolicy | null, info: GateEventInfo): GateDecision {
     if (!policy) {
-      // No policy matched — use default
       const trigger = (this.config.default ?? 'always') === 'always';
       return { trigger, policyName: null, behavior: this.config.default ?? 'always' };
     }
@@ -407,7 +498,7 @@ export class EventGate {
     policyStats.lastMatchTimestamp = Date.now();
     this.stats.set(policy.name, policyStats);
 
-    // Emit trace
+    // Legacy trace kept for backward compatibility with existing consumers.
     this.emitTrace({
       type: 'gate:policy-matched',
       policyName: policy.name,
@@ -599,6 +690,9 @@ export class EventGate {
       return result;
     });
 
+    const byEventType: Record<string, { triggered: number; skipped: number }> = {};
+    for (const [k, v] of this.defaultByEventType) byEventType[k] = { ...v };
+
     return {
       configPath: this.configPath,
       configSource: this.configSource,
@@ -606,6 +700,12 @@ export class EventGate {
       default: this.config.default ?? 'always',
       policies,
       errors: [...this.configErrors],
+      totalEvaluations: this.totalEvaluations,
+      defaultDecisions: {
+        triggered: this.defaultTriggered,
+        skipped: this.defaultSkipped,
+        byEventType,
+      },
     };
   }
 

package/src/gate/types.ts

@@ -30,6 +30,16 @@ export interface GatePolicyMatch {
   channel?: string;
   /** Content text filter. */
   filter?: { type: 'text' | 'regex'; pattern: string };
+  /**
+   * Mount name to match (exact or glob with *). Populated for workspace
+   * filesystem events (workspace:created/modified/deleted).
+   */
+  mount?: string;
+  /**
+   * Glob applied against each path in the event. Matches if ANY path matches.
+   * Supports `*` wildcard; not full gitignore syntax.
+   */
+  pathGlob?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -87,6 +97,10 @@ export interface GateEventInfo {
   serverId: string;
   channelId: string;
   metadata?: Record<string, unknown>;
+  /** Workspace mount name (for workspace:* events). */
+  mount?: string;
+  /** Mount-prefixed paths touched (for workspace:* events). */
+  paths?: string[];
 }
 
 /** Per-policy runtime statistics (for gate:status). */
@@ -109,4 +123,18 @@ export interface GateStatus {
   default: 'always' | 'skip';
   policies: GatePolicyStats[];
   errors: string[];
+  /** Total events the gate has evaluated since startup. */
+  totalEvaluations: number;
+  /**
+   * Count of events that fell through to `default` (no policy matched),
+   * broken down by whether they triggered or were skipped. Useful for
+   * spotting events that are arriving but silently dropped — if a policy
+   * appears to never fire (matchCount 0) and this count is growing for the
+   * same eventType, the event is reaching the gate but being dropped.
+   */
+  defaultDecisions: {
+    triggered: number;
+    skipped: number;
+    byEventType: Record<string, { triggered: number; skipped: number }>;
+  };
 }

package/src/index.ts

@@ -52,6 +52,10 @@ export type {
 // Note: AgentInfo, MessageEditedEvent, MessageRemovedEvent intentionally not re-exported
 // from api/types.js to avoid conflicts with ./types/index.js
 
+// Usage tracking
+export { UsageTracker } from './usage/index.js';
+export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
+
 // EventGate
 export { EventGate } from './gate/index.js';
 export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior } from './gate/index.js';

package/src/mcpl/channel-registry.ts

@@ -195,6 +195,13 @@ export class ChannelRegistry {
   /** Per-channel typing indicator timers. */
   private typingIntervals = new Map<string, ReturnType<typeof setInterval>>();
 
+  /**
+   * Per-server channel auto-open policy. Populated by the framework from
+   * each McplServerConfig at connect time; default ('auto') applies when
+   * unset.
+   */
+  private subscriptionPolicies = new Map<string, 'auto' | 'manual' | string[]>();
+
   constructor(
     serverRegistry: McplServerRegistry,
     featureSetManager: FeatureSetManager,
@@ -212,6 +219,14 @@ export class ChannelRegistry {
     this.shouldTriggerInference = options?.shouldTriggerInference;
   }
 
+  /**
+   * Set the channel auto-open policy for a server. Called by the framework
+   * when each MCPL server is registered.
+   */
+  setSubscriptionPolicy(serverId: string, policy: 'auto' | 'manual' | string[]): void {
+    this.subscriptionPolicies.set(serverId, policy);
+  }
+
   // ==========================================================================
   // Handler Methods (called from framework.ts wireMcplEvents)
   // ==========================================================================
@@ -339,7 +354,7 @@ export class ChannelRegistry {
           textContent,
           {
             ...message.metadata,
-            eventType: 'channel:incoming',
+            eventType: 'mcpl:channel-incoming',
             serverId,
             channelId: message.channelId,
             messageId: message.messageId,
@@ -574,7 +589,23 @@ export class ChannelRegistry {
     const server = this.serverRegistry.getServer(serverId);
     if (!server) return;
 
+    const policy = this.subscriptionPolicies.get(serverId) ?? 'auto';
+    if (policy === 'manual') {
+      this.emitTraceFn({
+        type: 'mcpl:channels-auto-open-skipped',
+        serverId,
+        reason: 'manual',
+        count: channels.length,
+      });
+      return;
+    }
+
+    const allowList = Array.isArray(policy) ? new Set(policy) : null;
+    let opened = 0;
+
     for (const channel of channels) {
+      if (allowList && !allowList.has(channel.id)) continue;
+
       const key = `${serverId}:${channel.id}`;
       try {
         await server.sendChannelsOpen({
@@ -585,6 +616,7 @@ export class ChannelRegistry {
         if (entry) {
           entry.open = true;
         }
+        opened++;
       } catch (err) {
         this.emitTraceFn({
           type: 'mcpl:channel-open-failed',
@@ -594,6 +626,18 @@ export class ChannelRegistry {
         });
       }
     }
+
+    // Surface the common typo failure mode: allow-list set but nothing
+    // matched. Without this trace a one-char typo in a channel id looks
+    // identical to "MCPL didn't register the channel".
+    if (allowList && opened === 0 && channels.length > 0) {
+      this.emitTraceFn({
+        type: 'mcpl:channels-allow-list-empty',
+        serverId,
+        allowList: [...allowList],
+        registered: channels.map(c => c.id),
+      });
+    }
   }
 
   // ==========================================================================

package/src/mcpl/push-handler.ts

@@ -195,7 +195,7 @@ export class PushHandler {
         serverId,
         featureSet: params.featureSet,
         eventId: params.eventId,
-        eventType: 'push:event',
+        eventType: 'mcpl:push-event',
         ...(params.origin ?? {}),
       };
       triggerInference = this.shouldTriggerInference(textContent, metadata);

package/src/mcpl/types.ts

@@ -222,6 +222,22 @@ export interface McplServerConfig {
    * Must not collide with any module name or another server's prefix.
    */
   toolPrefix?: string;
+
+  /**
+   * How channels registered by this server are opened.
+   * - `'auto'` (default) — every registered channel is auto-opened; the host
+   *   receives all traffic. Matches prior behavior. Right for agents that
+   *   should listen passively (e.g. a frontdesk clerk).
+   * - `'manual'` — registered channels are listed but not opened. The agent
+   *   must call the `channel_open` tool to start receiving messages. Right
+   *   for focused agents that should not be flooded with chatter from
+   *   servers that advertise many public channels (e.g. Zulip's full stream
+   *   list).
+   * - `string[]` — allow-list of channel ids; only matching channels are
+   *   auto-opened. Ids are server-scoped (the raw id the server registers,
+   *   e.g. `"zulip:tracker-miner-f"`).
+   */
+  channelSubscription?: 'auto' | 'manual' | string[];
 }
 
 // ============================================================================