@lleverage-ai/agent-threads

Event transport, replay, and durable transcripts for AI agent conversations.

@lleverage-ai/agent-threads is the infrastructure package in this monorepo. It is for teams that need reusable primitives for conversation transport, replay, and persistence, whether or not they use @lleverage-ai/agent-sdk.

If you want to build agents, start with @lleverage-ai/agent-sdk. Add @lleverage-ai/agent-threads when you need lower-level control over thread history, transport, or transcript storage.

Installation

bun add @lleverage-ai/agent-threads zod

Overview

agent-threads provides the full infrastructure stack for durable AI agent conversations — from low-level event sourcing and real-time WebSocket transport to high-level canonical transcripts and run lifecycle management.

This package is useful in two common situations:

• you are building your own agent runtime or app-specific orchestration layer and need conversation infrastructure directly
• you are using @lleverage-ai/agent-sdk and want separate, explicit transport/transcript primitives in your broader system architecture

The package is organized into two layers:

• Stream layer — Append-only event stores, projectors, and WebSocket server/client for real-time event transport and replay
• Ledger layer — Canonical message schema, run lifecycle orchestration, accumulator (events → messages), and durable transcript stores

Sub-path Exports

Quick Start

Event Stores

import { InMemoryEventStore } from "@lleverage-ai/agent-threads/stores/event-memory";

const store = new InMemoryEventStore();

await store.append("thread-1", [
  { kind: "text-delta", payload: { delta: "Hello" } },
]);

const events = await store.replay("thread-1");

Run Lifecycle

import { RunManager } from "@lleverage-ai/agent-threads";
import { InMemoryEventStore } from "@lleverage-ai/agent-threads/stores/event-memory";
import { InMemoryLedgerStore } from "@lleverage-ai/agent-threads/stores/ledger-memory";

const eventStore = new InMemoryEventStore();
const ledgerStore = new InMemoryLedgerStore();
const manager = new RunManager(ledgerStore, eventStore);

const run = await manager.beginRun({ threadId: "thread-1" });
await manager.appendEvents(run.runId, events);
await manager.finalizeRun(run.runId, "committed");

Accumulator

import { accumulateEvents } from "@lleverage-ai/agent-threads";

const messages = accumulateEvents(storedEvents);

WebSocket Transport

import { WsServer } from "@lleverage-ai/agent-threads/server";
import { WsClient } from "@lleverage-ai/agent-threads/client";

const server = new WsServer({ store });
// Call server.handleConnection(ws) from your HTTP server's upgrade handler

const client = new WsClient({ url: "ws://localhost:8080" });

License

MIT