@amalgm/agents 0.1.0

package/dist/runtime.js

@@ -0,0 +1,176 @@
+import { AgentError, asAgentError } from './errors.js';
+import { assertByteLimit, isObject } from './json.js';
+import { normalizeMessage } from './messages.js';
+export class AgentRuntime {
+    agents;
+    sessions;
+    turns;
+    events;
+    limits;
+    drivers = new Map();
+    active = new Map();
+    constructor(agents, sessions, turns, events, limits, drivers = []) {
+        this.agents = agents;
+        this.sessions = sessions;
+        this.turns = turns;
+        this.events = events;
+        this.limits = limits;
+        for (const driver of drivers)
+            this.register(driver);
+    }
+    register(driver) {
+        if (!driver || typeof driver.id !== 'string' || typeof driver.run !== 'function') {
+            throw new AgentError('invalid_input', 'Agent drivers require id and run.');
+        }
+        if (this.drivers.has(driver.id)) {
+            throw new AgentError('conflict', `Agent driver already registered: ${driver.id}`);
+        }
+        this.drivers.set(driver.id, driver);
+    }
+    driverIds() {
+        return [...this.drivers.keys()].sort();
+    }
+    enqueue(sessionId, input) {
+        const message = normalizeMessage(input.message, 'user');
+        assertByteLimit(message, this.limits.maxInputBytes, 'message');
+        const reserved = this.turns.reserve(sessionId, message, input.idempotencyKey);
+        if (reserved.duplicate) {
+            const running = this.active.get(reserved.turn.id);
+            return {
+                turn: reserved.turn,
+                completion: running?.completion || Promise.resolve(reserved.turn),
+                duplicate: true,
+            };
+        }
+        const controller = new AbortController();
+        const completion = this.execute(reserved.turn, controller);
+        this.active.set(reserved.turn.id, { controller, completion });
+        void completion.then(() => this.active.delete(reserved.turn.id), () => this.active.delete(reserved.turn.id));
+        return { turn: reserved.turn, completion, duplicate: false };
+    }
+    async send(sessionId, input) {
+        return this.enqueue(sessionId, input).completion;
+    }
+    cancel(sessionId) {
+        const turn = this.turns.active(sessionId);
+        if (!turn)
+            throw new AgentError('conflict', 'Session has no active turn.');
+        const execution = this.active.get(turn.id);
+        if (!execution)
+            throw new AgentError('conflict', 'Active turn is not owned by this process.');
+        const cancelling = this.turns.requestCancellation(turn.id);
+        execution.controller.abort(new AgentError('cancelled', 'Turn cancelled by caller.'));
+        return cancelling;
+    }
+    async shutdown() {
+        const executions = [...this.active.entries()];
+        for (const [turnId, execution] of executions) {
+            const turn = this.turns.get(turnId);
+            if (turn && (turn.status === 'queued' || turn.status === 'running')) {
+                this.turns.requestCancellation(turnId);
+            }
+            execution.controller.abort(new Error('Agents service shutting down.'));
+        }
+        await Promise.allSettled(executions.map(([, execution]) => execution.completion));
+    }
+    async execute(turn, controller) {
+        const session = this.sessions.require(turn.sessionId);
+        const revision = this.agents.revision(session.agentId, session.agentRevisionId);
+        const driver = this.drivers.get(revision.definition.driver.id);
+        if (!driver) {
+            return this.turns.fail(turn.id, failure('driver_unavailable', `Agent driver is not registered: ${revision.definition.driver.id}`));
+        }
+        this.turns.markRunning(turn.id);
+        let timedOut = false;
+        const timer = this.limits.turnTimeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                controller.abort(new Error('Turn timed out.'));
+            }, this.limits.turnTimeoutMs)
+            : null;
+        timer?.unref();
+        try {
+            const result = await driver.run({
+                agent: revision,
+                session,
+                turn: this.turns.require(turn.id),
+                history: this.turns.history(session.id, turn.id),
+                input: turn.input,
+                driverSessionId: session.driverSessionId,
+            }, {
+                signal: controller.signal,
+                emit: (event) => this.emit(session.id, turn.id, event),
+            });
+            if (controller.signal.aborted) {
+                if (this.turns.require(turn.id).status === 'cancelling')
+                    return this.turns.cancel(turn.id);
+                return this.turns.fail(turn.id, failure('turn_timeout', 'Turn timed out.'));
+            }
+            const normalized = this.normalizeResult(result);
+            if (normalized.message) {
+                const data = {
+                    message: normalized.message,
+                };
+                assertByteLimit(data, this.limits.maxEventBytes, 'driver result message');
+                this.events.append(session.id, turn.id, 'message', data);
+            }
+            if (normalized.driverSessionId) {
+                this.sessions.setDriverSession(session.id, normalized.driverSessionId);
+            }
+            const storedResult = {
+                metadata: normalized.metadata || {},
+                ...(normalized.driverSessionId ? { driverSessionId: normalized.driverSessionId } : {}),
+            };
+            assertByteLimit(storedResult, this.limits.maxEventBytes, 'driver result');
+            return this.turns.complete(turn.id, storedResult);
+        }
+        catch (error) {
+            const current = this.turns.require(turn.id);
+            if (current.status === 'cancelling')
+                return this.turns.cancel(turn.id);
+            const normalized = asAgentError(error);
+            return this.turns.fail(turn.id, failure(timedOut ? 'turn_timeout' : normalized.code === 'internal' ? 'driver_error' : normalized.code, normalized.message, normalized.details));
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    emit(sessionId, turnId, event) {
+        if (!event || typeof event.type !== 'string' || !event.type.trim() || !isObject(event.data)) {
+            throw new AgentError('invalid_input', 'Driver events require type and object data.');
+        }
+        if (/^(session|turn)\./.test(event.type)) {
+            throw new AgentError('invalid_input', 'Driver events cannot use reserved session.* or turn.* types.');
+        }
+        assertByteLimit(event.data, this.limits.maxEventBytes, 'driver event');
+        if (event.type === 'message' && event.data.message) {
+            const message = normalizeMessage(event.data.message, 'assistant');
+            if (message.role !== 'assistant') {
+                throw new AgentError('invalid_input', 'Driver message events must have assistant role.');
+            }
+            return this.events.append(sessionId, turnId, 'message', { message: message });
+        }
+        return this.events.append(sessionId, turnId, event.type.trim(), event.data);
+    }
+    normalizeResult(result) {
+        if (!result)
+            return {};
+        const normalized = {};
+        if (result.message) {
+            normalized.message = normalizeMessage(result.message, 'assistant');
+            if (normalized.message.role !== 'assistant') {
+                throw new AgentError('invalid_input', 'Driver result messages must have assistant role.');
+            }
+        }
+        if (typeof result.driverSessionId === 'string' && result.driverSessionId.trim()) {
+            normalized.driverSessionId = result.driverSessionId.trim();
+        }
+        if (result.metadata && isObject(result.metadata))
+            normalized.metadata = result.metadata;
+        return normalized;
+    }
+}
+function failure(code, message, details = {}) {
+    return { code, message, details };
+}

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import type Database from 'better-sqlite3';
+export declare function migrate(database: Database.Database): void;

package/dist/schema.js

@@ -0,0 +1,127 @@
+const SCHEMA_VERSION = 2;
+function migrateRevisionHashes(database) {
+    database.pragma('foreign_keys = OFF');
+    try {
+        database.exec(`
+      BEGIN IMMEDIATE;
+
+      CREATE TABLE agent_revisions_next (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL REFERENCES agents(id),
+        revision_number INTEGER NOT NULL,
+        definition_hash TEXT NOT NULL,
+        definition_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        UNIQUE(agent_id, revision_number)
+      );
+
+      INSERT INTO agent_revisions_next
+        (id, agent_id, revision_number, definition_hash, definition_json, created_at)
+      SELECT id, agent_id, revision_number, definition_hash, definition_json, created_at
+      FROM agent_revisions;
+
+      DROP TABLE agent_revisions;
+      ALTER TABLE agent_revisions_next RENAME TO agent_revisions;
+
+      CREATE INDEX agent_revisions_agent_idx
+        ON agent_revisions(agent_id, revision_number DESC);
+
+      PRAGMA user_version = ${SCHEMA_VERSION};
+      COMMIT;
+    `);
+    }
+    catch (error) {
+        if (database.inTransaction)
+            database.exec('ROLLBACK');
+        throw error;
+    }
+    finally {
+        database.pragma('foreign_keys = ON');
+    }
+}
+export function migrate(database) {
+    const current = database.pragma('user_version', { simple: true });
+    if (current > SCHEMA_VERSION) {
+        throw new Error(`Agents database version ${current} is newer than supported version ${SCHEMA_VERSION}.`);
+    }
+    if (current === SCHEMA_VERSION)
+        return;
+    if (current === 1) {
+        migrateRevisionHashes(database);
+        return;
+    }
+    database.exec(`
+    CREATE TABLE agents (
+      id TEXT PRIMARY KEY,
+      current_revision_id TEXT,
+      current_revision_number INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      deleted_at TEXT
+    );
+
+    CREATE TABLE agent_revisions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id),
+      revision_number INTEGER NOT NULL,
+      definition_hash TEXT NOT NULL,
+      definition_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(agent_id, revision_number)
+    );
+
+    CREATE TABLE sessions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id),
+      agent_revision_id TEXT NOT NULL REFERENCES agent_revisions(id),
+      agent_revision_number INTEGER NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('active', 'archived')),
+      driver_session_id TEXT,
+      metadata_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      archived_at TEXT
+    );
+
+    CREATE TABLE turns (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES sessions(id),
+      idempotency_key TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN (
+        'queued', 'running', 'cancelling', 'completed', 'failed', 'cancelled', 'interrupted'
+      )),
+      input_json TEXT NOT NULL,
+      result_json TEXT,
+      error_json TEXT,
+      created_at TEXT NOT NULL,
+      started_at TEXT,
+      completed_at TEXT,
+      UNIQUE(session_id, idempotency_key)
+    );
+
+    CREATE TABLE session_events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES sessions(id),
+      turn_id TEXT REFERENCES turns(id),
+      sequence INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      data_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(session_id, sequence)
+    );
+
+    CREATE INDEX agent_revisions_agent_idx
+      ON agent_revisions(agent_id, revision_number DESC);
+    CREATE INDEX sessions_agent_idx
+      ON sessions(agent_id, updated_at DESC);
+    CREATE INDEX turns_session_idx
+      ON turns(session_id, created_at ASC);
+    CREATE UNIQUE INDEX turns_one_active_per_session_idx
+      ON turns(session_id)
+      WHERE status IN ('queued', 'running', 'cancelling');
+    CREATE INDEX session_events_session_idx
+      ON session_events(session_id, sequence ASC);
+
+    PRAGMA user_version = ${SCHEMA_VERSION};
+  `);
+}

package/dist/session-store.d.ts

@@ -0,0 +1,15 @@
+import type Database from 'better-sqlite3';
+import type { AgentRevision, AgentSession, JsonObject } from './types.js';
+import type { EventStore } from './event-store.js';
+export declare class SessionStore {
+    private readonly database;
+    private readonly events;
+    private readonly now;
+    constructor(database: Database.Database, events: EventStore, now: () => string);
+    create(revision: AgentRevision, sessionId?: string, metadata?: JsonObject): AgentSession;
+    get(id: string): AgentSession | null;
+    require(id: string): AgentSession;
+    list(agentId?: string, includeArchived?: boolean): AgentSession[];
+    archive(id: string, hasActiveTurn: boolean): AgentSession;
+    setDriverSession(id: string, driverSessionId: string): void;
+}

package/dist/session-store.js

@@ -0,0 +1,83 @@
+import { AgentError } from './errors.js';
+import { newId, optionalId, requireId } from './ids.js';
+import { assertJsonObject } from './json.js';
+import { sessionFromRow } from './rows.js';
+export class SessionStore {
+    database;
+    events;
+    now;
+    constructor(database, events, now) {
+        this.database = database;
+        this.events = events;
+        this.now = now;
+    }
+    create(revision, sessionId, metadata = {}) {
+        const id = optionalId(sessionId, 'session id') || newId('session');
+        if (this.get(id))
+            throw new AgentError('conflict', `Session id already exists: ${id}`);
+        const timestamp = this.now();
+        const storedMetadata = assertJsonObject(metadata, 'metadata');
+        let event;
+        this.database.transaction(() => {
+            this.database.prepare(`
+        INSERT INTO sessions
+          (id, agent_id, agent_revision_id, agent_revision_number, status, metadata_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, 'active', ?, ?, ?)
+      `).run(id, revision.agentId, revision.id, revision.number, JSON.stringify(storedMetadata), timestamp, timestamp);
+            event = this.events.write(id, null, 'session.started', {
+                agentId: revision.agentId,
+                agentRevisionId: revision.id,
+                agentRevision: revision.number,
+            });
+        })();
+        if (event)
+            this.events.announce(event);
+        return this.require(id);
+    }
+    get(id) {
+        const clean = requireId(id, 'session id');
+        const row = this.database.prepare('SELECT * FROM sessions WHERE id = ?').get(clean);
+        return row ? sessionFromRow(row) : null;
+    }
+    require(id) {
+        const session = this.get(id);
+        if (!session)
+            throw new AgentError('not_found', `Session not found: ${id}`);
+        return session;
+    }
+    list(agentId, includeArchived = false) {
+        const filters = [];
+        const values = [];
+        if (agentId) {
+            filters.push('agent_id = ?');
+            values.push(requireId(agentId, 'agent id'));
+        }
+        if (!includeArchived)
+            filters.push("status = 'active'");
+        const where = filters.length ? ` WHERE ${filters.join(' AND ')}` : '';
+        return this.database.prepare(`SELECT * FROM sessions${where} ORDER BY updated_at DESC`).all(...values)
+            .map(sessionFromRow);
+    }
+    archive(id, hasActiveTurn) {
+        const session = this.require(id);
+        if (hasActiveTurn)
+            throw new AgentError('conflict', 'Cannot archive a session with an active turn.');
+        if (session.status === 'archived')
+            return session;
+        const timestamp = this.now();
+        let event;
+        this.database.transaction(() => {
+            this.database.prepare(`
+        UPDATE sessions SET status = 'archived', archived_at = ?, updated_at = ? WHERE id = ?
+      `).run(timestamp, timestamp, session.id);
+            event = this.events.write(session.id, null, 'session.archived', {});
+        })();
+        if (event)
+            this.events.announce(event);
+        return this.require(session.id);
+    }
+    setDriverSession(id, driverSessionId) {
+        this.database.prepare('UPDATE sessions SET driver_session_id = ?, updated_at = ? WHERE id = ?')
+            .run(driverSessionId, this.now(), requireId(id, 'session id'));
+    }
+}

package/dist/turn-store.d.ts

@@ -0,0 +1,31 @@
+import type Database from 'better-sqlite3';
+import type { EventStore } from './event-store.js';
+import type { SessionStore } from './session-store.js';
+import type { AgentFailure, AgentMessage, AgentTurn, JsonObject } from './types.js';
+export declare class TurnStore {
+    private readonly database;
+    private readonly sessions;
+    private readonly events;
+    private readonly now;
+    constructor(database: Database.Database, sessions: SessionStore, events: EventStore, now: () => string);
+    reserve(sessionId: string, input: AgentMessage, key?: string): {
+        turn: AgentTurn;
+        duplicate: boolean;
+    };
+    markRunning(id: string): AgentTurn;
+    requestCancellation(id: string): AgentTurn;
+    complete(id: string, result: JsonObject): AgentTurn;
+    fail(id: string, failure: AgentFailure): AgentTurn;
+    cancel(id: string): AgentTurn;
+    interrupt(id: string, failure: AgentFailure): AgentTurn;
+    get(id: string): AgentTurn | null;
+    require(id: string): AgentTurn;
+    list(sessionId: string): AgentTurn[];
+    active(sessionId: string): AgentTurn | null;
+    history(sessionId: string, beforeTurnId?: string): AgentMessage[];
+    recoverInterrupted(): number;
+    private byKey;
+    private transition;
+    private terminal;
+    private touch;
+}

package/dist/turn-store.js

@@ -0,0 +1,164 @@
+import { AgentError } from './errors.js';
+import { newId, optionalKey, randomKey, requireId } from './ids.js';
+import { isObject } from './json.js';
+import { turnFromRow } from './rows.js';
+const ACTIVE_SQL = `status IN ('queued', 'running', 'cancelling')`;
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'interrupted']);
+export class TurnStore {
+    database;
+    sessions;
+    events;
+    now;
+    constructor(database, sessions, events, now) {
+        this.database = database;
+        this.sessions = sessions;
+        this.events = events;
+        this.now = now;
+    }
+    reserve(sessionId, input, key) {
+        const session = this.sessions.require(sessionId);
+        if (session.status !== 'active')
+            throw new AgentError('conflict', 'Session is archived.');
+        const idempotencyKey = optionalKey(key) || randomKey('turn-key');
+        const existing = this.byKey(session.id, idempotencyKey);
+        if (existing)
+            return { turn: existing, duplicate: true };
+        if (this.active(session.id))
+            throw new AgentError('conflict', 'Session already has an active turn.');
+        const id = newId('turn');
+        const timestamp = this.now();
+        let event;
+        try {
+            this.database.transaction(() => {
+                this.database.prepare(`
+          INSERT INTO turns (id, session_id, idempotency_key, status, input_json, created_at)
+          VALUES (?, ?, ?, 'queued', ?, ?)
+        `).run(id, session.id, idempotencyKey, JSON.stringify(input), timestamp);
+                event = this.events.write(session.id, id, 'turn.input', { message: input });
+                this.touch(session.id, timestamp);
+            })();
+        }
+        catch (error) {
+            const racedDuplicate = this.byKey(session.id, idempotencyKey);
+            if (racedDuplicate)
+                return { turn: racedDuplicate, duplicate: true };
+            if (isUniqueConstraint(error)) {
+                throw new AgentError('conflict', 'Session already has an active turn.');
+            }
+            throw error;
+        }
+        if (event)
+            this.events.announce(event);
+        return { turn: this.require(id), duplicate: false };
+    }
+    markRunning(id) {
+        return this.transition(id, 'running', 'turn.running', true);
+    }
+    requestCancellation(id) {
+        return this.transition(id, 'cancelling', 'turn.cancelling');
+    }
+    complete(id, result) {
+        return this.terminal(id, 'completed', result, null, 'turn.completed');
+    }
+    fail(id, failure) {
+        return this.terminal(id, 'failed', null, failure, 'turn.failed');
+    }
+    cancel(id) {
+        return this.terminal(id, 'cancelled', null, null, 'turn.cancelled');
+    }
+    interrupt(id, failure) {
+        return this.terminal(id, 'interrupted', null, failure, 'turn.interrupted');
+    }
+    get(id) {
+        const row = this.database.prepare('SELECT * FROM turns WHERE id = ?').get(requireId(id, 'turn id'));
+        return row ? turnFromRow(row) : null;
+    }
+    require(id) {
+        const turn = this.get(id);
+        if (!turn)
+            throw new AgentError('not_found', `Turn not found: ${id}`);
+        return turn;
+    }
+    list(sessionId) {
+        this.sessions.require(sessionId);
+        return this.database.prepare('SELECT * FROM turns WHERE session_id = ? ORDER BY created_at ASC')
+            .all(sessionId).map(turnFromRow);
+    }
+    active(sessionId) {
+        const row = this.database.prepare(`
+      SELECT * FROM turns WHERE session_id = ? AND ${ACTIVE_SQL} ORDER BY created_at DESC LIMIT 1
+    `).get(sessionId);
+        return row ? turnFromRow(row) : null;
+    }
+    history(sessionId, beforeTurnId) {
+        const messages = [];
+        for (const turn of this.list(sessionId)) {
+            if (turn.id === beforeTurnId)
+                break;
+            messages.push(turn.input);
+            for (const event of this.events.forTurn(turn.id)) {
+                const message = isObject(event.data.message) ? event.data.message : null;
+                if (event.type === 'message' && message)
+                    messages.push(message);
+            }
+        }
+        return messages;
+    }
+    recoverInterrupted() {
+        const rows = this.database.prepare(`SELECT * FROM turns WHERE ${ACTIVE_SQL}`).all();
+        for (const row of rows) {
+            this.interrupt(turnFromRow(row).id, {
+                code: 'process_restarted',
+                message: 'The owning process restarted before the driver settled.',
+                details: {},
+            });
+        }
+        return rows.length;
+    }
+    byKey(sessionId, key) {
+        const row = this.database.prepare('SELECT * FROM turns WHERE session_id = ? AND idempotency_key = ?')
+            .get(sessionId, key);
+        return row ? turnFromRow(row) : null;
+    }
+    transition(id, status, type, started = false) {
+        const turn = this.require(id);
+        const timestamp = this.now();
+        let event;
+        this.database.transaction(() => {
+            this.database.prepare(`UPDATE turns SET status = ?, started_at = COALESCE(started_at, ?) WHERE id = ?`)
+                .run(status, started ? timestamp : turn.startedAt, turn.id);
+            event = this.events.write(turn.sessionId, turn.id, type, {});
+            this.touch(turn.sessionId, timestamp);
+        })();
+        if (event)
+            this.events.announce(event);
+        return this.require(turn.id);
+    }
+    terminal(id, status, result, error, type) {
+        const turn = this.require(id);
+        if (TERMINAL.has(turn.status))
+            return turn;
+        const timestamp = this.now();
+        let event;
+        this.database.transaction(() => {
+            this.database.prepare(`
+        UPDATE turns SET status = ?, result_json = ?, error_json = ?, completed_at = ? WHERE id = ?
+      `).run(status, result && JSON.stringify(result), error && JSON.stringify(error), timestamp, turn.id);
+            const data = error ? { error: error } : {};
+            event = this.events.write(turn.sessionId, turn.id, type, data);
+            this.touch(turn.sessionId, timestamp);
+        })();
+        if (event)
+            this.events.announce(event);
+        return this.require(turn.id);
+    }
+    touch(sessionId, timestamp) {
+        this.database.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?').run(timestamp, sessionId);
+    }
+}
+function isUniqueConstraint(error) {
+    return Boolean(error
+        && typeof error === 'object'
+        && 'code' in error
+        && String(error.code).startsWith('SQLITE_CONSTRAINT'));
+}