@amalgm/agents 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export interface AgentModel {
+    id: string;
+    settings: JsonObject;
+}
+export interface AgentDriverRef {
+    id: string;
+    config: JsonObject;
+}
+export interface AgentResources {
+    files: string[];
+    skills: string[];
+    subagents: string[];
+}
+export interface ToolboxLoadoutRef {
+    toolIds: string[];
+    actionIds: string[];
+}
+export interface AgentWorkspace {
+    cwd: string | null;
+}
+export interface AgentDefinition {
+    id: string;
+    name: string;
+    description: string;
+    instructions: string;
+    driver: AgentDriverRef;
+    model: AgentModel | null;
+    authRef: string | null;
+    resources: AgentResources;
+    toolbox: ToolboxLoadoutRef;
+    workspace: AgentWorkspace;
+    metadata: JsonObject;
+}
+export type AgentDefinitionInput = Partial<Omit<AgentDefinition, 'driver' | 'model' | 'resources' | 'toolbox' | 'workspace'>> & {
+    driver?: string | Partial<AgentDriverRef>;
+    model?: (Omit<AgentModel, 'settings'> & {
+        settings?: JsonObject;
+    }) | null;
+    resources?: Partial<AgentResources>;
+    toolbox?: Partial<ToolboxLoadoutRef>;
+    workspace?: Partial<AgentWorkspace>;
+};
+export type AgentPatch = Omit<Partial<AgentDefinitionInput>, 'id'>;
+export interface AgentRevision {
+    id: string;
+    agentId: string;
+    number: number;
+    hash: string;
+    definition: AgentDefinition;
+    createdAt: string;
+}
+export interface AgentRecord {
+    id: string;
+    currentRevisionId: string;
+    currentRevision: number;
+    definition: AgentDefinition;
+    createdAt: string;
+    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/dist/types.js

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

package/docs/ARCHITECTURE.md

@@ -0,0 +1,73 @@
+# Architecture
+
+## Ownership
+
+The Agents service owns four 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.
+
+Everything else crosses an adapter boundary.
+
+```text
+                    SDK
+                     │
+        CLI ───┐      │      ┌─── REST + SSE
+               ├── Agents ───┤
+        MCP ───┘      │      └─── Engine adapter
+                     │
+              SQLite ledger
+                     │
+                AgentDriver
+              ┌──────┼──────┐
+           Codex   Claude   custom
+```
+
+CLI, MCP, REST, and Engine never write SQLite directly. `Agents` is the
+public service; the stores below it are implementation details.
+
+## Product boundaries
+
+| Product | Owns | Agents keeps |
+|---|---|---|
+| 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` |
+| Engine | native harness processes, cloud routing, composition | injected drivers |
+| Agents | definitions, revisions, sessions, turns, events | canonical 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.
+
+## Mutation path
+
+`createAgent` creates an identity and revision 1 atomically. `updateAgent`
+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.
+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.
+
+## Why drivers are injected
+
+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.

package/docs/CLI.md

@@ -0,0 +1,61 @@
+# CLI reference
+
+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]
+amalgm-agents agent create <definition.json>
+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).
+
+## 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
+
+```bash
+amalgm-agents-rest --host 127.0.0.1 --port 4317 --token "$TOKEN"
+amalgm-agents-mcp --state-dir ./state --drivers ./dist/driver.js
+```
+
+The REST CLI binds loopback by default. Use a bearer token before deliberately
+binding to any shared interface.

package/docs/DATA_MODEL.md

@@ -0,0 +1,56 @@
+# Persistence and recovery
+
+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.
+
+## 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.

package/docs/DEFINITIONS.md

@@ -0,0 +1,65 @@
+# Agent definitions
+
+An agent definition is complete, portable execution configuration. It contains
+references, never resolved secrets or copies of records owned by other
+products.
+
+```json
+{
+  "id": "reviewer",
+  "name": "Reviewer",
+  "description": "Reviews implementation work",
+  "instructions": "Find correctness risks before style issues.",
+  "driver": {
+    "id": "codex",
+    "config": { "sandbox": "workspace-write" }
+  },
+  "model": {
+    "id": "openai/gpt-5.5",
+    "settings": { "effort": "high" }
+  },
+  "authRef": "openai-primary",
+  "resources": {
+    "files": ["AGENTS.md"],
+    "skills": ["code-review"],
+    "subagents": ["security-reviewer"]
+  },
+  "toolbox": {
+    "toolIds": ["git"],
+    "actionIds": ["github.pull_request_get"]
+  },
+  "workspace": { "cwd": "/projects/product" },
+  "metadata": { "icon": "search" }
+}
+```
+
+## Identity
+
+`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.
+
+## 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.
+
+## PATCH behavior
+
+Top-level fields replace their prior values. Known nested objects—`driver`,
+`resources`, `toolbox`, and `workspace`—merge by field, so a patch containing
+only `resources.skills` preserves files and subagent references. Arrays are
+authoritative and de-duplicated. Set nullable fields such as `model` or
+`authRef` to `null` to clear them.
+
+## References
+
+- `authRef` names a credential the host resolves at execution time.
+- `toolbox` matches the selection concepts in `@amalgm/tools` but does not
+  import or mutate a Toolbox.
+- `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.

package/docs/DRIVERS.md

@@ -0,0 +1,72 @@
+# Agent drivers
+
+Drivers connect durable Agents state to a native or hosted runtime. They are
+registered by the embedding process and selected by `definition.driver.id`.
+
+```ts
+import { defineDriver } from '@amalgm/agents';
+
+export default defineDriver({
+  id: 'my-runtime',
+  async run(request, context) {
+    context.signal.throwIfAborted();
+    context.emit({ type: 'text.delta', data: { text: 'Working…' } });
+
+    return {
+      driverSessionId: request.driverSessionId ?? 'native-session-id',
+      message: {
+        role: 'assistant',
+        parts: [{ type: 'text', text: 'Done.' }],
+      },
+      metadata: { provider: 'example' },
+    };
+  },
+});
+```
+
+## Request
+
+`DriverRunRequest` includes:
+
+- the immutable `AgentRevision`;
+- the durable session and current turn;
+- ordered completed history before this turn;
+- the accepted input; and
+- the opaque `driverSessionId` returned by an earlier turn.
+
+Drivers do not receive a database handle. They resolve Toolbox actions,
+credentials, skills, files, and native processes through dependencies supplied
+by their host.
+
+## Events and results
+
+Call `context.emit` for streaming or structured observations. The event is
+committed before the call returns. Use type `message` with an assistant
+`AgentMessage` for a durable output message; other event names are driver-owned
+and their data must be JSON.
+
+A final returned `message` is appended once before turn completion. Returned
+`driverSessionId` replaces the prior opaque value for future continuation.
+
+## Cancellation and limits
+
+Drivers must observe `context.signal` and stop their underlying process or
+request. The service records cancellation intent before aborting the signal.
+Input and event sizes are bounded. A driver that emits invalid or oversized
+data fails the turn explicitly.
+
+The in-process boundary cannot forcibly kill an uncooperative driver. Process
+drivers should own their child process and terminate it when signalled.
+
+## Loading drivers in CLIs
+
+Compile driver modules to JavaScript and export either an `AgentDriver`, a
+`driver` value, or a zero-argument factory:
+
+```bash
+AMALGM_AGENT_DRIVERS=./dist/codex-driver.js amalgm-agents-rest
+amalgm-agents --drivers ./dist/codex-driver.js talk reviewer "Review this"
+```
+
+Multiple modules are comma-separated. Secret values belong in the host's
+credential resolver, not in agent definitions or driver module arguments.

package/docs/ENGINE_INTEGRATION.md

@@ -0,0 +1,74 @@
+# Amalgm 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.
+
+## Existing ownership to replace
+
+| 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 bundles currently mix agents, apps, automations, and tool bindings. That
+cross-product packaging concern should remain outside this repository. A bundle
+installer may call each product's public apply method.
+
+## 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.

package/docs/MCP.md

@@ -0,0 +1,24 @@
+# MCP server
+
+`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.

package/docs/REST.md

@@ -0,0 +1,78 @@
+# REST API
+
+Create an embeddable server with `createRestServer` from
+`@amalgm/agents/http`, or run `amalgm-agents-rest`.
+
+The CLI default is `127.0.0.1:4317`. If a token is configured, all `/v1`
+requests require the token via `Authorization: Bearer <token>` (scheme
+case-insensitive) or the `x-amalgm-runtime-token` header. A missing or wrong
+token receives the kernel's canonical 401 from `@amalgm/core/transport`,
+compared in constant time. `/healthz` is a minimal unauthenticated liveness
+response. JSON bodies default to a 512 KB limit.
+
+## Agents
+
+| Method | Path | Result |
+|---|---|---|
+| `GET` | `/v1/agents` | List live agents |
+| `POST` | `/v1/agents` | Create from complete body |
+| `GET` | `/v1/agents/:id` | Read current definition |
+| `PATCH` | `/v1/agents/:id` | Merge a definition patch |
+| `DELETE` | `/v1/agents/:id` | Tombstone agent |
+
+Use `?include_deleted=true` on list or get to include tombstones.
+
+## Sessions
+
+| Method | Path | Result |
+|---|---|---|
+| `GET` | `/v1/sessions` | List sessions |
+| `POST` | `/v1/sessions` | Start `{ agentId, revisionId?, sessionId?, metadata? }` |
+| `GET` | `/v1/sessions/:id` | Read session |
+| `DELETE` | `/v1/sessions/:id` | Archive inactive session |
+| `GET` | `/v1/sessions/:id/turns` | List turns |
+| `GET` | `/v1/sessions/:id/events` | List ordered events |
+| `POST` | `/v1/sessions/:id/messages` | Send a turn |
+| `POST` | `/v1/sessions/:id/cancel` | Cancel active turn |
+
+List filters are `agent_id` and `include_archived=true`. Event pagination uses
+`after` and `limit` (maximum 1000).
+
+Send a message:
+
+```json
+{
+  "message": "Review the current diff.",
+  "idempotencyKey": "review-001",
+  "wait": true
+}
+```
+
+`message` may also be a structured `AgentMessage`. `wait: false` returns `202`
+after durable acceptance; otherwise the response waits for a terminal turn.
+
+## Server-sent events
+
+Connect to:
+
+```text
+GET /v1/sessions/:id/events/stream?after=<last-sequence>
+```
+
+The stream sends committed backlog first and then live events. SSE `id` equals
+the session sequence. Reconnect with the last seen id as `after`. Heartbeat
+comments are sent every 15 seconds.
+
+## Errors
+
+Errors use the HTTP status associated with `AgentError`:
+
+```json
+{
+  "error": {
+    "code": "conflict",
+    "message": "Session already has an active turn.",
+    "details": {}
+  }
+}
+```