@amalgm/agents 0.2.0 → 0.2.1

package/dist/http/server.js

@@ -5,7 +5,9 @@ import { routeAgentConfig } from './config-routes.js';
 import { routeAgentBundles } from './bundle-routes.js';
 import { routeAgents } from './agent-routes.js';
 import { guardRequest, readJson, sendJson } from './request.js';
+import { routeSessions } from './session-routes.js';
 import { routeSkills } from './skill-routes.js';
+import { streamEvents } from './stream.js';
 export function createRestServer(options = {}) {
     const agents = options.agents || new Agents(options);
     const owned = !options.agents;
@@ -55,7 +57,11 @@ export function createRestServer(options = {}) {
             sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
             return;
         }
-        if (await routeAgents(context))
+        if (path[0] === 'sessions' && path[2] === 'events' && path[3] === 'stream' && request.method === 'GET') {
+            streamEvents(agents, path[1] || '', request, response, Number(url.searchParams.get('after') || 0));
+            return;
+        }
+        if (await routeAgents(context) || await routeSessions(context))
             return;
         sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
     }

package/dist/http/session-routes.d.ts

@@ -0,0 +1,2 @@
+import type { RouteContext } from '../http-types.js';
+export declare function routeSessions(context: RouteContext): Promise<boolean>;

package/dist/http/session-routes.js

@@ -0,0 +1,67 @@
+import { AgentError } from '../errors.js';
+export async function routeSessions(context) {
+    const [resource, id, child] = context.path;
+    if (resource !== 'sessions')
+        return false;
+    if (!id && context.method === 'GET') {
+        const agentId = context.url.searchParams.get('agent_id') || undefined;
+        const archived = context.url.searchParams.get('include_archived') === 'true';
+        context.json(200, { sessions: context.agents.listSessions(agentId, archived) });
+        return true;
+    }
+    if (!id && context.method === 'POST') {
+        const body = await context.body();
+        if (typeof body.agentId !== 'string')
+            throw new AgentError('invalid_input', 'agentId is required.');
+        context.json(201, { session: context.agents.startSession({
+                agentId: body.agentId,
+                ...(typeof body.revisionId === 'string' ? { revisionId: body.revisionId } : {}),
+                ...(typeof body.sessionId === 'string' ? { sessionId: body.sessionId } : {}),
+                ...(body.metadata ? { metadata: body.metadata } : {}),
+            }) });
+        return true;
+    }
+    if (!id)
+        throw new AgentError('not_found', 'Route not found.');
+    if (!child && context.method === 'GET') {
+        const session = context.agents.getSession(id);
+        if (!session)
+            throw new AgentError('not_found', `Session not found: ${id}`);
+        context.json(200, { session });
+        return true;
+    }
+    if (!child && context.method === 'DELETE') {
+        context.json(200, { session: context.agents.archiveSession(id) });
+        return true;
+    }
+    if (child === 'events' && context.method === 'GET') {
+        const after = Number(context.url.searchParams.get('after') || 0);
+        const limit = Number(context.url.searchParams.get('limit') || 200);
+        context.json(200, { events: context.agents.listEvents(id, after, limit) });
+        return true;
+    }
+    if (child === 'turns' && context.method === 'GET') {
+        context.json(200, { turns: context.agents.listTurns(id) });
+        return true;
+    }
+    if (child === 'cancel' && context.method === 'POST') {
+        context.json(202, { turn: context.agents.cancelSession(id) });
+        return true;
+    }
+    if (child === 'messages' && context.method === 'POST') {
+        const body = await context.body();
+        if (body.message === undefined)
+            throw new AgentError('invalid_input', 'message is required.');
+        const enqueued = context.agents.enqueue(id, {
+            message: body.message,
+            ...(typeof body.idempotencyKey === 'string' ? { idempotencyKey: body.idempotencyKey } : {}),
+        });
+        if (body.wait === false) {
+            context.json(202, { turn: enqueued.turn, duplicate: enqueued.duplicate });
+            return true;
+        }
+        context.json(200, { turn: await enqueued.completion, duplicate: enqueued.duplicate });
+        return true;
+    }
+    return false;
+}

package/dist/http/stream.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Agents } from '../agents.js';
+export declare function streamEvents(agents: Agents, sessionId: string, request: IncomingMessage, response: ServerResponse, after?: number): void;

package/dist/http/stream.js

@@ -0,0 +1,30 @@
+import { AgentError } from '../errors.js';
+export function streamEvents(agents, sessionId, request, response, after = 0) {
+    if (!agents.getSession(sessionId))
+        throw new AgentError('not_found', `Session not found: ${sessionId}`);
+    response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+    });
+    response.flushHeaders();
+    let last = after;
+    const write = (event) => {
+        if (event.sequence <= last || response.destroyed)
+            return;
+        last = event.sequence;
+        response.write(`id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+    };
+    for (const event of agents.listEvents(sessionId, after, 1000))
+        write(event);
+    const unsubscribe = agents.subscribe(sessionId, write);
+    const heartbeat = setInterval(() => {
+        if (!response.destroyed)
+            response.write(': heartbeat\n\n');
+    }, 15_000);
+    heartbeat.unref();
+    request.once('close', () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { Agents } from './agents.js';
 export { AgentError, asAgentError } from './errors.js';
+export { defineDriver, driverSpecifiers, loadDriverModules } from './drivers.js';
 export { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
+export { messageText, normalizeMessage } from './messages.js';
 export type * from './types.js';
 export { buildCanonicalSkillRoots, classifySkillRoot } from './skills/roots.js';
 export type { SkillRootClassification, SkillRootOptions } from './skills/roots.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 export { Agents } from './agents.js';
 export { AgentError, asAgentError } from './errors.js';
+export { defineDriver, driverSpecifiers, loadDriverModules } from './drivers.js';
 export { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
+export { messageText, normalizeMessage } from './messages.js';
 export { buildCanonicalSkillRoots, classifySkillRoot } from './skills/roots.js';
 export { parseSkillFrontmatter, scanInstalledSkills } from './skills/scanner.js';
 export { normalizeAgentConfig, stableConfigId } from './config/schema.js';

package/dist/mcp/agent-tools.js

@@ -41,7 +41,7 @@ export function agentTools(agents) {
         },
         {
             name: 'agents_delete',
-            description: 'Tombstone an agent identity while retaining its immutable revisions.',
+            description: 'Delete an agent while retaining immutable session history.',
             inputSchema: objectSchema({ agent_id: string }, ['agent_id']),
             handler(input) {
                 return toolResult({ agent: agents.deleteAgent(stringArg(input, 'agent_id')) });

package/dist/mcp/session-tools.d.ts

@@ -0,0 +1,3 @@
+import type { Agents } from '../agents.js';
+import type { McpTool } from './types.js';
+export declare function sessionTools(agents: Agents): McpTool[];

package/dist/mcp/session-tools.js

@@ -0,0 +1,81 @@
+import { AgentError } from '../errors.js';
+import { objectSchema, toolResult } from './helpers.js';
+const string = { type: 'string' };
+function text(input, ...keys) {
+    for (const key of keys) {
+        if (typeof input[key] === 'string' && input[key])
+            return input[key];
+    }
+    return undefined;
+}
+function resolveAgentId(agents, requested) {
+    const normalized = requested.toLowerCase();
+    const matches = agents.listAgents().filter(({ id, definition }) => {
+        return id.toLowerCase() === normalized || definition.name.toLowerCase() === normalized;
+    });
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1)
+        throw new AgentError('conflict', `Agent name is ambiguous: ${requested}`);
+    throw new AgentError('not_found', `Agent not found: ${requested}`);
+}
+export function sessionTools(agents) {
+    return [
+        {
+            name: 'agents_get_conversation',
+            description: 'Read one durable agent session, including its turns and ordered events.',
+            inputSchema: objectSchema({ conversation_id: string, session_id: string, after: { type: 'number' } }),
+            handler(input) {
+                const id = text(input, 'conversation_id', 'session_id');
+                if (!id)
+                    throw new AgentError('invalid_input', 'conversation_id is required.');
+                return toolResult({
+                    conversation_id: id,
+                    session: agents.getSession(id),
+                    turns: agents.listTurns(id),
+                    events: agents.listEvents(id, Number(input.after || 0)),
+                });
+            },
+        },
+        {
+            name: 'talk_to_agent',
+            description: 'Start or continue a durable agent session. Agents sessions are not Chat conversations.',
+            inputSchema: objectSchema({
+                agent: string,
+                agent_id: string,
+                conversation_id: string,
+                session_id: string,
+                description: string,
+                prompt: string,
+                message: { type: ['string', 'object'] },
+                idempotency_key: string,
+                run_in_background: { type: 'boolean' },
+            }),
+            async handler(input) {
+                const requestedAgent = text(input, 'agent', 'agent_id');
+                if (!requestedAgent)
+                    throw new AgentError('invalid_input', 'agent is required.');
+                const agentId = resolveAgentId(agents, requestedAgent);
+                const message = input.message ?? input.prompt;
+                if (message === undefined)
+                    throw new AgentError('invalid_input', 'prompt or message is required.');
+                const sessionId = text(input, 'conversation_id', 'session_id');
+                const idempotencyKey = text(input, 'idempotency_key');
+                const call = agents.talk(agentId, {
+                    message: message,
+                    ...(sessionId ? { sessionId } : {}),
+                    ...(idempotencyKey ? { idempotencyKey } : {}),
+                });
+                const base = {
+                    conversation_id: call.session.id,
+                    session: call.session,
+                    turn: call.turn,
+                    duplicate: call.duplicate,
+                };
+                if (input.run_in_background === true)
+                    return toolResult(base);
+                return toolResult({ ...base, turn: await call.completion });
+            },
+        },
+    ];
+}

package/dist/mcp/tools.js

@@ -1,4 +1,5 @@
 import { agentTools } from './agent-tools.js';
+import { sessionTools } from './session-tools.js';
 export function createMcpTools(agents) {
-    return agentTools(agents);
+    return [...agentTools(agents), ...sessionTools(agents)];
 }

package/dist/messages.d.ts

@@ -0,0 +1,3 @@
+import type { AgentMessage } from './types.js';
+export declare function normalizeMessage(value: string | AgentMessage, role?: AgentMessage['role']): AgentMessage;
+export declare function messageText(message: AgentMessage): string;

package/dist/messages.js

@@ -0,0 +1,56 @@
+import { AgentError } from './errors.js';
+import { isObject } from './json.js';
+function normalizePart(value) {
+    if (!isObject(value))
+        throw new AgentError('invalid_input', 'message parts must be objects.');
+    if (value.type === 'text') {
+        if (typeof value.text !== 'string' || !value.text) {
+            throw new AgentError('invalid_input', 'text parts require non-empty text.');
+        }
+        return { type: 'text', text: value.text };
+    }
+    if (value.type === 'reference') {
+        if (typeof value.uri !== 'string' || !value.uri.trim()) {
+            throw new AgentError('invalid_input', 'reference parts require uri.');
+        }
+        return {
+            type: 'reference',
+            uri: value.uri.trim(),
+            name: typeof value.name === 'string' && value.name.trim() ? value.name.trim() : null,
+            mediaType: typeof value.mediaType === 'string' && value.mediaType.trim()
+                ? value.mediaType.trim()
+                : null,
+        };
+    }
+    if (value.type === 'data') {
+        if (typeof value.name !== 'string' || !value.name.trim() || value.data === undefined) {
+            throw new AgentError('invalid_input', 'data parts require name and data.');
+        }
+        return {
+            type: 'data',
+            name: value.name.trim(),
+            data: JSON.parse(JSON.stringify(value.data)),
+        };
+    }
+    throw new AgentError('invalid_input', `Unsupported message part: ${String(value.type)}`);
+}
+export function normalizeMessage(value, role = 'user') {
+    if (typeof value === 'string') {
+        if (!value)
+            throw new AgentError('invalid_input', 'message must not be empty.');
+        return { role, parts: [{ type: 'text', text: value }] };
+    }
+    if (!isObject(value) || !Array.isArray(value.parts) || value.parts.length === 0) {
+        throw new AgentError('invalid_input', 'message requires at least one part.');
+    }
+    const validRoles = new Set(['user', 'assistant', 'system']);
+    if (!validRoles.has(value.role))
+        throw new AgentError('invalid_input', 'message role is invalid.');
+    return { role: value.role, parts: value.parts.map(normalizePart) };
+}
+export function messageText(message) {
+    return message.parts
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('');
+}

package/dist/rows.d.ts

@@ -1,4 +1,7 @@
-import type { AgentRecord, AgentRevision } from './types.js';
+import type { AgentRecord, AgentRevision, AgentSession, AgentTurn, SessionEvent } from './types.js';
 export type Row = Record<string, unknown>;
 export declare function revisionFromRow(row: Row): AgentRevision;
 export declare function agentFromRow(row: Row): AgentRecord;
+export declare function sessionFromRow(row: Row): AgentSession;
+export declare function turnFromRow(row: Row): AgentTurn;
+export declare function eventFromRow(row: Row): SessionEvent;

package/dist/rows.js

@@ -24,3 +24,42 @@ export function agentFromRow(row) {
         deletedAt: nullable(row.deleted_at),
     };
 }
+export function sessionFromRow(row) {
+    return {
+        id: String(row.id),
+        agentId: String(row.agent_id),
+        agentRevisionId: String(row.agent_revision_id),
+        agentRevision: Number(row.agent_revision_number),
+        status: String(row.status),
+        driverSessionId: nullable(row.driver_session_id),
+        metadata: parseObject(String(row.metadata_json)),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        archivedAt: nullable(row.archived_at),
+    };
+}
+export function turnFromRow(row) {
+    return {
+        id: String(row.id),
+        sessionId: String(row.session_id),
+        idempotencyKey: String(row.idempotency_key),
+        status: String(row.status),
+        input: JSON.parse(String(row.input_json)),
+        result: row.result_json ? parseObject(String(row.result_json)) : null,
+        error: row.error_json ? parseObject(String(row.error_json)) : null,
+        createdAt: String(row.created_at),
+        startedAt: nullable(row.started_at),
+        completedAt: nullable(row.completed_at),
+    };
+}
+export function eventFromRow(row) {
+    return {
+        id: String(row.id),
+        sessionId: String(row.session_id),
+        turnId: nullable(row.turn_id),
+        sequence: Number(row.sequence),
+        type: String(row.type),
+        data: parseObject(String(row.data_json)),
+        createdAt: String(row.created_at),
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,29 @@
+import type { AgentStore } from './agent-store.js';
+import type { EventStore } from './event-store.js';
+import type { SessionStore } from './session-store.js';
+import type { TurnStore } from './turn-store.js';
+import type { AgentDriver, AgentTurn, EnqueuedTurn, SendInput } from './types.js';
+export interface RuntimeLimits {
+    maxInputBytes: number;
+    maxEventBytes: number;
+    turnTimeoutMs: number;
+}
+export declare class AgentRuntime {
+    private readonly agents;
+    private readonly sessions;
+    private readonly turns;
+    private readonly events;
+    private readonly limits;
+    private readonly drivers;
+    private readonly active;
+    constructor(agents: AgentStore, sessions: SessionStore, turns: TurnStore, events: EventStore, limits: RuntimeLimits, drivers?: AgentDriver[]);
+    register(driver: AgentDriver): void;
+    driverIds(): string[];
+    enqueue(sessionId: string, input: SendInput): EnqueuedTurn;
+    send(sessionId: string, input: SendInput): Promise<AgentTurn>;
+    cancel(sessionId: string): AgentTurn;
+    shutdown(): Promise<void>;
+    private execute;
+    private emit;
+    private normalizeResult;
+}

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 };
+}