@animalabs/agent-framework 0.1.0

package/dist/src/types/trace.d.ts

@@ -0,0 +1,173 @@
+import type { ProcessEvent } from './events.js';
+import type { ModuleProcessResponse } from './framework.js';
+/**
+ * Base for all trace events.
+ * TraceEvents are observability-only — they NEVER drive logic.
+ */
+export interface TraceEventBase {
+    /** When this trace was emitted */
+    timestamp: number;
+    /** Optional correlation ID for distributed tracing */
+    traceId?: string;
+}
+/**
+ * Observability events emitted by the framework.
+ * Subscribe via framework.onTrace() to monitor system behavior.
+ *
+ * These are purely informational — use them for:
+ * - UI updates (showing inference progress, tool execution)
+ * - Logging and debugging
+ * - Metrics and monitoring
+ * - Broadcasting to WebSocket clients
+ *
+ * They should NEVER be used to drive application logic.
+ * For that, use ProcessEvent via the event queue.
+ */
+export type TraceEvent = (TraceEventBase & {
+    type: 'process:received';
+    processEvent: ProcessEvent;
+}) | (TraceEventBase & {
+    type: 'process:completed';
+    processEvent: ProcessEvent;
+    responses: ModuleProcessResponse[];
+    durationMs: number;
+}) | (TraceEventBase & {
+    type: 'inference:started';
+    agentName: string;
+}) | (TraceEventBase & {
+    type: 'inference:completed';
+    agentName: string;
+    durationMs: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        cacheCreation?: number;
+        cacheRead?: number;
+    };
+}) | (TraceEventBase & {
+    type: 'inference:aborted';
+    agentName: string;
+    durationMs: number;
+    reason?: string;
+}) | (TraceEventBase & {
+    type: 'inference:failed';
+    agentName: string;
+    error: string;
+    stack?: string;
+}) | (TraceEventBase & {
+    type: 'inference:exhausted';
+    agentName: string;
+    error: string;
+}) | (TraceEventBase & {
+    type: 'inference:tokens';
+    agentName: string;
+    content: string;
+}) | (TraceEventBase & {
+    type: 'inference:tool_calls_yielded';
+    agentName: string;
+    calls: Array<{
+        id: string;
+        name: string;
+        input?: unknown;
+    }>;
+}) | (TraceEventBase & {
+    type: 'inference:usage';
+    agentName: string;
+    tokenUsage: {
+        input: number;
+        output: number;
+    };
+}) | (TraceEventBase & {
+    type: 'inference:stream_resumed';
+    agentName: string;
+}) | (TraceEventBase & {
+    type: 'inference:stream_restarted';
+    agentName: string;
+    reason: string;
+    inputTokens: number;
+    budget: number;
+}) | (TraceEventBase & {
+    type: 'inference:turn_ended';
+    agentName: string;
+}) | (TraceEventBase & {
+    type: 'tool:started';
+    module: string;
+    tool: string;
+    callId: string;
+    input?: unknown;
+}) | (TraceEventBase & {
+    type: 'tool:completed';
+    module: string;
+    tool: string;
+    callId: string;
+    durationMs: number;
+}) | (TraceEventBase & {
+    type: 'tool:failed';
+    module: string;
+    tool: string;
+    callId: string;
+    error: string;
+    stack?: string;
+}) | (TraceEventBase & {
+    type: 'tool:result_dropped';
+    agentName: string;
+    callId: string;
+    agentStatus: string;
+    result: unknown;
+}) | (TraceEventBase & {
+    type: 'module:added';
+    moduleName: string;
+}) | (TraceEventBase & {
+    type: 'module:removed';
+    moduleName: string;
+}) | (TraceEventBase & {
+    type: 'inference:request_dropped';
+    agentName: string;
+    reason: string;
+    requestCount: number;
+    oldestRequestAge: number;
+}) | (TraceEventBase & {
+    type: 'inference:request_stale';
+    agentName: string;
+    agentStatus: string;
+    requestCount: number;
+    oldestRequestAge: number;
+}) | (TraceEventBase & {
+    type: 'message:added';
+    messageId: string;
+    source: string;
+}) | (TraceEventBase & {
+    type: 'gate:policy-matched';
+    policyName: string;
+    behavior: string;
+    eventType: string;
+    source?: string;
+}) | (TraceEventBase & {
+    type: 'gate:config-error';
+    error: string;
+    configPath: string;
+}) | (TraceEventBase & {
+    type: 'gate:debounce-delivered';
+    policyName: string;
+    eventCount: number;
+}) | (TraceEventBase & {
+    type: 'gate:config-reloaded';
+    configPath: string;
+    policyCount: number;
+}) | (TraceEventBase & {
+    type: 'undo:completed';
+    agentName: string;
+    turnIndex: number;
+    fromBranch: string;
+    toBranch: string;
+}) | (TraceEventBase & {
+    type: 'redo:completed';
+    agentName: string;
+    fromBranch: string;
+    toBranch: string;
+});
+/**
+ * Listener for trace events.
+ */
+export type TraceEventListener = (event: TraceEvent) => void;
+//# sourceMappingURL=trace.d.ts.map

package/dist/src/types/trace.d.ts.map

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

package/dist/src/types/trace.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trace.js.map

package/dist/src/types/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../../src/types/trace.ts"],"names":[],"mappings":""}

package/dist/test/event-gate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-gate.test.d.ts.map

package/dist/test/event-gate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-gate.test.d.ts","sourceRoot":"","sources":["../../test/event-gate.test.ts"],"names":[],"mappings":""}