@animalabs/agent-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 antra-tess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# @connectome/agent-framework
+
+Multi-agent framework with pluggable modules, persistent state, streaming inference, and concurrent tool execution.
+
+## Overview
+
+Agent Framework orchestrates one or more LLM-powered agents that interact with the world through **modules** (pluggable capability providers). It handles the full lifecycle: event processing, context compilation, inference (streaming or request/response), tool dispatch, and state persistence via [Chronicle](https://github.com/antra-tess/chronicle).
+
+```
+External events (Discord, API, MCPL servers, timers)
+    ↓
+ProcessQueue → Module.onProcess() → EventResponse
+    ↓                                    ↓
+Inference trigger              Messages / state updates
+    ↓
+Context compilation (with injections from modules + MCPL hooks)
+    ↓
+Membrane (LLM abstraction) → YieldingStream
+    ↓
+Tool calls → Module.handleToolCall() → results → stream resumes
+    ↓
+Agent speech → Module.onAgentSpeech() → external delivery
+```
+
+## Quick Start
+
+```typescript
+import { AgentFramework, ApiModule, ApiServer } from '@connectome/agent-framework';
+import { Membrane, AnthropicAdapter } from 'membrane';
+
+const membrane = new Membrane({ adapter: new AnthropicAdapter() });
+
+const framework = await AgentFramework.create({
+  storePath: './data/store',
+  membrane,
+  agents: [{
+    name: 'assistant',
+    model: 'claude-sonnet-4-20250514',
+    systemPrompt: 'You are a helpful assistant.',
+  }],
+  modules: [new ApiModule()],
+});
+
+framework.start();
+
+const server = new ApiServer(framework, { port: 8765 });
+await server.start();
+```
+
+## Core Concepts
+
+### Agents
+
+An agent wraps an LLM identity: model, system prompt, context strategy, and tool permissions. Multiple agents can coexist, each with independent context and inference state.
+
+```typescript
+{
+  name: 'researcher',
+  model: 'claude-opus-4-20250514',
+  systemPrompt: '...',
+  strategy: new AutobiographicalStrategy({ recentWindowTokens: 30000 }),
+  allowedTools: ['search', 'read', 'write'],   // or 'all'
+  triggerSources: ['discord'],                   // or 'all'
+  maxTokens: 8192,
+  maxStreamTokens: 150_000,  // input token budget before stream restart
+}
+```
+
+**Inference modes:**
+- **Streaming** (default in framework): `startStreamWithInjections()` returns a `YieldingStream` that emits tokens, tool calls, and completion events. The framework drives the stream, dispatches tools, and resumes automatically.
+- **Request/response**: `runInferenceWithInjections()` for simple complete-and-return usage with optional `AbortSignal` for cancellation.
+
+**State machine:**
+```
+idle → inferring → streaming ⇄ waiting_for_tools → ready → streaming → ... → idle
+                 ↘ (abort) → idle
+```
+
+### Modules
+
+Modules are pluggable capability providers. They process events, expose tools, deliver speech, and optionally inject context before inference.
+
+```typescript
+interface Module {
+  readonly name: string;
+
+  start(ctx: ModuleContext): Promise<void>;
+  stop(): Promise<void>;
+
+  getTools(): ToolDefinition[];
+  handleToolCall(call: ToolCall): Promise<ToolResult>;
+  onProcess(event: ProcessEvent, state: ProcessState): Promise<EventResponse>;
+
+  // Optional
+  onAgentSpeech?(agentName: string, content: ContentBlock[], context: SpeechContext): Promise<void>;
+  gatherContext?(agentName: string): Promise<ContextInjection[]>;
+}
+```
+
+An `EventResponse` can add/edit/remove messages, request inference, signal tool changes, and atomically update module state:
+
+```typescript
+return {
+  addMessages: [{ participant: 'user', content: [{ type: 'text', text: '...' }] }],
+  requestInference: true,
+  stateUpdate: { lastProcessed: Date.now() },
+};
+```
+
+**Built-in modules:**
+- **DiscordModule** - Discord bot integration (messages, reactions, threads, typing indicators)
+- **ApiModule** - WebSocket API event processing
+- **WorkspaceModule** - Mountable filesystem abstraction with Chronicle tree state, filesystem watching, and materialization
+
+### Event Processing
+
+The framework runs an event loop over a `ProcessQueue`. Each event is processed by all modules, which return `EventResponse` objects. If any response requests inference, the framework compiles context and starts a stream.
+
+**Event types:** `ExternalMessageEvent`, `ToolCallEvent`, `ToolResultEvent`, `InferenceRequestEvent`, `McplPushEvent`, `McplChannelIncomingEvent`, `TimerFiredEvent`, `ApiMessageEvent`, `ModuleEvent`, `CustomEvent`
+
+### Context Management
+
+Each agent has a `ContextManager` (from `@connectome/context-manager`) that maintains conversation history with optional compression strategies:
+
+- **PassthroughStrategy** - No compression, raw message replay up to budget
+- **AutobiographicalStrategy** - Chunks old messages and summarizes them into diary entries, preserving recent context uncompressed
+
+Before inference, modules and MCPL hooks can inject additional context via `gatherContext()`.
+
+### Persistence
+
+All state is persisted in a [Chronicle](https://github.com/antra-tess/chronicle) store:
+
+| State | Strategy | Description |
+|-------|----------|-------------|
+| `framework/state` | snapshot | Agent configs |
+| `framework/inference-log` | append_log | Raw LLM requests/responses |
+| `messages` | (context-manager) | Shared conversation log |
+| `agents/{name}/context` | (context-manager) | Per-agent context log |
+| `modules/{name}/state` | snapshot | Per-module persistent state |
+
+Chronicle's branching support enables time-travel and what-if exploration across all state.
+
+### MCPL (MCP Live)
+
+Optional host-side implementation of the MCP Live protocol. External servers (game engines, dev tools, etc.) can:
+- Push events into agent context
+- Hook into inference lifecycle (beforeInference/afterInference)
+- Initiate inference requests
+- Publish and observe channels
+- Provide tools (namespaced automatically)
+
+```typescript
+{
+  mcplServers: [{
+    id: 'game-engine',
+    command: 'node',
+    args: ['./game-server.js'],
+    toolPrefix: 'game',
+  }],
+}
+```
+
+### Streaming Lifecycle
+
+1. **Start**: Framework calls `agent.startStreamWithInjections()` → `YieldingStream`
+2. **Drive**: Framework iterates stream events (tokens, tool-calls, complete, error)
+3. **Tool yield**: Stream yields tool calls → framework dispatches concurrently → collects results
+4. **Resume**: All results in → stream resumes with tool results
+5. **Budget restart**: If input tokens exceed `maxStreamTokens`, the stream is cancelled, context is recompressed, and a fresh stream starts
+6. **Complete**: Final response saved to context, agent returns to idle
+
+### Abort / Cancellation
+
+```typescript
+// Cancel in-flight inference for an agent
+framework.abortInference('assistant', 'user requested stop');
+```
+
+The non-streaming path uses `AbortSignal` forwarded to `membrane.stream()`, which returns an `AbortedResponse` with partial content. The streaming path cancels the `YieldingStream` directly.
+
+## API Server
+
+WebSocket server for external clients (UIs, scripts, other agents).
+
+```typescript
+const server = new ApiServer(framework, { port: 8765 });
+await server.start();
+```
+
+**Commands:** `message.send`, `message.list`, `inference.request`, `inference.abort`, `branch.*`, `agent.*`, `module.*`, `store.*`, `inference.tail/inspect/search`, `events.*`
+
+Also available as an MCP server via the `agent-framework-mcp` binary.
+
+## Observability
+
+Subscribe to trace events for logging, UI updates, or debugging:
+
+```typescript
+framework.onTrace((event) => {
+  // inference:started, inference:completed, inference:aborted
+  // tool:started, tool:completed, tool:failed
+  // process:received, process:completed
+  // message:added, module:added, module:removed
+  console.log(event.type, event);
+});
+```
+
+Query raw inference logs:
+
+```typescript
+const logs = framework.queryInferenceLogs({ agentName: 'assistant', limit: 10 });
+```
+
+## Dependencies
+
+| Package | Role |
+|---------|------|
+| [membrane](https://github.com/antra-tess/membrane) | LLM provider abstraction (Anthropic, Bedrock, OpenRouter) |
+| [@connectome/context-manager](https://github.com/anima-research/context-manager) | Context window management and compression |
+| [chronicle](https://github.com/antra-tess/chronicle) | Branchable persistent event store (Rust + N-API) |
+
+## Development
+
+```bash
+npm install
+npm run build      # TypeScript compilation
+npm run dev        # Watch mode
+npm test           # Run tests
+npm run typecheck  # Type-check without emitting
+```
+
+Requires Node.js >= 20. Chronicle requires a Rust toolchain for native module compilation (`npm run build` in the chronicle directory).

package/dist/src/agent.d.ts

@@ -0,0 +1,130 @@
+import type { Membrane, NormalizedRequest, ContentBlock, YieldingStream } from '@animalabs/membrane';
+export interface StartStreamResult {
+    stream: YieldingStream;
+    request: NormalizedRequest;
+}
+import type { ContextManager, TokenBudget, ContextInjection, CompileResult } from '@animalabs/context-manager';
+import type { AgentConfig, AgentState, ToolCallId, ToolCall, ToolResult, ToolDefinition, AgentInfo, InferenceResult, InferenceOptions } from './types/index.js';
+/**
+ * An agent wraps a context manager and manages inference state.
+ */
+export declare class Agent {
+    readonly name: string;
+    readonly model: string;
+    readonly systemPrompt: string;
+    readonly allowedTools: 'all' | string[];
+    readonly triggerSources: 'all' | string[];
+    readonly maxTokens: number;
+    readonly temperature: number;
+    private _state;
+    private _inferenceStartedAt;
+    private _streamId;
+    lastStreamInputTokens: number;
+    maxStreamTokens: number;
+    private contextManager;
+    private membrane;
+    constructor(config: AgentConfig, contextManager: ContextManager, membrane: Membrane);
+    /**
+     * Get current agent state.
+     */
+    get state(): AgentState;
+    /**
+     * Monotonically increasing stream generation counter.
+     * Used to guard stale driveStream handlers after a budget restart.
+     */
+    get streamId(): number;
+    /**
+     * Get agent info.
+     */
+    get info(): AgentInfo;
+    /**
+     * Check if agent can use a specific tool.
+     */
+    canUseTool(toolName: string): boolean;
+    /**
+     * Check if a source can trigger inference for this agent.
+     */
+    canBeTriggeredBy(source: string): boolean;
+    /**
+     * Compile the context without injections.
+     * Step 1 of the inference pipeline — callers can inspect/modify the result
+     * before building a request.
+     */
+    compileContext(budget?: TokenBudget): Promise<CompileResult>;
+    /**
+     * Compile the context with injections.
+     * Same as compileContext but forwards injections (e.g. from MCPL servers)
+     * to the context manager so they are merged into the compiled messages.
+     */
+    compileWithInjections(budget?: TokenBudget, injections?: ContextInjection[]): Promise<CompileResult>;
+    /**
+     * Run inference and return result with tool calls and speech content.
+     * Updates agent state during execution.
+     */
+    runInference(availableTools: ToolDefinition[], budget?: TokenBudget, options?: InferenceOptions): Promise<InferenceResult>;
+    /**
+     * Run inference with context injections.
+     * Same as runInference but passes injections through to compile.
+     */
+    runInferenceWithInjections(availableTools: ToolDefinition[], injections?: ContextInjection[], budget?: TokenBudget, options?: InferenceOptions): Promise<InferenceResult>;
+    /**
+     * Provide a tool result.
+     */
+    provideToolResult(callId: ToolCallId, result: ToolResult): void;
+    /**
+     * Start a yielding stream for inference.
+     * Returns the stream — the caller (framework) iterates it.
+     */
+    startStream(availableTools: ToolDefinition[], budget?: TokenBudget): Promise<StartStreamResult>;
+    /**
+     * Start a yielding stream with context injections.
+     * Same as startStream but passes injections through to compile.
+     */
+    startStreamWithInjections(availableTools: ToolDefinition[], injections?: ContextInjection[], budget?: TokenBudget): Promise<StartStreamResult>;
+    /**
+     * Transition to waiting_for_tools when stream yields tool calls.
+     * Called by framework's driveStream.
+     */
+    enterWaitingForTools(calls: ToolCall[], stream: YieldingStream): void;
+    /**
+     * Add an assistant response to context.
+     * Called by framework when stream completes.
+     */
+    addAssistantResponse(content: ContentBlock[]): void;
+    /**
+     * Transition back to streaming state after tool results are provided.
+     */
+    setStreaming(stream: YieldingStream): void;
+    /**
+     * Cancel any active stream and reset to idle.
+     */
+    cancelStream(): void;
+    /**
+     * Check if agent has pending tool calls.
+     */
+    hasPendingTools(): boolean;
+    /**
+     * Get pending tool call IDs.
+     */
+    getPendingToolIds(): ToolCallId[];
+    /**
+     * Reset agent to idle state.
+     */
+    reset(): void;
+    /**
+     * Get the context manager.
+     */
+    getContextManager(): ContextManager;
+    /**
+     * Build the effective system prompt, appending any system-position injections.
+     */
+    private buildSystemPrompt;
+    abortInference(reason?: string): {
+        aborted: true;
+        durationMs: number;
+    } | false;
+    private doInference;
+    private extractToolCallsAndSpeech;
+    private buildToolResultMessages;
+}
+//# sourceMappingURL=agent.d.ts.map

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

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