@amalgm/agents 0.2.0 → 0.2.1

package/dist/schema.js

@@ -1,56 +1,31 @@
-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) {
+const SCHEMA_VERSION = 2;
+function migrateRevisionHashes(database) {
     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(`
-      DROP TABLE IF EXISTS session_events;
-      DROP TABLE IF EXISTS turns;
-      DROP TABLE IF EXISTS sessions;
+      BEGIN IMMEDIATE;
+
+      CREATE TABLE agent_revisions_next (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL REFERENCES agents(id),
+        revision_number INTEGER NOT NULL,
+        definition_hash TEXT NOT NULL,
+        definition_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        UNIQUE(agent_id, revision_number)
+      );
+
+      INSERT INTO agent_revisions_next
+        (id, agent_id, revision_number, definition_hash, definition_json, created_at)
+      SELECT id, agent_id, revision_number, definition_hash, definition_json, created_at
+      FROM agent_revisions;
+
+      DROP TABLE agent_revisions;
+      ALTER TABLE agent_revisions_next RENAME TO agent_revisions;
+
+      CREATE INDEX agent_revisions_agent_idx
+        ON agent_revisions(agent_id, revision_number DESC);
+
       PRAGMA user_version = ${SCHEMA_VERSION};
       COMMIT;
     `);
@@ -71,9 +46,82 @@ export function migrate(database) {
     }
     if (current === SCHEMA_VERSION)
         return;
-    if (current > 0) {
-        upgradeRegistry(database, current);
+    if (current === 1) {
+        migrateRevisionHashes(database);
         return;
     }
-    database.exec(`${REGISTRY_SCHEMA}\nPRAGMA user_version = ${SCHEMA_VERSION};`);
+    database.exec(`
+    CREATE TABLE agents (
+      id TEXT PRIMARY KEY,
+      current_revision_id TEXT,
+      current_revision_number INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      deleted_at TEXT
+    );
+
+    CREATE TABLE agent_revisions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id),
+      revision_number INTEGER NOT NULL,
+      definition_hash TEXT NOT NULL,
+      definition_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(agent_id, revision_number)
+    );
+
+    CREATE TABLE sessions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id),
+      agent_revision_id TEXT NOT NULL REFERENCES agent_revisions(id),
+      agent_revision_number INTEGER NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('active', 'archived')),
+      driver_session_id TEXT,
+      metadata_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      archived_at TEXT
+    );
+
+    CREATE TABLE turns (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES sessions(id),
+      idempotency_key TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN (
+        'queued', 'running', 'cancelling', 'completed', 'failed', 'cancelled', 'interrupted'
+      )),
+      input_json TEXT NOT NULL,
+      result_json TEXT,
+      error_json TEXT,
+      created_at TEXT NOT NULL,
+      started_at TEXT,
+      completed_at TEXT,
+      UNIQUE(session_id, idempotency_key)
+    );
+
+    CREATE TABLE session_events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES sessions(id),
+      turn_id TEXT REFERENCES turns(id),
+      sequence INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      data_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE(session_id, sequence)
+    );
+
+    CREATE INDEX agent_revisions_agent_idx
+      ON agent_revisions(agent_id, revision_number DESC);
+    CREATE INDEX sessions_agent_idx
+      ON sessions(agent_id, updated_at DESC);
+    CREATE INDEX turns_session_idx
+      ON turns(session_id, created_at ASC);
+    CREATE UNIQUE INDEX turns_one_active_per_session_idx
+      ON turns(session_id)
+      WHERE status IN ('queued', 'running', 'cancelling');
+    CREATE INDEX session_events_session_idx
+      ON session_events(session_id, sequence ASC);
+
+    PRAGMA user_version = ${SCHEMA_VERSION};
+  `);
 }

package/dist/session-store.d.ts

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

package/dist/session-store.js

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

package/dist/turn-store.d.ts

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

package/dist/turn-store.js

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

package/dist/types.d.ts

@@ -63,8 +63,114 @@ 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,22 +2,27 @@
 
 ## Ownership
 
-The Agents service owns three facts:
+The Agents service owns four facts:
 
 1. which agent identities exist;
-2. the immutable revisions of each identity; and
-3. which installed agents and Agent Home descriptors are available locally.
+2. the immutable revisions of each identity;
+3. which revision each session uses; and
+4. the ordered turns and events inside each session.
 
 Everything else crosses an adapter boundary.
 
 ```text
                     SDK
                      │
-        CLI ───┐      │      ┌─── REST
+        CLI ───┐      │      ┌─── REST + SSE
                ├── Agents ───┤
         MCP ───┘      │      └─── Engine adapter
                      │
-               SQLite registry
+              SQLite ledger
+                     │
+                AgentDriver
+              ┌──────┼──────┐
+           Codex   Claude   custom
 ```
 
 CLI, MCP, REST, and Engine never write SQLite directly. `Agents` is the
@@ -27,17 +32,15 @@ public service; the stores below it are implementation details.
 
 | Product | Owns | Agents keeps |
 |---|---|---|
-| Chat | conversations, prepared execution, turns, streams, persistence, reconnect, usage, interrupt | exact agent revision selection |
+| Chat | presentation, titles, participants, read state | no Chat record |
 | Tools | tools, actions, drivers, loadouts | opaque tool/action ids |
 | Skills | skill content and installation | opaque skill ids |
 | Credentials | secret material and authorization | opaque `authRef` |
-| Shell | native harness processes, auth, machine effects, exact SDK composition | resolved revision projection |
-| Agents | identities, installations, Agent Home descriptors, immutable revisions | canonical registry records |
+| Engine | native harness processes, cloud routing, composition | injected drivers |
+| Agents | definitions, revisions, sessions, turns, events | canonical records |
 
-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.
+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.
 
 ## Mutation path
 
@@ -46,16 +49,25 @@ 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 immutable revisions or
-Chat conversations that already name them.
+Deleting an agent sets `deleted_at`. It does not delete revisions or sessions.
 The id cannot be recreated accidentally.
 
-## Resolution path
+## 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.
 
-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.
+## Why drivers are injected
 
-Agents ends at this resolution result. Chat is the only execution path.
+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.