@animalabs/agent-framework 0.1.0 → 0.3.0

package/dist/src/framework.d.ts

@@ -3,6 +3,8 @@ import type { Membrane } from '@animalabs/membrane';
 import { ContextManager } from '@animalabs/context-manager';
 import type { FrameworkConfig, TraceEventListener, InferenceLogQuery, InferenceLogQueryResult, InferenceLogEntryWithId, ProcessLogQuery, ProcessLogQueryResult, ProcessLogEntryWithId, ProcessEvent, ToolCall, ToolResult, AgentConfig, Module } from './types/index.js';
 import { Agent } from './agent.js';
+import { ChannelRegistry } from './mcpl/channel-registry.js';
+import type { SessionUsageSnapshot } from './usage/types.js';
 /**
  * The main agent framework.
  */
@@ -46,6 +48,7 @@ export declare class AgentFramework {
     /** Maps serverId → McplServerConfig for prefix lookup. */
     private mcplServerConfigs;
     private eventGate;
+    private usageTracker;
     private constructor();
     /**
      * Create and start the framework.
@@ -67,6 +70,13 @@ export declare class AgentFramework {
      * Add a trace event listener for observability.
      */
     onTrace(listener: TraceEventListener): void;
+    /**
+     * 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;
     /**
      * Remove a trace event listener.
      */
@@ -118,6 +128,9 @@ export declare class AgentFramework {
      * Get the Membrane instance.
      */
     getMembrane(): Membrane;
+    getSessionUsage(): SessionUsageSnapshot;
+    private restoreUsageState;
+    private persistUsageState;
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *

package/dist/src/framework.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"framework.d.ts","sourceRoot":"","sources":["../../src/framework.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"framework.d.ts","sourceRoot":"","sources":["../../src/framework.ts"],"names":[],"mappings":"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"}

package/dist/src/framework.js

@@ -13,7 +13,9 @@ 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 } from './usage/usage-tracker.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
@@ -42,6 +44,37 @@ class DefaultErrorPolicy {
 }
 /** 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) {
+    const rec = event;
+    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 && typeof b === 'object' && b.type === 'text'
+            && typeof b.text === 'string')
+            .map(b => b.text)
+            .join('\n');
+    }
+    const metadata = (rec.metadata && typeof rec.metadata === 'object')
+        ? rec.metadata
+        : {};
+    const mount = typeof rec.mount === 'string' ? rec.mount : undefined;
+    const paths = Array.isArray(rec.paths)
+        ? rec.paths.filter((p) => typeof p === 'string')
+        : undefined;
+    return { content, metadata, mount, paths };
+}
 /**
  * The main agent framework.
  */
@@ -90,6 +123,8 @@ export class AgentFramework {
     mcplServerConfigs = new Map();
     // EventGate (null when FrameworkConfig.gate is omitted)
     eventGate = null;
+    // Session-level token usage tracking (always-on)
+    usageTracker;
     constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, processLoggingPersist, processLoggingBroadcast) {
         this.store = store;
         this.ownsStore = ownsStore;
@@ -100,6 +135,9 @@ export class AgentFramework {
         this.processLoggingPersist = processLoggingPersist;
         this.processLoggingBroadcast = processLoggingBroadcast;
         this.queue = new ProcessQueueImpl();
+        this.usageTracker = new UsageTracker({
+            emitTrace: (e) => this.emitTrace({ ...e }),
+        });
         // Initialize module registry with callbacks
         this.moduleRegistry = new ModuleRegistry(store, this.queue, {
             getAgents: () => Array.from(this.agents.values()),
@@ -171,6 +209,8 @@ export class AgentFramework {
             }
         }
         const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast);
+        // Restore persisted usage data (if any) from prior session
+        framework.restoreUsageState();
         // Create agents
         for (const agentConfig of config.agents) {
             await framework.createAgent(agentConfig);
@@ -296,6 +336,15 @@ export class AgentFramework {
     onTrace(listener) {
         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() {
+        return this.channelRegistry;
+    }
     /**
      * Remove a trace event listener.
      */
@@ -390,6 +439,35 @@ export class AgentFramework {
     getMembrane() {
         return this.membrane;
     }
+    getSessionUsage() {
+        return this.usageTracker.getSnapshot();
+    }
+    restoreUsageState() {
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            if (data && typeof data === 'object' && data.usage) {
+                const restored = data.usage;
+                this.usageTracker = new UsageTracker({
+                    emitTrace: (e) => this.emitTrace({ ...e }),
+                    restored,
+                });
+            }
+        }
+        catch {
+            // No prior state or corrupt — start fresh (already initialized in constructor)
+        }
+    }
+    persistUsageState() {
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const state = (data && typeof data === 'object' ? data : {});
+            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.
      *
@@ -1141,13 +1219,11 @@ export class AgentFramework {
             const source = 'source' in event ? event.source : 'unknown';
             // 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.content) : '';
                 const decision = this.eventGate.evaluate({
-                    content,
+                    ...extractGateFields(event),
                     eventType: event.type,
                     serverId: source,
                     channelId: '',
-                    metadata: 'metadata' in event ? event.metadata : {},
                 });
                 if (!decision.trigger)
                     return;
@@ -1483,12 +1559,13 @@ export class AgentFramework {
                         const allText = response.content.filter(isTextBlock);
                         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({
@@ -1497,6 +1574,15 @@ export class AgentFramework {
                             durationMs,
                             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,
@@ -1590,6 +1676,8 @@ export class AgentFramework {
                             tokenUsage: {
                                 input: event.usage.inputTokens,
                                 output: event.usage.outputTokens,
+                                cacheCreation: event.usage.cacheCreationTokens,
+                                cacheRead: event.usage.cacheReadTokens,
                             },
                         });
                         break;
@@ -1657,6 +1745,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);
             return {
@@ -1948,10 +2043,10 @@ export class AgentFramework {
         this.checkpointManager = new CheckpointManager(this.store, (event) => this.emitTrace(event));
         // Channel registry (Step 7)
         this.channelRegistry = new ChannelRegistry(this.mcplServerRegistry, this.featureSetManager, (event) => this.pushEvent(event), (event) => this.emitTrace(event), {
-            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,
@@ -1968,6 +2063,11 @@ 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
                 // handshake window (between setupMessageRouting and now).
@@ -2018,6 +2118,11 @@ export class AgentFramework {
      * Push events and inference requests are deferred to Steps 6/7.
      */
     wireMcplEvents(connection) {
+        // Forward subprocess stderr lines as trace events so consumers (conhost,
+        // log sinks, TUI badges) can persist and surface them.
+        connection.on('stderr', (params) => {
+            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) => {
             this.featureSetManager?.handleFeatureSetsChanged(connection.id, params);
@@ -2090,6 +2195,8 @@ 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;
                     tools.push({
@@ -2170,6 +2277,22 @@ 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 : {};