@amalgm/agents 0.1.0

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/http-types.d.ts

@@ -0,0 +1,23 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { Agents } from './agents.js';
+import type { AgentsOptions } from './types.js';
+export interface RestServerOptions extends AgentsOptions {
+    agents?: Agents;
+    token?: string;
+    bodyLimitBytes?: number;
+}
+export interface RestServer {
+    agents: Agents;
+    server: Server;
+    listen(port?: number, host?: string): Promise<AddressInfo>;
+    close(): Promise<void>;
+}
+export interface RouteContext {
+    agents: Agents;
+    method: string;
+    path: string[];
+    url: URL;
+    body(): Promise<Record<string, unknown>>;
+    json(status: number, value: unknown): void;
+}

package/dist/http-types.js

@@ -0,0 +1 @@
+export {};

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+export { createRestServer } from './http/server.js';
+export type { RestServer, RestServerOptions } from './http-types.js';

package/dist/http.js

@@ -0,0 +1 @@
+export { createRestServer } from './http/server.js';

package/dist/ids.d.ts

@@ -0,0 +1,5 @@
+export declare function newId(prefix: string): string;
+export declare function requireId(value: unknown, field: string): string;
+export declare function optionalId(value: unknown, field: string): string | undefined;
+export declare function randomKey(prefix: string): string;
+export declare function optionalKey(value: unknown): string | undefined;

package/dist/ids.js

@@ -0,0 +1,32 @@
+import crypto from 'node:crypto';
+import { AgentError } from './errors.js';
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+export function newId(prefix) {
+    return `${prefix}-${crypto.randomUUID()}`;
+}
+export function requireId(value, field) {
+    const id = typeof value === 'string' ? value.trim() : '';
+    if (!ID_PATTERN.test(id)) {
+        throw new AgentError('invalid_input', `${field} must be 1-128 lowercase letters, numbers, dots, underscores, or hyphens.`);
+    }
+    return id;
+}
+export function optionalId(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return requireId(value, field);
+}
+export function randomKey(prefix) {
+    return newId(prefix);
+}
+export function optionalKey(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string')
+        throw new AgentError('invalid_input', 'idempotency key must be a string.');
+    const key = value.trim();
+    if (!key || key.length > 256 || /[\u0000-\u001f\u007f]/.test(key)) {
+        throw new AgentError('invalid_input', 'idempotency key must be 1-256 printable characters.');
+    }
+    return key;
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/json.d.ts

@@ -0,0 +1,7 @@
+import type { JsonObject, JsonValue } from './types.js';
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function jsonClone<T extends JsonValue>(value: T): T;
+export declare function parseObject(value: string): JsonObject;
+export declare function canonicalJson(value: JsonValue): string;
+export declare function assertJsonObject(value: unknown, field: string): JsonObject;
+export declare function assertByteLimit(value: JsonValue, limit: number, label: string): void;

package/dist/json.js

@@ -0,0 +1,41 @@
+import { AgentError } from './errors.js';
+export function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function jsonClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function parseObject(value) {
+    const parsed = JSON.parse(value);
+    if (!isObject(parsed))
+        throw new AgentError('internal', 'Stored JSON is not an object.');
+    return parsed;
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, sortValue(item)]));
+}
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+export function assertJsonObject(value, field) {
+    if (!isObject(value))
+        throw new AgentError('invalid_input', `${field} must be an object.`);
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        throw new AgentError('invalid_input', `${field} must contain JSON values only.`);
+    }
+}
+export function assertByteLimit(value, limit, label) {
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    if (bytes > limit) {
+        throw new AgentError('too_large', `${label} is ${bytes} bytes; maximum is ${limit}.`, { bytes, limit });
+    }
+}

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

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

package/dist/mcp/agent-tools.js

@@ -0,0 +1,51 @@
+import { objectArg, objectSchema, stringArg, toolResult } from './helpers.js';
+const string = { type: 'string' };
+export function agentTools(agents) {
+    return [
+        {
+            name: 'agents_list',
+            description: 'List persistent agent definitions. This does not list chats.',
+            inputSchema: objectSchema({ include_deleted: { type: 'boolean' } }),
+            handler(input) {
+                return toolResult({ agents: agents.listAgents(input.include_deleted === true) });
+            },
+        },
+        {
+            name: 'agents_get',
+            description: 'Read one agent and its current immutable revision.',
+            inputSchema: objectSchema({ agent_id: string, include_deleted: { type: 'boolean' } }, ['agent_id']),
+            handler(input) {
+                const id = stringArg(input, 'agent_id');
+                return toolResult({ agent: agents.getAgent(id, input.include_deleted === true) });
+            },
+        },
+        {
+            name: 'agents_create',
+            description: 'Create an agent from a complete definition.',
+            inputSchema: objectSchema({ definition: { type: 'object' } }, ['definition']),
+            handler(input) {
+                return toolResult({
+                    agent: agents.createAgent(objectArg(input, 'definition')),
+                });
+            },
+        },
+        {
+            name: 'agents_update',
+            description: 'Patch an agent. Executable changes create an immutable revision.',
+            inputSchema: objectSchema({ agent_id: string, patch: { type: 'object' } }, ['agent_id', 'patch']),
+            handler(input) {
+                return toolResult({
+                    agent: agents.updateAgent(stringArg(input, 'agent_id'), objectArg(input, 'patch')),
+                });
+            },
+        },
+        {
+            name: 'agents_delete',
+            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/helpers.d.ts

@@ -0,0 +1,5 @@
+import type { JsonObject } from '../types.js';
+export declare const objectSchema: (properties: JsonObject, required?: string[]) => JsonObject;
+export declare function stringArg(input: Record<string, unknown>, name: string): string;
+export declare function objectArg(input: Record<string, unknown>, name: string): Record<string, unknown>;
+export declare function toolResult(value: unknown): JsonObject;

package/dist/mcp/helpers.js

@@ -0,0 +1,27 @@
+import { AgentError } from '../errors.js';
+import { isObject } from '../json.js';
+export const objectSchema = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    additionalProperties: false,
+    ...(required.length ? { required } : {}),
+});
+export function stringArg(input, name) {
+    const value = input[name];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new AgentError('invalid_input', `${name} is required.`);
+    }
+    return value.trim();
+}
+export function objectArg(input, name) {
+    const value = input[name];
+    if (!isObject(value))
+        throw new AgentError('invalid_input', `${name} must be an object.`);
+    return value;
+}
+export function toolResult(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        structuredContent: value,
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,6 @@
+import { Agents } from '../agents.js';
+import type { AgentsOptions } from '../types.js';
+import type { McpServer } from './types.js';
+export declare function createMcpServer(options?: AgentsOptions & {
+    agents?: Agents;
+}): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,73 @@
+import readline from 'node:readline';
+import { Agents } from '../agents.js';
+import { asAgentError } from '../errors.js';
+import { createMcpTools } from './tools.js';
+function descriptor(tool) {
+    const { handler, ...definition } = tool;
+    return definition;
+}
+export function createMcpServer(options = {}) {
+    const agents = options.agents || new Agents(options);
+    const owned = !options.agents;
+    const tools = createMcpTools(agents);
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    async function handle(message) {
+        if (message.method === 'initialize') {
+            return {
+                protocolVersion: message.params?.protocolVersion || '2024-11-05',
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'amalgm-agents', version: '0.1.0' },
+            };
+        }
+        if (message.method === 'ping')
+            return {};
+        if (message.method === 'tools/list')
+            return { tools: tools.map(descriptor) };
+        if (message.method === 'tools/call') {
+            const name = message.params?.name;
+            const tool = typeof name === 'string' ? byName.get(name) : undefined;
+            if (!tool)
+                throw Object.assign(new Error(`Unknown tool: ${String(name)}`), { rpcCode: -32602 });
+            const args = message.params?.arguments;
+            return tool.handler(args && typeof args === 'object' ? args : {});
+        }
+        if (message.method?.startsWith('notifications/'))
+            return undefined;
+        throw Object.assign(new Error(`Method not found: ${message.method}`), { rpcCode: -32601 });
+    }
+    async function start(input = process.stdin, output = process.stdout) {
+        const lines = readline.createInterface({ input, crlfDelay: Infinity });
+        lines.on('line', (line) => {
+            void respond(line, output);
+        });
+        return async () => {
+            lines.close();
+            if (owned)
+                await agents.close();
+        };
+    }
+    async function respond(line, output) {
+        let request;
+        try {
+            request = JSON.parse(line);
+            const result = await handle(request);
+            if (request.id === undefined || result === undefined)
+                return;
+            output.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`);
+        }
+        catch (error) {
+            if (request?.id === undefined)
+                return;
+            const normalized = asAgentError(error);
+            const rpcCode = typeof error === 'object' && error && 'rpcCode' in error
+                ? Number(error.rpcCode)
+                : -32603;
+            output.write(`${JSON.stringify({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: { code: rpcCode, message: normalized.message, data: { code: normalized.code } },
+            })}\n`);
+        }
+    }
+    return { tools, handle, start };
+}

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.d.ts

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

package/dist/mcp/tools.js

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

package/dist/mcp/types.d.ts

@@ -0,0 +1,18 @@
+import type { JsonObject } from '../types.js';
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: JsonObject;
+    handler(input: Record<string, unknown>): Promise<unknown> | unknown;
+}
+export interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+export interface McpServer {
+    tools: McpTool[];
+    handle(message: JsonRpcRequest): Promise<unknown>;
+    start(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<() => Promise<void>>;
+}

package/dist/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp.d.ts

@@ -0,0 +1,3 @@
+export { createMcpServer } from './mcp/server.js';
+export { createMcpTools } from './mcp/tools.js';
+export type { JsonRpcRequest, McpServer, McpTool } from './mcp/types.js';

package/dist/mcp.js

@@ -0,0 +1,2 @@
+export { createMcpServer } from './mcp/server.js';
+export { createMcpTools } from './mcp/tools.js';

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

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

@@ -0,0 +1,65 @@
+import { parseObject } from './json.js';
+function nullable(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+export function revisionFromRow(row) {
+    return {
+        id: String(row.revision_id ?? row.id),
+        agentId: String(row.agent_id),
+        number: Number(row.revision_number),
+        hash: String(row.definition_hash),
+        definition: parseObject(String(row.definition_json)),
+        createdAt: String(row.revision_created_at ?? row.created_at),
+    };
+}
+export function agentFromRow(row) {
+    const revision = revisionFromRow(row);
+    return {
+        id: String(row.id),
+        currentRevisionId: String(row.current_revision_id),
+        currentRevision: Number(row.current_revision_number),
+        definition: revision.definition,
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        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;
+}