@animalabs/agent-framework 0.1.0 → 0.3.0

package/src/framework.ts

@@ -51,7 +51,10 @@ import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { safeSlice } from './safe-slice.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
+import { isToolAllowed } from './mcpl/tool-policy.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 +123,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 +214,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 +236,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 +323,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);
@@ -424,6 +474,16 @@ export class AgentFramework {
     this.traceListeners.push(listener);
   }
 
+  /**
+   * Public accessor for the MCPL channel registry.
+   * Null when no MCPL servers are configured.
+   * Modules that need channel-level operations (typing indicators, default publish channel,
+   * etc.) obtain them here.
+   */
+  get channels(): ChannelRegistry | null {
+    return this.channelRegistry;
+  }
+
   /**
    * Remove a trace event listener.
    */
@@ -530,6 +590,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 +1512,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 +1911,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 +1927,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 +2041,8 @@ export class AgentFramework {
               tokenUsage: {
                 input: event.usage.inputTokens,
                 output: event.usage.outputTokens,
+                cacheCreation: event.usage.cacheCreationTokens,
+                cacheRead: event.usage.cacheReadTokens,
               },
             });
             break;
@@ -2011,6 +2112,13 @@ export class AgentFramework {
     }
     const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
     const toolName = call.name.slice(prefix.length + 2); // Strip prefix + '--'
+    if (!isToolAllowed(toolName, config)) {
+      return {
+        success: false,
+        error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+        isError: true,
+      };
+    }
     try {
       const result = await server.sendToolsCall(toolName, call.input as Record<string, unknown>);
       return {
@@ -2367,10 +2475,10 @@ export class AgentFramework {
       (event) => this.pushEvent(event),
       (event) => this.emitTrace(event as { type: TraceEvent['type']; [key: string]: unknown }),
       {
-        sendTypingFn: (serverId, channelId) => {
+        sendTypingFn: (serverId, channelId, metadata, op) => {
           const server = this.mcplServerRegistry!.getServer(serverId);
           if (server) {
-            server.sendChannelsTyping(channelId);
+            server.sendChannelsTyping(channelId, metadata, op);
           }
         },
         shouldTriggerInference: triggerFilter,
@@ -2390,6 +2498,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
@@ -2451,6 +2565,12 @@ export class AgentFramework {
    * Push events and inference requests are deferred to Steps 6/7.
    */
   private wireMcplEvents(connection: McplServerConnection): void {
+    // Forward subprocess stderr lines as trace events so consumers (conhost,
+    // log sinks, TUI badges) can persist and surface them.
+    connection.on('stderr', (params: { line: string }) => {
+      this.emitTrace({ type: 'mcpl:server-stderr', serverId: connection.id, line: params.line });
+    });
+
     // Handle dynamic feature set changes from server
     connection.on('feature-sets-changed', (params: FeatureSetsChangedParams) => {
       this.featureSetManager?.handleFeatureSetsChanged(connection.id, params);
@@ -2548,6 +2668,7 @@ export class AgentFramework {
       try {
         const result = await server.sendToolsList();
         for (const tool of result.tools) {
+          if (!isToolAllowed(tool.name, config)) continue;
           // MCP tool schemas are generic JSON Schema; cast to membrane's ToolDefinition format
           const schema = tool.inputSchema as import('./types/index.js').ToolDefinition['inputSchema'];
           tools.push({
@@ -2637,6 +2758,23 @@ export class AgentFramework {
       return;
     }
 
+    const config = this.mcplServerConfigs.get(serverId);
+    if (!isToolAllowed(toolName, config)) {
+      this.emitTrace({ type: 'tool:failed', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, error: 'denied by tool policy' });
+      this.pushEvent({
+        type: 'tool-result',
+        callId: call.id,
+        agentName,
+        moduleName: `mcpl:${serverId}`,
+        result: {
+          success: false,
+          error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+          isError: true,
+        },
+      });
+      return;
+    }
+
     this.emitTrace({ type: 'tool:started', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, input: call.input });
     const startTime = Date.now();
     const args = (call.input && typeof call.input === 'object') ? call.input as Record<string, unknown> : {};

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,10 +52,17 @@ 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';
 
+// MCPL channel registry (exposed for modules that need channel-level operations)
+export { ChannelRegistry } from './mcpl/index.js';
+
 // Re-export commonly used types from dependencies
 export type { ContextManager, ContextStrategy, TokenBudget } from '@animalabs/context-manager';
 export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from '@animalabs/context-manager';