@amalgm/agents 0.1.2 → 0.2.0

package/dist/http/server.js

@@ -2,11 +2,10 @@ import http from 'node:http';
 import { Agents } from '../agents.js';
 import { asAgentError } from '../errors.js';
 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;
@@ -46,20 +45,17 @@ export function createRestServer(options = {}) {
             url,
             skillRoots: options.skillRoots || {},
             ...(options.nativeHomeDir ? { nativeHomeDir: options.nativeHomeDir } : {}),
+            ...(options.bundlePort ? { bundlePort: options.bundlePort } : {}),
             body: () => readJson(request, bodyLimit),
             json: (status, value) => sendJson(response, status, value),
         };
-        if (await routeAgentConfig(context) || await routeSkills(context))
+        if (await routeAgentBundles(context) || await routeAgentConfig(context) || await routeSkills(context))
             return;
         if (path.shift() !== 'v1') {
             sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
             return;
         }
-        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))
+        if (await routeAgents(context))
             return;
         sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
     }

package/dist/http-types.d.ts

@@ -3,12 +3,14 @@ import type { AddressInfo } from 'node:net';
 import type { Agents } from './agents.js';
 import type { AgentsOptions } from './types.js';
 import type { SkillRootOptions } from './skills/roots.js';
+import type { AgentBundlePort } from './bundles/types.js';
 export interface RestServerOptions extends AgentsOptions {
     agents?: Agents;
     token?: string;
     bodyLimitBytes?: number;
     skillRoots?: SkillRootOptions;
     nativeHomeDir?: string;
+    bundlePort?: AgentBundlePort;
 }
 export interface RestServer {
     agents: Agents;
@@ -23,6 +25,7 @@ export interface RouteContext {
     url: URL;
     skillRoots: SkillRootOptions;
     nativeHomeDir?: string;
+    bundlePort?: AgentBundlePort;
     body(): Promise<Record<string, unknown>>;
     json(status: number, value: unknown): void;
 }

package/dist/index.d.ts

@@ -1,8 +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';
 export { buildCanonicalSkillRoots, classifySkillRoot } from './skills/roots.js';
 export type { SkillRootClassification, SkillRootOptions } from './skills/roots.js';
@@ -13,3 +11,10 @@ export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/s
 export { importAgentConfig } from './config/import.js';
 export { importNativeConfig } from './config/native.js';
 export type * from './config/types.js';
+export { createAgentBundle } from './bundles/create.js';
+export type { CreateBundleOptions } from './bundles/create.js';
+export { installAgentBundle } from './bundles/install.js';
+export { buildBundleGraph } from './bundles/graph.js';
+export { validateAgentBundle } from './bundles/validate.js';
+export { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from './bundles/util.js';
+export type * from './bundles/types.js';

package/dist/index.js

@@ -1,11 +1,14 @@
 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';
 export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/store.js';
 export { importAgentConfig } from './config/import.js';
 export { importNativeConfig } from './config/native.js';
+export { createAgentBundle } from './bundles/create.js';
+export { installAgentBundle } from './bundles/install.js';
+export { buildBundleGraph } from './bundles/graph.js';
+export { validateAgentBundle } from './bundles/validate.js';
+export { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from './bundles/util.js';

package/dist/mcp/agent-tools.js

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

package/dist/mcp/server.js

@@ -16,7 +16,7 @@ export function createMcpServer(options = {}) {
             return {
                 protocolVersion: message.params?.protocolVersion || '2024-11-05',
                 capabilities: { tools: { listChanged: false } },
-                serverInfo: { name: 'amalgm-agents', version: '0.1.2' },
+                serverInfo: { name: 'amalgm-agents', version: '0.1.3' },
             };
         }
         if (message.method === 'ping')

package/dist/mcp/tools.js

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

package/dist/rows.d.ts

@@ -1,7 +1,4 @@
-import type { AgentRecord, AgentRevision, AgentSession, AgentTurn, SessionEvent } from './types.js';
+import type { AgentRecord, AgentRevision } 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,42 +24,3 @@ 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/schema.js

@@ -1,31 +1,56 @@
-const SCHEMA_VERSION = 2;
-function migrateRevisionHashes(database) {
+const SCHEMA_VERSION = 3;
+const REGISTRY_SCHEMA = `
+  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 INDEX agent_revisions_agent_idx
+    ON agent_revisions(agent_id, revision_number DESC);
+`;
+function upgradeRegistry(database, current) {
     database.pragma('foreign_keys = OFF');
     try {
+        database.exec('BEGIN IMMEDIATE');
+        if (current === 1) {
+            database.exec(`
+        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);
+      `);
+        }
         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);
-
+      DROP TABLE IF EXISTS session_events;
+      DROP TABLE IF EXISTS turns;
+      DROP TABLE IF EXISTS sessions;
       PRAGMA user_version = ${SCHEMA_VERSION};
       COMMIT;
     `);
@@ -46,82 +71,9 @@ export function migrate(database) {
     }
     if (current === SCHEMA_VERSION)
         return;
-    if (current === 1) {
-        migrateRevisionHashes(database);
+    if (current > 0) {
+        upgradeRegistry(database, current);
         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};
-  `);
+    database.exec(`${REGISTRY_SCHEMA}\nPRAGMA user_version = ${SCHEMA_VERSION};`);
 }

package/dist/types.d.ts

@@ -63,114 +63,8 @@ export interface AgentRecord {
     updatedAt: string;
     deletedAt: string | null;
 }
-export type SessionStatus = 'active' | 'archived';
-export type TurnStatus = 'queued' | 'running' | 'cancelling' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
-export interface TextPart {
-    type: 'text';
-    text: string;
-}
-export interface ReferencePart {
-    type: 'reference';
-    uri: string;
-    name: string | null;
-    mediaType: string | null;
-}
-export interface DataPart {
-    type: 'data';
-    name: string;
-    data: JsonValue;
-}
-export type AgentPart = TextPart | ReferencePart | DataPart;
-export type MessageRole = 'user' | 'assistant' | 'system';
-export interface AgentMessage {
-    role: MessageRole;
-    parts: AgentPart[];
-}
-export interface AgentSession {
-    id: string;
-    agentId: string;
-    agentRevisionId: string;
-    agentRevision: number;
-    status: SessionStatus;
-    driverSessionId: string | null;
-    metadata: JsonObject;
-    createdAt: string;
-    updatedAt: string;
-    archivedAt: string | null;
-}
-export interface AgentTurn {
-    id: string;
-    sessionId: string;
-    idempotencyKey: string;
-    status: TurnStatus;
-    input: AgentMessage;
-    result: JsonObject | null;
-    error: AgentFailure | null;
-    createdAt: string;
-    startedAt: string | null;
-    completedAt: string | null;
-}
-export interface AgentFailure {
-    code: string;
-    message: string;
-    details: JsonObject;
-}
-export interface SessionEvent {
-    id: string;
-    sessionId: string;
-    turnId: string | null;
-    sequence: number;
-    type: string;
-    data: JsonObject;
-    createdAt: string;
-}
-export interface DriverEvent {
-    type: string;
-    data: JsonObject;
-}
-export interface DriverRunRequest {
-    agent: AgentRevision;
-    session: AgentSession;
-    turn: AgentTurn;
-    history: AgentMessage[];
-    input: AgentMessage;
-    driverSessionId: string | null;
-}
-export interface DriverRunResult {
-    message?: AgentMessage;
-    driverSessionId?: string;
-    metadata?: JsonObject;
-}
-export interface DriverRunContext {
-    signal: AbortSignal;
-    emit(event: DriverEvent): SessionEvent;
-}
-export interface AgentDriver {
-    id: string;
-    run(request: DriverRunRequest, context: DriverRunContext): Promise<DriverRunResult | void>;
-}
 export interface AgentsOptions {
     stateDir?: string;
     databasePath?: string;
-    drivers?: AgentDriver[];
-    maxInputBytes?: number;
-    maxEventBytes?: number;
-    turnTimeoutMs?: number;
     now?: () => string;
 }
-export interface StartSessionInput {
-    agentId: string;
-    revisionId?: string;
-    sessionId?: string;
-    metadata?: JsonObject;
-}
-export interface SendInput {
-    message: string | AgentMessage;
-    idempotencyKey?: string;
-}
-export interface EnqueuedTurn {
-    turn: AgentTurn;
-    completion: Promise<AgentTurn>;
-    duplicate: boolean;
-}
-export type EventListener = (event: SessionEvent) => void;

package/docs/ARCHITECTURE.md

@@ -2,27 +2,22 @@
 
 ## Ownership
 
-The Agents service owns four facts:
+The Agents service owns three facts:
 
 1. which agent identities exist;
-2. the immutable revisions of each identity;
-3. which revision each session uses; and
-4. the ordered turns and events inside each session.
+2. the immutable revisions of each identity; and
+3. which installed agents and Agent Home descriptors are available locally.
 
 Everything else crosses an adapter boundary.
 
 ```text
                     SDK
                      │
-        CLI ───┐      │      ┌─── REST + SSE
+        CLI ───┐      │      ┌─── REST
                ├── Agents ───┤
         MCP ───┘      │      └─── Engine adapter
                      │
-              SQLite ledger
-                     │
-                AgentDriver
-              ┌──────┼──────┐
-           Codex   Claude   custom
+               SQLite registry
 ```
 
 CLI, MCP, REST, and Engine never write SQLite directly. `Agents` is the
@@ -32,15 +27,17 @@ public service; the stores below it are implementation details.
 
 | Product | Owns | Agents keeps |
 |---|---|---|
-| Chat | presentation, titles, participants, read state | no Chat record |
+| Chat | conversations, prepared execution, turns, streams, persistence, reconnect, usage, interrupt | exact agent revision selection |
 | Tools | tools, actions, drivers, loadouts | opaque tool/action ids |
 | Skills | skill content and installation | opaque skill ids |
 | Credentials | secret material and authorization | opaque `authRef` |
-| Engine | native harness processes, cloud routing, composition | injected drivers |
-| Agents | definitions, revisions, sessions, turns, events | canonical records |
+| Shell | native harness processes, auth, machine effects, exact SDK composition | resolved revision projection |
+| Agents | identities, installations, Agent Home descriptors, immutable revisions | canonical registry records |
 
-An Agents session is executable history. A Chat conversation is a presentation
-object. A Chat may point to a session; the reverse dependency is forbidden.
+A Chat conversation is executable history. It names one Agents installation
+and the exact immutable revision used by each prepared execution. Agents never
+imports Chat and Chat never imports the Agents store; Shell composes their
+public capabilities through an explicit resolver.
 
 ## Mutation path
 
@@ -49,25 +46,16 @@ merges a typed patch into the current definition and compares its canonical
 hash with the current revision. Equal content is idempotent; changed content
 appends a revision and moves the identity's current pointer.
 
-Deleting an agent sets `deleted_at`. It does not delete revisions or sessions.
+Deleting an agent sets `deleted_at`. It does not delete immutable revisions or
+Chat conversations that already name them.
 The id cannot be recreated accidentally.
 
-## Execution path
-
-1. A caller starts a session; the current revision id is copied onto it.
-2. A turn and its input event commit in one transaction.
-3. The turn becomes `running` before its driver is invoked.
-4. Driver events commit to the ordered event ledger before subscribers see them.
-5. The driver returns a message, opaque native session id, and metadata.
-6. The turn reaches exactly one terminal state.
-
-One session serializes turns. Different sessions can execute concurrently.
+## Resolution path
 
-## Why drivers are injected
+1. A caller selects an installed agent identity.
+2. Agents returns the requested immutable revision, or the current revision
+   when no revision was requested.
+3. Shell projects that revision into Chat's execution-preparation resolver.
+4. Chat freezes the resolved facts before accepting a turn.
 
-Native agent runtimes have different authentication, installation, process,
-streaming, and resume rules. Baking them into storage would couple every user
-of the SDK to Engine. `AgentDriver` receives a complete immutable revision and
-ordered history, then emits durable events. Engine can reuse its current
-chat-core adapters behind this interface; standalone users can provide their
-own drivers.
+Agents ends at this resolution result. Chat is the only execution path.

package/docs/CLI.md

@@ -3,18 +3,6 @@
 The CLI prints JSON to stdout and errors to stderr. It shares the SDK database;
 there is no CLI-specific registry.
 
-## Global options
-
-| Option | Meaning |
-|---|---|
-| `--state-dir <path>` | Override the Agents state directory |
-| `--drivers <a.js,b.js>` | Load compiled driver modules |
-| `--help` | Print command help |
-
-`AMALGM_AGENT_DRIVERS` supplies the same comma-separated driver list.
-
-## Agent commands
-
 ```bash
 amalgm-agents agent list [--include-deleted]
 amalgm-agents agent show <id> [--include-deleted]
@@ -23,39 +11,11 @@ amalgm-agents agent update <id> <patch.json>
 amalgm-agents agent delete <id>
 ```
 
-`create` requires an unused id. `update` uses the nested PATCH rules in
-[Definitions](./DEFINITIONS.md).
+Global options are `--state-dir <path>` and `--help`.
 
-## Session commands
-
-```bash
-amalgm-agents session list [--agent <id>] [--include-archived]
-amalgm-agents session start <agent-id> [--id <id>] [--revision <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>
-```
-
-`session show` returns the session, turns, and event ledger together.
-
-## Talk shortcut
-
-```bash
-amalgm-agents talk <agent-id> <message> \
-  [--session <session-id>] [--key <idempotency-key>] [--background]
-```
-
-Without `--session`, the command starts one. Foreground waits for a terminal
-turn; background returns the accepted turn immediately.
-
-## Servers
+The REST CLI binds loopback by default:
 
 ```bash
 amalgm-agents-rest --host 127.0.0.1 --port 4317 --token "$TOKEN"
-amalgm-agents-mcp --state-dir ./state --drivers ./dist/driver.js
+amalgm-agents-mcp --state-dir ./state
 ```
-
-The REST CLI binds loopback by default. Use a bearer token before deliberately
-binding to any shared interface.