@amalgm/agents 0.1.0

package/PURPOSE.md

@@ -0,0 +1,45 @@
+# Amalgm Agents
+
+## Purpose
+
+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.
+
+## Primitives
+
+- An **agent** is a stable identity with a complete current definition.
+- 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
+
+1. A user can create, list, inspect, edit, and delete agents.
+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. 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
+   a new immutable revision, even when its content matches an earlier revision.
+
+## Consequences
+
+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. Internal revisions, ordered events, idempotency, and cancellation
+exist only to make the six behaviors above durable and predictable.

package/README.md

@@ -0,0 +1,110 @@
+# Amalgm Agents
+
+`@amalgm/agents` is a local-first TypeScript SDK for persistent agent
+definitions and durable multi-turn sessions. The same service powers its CLI,
+REST API, and MCP server.
+
+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
+
+```bash
+npm install @amalgm/agents
+```
+
+Node 20 or newer is required.
+
+## First agent
+
+```ts
+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', drivers: [echo] });
+
+agents.createAgent({
+  id: 'reviewer',
+  name: 'Reviewer',
+  driver: { id: 'echo' },
+  instructions: 'Review work carefully.',
+  toolbox: { toolIds: ['git'], actionIds: ['git.diff'] },
+});
+
+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. 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 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 |
+
+## CLI
+
+```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 database as the SDK. Driver modules are loaded
+with `--drivers ./dist/codex-driver.js` or `AMALGM_AGENT_DRIVERS`.
+
+## Documentation
+
+- [Purpose and axioms](./PURPOSE.md)
+- [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 and recovery](./docs/DATA_MODEL.md)
+- [Security model](./docs/SECURITY.md)
+- [Engine integration](./docs/ENGINE_INTEGRATION.md)
+
+## Development
+
+```bash
+npm ci
+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, process-restart, TCP/SSE, stdio MCP, and CLI tests.

package/dist/agent-store.d.ts

@@ -0,0 +1,17 @@
+import type Database from 'better-sqlite3';
+import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision } from './types.js';
+export declare class AgentStore {
+    private readonly database;
+    private readonly now;
+    constructor(database: Database.Database, now: () => string);
+    create(input: AgentDefinitionInput): AgentRecord;
+    apply(input: AgentDefinitionInput): AgentRecord;
+    update(id: string, patch: AgentPatch): AgentRecord;
+    delete(id: string): AgentRecord;
+    get(id: string, includeDeleted?: boolean): AgentRecord | null;
+    require(id: string, includeDeleted?: boolean): AgentRecord;
+    list(includeDeleted?: boolean): AgentRecord[];
+    revision(agentId: string, revisionId?: string): AgentRevision;
+    private rawAgent;
+    private insertRevision;
+}

package/dist/agent-store.js

@@ -0,0 +1,111 @@
+import { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
+import { AgentError } from './errors.js';
+import { newId, requireId } from './ids.js';
+import { agentFromRow, revisionFromRow } from './rows.js';
+const AGENT_SELECT = `
+  SELECT a.*, r.id AS revision_id, r.revision_number, r.definition_hash,
+    r.definition_json, r.created_at AS revision_created_at
+  FROM agents a
+  JOIN agent_revisions r ON r.id = a.current_revision_id
+`;
+export class AgentStore {
+    database;
+    now;
+    constructor(database, now) {
+        this.database = database;
+        this.now = now;
+    }
+    create(input) {
+        const definition = normalizeDefinition(input);
+        if (this.rawAgent(definition.id)) {
+            throw new AgentError('conflict', `Agent id already exists: ${definition.id}`);
+        }
+        const timestamp = this.now();
+        const revisionId = newId('revision');
+        this.database.transaction(() => {
+            this.database.prepare(`
+        INSERT INTO agents (id, created_at, updated_at) VALUES (?, ?, ?)
+      `).run(definition.id, timestamp, timestamp);
+            this.insertRevision(revisionId, definition.id, 1, definition, timestamp);
+            this.database.prepare(`
+        UPDATE agents SET current_revision_id = ?, current_revision_number = 1 WHERE id = ?
+      `).run(revisionId, definition.id);
+        })();
+        return this.require(definition.id);
+    }
+    apply(input) {
+        const definition = normalizeDefinition(input);
+        const existing = this.get(definition.id, true);
+        if (!existing)
+            return this.create(definition);
+        if (existing.deletedAt)
+            throw new AgentError('deleted', `Agent is deleted: ${definition.id}`);
+        const hash = definitionHash(definition);
+        const equal = this.database.prepare(`
+      SELECT 1 FROM agent_revisions WHERE id = ? AND definition_hash = ?
+    `).get(existing.currentRevisionId, hash);
+        if (equal)
+            return existing;
+        const timestamp = this.now();
+        const revisionId = newId('revision');
+        const number = existing.currentRevision + 1;
+        this.database.transaction(() => {
+            this.insertRevision(revisionId, existing.id, number, definition, timestamp);
+            this.database.prepare(`
+        UPDATE agents SET current_revision_id = ?, current_revision_number = ?, updated_at = ?
+        WHERE id = ? AND deleted_at IS NULL
+      `).run(revisionId, number, timestamp, existing.id);
+        })();
+        return this.require(existing.id);
+    }
+    update(id, patch) {
+        const existing = this.require(id);
+        return this.apply(patchDefinition(existing.definition, patch));
+    }
+    delete(id) {
+        const existing = this.require(id, true);
+        if (existing.deletedAt)
+            return existing;
+        const timestamp = this.now();
+        this.database.prepare(`UPDATE agents SET deleted_at = ?, updated_at = ? WHERE id = ?`)
+            .run(timestamp, timestamp, existing.id);
+        return this.require(existing.id, true);
+    }
+    get(id, includeDeleted = false) {
+        const clean = requireId(id, 'agent id');
+        const deleted = includeDeleted ? '' : ' AND a.deleted_at IS NULL';
+        const row = this.database.prepare(`${AGENT_SELECT} WHERE a.id = ?${deleted}`).get(clean);
+        return row ? agentFromRow(row) : null;
+    }
+    require(id, includeDeleted = false) {
+        const agent = this.get(id, includeDeleted);
+        if (!agent)
+            throw new AgentError('not_found', `Agent not found: ${id}`);
+        return agent;
+    }
+    list(includeDeleted = false) {
+        const where = includeDeleted ? '' : ' WHERE a.deleted_at IS NULL';
+        return this.database.prepare(`${AGENT_SELECT}${where} ORDER BY a.updated_at DESC`).all()
+            .map(agentFromRow);
+    }
+    revision(agentId, revisionId) {
+        const agent = this.require(agentId, true);
+        const id = revisionId || agent.currentRevisionId;
+        const row = this.database.prepare(`
+      SELECT * FROM agent_revisions WHERE id = ? AND agent_id = ?
+    `).get(id, agent.id);
+        if (!row)
+            throw new AgentError('not_found', `Agent revision not found: ${id}`);
+        return revisionFromRow(row);
+    }
+    rawAgent(id) {
+        return this.database.prepare('SELECT 1 FROM agents WHERE id = ?').get(id);
+    }
+    insertRevision(id, agentId, number, definition, timestamp) {
+        this.database.prepare(`
+      INSERT INTO agent_revisions
+        (id, agent_id, revision_number, definition_hash, definition_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(id, agentId, number, definitionHash(definition), JSON.stringify(definition), timestamp);
+    }
+}

package/dist/agents.d.ts

@@ -0,0 +1,39 @@
+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;
+    updateAgent(id: string, patch: AgentPatch): AgentRecord;
+    deleteAgent(id: string): AgentRecord;
+    getAgent(id: string, includeDeleted?: boolean): AgentRecord | null;
+    listAgents(includeDeleted?: boolean): AgentRecord[];
+    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(): Promise<void>;
+    private publish;
+}

package/dist/agents.js

@@ -0,0 +1,129 @@
+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);
+    }
+    updateAgent(id, patch) {
+        return this.agentStore.update(id, patch);
+    }
+    deleteAgent(id) {
+        return this.agentStore.delete(id);
+    }
+    getAgent(id, includeDeleted = false) {
+        return this.agentStore.get(id, includeDeleted);
+    }
+    listAgents(includeDeleted = false) {
+        return this.agentStore.list(includeDeleted);
+    }
+    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(),
+        };
+    }
+    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/agents.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/agents.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../cli/run.js';
+void runCli().then((code) => {
+    process.exitCode = code;
+});

package/dist/bin/fatal.d.ts

@@ -0,0 +1 @@
+export declare function fatal(error: unknown): void;

package/dist/bin/fatal.js

@@ -0,0 +1,5 @@
+export function fatal(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`amalgm-agents: ${message}\n`);
+    process.exitCode = 1;
+}

package/dist/bin/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/mcp.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { parseArgs } from '../cli/args.js';
+import { openAgents } from '../cli/open.js';
+import { createMcpServer } from '../mcp/server.js';
+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>] [--drivers <a.js,b.js>]\n');
+        return;
+    }
+    const agents = await openAgents(args);
+    const server = createMcpServer({ agents });
+    const stop = await server.start();
+    const close = () => void stop().then(() => agents.close()).catch(fatal);
+    process.once('SIGTERM', close);
+    process.once('SIGINT', close);
+}
+void main().catch(fatal);

package/dist/bin/rest.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/rest.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { parseArgs, flag } from '../cli/args.js';
+import { openAgents } from '../cli/open.js';
+import { createRestServer } from '../http/server.js';
+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-rest [--host 127.0.0.1] [--port 4317] [--token value]\n');
+        return;
+    }
+    const agents = await openAgents(args);
+    const token = flag(args, 'token') || process.env.AMALGM_AGENTS_TOKEN;
+    const rest = createRestServer({ agents, ...(token ? { token } : {}) });
+    const address = await rest.listen(Number(flag(args, 'port') || 4317), flag(args, 'host') || '127.0.0.1');
+    process.stderr.write(`amalgm-agents REST listening on http://${address.address}:${address.port}\n`);
+    const close = () => void rest.close().then(() => agents.close()).catch(fatal);
+    process.once('SIGTERM', close);
+    process.once('SIGINT', close);
+}
+void main().catch(fatal);

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

@@ -0,0 +1,3 @@
+import type { Agents } from '../agents.js';
+import type { ParsedArgs } from './args.js';
+export declare function runAgentCommand(agents: Agents, args: ParsedArgs): unknown;

package/dist/cli/agent-commands.js

@@ -0,0 +1,23 @@
+import { AgentError } from '../errors.js';
+import { enabled } from './args.js';
+import { readObjectFile } from './files.js';
+export function runAgentCommand(agents, args) {
+    const [, action, first, second] = args.words;
+    if (action === 'list')
+        return { agents: agents.listAgents(enabled(args, 'include-deleted')) };
+    if (action === 'show' && first) {
+        const agent = agents.getAgent(first, enabled(args, 'include-deleted'));
+        if (!agent)
+            throw new AgentError('not_found', `Agent not found: ${first}`);
+        return { agent };
+    }
+    if (action === 'create' && first) {
+        return { agent: agents.createAgent(readObjectFile(first)) };
+    }
+    if (action === 'update' && first && second) {
+        return { agent: agents.updateAgent(first, readObjectFile(second)) };
+    }
+    if (action === 'delete' && first)
+        return { agent: agents.deleteAgent(first) };
+    throw new AgentError('invalid_input', 'Unknown or incomplete agent command. Run with --help.');
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedArgs {
+    words: string[];
+    flags: Map<string, string | boolean>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function flag(args: ParsedArgs, name: string): string | undefined;
+export declare function enabled(args: ParsedArgs, name: string): boolean;

package/dist/cli/args.js

@@ -0,0 +1,31 @@
+export function parseArgs(argv) {
+    const words = [];
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const item = argv[index];
+        if (!item?.startsWith('--')) {
+            if (item !== undefined)
+                words.push(item);
+            continue;
+        }
+        const [rawName, inline] = item.slice(2).split('=', 2);
+        const next = argv[index + 1];
+        if (inline !== undefined)
+            flags.set(rawName || '', inline);
+        else if (next !== undefined && !next.startsWith('--')) {
+            flags.set(rawName || '', next);
+            index += 1;
+        }
+        else
+            flags.set(rawName || '', true);
+    }
+    return { words, flags };
+}
+export function flag(args, name) {
+    const value = args.flags.get(name);
+    return typeof value === 'string' ? value : undefined;
+}
+export function enabled(args, name) {
+    const value = args.flags.get(name);
+    return value === true || value === 'true';
+}

package/dist/cli/files.d.ts

@@ -0,0 +1,2 @@
+export declare function readObjectFile(file: string): Record<string, unknown>;
+export declare function writeJson(value: unknown): void;

package/dist/cli/files.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AgentError } from '../errors.js';
+export function readObjectFile(file) {
+    const target = path.resolve(file);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(target, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new AgentError('invalid_input', `Cannot read JSON file ${target}: ${message}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new AgentError('invalid_input', `JSON file must contain an object: ${target}`);
+    }
+    return value;
+}
+export function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+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

@@ -0,0 +1,24 @@
+export const HELP = `amalgm-agents — local agent definitions and durable sessions
+
+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

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

package/dist/cli/open.js

@@ -0,0 +1,12 @@
+import { Agents } from '../agents.js';
+import { driverSpecifiers, loadDriverModules } from '../drivers.js';
+import { flag } from './args.js';
+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 } : {}),
+    });
+}