@animalabs/agent-framework 0.1.0

package/dist/src/modules/workspace/watcher.js

@@ -0,0 +1,120 @@
+/**
+ * Filesystem watcher with debounce, ignore patterns, and suppression.
+ */
+import { watch } from 'chokidar';
+/**
+ * Manages filesystem watching for a single mount.
+ * Handles debouncing, ignore patterns, and write suppression.
+ */
+export class MountWatcher {
+    watcher = null;
+    pendingChanges = new Set();
+    debounceTimer = null;
+    suppressedPaths = new Set();
+    suppressionTimers = new Map();
+    debounceMs;
+    config;
+    onChangeCallback;
+    constructor(config, onChange) {
+        this.config = config;
+        this.debounceMs = config.watchDebounceMs ?? 300;
+        this.onChangeCallback = onChange;
+    }
+    /**
+     * Start watching the filesystem.
+     */
+    start() {
+        if (this.watcher)
+            return;
+        const ignored = this.config.ignore ?? [];
+        this.watcher = watch(this.config.path, {
+            ignored: ignored.length > 0 ? ignored : undefined,
+            persistent: true,
+            ignoreInitial: true,
+            followSymlinks: this.config.followSymlinks ?? false,
+            awaitWriteFinish: {
+                stabilityThreshold: 100,
+                pollInterval: 50,
+            },
+        });
+        const handleEvent = (filePath) => {
+            // Convert absolute path to mount-relative
+            const relative = this.toRelative(filePath);
+            if (!relative)
+                return;
+            // Skip if this path is suppressed (we just wrote it)
+            if (this.suppressedPaths.has(relative))
+                return;
+            this.pendingChanges.add(relative);
+            this.scheduleFire();
+        };
+        this.watcher.on('add', handleEvent);
+        this.watcher.on('change', handleEvent);
+        this.watcher.on('unlink', handleEvent);
+    }
+    /**
+     * Stop watching.
+     */
+    async stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        for (const timer of this.suppressionTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.suppressionTimers.clear();
+        this.suppressedPaths.clear();
+        this.pendingChanges.clear();
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /**
+     * 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, cooldownMs = 500) {
+        this.suppressedPaths.add(relativePath);
+        // Clear existing timer for this path
+        const existing = this.suppressionTimers.get(relativePath);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.suppressedPaths.delete(relativePath);
+            this.suppressionTimers.delete(relativePath);
+        }, cooldownMs);
+        this.suppressionTimers.set(relativePath, timer);
+    }
+    /**
+     * Check if a path is currently suppressed.
+     */
+    isSuppressed(relativePath) {
+        return this.suppressedPaths.has(relativePath);
+    }
+    scheduleFire() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            if (this.pendingChanges.size > 0) {
+                const paths = [...this.pendingChanges];
+                this.pendingChanges.clear();
+                this.onChangeCallback(paths);
+            }
+        }, this.debounceMs);
+    }
+    toRelative(absolutePath) {
+        const base = this.config.path.endsWith('/')
+            ? this.config.path
+            : this.config.path + '/';
+        if (absolutePath.startsWith(base)) {
+            return absolutePath.slice(base.length);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=watcher.js.map

package/dist/src/modules/workspace/watcher.js.map

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

package/dist/src/queue.d.ts

@@ -0,0 +1,50 @@
+import type { ProcessEvent, ProcessQueue } from './types/index.js';
+/**
+ * Process queue for the framework.
+ * ProcessEvents from external sources and internal operations flow through here.
+ */
+export declare class ProcessQueueImpl implements ProcessQueue {
+    private queue;
+    private waiters;
+    private closed;
+    /**
+     * Push a process event to the queue.
+     */
+    push(event: ProcessEvent): void;
+    /**
+     * Pop the next process event from the queue.
+     * Returns immediately if an event is available, otherwise waits.
+     */
+    pop(): Promise<ProcessEvent>;
+    /**
+     * Try to pop a process event without waiting.
+     * Returns null if queue is empty.
+     */
+    tryPop(): ProcessEvent | null;
+    /**
+     * Peek at the next process event without removing it.
+     */
+    peek(): ProcessEvent | null;
+    /**
+     * Get current queue depth.
+     */
+    get depth(): number;
+    /**
+     * Check if queue is empty.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Clear all events from the queue.
+     */
+    clear(): void;
+    /**
+     * Close the queue.
+     * Rejects any pending waiters.
+     */
+    close(): void;
+    /**
+     * Check if queue is closed.
+     */
+    get isClosed(): boolean;
+}
+//# sourceMappingURL=queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,MAAM,CAAS;IAEvB;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAiB/B;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC;IAiBlC;;;OAGG;IACH,MAAM,IAAI,YAAY,GAAG,IAAI;IAI7B;;OAEG;IACH,IAAI,IAAI,YAAY,GAAG,IAAI;IAI3B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}

package/dist/src/queue.js

@@ -0,0 +1,95 @@
+/**
+ * Process queue for the framework.
+ * ProcessEvents from external sources and internal operations flow through here.
+ */
+export class ProcessQueueImpl {
+    queue = [];
+    waiters = [];
+    closed = false;
+    /**
+     * Push a process event to the queue.
+     */
+    push(event) {
+        if (this.closed) {
+            throw new Error('Queue is closed');
+        }
+        // If someone is waiting, deliver immediately
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter(event);
+        }
+        else if (event.type === 'external-message') {
+            // User input jumps to front so it's processed before queued internal events
+            this.queue.unshift(event);
+        }
+        else {
+            this.queue.push(event);
+        }
+    }
+    /**
+     * Pop the next process event from the queue.
+     * Returns immediately if an event is available, otherwise waits.
+     */
+    async pop() {
+        if (this.closed) {
+            throw new Error('Queue is closed');
+        }
+        // If there's an event waiting, return it
+        const event = this.queue.shift();
+        if (event) {
+            return event;
+        }
+        // Otherwise, wait for one
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    /**
+     * Try to pop a process event without waiting.
+     * Returns null if queue is empty.
+     */
+    tryPop() {
+        return this.queue.shift() ?? null;
+    }
+    /**
+     * Peek at the next process event without removing it.
+     */
+    peek() {
+        return this.queue[0] ?? null;
+    }
+    /**
+     * Get current queue depth.
+     */
+    get depth() {
+        return this.queue.length;
+    }
+    /**
+     * Check if queue is empty.
+     */
+    get isEmpty() {
+        return this.queue.length === 0;
+    }
+    /**
+     * Clear all events from the queue.
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Close the queue.
+     * Rejects any pending waiters.
+     */
+    close() {
+        this.closed = true;
+        // Reject pending waiters by not resolving them
+        // In a real implementation, we might want to reject with an error
+        this.waiters = [];
+    }
+    /**
+     * Check if queue is closed.
+     */
+    get isClosed() {
+        return this.closed;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/src/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,KAAK,GAAmB,EAAE,CAAC;IAC3B,OAAO,GAAyC,EAAE,CAAC;IACnD,MAAM,GAAG,KAAK,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,KAAmB;QACtB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACrC,CAAC;QAED,6CAA6C;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC7C,4EAA4E;YAC5E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG;QACP,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACrC,CAAC;QAED,yCAAyC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QAED,0BAA0B;QAC1B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,+CAA+C;QAC/C,kEAAkE;QAClE,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/src/safe-slice.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Slice a string without splitting surrogate pairs.
+ *
+ * Regular String.prototype.slice can cut in the middle of a surrogate pair,
+ * producing invalid UTF-16. This function adjusts the end index to avoid that.
+ */
+export declare function safeSlice(str: string, start: number, end: number): string;
+//# sourceMappingURL=safe-slice.d.ts.map

package/dist/src/safe-slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-slice.d.ts","sourceRoot":"","sources":["../../src/safe-slice.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAWzE"}

package/dist/src/safe-slice.js

@@ -0,0 +1,18 @@
+/**
+ * Slice a string without splitting surrogate pairs.
+ *
+ * Regular String.prototype.slice can cut in the middle of a surrogate pair,
+ * producing invalid UTF-16. This function adjusts the end index to avoid that.
+ */
+export function safeSlice(str, start, end) {
+    if (end >= str.length)
+        return str.slice(start);
+    // If we're about to cut between a high and low surrogate, back up one char
+    const code = str.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff) {
+        // end-1 is a high surrogate — don't split the pair
+        return str.slice(start, end - 1);
+    }
+    return str.slice(start, end);
+}
+//# sourceMappingURL=safe-slice.js.map

package/dist/src/safe-slice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-slice.js","sourceRoot":"","sources":["../../src/safe-slice.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,KAAa,EAAE,GAAW;IAC/D,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE/C,2EAA2E;IAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACrC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;QACrC,mDAAmD;QACnD,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,118 @@
+import type { ContentBlock, YieldingStream } from '@animalabs/membrane';
+import type { ContextStrategy } from '@animalabs/context-manager';
+import type { ToolCallId, ToolResult, ToolCall } from './events.js';
+/**
+ * Configuration for an agent.
+ */
+export interface AgentConfig {
+    /** Unique name for this agent */
+    name: string;
+    /** Model to use (e.g., 'claude-sonnet-4-20250514') */
+    model: string;
+    /** System prompt */
+    systemPrompt: string;
+    /** Context management strategy */
+    strategy?: ContextStrategy;
+    /**
+     * Which tools this agent can use.
+     * - 'all': all available tools
+     * - string[]: specific tool names (with module prefix)
+     */
+    allowedTools?: 'all' | string[];
+    /**
+     * Which modules can trigger inference for this agent.
+     * - 'all': any module
+     * - string[]: specific module names
+     */
+    triggerSources?: 'all' | string[];
+    /** Maximum tokens for response */
+    maxTokens?: number;
+    /** Temperature for inference */
+    temperature?: number;
+    /** Max input tokens before framework breaks a yielding stream and
+     *  restarts with recompiled (compressed) context. Default: 150000. */
+    maxStreamTokens?: number;
+}
+/**
+ * Result of running inference.
+ */
+export interface InferenceResult {
+    /** Tool calls to execute */
+    toolCalls: ToolCall[];
+    /** Speech content (text blocks) to send to handlers */
+    speechContent: ContentBlock[];
+    /** Raw request/response for logging */
+    raw?: {
+        request: unknown;
+        response: unknown;
+    };
+    /** Usage stats */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Stop reason */
+    stopReason?: string;
+    /** Whether inference was aborted */
+    aborted?: boolean;
+    /** Reason for abort, if available */
+    abortReason?: string;
+}
+/**
+ * Options for running inference.
+ */
+export interface InferenceOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Internal state of an agent.
+ */
+export type AgentState = {
+    status: 'idle';
+} | {
+    status: 'inferring';
+    promise: Promise<InferenceResult>;
+    abortController: AbortController;
+} | {
+    status: 'streaming';
+    stream: YieldingStream;
+} | {
+    status: 'waiting_for_tools';
+    pending: Map<ToolCallId, PendingToolCall>;
+    completed: CompletedToolCall[];
+    stream?: YieldingStream;
+} | {
+    status: 'ready';
+    toolResults: CompletedToolCall[];
+    stream?: YieldingStream;
+};
+/**
+ * A tool call that's in progress.
+ */
+export interface PendingToolCall {
+    id: ToolCallId;
+    name: string;
+    input: unknown;
+    startedAt: number;
+}
+/**
+ * A tool call that has completed.
+ */
+export interface CompletedToolCall {
+    id: ToolCallId;
+    name: string;
+    input: unknown;
+    result: ToolResult;
+    durationMs: number;
+}
+/**
+ * Inference request for an agent.
+ */
+export interface InferenceRequest {
+    agentName: string;
+    reason: string;
+    source: string;
+    timestamp: number;
+}
+//# sourceMappingURL=agent.d.ts.map

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

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

package/dist/src/types/agent.js

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

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

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

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

@@ -0,0 +1,220 @@
+import type { ContentBlock, ToolDefinition as MembraneToolDefinition } from '@animalabs/membrane';
+import type { MessageId } from '@animalabs/context-manager';
+/**
+ * Unique identifier for a tool call.
+ */
+export type ToolCallId = string;
+/**
+ * Re-export membrane's ToolDefinition for modules to use.
+ */
+export type ToolDefinition = MembraneToolDefinition;
+/**
+ * Events that flow through the framework's processing queue.
+ *
+ * ProcessEvents represent work to be done — modules respond to them via onProcess().
+ * They are distinct from TraceEvents, which are observability-only notifications.
+ *
+ * Modules can define their own namespaced events (e.g., 'api:message', 'discord:reaction').
+ */
+export type ProcessEvent = ExternalMessageEvent | ToolCallEvent | ToolResultEvent | TimerFiredEvent | InferenceRequestEvent | MessageEditedEvent | MessageRemovedEvent | ModuleEvent | ApiMessageEvent | ApiInferenceRequestEvent | McplPushEvent | McplChannelIncomingEvent | CustomEvent;
+/**
+ * API message event - from the API server.
+ */
+export interface ApiMessageEvent {
+    type: 'api:message';
+    participant: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    triggerInference?: boolean;
+    targetAgents?: string[];
+}
+/**
+ * API inference request - from the API server.
+ */
+export interface ApiInferenceRequestEvent {
+    type: 'api:inference-request';
+    agentName?: string;
+    reason?: string;
+}
+/**
+ * Generic custom event for module-specific namespaced events.
+ * Use this for events like 'discord:message', 'slack:reaction', etc.
+ */
+export interface CustomEvent {
+    type: `${string}:${string}`;
+    [key: string]: unknown;
+}
+/**
+ * Message from an external source (Discord, HTTP, CLI, etc.)
+ */
+export interface ExternalMessageEvent {
+    type: 'external-message';
+    /** Module that produced this event */
+    source: string;
+    /** Raw content from external system */
+    content: unknown;
+    /** External system metadata */
+    metadata: Record<string, unknown>;
+    /** Whether this should trigger inference */
+    triggerInference?: boolean;
+    /** Specific agents to trigger (if not all) */
+    targetAgents?: string[];
+}
+/**
+ * Result of a tool call.
+ */
+export interface ToolResultEvent {
+    type: 'tool-result';
+    /** ID of the original tool call */
+    callId: ToolCallId;
+    /** Agent that made the call */
+    agentName: string;
+    /** Module that handled the call */
+    moduleName: string;
+    /** Result of the tool call */
+    result: ToolResult;
+}
+/**
+ * Tool call scheduled for execution.
+ */
+export interface ToolCallEvent {
+    type: 'tool-call';
+    /** ID of the tool call */
+    callId: ToolCallId;
+    /** Agent that made the call */
+    agentName: string;
+    /** Module that will handle the call */
+    moduleName: string;
+    /** Un-prefixed tool name */
+    toolName: string;
+    /** Full tool call payload */
+    call: ToolCall;
+}
+/**
+ * Scheduled timer fired.
+ */
+export interface TimerFiredEvent {
+    type: 'timer-fired';
+    /** Timer identifier */
+    timerId: string;
+    /** Reason for the timer */
+    reason: string;
+    /** Specific agent to wake (if any) */
+    agentName?: string;
+}
+/**
+ * Explicit request to run inference.
+ */
+export interface InferenceRequestEvent {
+    type: 'inference-request';
+    /** Agent to run inference for */
+    agentName: string;
+    /** Reason for the request */
+    reason: string;
+    /** Module that requested it */
+    source: string;
+}
+/**
+ * External message was edited.
+ */
+export interface MessageEditedEvent {
+    type: 'message-edited';
+    /** Module that produced this event */
+    source: string;
+    /** Our internal message ID */
+    messageId: MessageId;
+    /** New content */
+    newContent: ContentBlock[];
+}
+/**
+ * External message was removed.
+ */
+export interface MessageRemovedEvent {
+    type: 'message-removed';
+    /** Module that produced this event */
+    source: string;
+    /** Our internal message ID */
+    messageId: MessageId;
+}
+/**
+ * Generic module-specific event.
+ */
+export interface ModuleEvent {
+    type: 'module-event';
+    /** Module that produced this event */
+    source: string;
+    /** Module-specific event type */
+    eventType: string;
+    /** Module-specific payload */
+    payload: unknown;
+}
+/**
+ * Result of a tool execution.
+ */
+export interface ToolResult {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Result data (if success) */
+    data?: unknown;
+    /** Error message (if failure) */
+    error?: string;
+    /** Whether this was an error (for LLM) */
+    isError?: boolean;
+    /**
+     * When true, the framework saves tool_use + tool_result messages to context,
+     * cancels the active stream, and resets the agent to idle.
+     * This is a "sleep until next event" primitive — the LLM expects the call to block.
+     * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+     */
+    endTurn?: boolean;
+}
+/**
+ * A tool call from the LLM.
+ */
+export interface ToolCall {
+    /** Unique ID for this call */
+    id: ToolCallId;
+    /** Full tool name (module:tool) */
+    name: string;
+    /** Tool input */
+    input: unknown;
+    /** The agent that made this tool call. Set by the framework dispatch layer. */
+    callerAgentName?: string;
+}
+/**
+ * Push event from an MCPL server (Section 9).
+ * Converted from wire-format McplContentBlock to membrane ContentBlock.
+ */
+export interface McplPushEvent {
+    type: 'mcpl:push-event';
+    serverId: string;
+    featureSet: string;
+    eventId: string;
+    content: ContentBlock[];
+    origin?: Record<string, unknown>;
+    timestamp: string;
+    inferenceId: string;
+    triggerInference?: boolean;
+    targetAgents?: string[];
+}
+/**
+ * Incoming channel message from an MCPL server (Section 14).
+ * Converted from wire-format McplContentBlock to membrane ContentBlock.
+ */
+export interface McplChannelIncomingEvent {
+    type: 'mcpl:channel-incoming';
+    serverId: string;
+    channelId: string;
+    messageId: string;
+    threadId?: string;
+    author: {
+        id: string;
+        name: string;
+    };
+    content: ContentBlock[];
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+    triggerInference?: boolean;
+    targetAgents?: string[];
+}
+//# sourceMappingURL=events.d.ts.map

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

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