@amalgm/agents 0.2.0 → 0.2.1

package/PURPOSE.md

@@ -2,14 +2,15 @@
 
 ## Purpose
 
-Amalgm Agents is the small, standalone registry for agent identities,
-installations, and immutable revisions. A user or another agent can create,
-register, install, list, inspect, edit, and delete an available agent, then
-resolve one exact revision for execution by Chat.
-
-Shell composes Agents with Chat, harnesses, credentials, Toolbox, files, Live,
-and UI. This package stores references to those products; it does not duplicate
-their state or execute a conversation.
+Amalgm Agents is the small, standalone product for defining agents and talking
+to them. A user can create, inspect, edit, and delete an agent, then start or
+continue a durable session with it through the SDK, CLI, REST, or MCP. Agents
+are not chats: Chat may present a session, but the agent definition and session
+remain usable without Chat or Amalgm Engine.
+
+Engine composes Agents with harnesses, credentials, Toolbox, files, Realtime,
+and UI. This package stores references to those products and delegates
+execution to an injected driver; it does not duplicate their state.
 It also discovers installed agent skills across the canonical project and
 harness roots so every transport presents the same available skill catalog.
 Rich harness configuration is stored inside the same immutable definition and
@@ -20,22 +21,25 @@ hosts supply explicit ports for resources owned by other products.
 ## Primitives
 
 - An **agent** is a stable identity with a complete current definition.
-- An **installation** is one locally available agent identity and its Agent
-  Home descriptor.
-- A **resolved agent** is one exact immutable revision selected for execution.
+- A **session** is a durable conversation with one agent definition.
+- A **turn** is one accepted input and its driver result.
+- A **driver** runs the agent using a host-provided harness.
 - The **Agents service** is the behavior shared by every public surface.
 
 ## Axioms
 
+Managed releases bind to one exact published Core version and build from the
+locked dependency graph on the supported Node toolchain.
+
 1. A user can create, list, inspect, edit, and delete agents.
-2. A user or another agent can resolve an available agent to one exact
-   immutable revision without starting a conversation.
+2. A user or another agent can start, inspect, and continue an agent session
+   without creating or depending on a Chat conversation.
 3. An agent definition can reference its harness, model, instructions, tools,
    skills, files, credentials, and subagents without Agents owning those
    products.
-4. Harness identity is part of an agent revision; provider execution belongs
-   to Chat behind a host runtime port.
-5. Agent definitions, installations, and revisions survive restart.
+4. Any compatible agent harness can be used through the same driver contract.
+5. Agent definitions and sessions survive restart, while uncertain interrupted
+   execution is never silently replayed.
 6. SDK, CLI, REST, MCP, and skill workflows expose the same Agents behavior;
    none is a second implementation.
 7. An unchanged current definition is idempotent; every actual change creates
@@ -47,12 +51,10 @@ hosts supply explicit ports for resources owned by other products.
 
 ## Consequences
 
-The package needs no conversation, turn, transcript, stream, reconnect,
-interrupt, cloud command inbox, scheduler, trigger relay, or general
-event-routing system. Shell and other hosts resolve Agents revisions while
-preparing a Chat execution. Bundle ports call Apps, Automations, and Toolbox
-public APIs; Agents never imports their stores or duplicates their lifecycle
-behavior.
-
-There is no execution subsystem in Agents. Chat is the single owner of every
-conversation and turn.
+The package needs no cloud command inbox, scheduler, trigger relay, Chat
+record, or general event-routing system. Engine and other hosts may call the
+SDK whenever they need to route work, but routing is outside the Agents
+product. Bundle ports call Apps, Automations, and Toolbox public APIs; Agents
+never imports their stores or duplicates their lifecycle behavior. Internal
+revisions, ordered events, idempotency, and cancellation exist only to make
+the behaviors above durable and predictable.

package/README.md

@@ -1,12 +1,12 @@
 # Amalgm Agents
 
 `@amalgm/agents` is a local-first TypeScript SDK for persistent agent
-identities, installations, and immutable revisions. The same registry powers
-its CLI, REST API, and MCP server.
+definitions and durable multi-turn sessions. The same service powers its CLI,
+REST API, and MCP server.
 
-It is intentionally not Chat. Agents resolves the exact installed revision;
-`@amalgm/chat` owns the durable conversation, turns, stream, reconnect, and
-interrupt lifecycle that executes it.
+It is intentionally not Chat. Chat may present an agent session, but Agents
+owns the agent definition, the pinned execution revision, turns, and ordered
+events.
 
 ## Install
 
@@ -19,9 +19,25 @@ Node 20 or newer is required.
 ## First agent
 
 ```ts
-import { Agents } from '@amalgm/agents';
+import { Agents, defineDriver } from '@amalgm/agents';
+
+const echo = defineDriver({
+  id: 'echo',
+  async run(request) {
+    const text = request.input.parts
+      .filter((part) => part.type === 'text')
+      .map((part) => part.text)
+      .join('');
+    return {
+      message: {
+        role: 'assistant',
+        parts: [{ type: 'text', text: `Received: ${text}` }],
+      },
+    };
+  },
+});
 
-const agents = new Agents({ stateDir: './state' });
+const agents = new Agents({ stateDir: './state', drivers: [echo] });
 
 agents.createAgent({
   id: 'reviewer',
@@ -31,22 +47,28 @@ agents.createAgent({
   toolbox: { toolIds: ['git'], actionIds: ['git.diff'] },
 });
 
-const revision = agents.getAgentRevision('reviewer');
-console.log(revision.id, revision.definition.driver.id);
-agents.close();
+const session = agents.startSession({ agentId: 'reviewer' });
+const turn = await agents.send(session.id, {
+  message: 'Review the current diff.',
+  idempotencyKey: 'review-001',
+});
+
+console.log(turn.status);
+console.log(agents.listEvents(session.id));
+await agents.close();
 ```
 
-An agent definition is normalized into a complete immutable revision. Chat
-records the resolved revision id in every prepared execution.
+An agent definition is normalized into a complete immutable revision. A
+session stays pinned to that revision even after the agent is edited.
 
 ## Product surfaces
 
 | Surface | Entry point | Purpose |
 |---|---|---|
-| SDK | `@amalgm/agents` | Embed the canonical registry and resolve revisions |
-| CLI | `amalgm-agents` | Manage agent identities and installations |
-| REST | `@amalgm/agents/http`, `amalgm-agents-rest` | Local registry integration |
-| MCP | `@amalgm/agents/mcp`, `amalgm-agents-mcp` | Agent registry tools |
+| SDK | `@amalgm/agents` | Embed the canonical service and supply drivers |
+| CLI | `amalgm-agents` | Manage definitions and sessions |
+| REST | `@amalgm/agents/http`, `amalgm-agents-rest` | Local HTTP and SSE integration |
+| MCP | `@amalgm/agents/mcp`, `amalgm-agents-mcp` | Agent CRUD and agent-to-agent calls |
 | Skill | `skills/amalgm-agents` | Minimal workflow over the Agents tools |
 
 Installed skills are available from the REST surface without introducing a
@@ -100,9 +122,13 @@ explicitly; dependencies are never omitted to make a bundle look portable.
 ```bash
 amalgm-agents agent create ./agent.json
 amalgm-agents agent list
+amalgm-agents session start reviewer
+amalgm-agents session send <session-id> "Review the diff"
+amalgm-agents talk reviewer "Review the diff"
 ```
 
-The CLI reads the same SQLite registry as the SDK.
+The CLI reads the same SQLite database as the SDK. Driver modules are loaded
+with `--drivers ./dist/codex-driver.js` or `AMALGM_AGENT_DRIVERS`.
 
 ## Documentation
 
@@ -110,10 +136,11 @@ The CLI reads the same SQLite registry as the SDK.
 - [Architecture and boundaries](./docs/ARCHITECTURE.md)
 - [Agent definitions](./docs/DEFINITIONS.md)
 - [SDK reference](./docs/SDK.md)
+- [Driver contract](./docs/DRIVERS.md)
 - [CLI reference](./docs/CLI.md)
 - [REST API](./docs/REST.md)
 - [MCP server](./docs/MCP.md)
-- [Persistence](./docs/DATA_MODEL.md)
+- [Persistence and recovery](./docs/DATA_MODEL.md)
 - [Security model](./docs/SECURITY.md)
 - [Engine integration](./docs/ENGINE_INTEGRATION.md)
 
@@ -126,4 +153,4 @@ npm run verify
 
 `verify` runs strict typechecking for source, tests, and examples; enforces the
 220-line source-file limit; builds JavaScript and declarations; and runs the
-real SQLite, TCP, stdio MCP, and CLI tests.
+real SQLite, process-restart, TCP/SSE, stdio MCP, and CLI tests.

package/dist/agents.d.ts

@@ -1,8 +1,14 @@
-import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, JsonObject } from './types.js';
+import type { AgentDefinitionInput, AgentDriver, AgentPatch, AgentRecord, AgentSession, AgentsOptions, AgentTurn, EnqueuedTurn, EventListener, JsonObject, SendInput, SessionEvent, StartSessionInput } from './types.js';
 export declare class Agents {
     readonly databasePath: string;
+    readonly recoveredTurns: number;
     private readonly opened;
     private readonly agentStore;
+    private readonly eventStore;
+    private readonly sessionStore;
+    private readonly turnStore;
+    private readonly runtime;
+    private readonly listeners;
     private closed;
     constructor(options?: AgentsOptions);
     createAgent(input: AgentDefinitionInput): AgentRecord;
@@ -10,8 +16,24 @@ export declare class Agents {
     deleteAgent(id: string): AgentRecord;
     getAgent(id: string, includeDeleted?: boolean): AgentRecord | null;
     listAgents(includeDeleted?: boolean): AgentRecord[];
-    /** Resolve one exact immutable revision for a host such as Chat. */
-    getAgentRevision(agentId: string, revisionId?: string): AgentRevision;
+    startSession(input: StartSessionInput): AgentSession;
+    getSession(id: string): AgentSession | null;
+    listSessions(agentId?: string, includeArchived?: boolean): AgentSession[];
+    archiveSession(id: string): AgentSession;
+    enqueue(id: string, input: SendInput): EnqueuedTurn;
+    send(id: string, input: SendInput): Promise<AgentTurn>;
+    talk(agentId: string, input: SendInput & {
+        sessionId?: string;
+    }): EnqueuedTurn & {
+        session: AgentSession;
+    };
+    cancelSession(id: string): AgentTurn;
+    listTurns(sessionId: string): AgentTurn[];
+    listEvents(sessionId: string, after?: number, limit?: number): SessionEvent[];
+    registerDriver(driver: AgentDriver): void;
+    driverIds(): string[];
+    subscribe(sessionId: string, listener: EventListener): () => void;
     health(): JsonObject;
-    close(): void;
+    close(): Promise<void>;
+    private publish;
 }

package/dist/agents.js

@@ -1,16 +1,36 @@
 import path from 'node:path';
 import { AgentStore } from './agent-store.js';
 import { openDatabase } from './database.js';
+import { EventStore } from './event-store.js';
+import { AgentError } from './errors.js';
+import { AgentRuntime } from './runtime.js';
+import { SessionStore } from './session-store.js';
+import { TurnStore } from './turn-store.js';
 export class Agents {
     databasePath;
+    recoveredTurns;
     opened;
     agentStore;
+    eventStore;
+    sessionStore;
+    turnStore;
+    runtime;
+    listeners = new Map();
     closed = false;
     constructor(options = {}) {
         this.opened = openDatabase(options);
         this.databasePath = this.opened.databasePath;
         const now = options.now || (() => new Date().toISOString());
+        this.eventStore = new EventStore(this.opened.database, now, (event) => this.publish(event));
         this.agentStore = new AgentStore(this.opened.database, now);
+        this.sessionStore = new SessionStore(this.opened.database, this.eventStore, now);
+        this.turnStore = new TurnStore(this.opened.database, this.sessionStore, this.eventStore, now);
+        this.recoveredTurns = this.turnStore.recoverInterrupted();
+        this.runtime = new AgentRuntime(this.agentStore, this.sessionStore, this.turnStore, this.eventStore, {
+            maxInputBytes: options.maxInputBytes || 256_000,
+            maxEventBytes: options.maxEventBytes || 256_000,
+            turnTimeoutMs: options.turnTimeoutMs ?? 600_000,
+        }, options.drivers);
     }
     createAgent(input) {
         return this.agentStore.create(input);
@@ -27,20 +47,83 @@ export class Agents {
     listAgents(includeDeleted = false) {
         return this.agentStore.list(includeDeleted);
     }
-    /** Resolve one exact immutable revision for a host such as Chat. */
-    getAgentRevision(agentId, revisionId) {
-        return this.agentStore.revision(agentId, revisionId);
+    startSession(input) {
+        const agent = this.agentStore.require(input.agentId);
+        const revision = this.agentStore.revision(agent.id, input.revisionId);
+        return this.sessionStore.create(revision, input.sessionId, input.metadata || {});
+    }
+    getSession(id) {
+        return this.sessionStore.get(id);
+    }
+    listSessions(agentId, includeArchived = false) {
+        return this.sessionStore.list(agentId, includeArchived);
+    }
+    archiveSession(id) {
+        return this.sessionStore.archive(id, Boolean(this.turnStore.active(id)));
+    }
+    enqueue(id, input) {
+        this.sessionStore.require(id);
+        return this.runtime.enqueue(id, input);
+    }
+    send(id, input) {
+        this.sessionStore.require(id);
+        return this.runtime.send(id, input);
+    }
+    talk(agentId, input) {
+        const session = input.sessionId
+            ? this.sessionStore.require(input.sessionId)
+            : this.startSession({ agentId });
+        if (session.agentId !== agentId) {
+            throw new AgentError('conflict', `Session ${session.id} belongs to agent ${session.agentId}.`);
+        }
+        return { session, ...this.enqueue(session.id, input) };
+    }
+    cancelSession(id) {
+        this.sessionStore.require(id);
+        return this.runtime.cancel(id);
+    }
+    listTurns(sessionId) {
+        return this.turnStore.list(sessionId);
+    }
+    listEvents(sessionId, after = 0, limit = 200) {
+        this.sessionStore.require(sessionId);
+        return this.eventStore.list(sessionId, after, limit);
+    }
+    registerDriver(driver) {
+        this.runtime.register(driver);
+    }
+    driverIds() {
+        return this.runtime.driverIds();
+    }
+    subscribe(sessionId, listener) {
+        this.sessionStore.require(sessionId);
+        const listeners = this.listeners.get(sessionId) || new Set();
+        listeners.add(listener);
+        this.listeners.set(sessionId, listeners);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0)
+                this.listeners.delete(sessionId);
+        };
     }
     health() {
         return {
             ok: !this.closed,
             database: path.basename(this.databasePath),
+            recoveredTurns: this.recoveredTurns,
+            drivers: this.driverIds(),
         };
     }
-    close() {
+    async close() {
         if (this.closed)
             return;
         this.closed = true;
+        await this.runtime.shutdown();
+        this.listeners.clear();
         this.opened.close();
     }
+    publish(event) {
+        for (const listener of this.listeners.get(event.sessionId) || [])
+            listener(event);
+    }
 }

package/dist/bin/mcp.js

@@ -6,7 +6,7 @@ import { fatal } from './fatal.js';
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.flags.has('help')) {
-        process.stdout.write('Usage: amalgm-agents-mcp [--state-dir <path>]\n');
+        process.stdout.write('Usage: amalgm-agents-mcp [--state-dir <path>] [--drivers <a.js,b.js>]\n');
         return;
     }
     const agents = await openAgents(args);

package/dist/cli/help.d.ts

@@ -1 +1 @@
-export declare const HELP = "amalgm-agents \u2014 local agent identities and immutable revisions\n\nAgents:\n  amalgm-agents agent list [--include-deleted]\n  amalgm-agents agent show <id>\n  amalgm-agents agent create <definition.json>\n  amalgm-agents agent update <id> <patch.json>\n  amalgm-agents agent delete <id>\n\nGlobal options:\n  --state-dir <path>       Agents state directory\n  --help                   Show this help\n";
+export declare const HELP = "amalgm-agents \u2014 local agent definitions and durable sessions\n\nAgent definitions:\n  amalgm-agents agent list [--include-deleted]\n  amalgm-agents agent show <id>\n  amalgm-agents agent create <definition.json>\n  amalgm-agents agent update <id> <patch.json>\n  amalgm-agents agent delete <id>\n\nSessions:\n  amalgm-agents session list [--agent <id>] [--include-archived]\n  amalgm-agents session start <agent-id> [--id <id>] [--revision <id>]\n  amalgm-agents session show <id>\n  amalgm-agents session events <id> [--after <sequence>]\n  amalgm-agents session send <id> <message> [--key <idempotency-key>]\n  amalgm-agents session cancel <id>\n  amalgm-agents session archive <id>\n  amalgm-agents talk <agent-id> <message> [--session <id>] [--background]\n\nGlobal options:\n  --state-dir <path>       Agents state directory\n  --drivers <a.js,b.js>    Driver modules (or AMALGM_AGENT_DRIVERS)\n  --help                   Show this help\n";

package/dist/cli/help.js

@@ -1,13 +1,24 @@
-export const HELP = `amalgm-agents — local agent identities and immutable revisions
+export const HELP = `amalgm-agents — local agent definitions and durable sessions
 
-Agents:
+Agent definitions:
   amalgm-agents agent list [--include-deleted]
   amalgm-agents agent show <id>
   amalgm-agents agent create <definition.json>
   amalgm-agents agent update <id> <patch.json>
   amalgm-agents agent delete <id>
 
+Sessions:
+  amalgm-agents session list [--agent <id>] [--include-archived]
+  amalgm-agents session start <agent-id> [--id <id>] [--revision <id>]
+  amalgm-agents session show <id>
+  amalgm-agents session events <id> [--after <sequence>]
+  amalgm-agents session send <id> <message> [--key <idempotency-key>]
+  amalgm-agents session cancel <id>
+  amalgm-agents session archive <id>
+  amalgm-agents talk <agent-id> <message> [--session <id>] [--background]
+
 Global options:
   --state-dir <path>       Agents state directory
+  --drivers <a.js,b.js>    Driver modules (or AMALGM_AGENT_DRIVERS)
   --help                   Show this help
 `;

package/dist/cli/open.d.ts

@@ -1,3 +1,3 @@
 import { Agents } from '../agents.js';
 import type { ParsedArgs } from './args.js';
-export declare function openAgents(args: ParsedArgs): Agents;
+export declare function openAgents(args: ParsedArgs): Promise<Agents>;

package/dist/cli/open.js

@@ -1,8 +1,12 @@
 import { Agents } from '../agents.js';
+import { driverSpecifiers, loadDriverModules } from '../drivers.js';
 import { flag } from './args.js';
-export function openAgents(args) {
+export async function openAgents(args) {
+    const modules = flag(args, 'drivers');
     const stateDir = flag(args, 'state-dir');
+    const drivers = await loadDriverModules(driverSpecifiers(modules));
     return new Agents({
+        drivers,
         ...(stateDir ? { stateDir } : {}),
     });
 }

package/dist/cli/run.js

@@ -4,6 +4,7 @@ import { runAgentCommand } from './agent-commands.js';
 import { writeJson } from './files.js';
 import { HELP } from './help.js';
 import { openAgents } from './open.js';
+import { runSessionCommand, runTalkCommand } from './session-commands.js';
 export async function runCli(argv = process.argv.slice(2)) {
     const args = parseArgs(argv);
     if (args.flags.has('help') || args.words.length === 0) {
@@ -12,11 +13,15 @@ export async function runCli(argv = process.argv.slice(2)) {
     }
     let agents;
     try {
-        agents = openAgents(args);
+        agents = await openAgents(args);
         const command = args.words[0];
         const value = command === 'agent'
             ? runAgentCommand(agents, args)
-            : undefined;
+            : command === 'session'
+                ? await runSessionCommand(agents, args)
+                : command === 'talk'
+                    ? await runTalkCommand(agents, args)
+                    : undefined;
         if (value === undefined)
             throw new Error(`Unknown command: ${String(command)}`);
         writeJson(value);
@@ -28,6 +33,6 @@ export async function runCli(argv = process.argv.slice(2)) {
         return 1;
     }
     finally {
-        agents?.close();
+        await agents?.close();
     }
 }

package/dist/cli/session-commands.d.ts

@@ -0,0 +1,4 @@
+import type { Agents } from '../agents.js';
+import type { ParsedArgs } from './args.js';
+export declare function runSessionCommand(agents: Agents, args: ParsedArgs): Promise<unknown>;
+export declare function runTalkCommand(agents: Agents, args: ParsedArgs): Promise<unknown>;

package/dist/cli/session-commands.js

@@ -0,0 +1,54 @@
+import { AgentError } from '../errors.js';
+import { enabled, flag } from './args.js';
+export async function runSessionCommand(agents, args) {
+    const [, action, first, second] = args.words;
+    if (action === 'list') {
+        return { sessions: agents.listSessions(flag(args, 'agent'), enabled(args, 'include-archived')) };
+    }
+    if (action === 'start' && first) {
+        const sessionId = flag(args, 'id');
+        const revisionId = flag(args, 'revision');
+        return { session: agents.startSession({
+                agentId: first,
+                ...(sessionId ? { sessionId } : {}),
+                ...(revisionId ? { revisionId } : {}),
+            }) };
+    }
+    if (action === 'show' && first) {
+        const session = agents.getSession(first);
+        if (!session)
+            throw new AgentError('not_found', `Session not found: ${first}`);
+        return { session, turns: agents.listTurns(first), events: agents.listEvents(first) };
+    }
+    if (action === 'events' && first) {
+        return { events: agents.listEvents(first, Number(flag(args, 'after') || 0)) };
+    }
+    if (action === 'send' && first && second) {
+        const idempotencyKey = flag(args, 'key');
+        return { turn: await agents.send(first, {
+                message: second,
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+            }) };
+    }
+    if (action === 'cancel' && first)
+        return { turn: agents.cancelSession(first) };
+    if (action === 'archive' && first)
+        return { session: agents.archiveSession(first) };
+    throw new AgentError('invalid_input', 'Unknown or incomplete session command. Run with --help.');
+}
+export async function runTalkCommand(agents, args) {
+    const [, agentId, message] = args.words;
+    if (!agentId || !message)
+        throw new AgentError('invalid_input', 'talk requires agent id and message.');
+    const sessionId = flag(args, 'session');
+    const idempotencyKey = flag(args, 'key');
+    const call = agents.talk(agentId, {
+        message,
+        ...(sessionId ? { sessionId } : {}),
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+    });
+    if (enabled(args, 'background')) {
+        return { session: call.session, turn: call.turn, duplicate: call.duplicate };
+    }
+    return { session: call.session, turn: await call.completion, duplicate: call.duplicate };
+}

package/dist/drivers.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDriver } from './types.js';
+export declare function defineDriver(driver: AgentDriver): AgentDriver;
+export declare function loadDriverModules(specifiers: string[]): Promise<AgentDriver[]>;
+export declare function driverSpecifiers(value?: string): string[];

package/dist/drivers.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { AgentError } from './errors.js';
+export function defineDriver(driver) {
+    if (!driver || typeof driver.id !== 'string' || typeof driver.run !== 'function') {
+        throw new AgentError('invalid_input', 'Agent drivers require id and run.');
+    }
+    return driver;
+}
+export async function loadDriverModules(specifiers) {
+    const drivers = [];
+    for (const specifier of specifiers) {
+        const target = specifier.startsWith('.') || specifier.startsWith('/')
+            ? pathToFileURL(path.resolve(specifier)).href
+            : specifier;
+        const loaded = await import(target);
+        const value = loaded.default ?? loaded.driver ?? loaded;
+        const driver = typeof value === 'function' ? await value() : value;
+        drivers.push(defineDriver(driver));
+    }
+    return drivers;
+}
+export function driverSpecifiers(value = process.env.AMALGM_AGENT_DRIVERS || '') {
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+}

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { JsonObject } from './types.js';
-export type AgentErrorCode = 'invalid_input' | 'not_found' | 'conflict' | 'deleted' | 'too_large' | 'internal';
+export type AgentErrorCode = 'invalid_input' | 'not_found' | 'conflict' | 'deleted' | 'driver_unavailable' | 'too_large' | 'cancelled' | 'internal';
 export declare class AgentError extends Error {
     readonly code: AgentErrorCode;
     readonly details: JsonObject;

package/dist/errors.js

@@ -3,7 +3,9 @@ const statusByCode = {
     not_found: 404,
     conflict: 409,
     deleted: 410,
+    driver_unavailable: 503,
     too_large: 413,
+    cancelled: 409,
     internal: 500,
 };
 export class AgentError extends Error {

package/dist/event-store.d.ts

@@ -0,0 +1,13 @@
+import type Database from 'better-sqlite3';
+import type { EventListener, JsonObject, SessionEvent } from './types.js';
+export declare class EventStore {
+    private readonly database;
+    private readonly now;
+    private readonly listener;
+    constructor(database: Database.Database, now: () => string, listener: EventListener);
+    append(sessionId: string, turnId: string | null, type: string, data: JsonObject): SessionEvent;
+    write(sessionId: string, turnId: string | null, type: string, data: JsonObject): SessionEvent;
+    announce(event: SessionEvent): void;
+    list(sessionId: string, after?: number, limit?: number): SessionEvent[];
+    forTurn(turnId: string): SessionEvent[];
+}

package/dist/event-store.js

@@ -0,0 +1,50 @@
+import { AgentError } from './errors.js';
+import { newId } from './ids.js';
+import { eventFromRow } from './rows.js';
+export class EventStore {
+    database;
+    now;
+    listener;
+    constructor(database, now, listener) {
+        this.database = database;
+        this.now = now;
+        this.listener = listener;
+    }
+    append(sessionId, turnId, type, data) {
+        let event;
+        this.database.transaction(() => {
+            event = this.write(sessionId, turnId, type, data);
+            this.database.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?').run(this.now(), sessionId);
+        })();
+        if (!event)
+            throw new AgentError('internal', 'Event transaction produced no event.');
+        this.announce(event);
+        return event;
+    }
+    write(sessionId, turnId, type, data) {
+        const sequence = Number(this.database.prepare(`
+      SELECT COALESCE(MAX(sequence), 0) + 1 AS value FROM session_events WHERE session_id = ?
+    `).get(sessionId).value);
+        const id = newId('event');
+        const createdAt = this.now();
+        this.database.prepare(`
+      INSERT INTO session_events (id, session_id, turn_id, sequence, type, data_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(id, sessionId, turnId, sequence, type, JSON.stringify(data), createdAt);
+        return { id, sessionId, turnId, sequence, type, data, createdAt };
+    }
+    announce(event) {
+        this.listener(event);
+    }
+    list(sessionId, after = 0, limit = 200) {
+        const cursor = Number.isFinite(after) ? Math.max(0, Math.floor(after)) : 0;
+        const bounded = Number.isFinite(limit) ? Math.max(1, Math.min(1000, Math.floor(limit))) : 200;
+        return this.database.prepare(`
+      SELECT * FROM session_events WHERE session_id = ? AND sequence > ? ORDER BY sequence ASC LIMIT ?
+    `).all(sessionId, cursor, bounded).map(eventFromRow);
+    }
+    forTurn(turnId) {
+        return this.database.prepare('SELECT * FROM session_events WHERE turn_id = ? ORDER BY sequence ASC')
+            .all(turnId).map(eventFromRow);
+    }
+}