@amalgm/agents 0.2.1 → 0.2.2

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.

package/docs/DATA_MODEL.md

@@ -1,56 +1,17 @@
-# Persistence and recovery
+# Persistence
 
 The default database is `agents.db` inside the state directory resolved by
-`@amalgm/core/identity`: `AMALGM_AGENTS_DIR` verbatim when set, otherwise
-`$AMALGM_DIR/agents`, otherwise the scoped layout
-`~/.amalgm/users/local/agents`. Set `stateDir` or `databasePath` to relocate
-it directly.
+`@amalgm/core/identity`: `AMALGAM_AGENTS_DIR` verbatim when set, otherwise
+`$AMALGAM_DIR/agents`, otherwise `~/.amalgm/users/local/agents`.
 
-## Tables
+The registry has two tables:
 
 | Table | Role |
 |---|---|
 | `agents` | stable identity, current revision pointer, tombstone |
 | `agent_revisions` | immutable normalized definitions |
-| `sessions` | pinned revision and opaque driver session id |
-| `turns` | accepted input and execution outcome |
-| `session_events` | ordered append-only execution observations |
-
-Foreign keys prevent orphan sessions, turns, and events. SQLite WAL mode and a
-five-second busy timeout support multiple read-oriented surfaces while one
-service owns mutations.
 
 Repeating the current definition is idempotent. Returning to content used by
-an earlier revision creates a new revision number so the definition timeline
-remains complete and append-only.
-
-## Turn states
-
-```text
-queued → running → completed
-             ├──→ failed
-             ├──→ cancelling → cancelled
-             └──→ interrupted
-```
-
-`queued`, `running`, and `cancelling` are non-terminal. At service startup they
-become `interrupted`, because the previous process may have completed external
-side effects before dying. The service never guesses and never automatically
-replays uncertain work.
-
-## Idempotency
-
-`idempotencyKey` is unique within a session. Repeating a key returns its
-existing turn and does not invoke the driver again. Callers should derive it
-from their durable request identity instead of generating a new value on every
-retry.
-
-## Events
-
-Every event receives the next integer sequence within its session. SSE first
-reads committed events after the requested sequence, then subscribes to newly
-committed events. Reconnecting with the last SSE id therefore closes the gap
-without polling or losing events.
-
-Events are facts, not mutable projections. User interfaces derive streaming
-text, messages, tool activity, and status from the ledger.
+an earlier revision creates a new revision number, keeping the definition
+timeline complete and append-only. Conversations and turns are stored only by
+Chat.

package/docs/DEFINITIONS.md

@@ -37,13 +37,13 @@ products.
 
 `id` is a stable machine identity: 1–128 lowercase letters, numbers, dots,
 underscores, or hyphens. Renaming `name` never changes it. Deleted ids remain
-reserved so historical sessions cannot be confused with a new agent.
+reserved so recorded revision identities cannot be reused.
 
 ## Revisions
 
 The normalized complete definition is hashed. An edit with equal content keeps
 the current revision. Any changed field creates a new immutable revision.
-Sessions always retain the revision selected at creation.
+Chat records the exact revision selected for every prepared execution.
 
 ## PATCH behavior
 
@@ -61,5 +61,5 @@ authoritative and de-duplicated. Set nullable fields such as `model` or
 - `resources.skills` and `resources.files` are resolved by the host.
 - `resources.subagents` describes intended relationships; the host still
   authorizes every agent-to-agent call.
-- `driver.config` is non-secret runtime configuration interpreted only by the
-  selected driver.
+- `driver.config` is non-secret harness configuration interpreted only by
+  Chat's host runtime.

package/docs/ENGINE_INTEGRATION.md

@@ -1,74 +1,12 @@
-# Amalgm Engine integration
+# Historical Engine integration
 
-Engine remains the composition root. This package becomes the canonical agent
-registry and session ledger; Engine supplies adapters for everything outside
-that domain.
+Amalgm Engine is deprecated. Its former agent registry, configuration, talk,
+REST, and MCP implementations are reference evidence for migrations and
+parity only. They are not active execution or persistence authorities and are
+never a fallback beside Shell.
 
-## Existing ownership to replace
+Agents now owns identities, installations, immutable revisions, and portable
+bundles. Chat owns conversations and turns. Shell resolves exact Agents
+revisions into prepared Chat executions through the public packages.
 
-| Current Engine area | Destination |
-|---|---|
-| `amalgm-mcp/agents/store.js` agent rows | `AgentStore` through `Agents` |
-| `amalgm-mcp/agent-config/*` normalized config | immutable agent definitions |
-| `amalgm-mcp/agents/talk.js` durable sessions and logs | Agents sessions, turns, events |
-| `amalgm-mcp/agents/tools.js` | packaged MCP tools |
-| `amalgm-mcp/agents/rest.js` and route wiring | packaged REST adapter |
-| `chat-core` native runtime execution | Engine-supplied `AgentDriver` implementations |
-| Toolbox lookup and MCP resolution | `@amalgm/tools` adapter inside drivers |
-| credential adapter | `authRef` resolver inside drivers |
-| Supabase Chat session creation | Chat/cloud adapter observing Agents events |
-
-Agent bundle-v2 graph and agent install laws live here. Engine supplies the
-`AgentBundlePort` that exports and installs apps, automations, and tools through
-their public SDKs; neither side imports another product's store.
-
-## Required driver adapter
-
-Engine should implement one driver per native harness identity (`codex`,
-`claude_code`, `opencode`, `pi`, and others). A driver translates the immutable
-revision into chat-core's runtime envelope, resolves `authRef`, projects the
-Toolbox loadout, forwards normalized streaming events, and returns the native
-session id for continuation.
-
-Drivers must not write Agents SQLite or invent another conversation log.
-
-## Chat boundary
-
-Engine may associate an Agents session id with a Chat record. Chat owns title,
-participants, layout, read state, and cloud presentation. Agents owns pinned
-revision, accepted inputs, driver execution, and events. Synchronization is an
-adapter subscribed to committed Agents events; neither database is imported by
-the other product.
-
-## One-time migration
-
-1. Stop the legacy agent mutation and talk surfaces.
-2. Read each legacy agent plus its `agent_config` as one complete definition.
-3. Map `baseHarnessId` to `driver.id`, model fields to `model`, auth mode to an
-   `authRef`, and legacy loadout ids to `toolbox.toolIds`.
-4. Create missing agents and update existing agents through `Agents`.
-5. Import local conversation JSONL as archived sessions only when its agent and
-   chronological message identity are unambiguous; otherwise retain it as a
-   legacy read-only export.
-6. Start packaged REST and MCP adapters behind Engine's existing authenticated
-   routes.
-7. Enable native drivers and verify continuation against real harness sessions.
-8. Delete the legacy registry, config, talk, REST, and MCP implementations only
-   after parity and rollback checks pass.
-
-Migration must be idempotent. Record the source identity and migration version
-outside agent metadata or in a namespaced metadata field; never manufacture a
-new revision on equal reruns.
-
-## Integration tests
-
-Before switchover, run:
-
-- legacy agent create/update/delete through the UI against `Agents`;
-- a session created on revision 1, followed by an agent edit and continuation;
-- native resume after Engine restart;
-- Toolbox loadout enforcement through `@amalgm/tools`;
-- provider authentication failure without credential persistence in Agents;
-- agent-to-agent background calls and cancellation;
-- Chat projection without Chat becoming the session source of truth; and
-- one-time migration twice with byte-for-byte equal resulting definitions.
+See [SHELL_INTEGRATION.md](./SHELL_INTEGRATION.md) for the active boundary.

package/docs/MCP.md

@@ -3,22 +3,6 @@
 `amalgm-agents-mcp` is the standalone stdio server. `createMcpServer` from
 `@amalgm/agents/mcp` embeds the same server.
 
-It exposes seven tools:
-
-| Tool | Purpose |
-|---|---|
-| `agents_list` | List persistent agents |
-| `agents_get` | Inspect one agent |
-| `agents_create` | Create an agent |
-| `agents_update` | Edit an agent |
-| `agents_delete` | Delete an agent while retaining session history |
-| `agents_get_conversation` | Inspect a durable agent session |
-| `talk_to_agent` | Start or continue an agent session |
-
-`talk_to_agent` accepts the legacy `agent`, `conversation_id`, `description`,
-and `prompt` fields. `agent_id`, `session_id`, and structured `message` are
-also accepted. It returns `conversation_id` as the durable Agents session ID,
-not a Chat ID. Use `run_in_background` for long work.
-
-All handlers call the injected `Agents` service. MCP contains no second
-registry, transcript, execution engine, or routing subsystem.
+It exposes five registry tools: `agents_list`, `agents_get`, `agents_create`,
+`agents_update`, and `agents_delete`. Their handlers call the injected
+`Agents` service; MCP contains no second registry and no conversation runtime.