@amalgm/agents 0.2.0 → 0.2.2

package/PURPOSE.md

@@ -27,6 +27,9 @@ hosts supply explicit ports for resources owned by other products.
 
 ## Axioms
 
+Managed releases bind to one exact published Core version and build from the
+locked dependency graph on the supported Node toolchain.
+
 1. A user can create, list, inspect, edit, and delete agents.
 2. A user or another agent can resolve an available agent to one exact
    immutable revision without starting a conversation.

package/README.md

@@ -115,7 +115,8 @@ The CLI reads the same SQLite registry as the SDK.
 - [MCP server](./docs/MCP.md)
 - [Persistence](./docs/DATA_MODEL.md)
 - [Security model](./docs/SECURITY.md)
-- [Engine integration](./docs/ENGINE_INTEGRATION.md)
+- [Shell integration](./docs/SHELL_INTEGRATION.md)
+- [Historical Engine integration](./docs/ENGINE_INTEGRATION.md)
 
 ## Development
 

package/docs/ENGINE_INTEGRATION.md

@@ -1,29 +1,12 @@
-# Shell integration
+# Historical Engine integration
 
-Shell is the composition root. Agents supplies the canonical registry and Chat
-supplies the canonical conversation runtime.
+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.
 
-## Resolver boundary
+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.
 
-Shell gives Chat a resolver with one job: map an installed agent id and optional
-revision id to `agents.getAgentRevision(agentId, revisionId)`, then project that
-immutable definition into Chat's execution contract. The resolver never writes
-either product's store.
-
-Chat owns the conversation, accepted prompt, provider session, ordered durable
-updates, transcript, usage, reconnect, and interrupt lifecycle. Agents owns the
-identity and revision selected by that execution. Neither product imports the
-other's database.
-
-Tool and action ids are resolved through `@amalgm/tools`; `authRef` is resolved
-through the credential boundary. The resulting concrete values are frozen by
-Chat before it accepts a turn.
-
-## Integration checks
-
-- create, update, list, delete, and exact revision resolution use `Agents`;
-- editing an agent never changes a Chat execution that already names a revision;
-- Toolbox and credential references are authorized during preparation;
-- provider restart, reconnect, and interrupt are handled only by Chat; and
-- agent-to-agent interaction creates or joins a Chat conversation through the
-  same prepared-execution protocol as the UI.
+See [SHELL_INTEGRATION.md](./SHELL_INTEGRATION.md) for the active boundary.

package/docs/SHELL_INTEGRATION.md

@@ -0,0 +1,29 @@
+# Shell integration
+
+Shell is the composition root. Agents supplies the canonical registry and Chat
+supplies the canonical conversation runtime.
+
+## Resolver boundary
+
+Shell gives Chat a resolver with one job: map an installed agent id and optional
+revision id to `agents.getAgentRevision(agentId, revisionId)`, then project that
+immutable definition into Chat's execution contract. The resolver never writes
+either product's store.
+
+Chat owns the conversation, accepted prompt, provider session, ordered durable
+updates, transcript, usage, reconnect, and interrupt lifecycle. Agents owns the
+identity and revision selected by that execution. Neither product imports the
+other's database.
+
+Tool and action ids are resolved through `@amalgm/tools`; `authRef` is resolved
+through the credential boundary. The resulting concrete values are frozen by
+Chat before it accepts a turn.
+
+## Integration checks
+
+- create, update, list, delete, and exact revision resolution use `Agents`;
+- editing an agent never changes a Chat execution that already names a revision;
+- Toolbox and credential references are authorized during preparation;
+- provider restart, reconnect, and interrupt are handled only by Chat; and
+- agent-to-agent interaction creates or joins a Chat conversation through the
+  same prepared-execution protocol as the UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/agents",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local-first agent identities, installations, and immutable revisions.",
   "license": "UNLICENSED",
   "private": false,
@@ -42,17 +42,17 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
     "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
     "verify": "npm run check && npm run build && npm test",
     "prepack": "npm run build"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "dependencies": {
-    "@amalgm/core": "^0.1.0",
+    "@amalgm/core": "0.4.7",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20.19.43",
     "better-sqlite3": "^12.6.2"

package/skills/amalgm-agents/SKILL.md

@@ -1,21 +1,241 @@
 ---
 name: amalgm-agents
-description: Create, inspect, edit, delete, install, and resolve persistent Amalgm agent identities and immutable revisions. Use when a user wants to manage an agent definition or discover available agents.
+description: Manage persistent Amalgm agent identities and their immutable revisions with the @amalgm/agents SDK, CLI, REST API, or MCP tools. Use when you need to define an agent (its harness, model, instructions, tools, skills, and workspace), list or inspect existing agents, edit or delete one, or resolve the exact revision to run through Chat.
 ---
 
-# Amalgm Agents
+# Agents
 
-Use the available Agents MCP tools. If MCP is unavailable, use the equivalent
-`amalgm-agents` CLI command.
+Agents is the registry for durable agent definitions on the Amalgm platform. It stores three things: **identities** (a stable id like `reviewer` that survives renames and edits), **installations** (the agent identities available on the local machine), and **immutable revisions** (append-only snapshots of every definition an identity has ever had). You define an agent once — its harness, model, instructions, tools, skills, and workspace — and every surface on the machine (SDK, CLI, REST, MCP, and the Amalgm apps) reads and writes the same local SQLite registry. Agents does not run conversations: it resolves an exact revision, and Chat executes it.
 
-## Manage agents
+## Installation
 
-1. List or inspect before changing an existing agent.
-2. Create from a complete definition.
-3. Update only the fields the user requested.
-4. Delete only when the user explicitly asks.
-5. Keep tool, skill, file, credential, and subagent values as references; do
-   not copy those products into the agent definition.
+Install the package from npm. It requires Node 20 or later.
 
-To run an agent, resolve its identity here and use Chat. Agents has no
-conversation, execution, transcript, interrupt, or reconnect operation.
+```bash
+npm install @amalgm/agents
+```
+
+The install also provides three executables: `amalgm-agents` (CLI), `amalgm-agents-mcp` (stdio MCP server), and `amalgm-agents-rest` (loopback REST server). Run them with `npx` or add the package's `.bin` directory to your `PATH`.
+
+```bash
+npx amalgm-agents --help
+```
+
+## Quickstart
+
+Create an agent, list what exists, and resolve the revision you would hand to Chat. The `Agents` class is synchronous and local-first — every mutation is written to disk before the call returns.
+
+```ts
+import { Agents } from '@amalgm/agents';
+
+const agents = new Agents({ stateDir: './state' });
+
+try {
+  // Define and create an agent. `id`, `name`, and `driver` are required;
+  // everything else has a sensible empty default.
+  agents.createAgent({
+    id: 'reviewer',
+    name: 'Reviewer',
+    description: 'Reviews implementation work',
+    driver: 'codex',
+    instructions: 'Find correctness risks before style issues.',
+  });
+
+  // List every available (non-deleted) agent.
+  for (const agent of agents.listAgents()) {
+    console.log(agent.id, agent.definition.name, `rev ${agent.currentRevision}`);
+  }
+
+  // Inspect one agent's current definition.
+  const record = agents.getAgent('reviewer');
+  console.log(record?.definition.instructions);
+
+  // Resolve the exact immutable revision a host such as Chat would execute.
+  const revision = agents.getAgentRevision('reviewer');
+  console.log(revision.id, revision.number, revision.hash);
+} finally {
+  agents.close();
+}
+```
+
+By default the registry lives at `~/.amalgm/users/local/agents/agents.db`. Pass `stateDir` to keep state somewhere else (useful for tests and embedded hosts), or `databasePath` to point at a database file directly. Setting the `AMALGAM_AGENTS_DIR` environment variable overrides the default location without code changes.
+
+## Core concepts
+
+Agents separates three ideas that most agent frameworks blur together. Keeping them distinct is what makes agent executions reproducible.
+
+### Identity
+
+An identity is the stable machine name of an agent: 1–128 lowercase letters, numbers, dots, underscores, or hyphens. Renaming the human-readable `name` never changes the `id`, and other products reference agents by this id. Deleting an agent tombstones the identity rather than erasing it — the id stays reserved so that recorded history can never silently point at a different, later agent.
+
+### Revision
+
+Every content change to a definition appends an immutable revision: a numbered, hashed snapshot of the complete normalized definition. Revisions are immutable for one reason — Chat records the exact revision used by each execution, so a conversation transcript always names precisely the instructions, model, and tool references that produced it. Editing an agent today can never rewrite what an execution meant yesterday.
+
+Two consequences follow from the append-only design:
+
+- **Idempotent edits.** Submitting a patch that produces identical content keeps the current revision; nothing is appended.
+- **No revision reuse.** Reverting to content an earlier revision had still creates a *new* revision number, so the timeline of what the definition was, and when, stays complete.
+
+### Installation
+
+An installation is one agent identity available on the local machine, together with its home descriptor. The registry is per-machine and local-first: `listAgents()` answers "which agents can this machine run right now". Portable bundles let you move an agent (with its subagent, skill, and tool graph) between machines; installing a bundle creates fresh local identities rather than overwriting existing ones.
+
+## Agent definitions
+
+A definition is complete, portable execution configuration. It holds *references* to things owned by other products — tools, skills, files, credentials, subagents — never copies of them and never secrets.
+
+```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" }
+}
+```
+
+Field notes:
+
+- `driver` names the harness that will run the agent. As shorthand you may pass a plain string (`"driver": "codex"` becomes `{ "id": "codex", "config": {} }`). `driver.config` is non-secret harness configuration interpreted at execution time.
+- `model` and `authRef` are nullable. `authRef` names a credential that the host resolves when the agent runs; the secret itself never enters the definition.
+- `resources` and `toolbox` are lists of opaque ids resolved by the host. Arrays are de-duplicated and order-normalized.
+- `metadata` is free-form JSON for your own annotations (icons, tags, owners).
+
+## SDK reference
+
+`Agents` is the single behavior boundary — the CLI, REST, and MCP surfaces are thin adapters over these same methods, so behavior is identical everywhere.
+
+| Method | Behavior |
+|---|---|
+| `createAgent(definition)` | Create an identity and immutable revision 1 |
+| `updateAgent(id, patch)` | Merge a patch; append a revision only when content changes |
+| `deleteAgent(id)` | Tombstone the identity, retaining all revisions |
+| `getAgent(id, includeDeleted?)` | Read the current record, or `null` if absent |
+| `listAgents(includeDeleted?)` | List available agents (tombstones excluded by default) |
+| `getAgentRevision(agentId, revisionId?)` | Resolve the current or one exact immutable revision |
+| `health()` | Liveness summary for the open registry |
+| `close()` | Release the underlying database |
+
+### Patching
+
+Patches are partial definitions with predictable merge rules: top-level fields replace their prior values, while the known nested objects — `driver`, `resources`, `toolbox`, and `workspace` — merge field by field. That means a patch touching only `resources.skills` preserves `resources.files` and `resources.subagents`. Set a nullable field to `null` to clear it.
+
+```ts
+const updated = agents.updateAgent('reviewer', {
+  instructions: 'Review for correctness first, style second.',
+  resources: { skills: ['code-review', 'security-review'] },
+  model: null, // clear the pinned model; the host default applies
+});
+console.log(updated.currentRevision); // bumped, because content changed
+```
+
+### Errors
+
+Expected failures throw `AgentError` with a stable `code` — `invalid_input`, `not_found`, `conflict`, `deleted`, or `too_large` — plus a matching HTTP `status` used by the REST surface. Catch and branch on the code rather than the message.
+
+```ts
+import { Agents, AgentError } from '@amalgm/agents';
+
+try {
+  agents.updateAgent('missing-id', { name: 'Nope' });
+} catch (error) {
+  if (error instanceof AgentError && error.code === 'not_found') {
+    console.log('No such agent.');
+  } else {
+    throw error;
+  }
+}
+```
+
+## CLI
+
+The `amalgm-agents` CLI shares the SDK database — there is no separate CLI registry. It prints JSON to stdout and errors to stderr, so it composes cleanly with `jq` and scripts.
+
+```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` and `update` read a JSON file — a complete definition and a partial patch respectively, using exactly the shapes shown above. Global options are `--state-dir <path>` (choose the registry location) and `--help`.
+
+```bash
+# Create from a file, then confirm the revision advanced after an edit.
+amalgm-agents agent create reviewer.json
+echo '{"instructions": "Be terse."}' > patch.json
+amalgm-agents agent update reviewer patch.json
+amalgm-agents agent show reviewer | jq .currentRevision
+```
+
+## REST API
+
+For non-Node hosts, run the loopback REST server or embed it with `createRestServer` from `@amalgm/agents/http`.
+
+```bash
+amalgm-agents-rest --host 127.0.0.1 --port 4317 --token "$TOKEN"
+```
+
+When a token is configured, authenticate with `Authorization: Bearer <token>`; `/healthz` stays unauthenticated. JSON bodies are limited to 512 KB by default.
+
+| Method | Path | Result |
+|---|---|---|
+| `GET` | `/v1/agents` | List available agents |
+| `POST` | `/v1/agents` | Create from a complete definition |
+| `GET` | `/v1/agents/:id` | Read the current definition |
+| `PATCH` | `/v1/agents/:id` | Apply a definition patch |
+| `DELETE` | `/v1/agents/:id` | Tombstone an identity |
+
+Add `?include_deleted=true` to list or get requests to include tombstones. There are no conversation routes — execution belongs to Chat.
+
+## MCP tools
+
+`amalgm-agents-mcp` runs the registry as a stdio MCP server, so any MCP-capable assistant can manage agents. `createMcpServer` from `@amalgm/agents/mcp` embeds the same server in your own host.
+
+```bash
+amalgm-agents-mcp --state-dir ./state
+```
+
+It exposes five tools, each a direct projection of an SDK method:
+
+| Tool | Arguments | Behavior |
+|---|---|---|
+| `agents_list` | `include_deleted?` | List persistent agent definitions |
+| `agents_get` | `agent_id`, `include_deleted?` | Read one agent and its current revision |
+| `agents_create` | `definition` | Create from a complete definition |
+| `agents_update` | `agent_id`, `patch` | Patch; content changes append a revision |
+| `agents_delete` | `agent_id` | Tombstone an identity, retaining revisions |
+
+When working through these tools, list or inspect before changing an existing agent, patch only the fields being changed, and keep tool, skill, file, credential, and subagent values as references rather than inlining their content.
+
+## Running agents with Chat
+
+Agents deliberately contains no conversation, execution, transcript, interrupt, or reconnect operation. To run an agent, resolve its identity here and hand the result to Chat:
+
+1. Select an installed agent identity (from `listAgents` or a known id).
+2. Call `getAgentRevision(agentId, revisionId?)` — you get the current revision, or one exact historical revision if you pass its id.
+3. Project that immutable definition into Chat's execution contract. Chat resolves the `toolbox`, `resources`, and `authRef` references into concrete values, freezes them, and then accepts the turn.
+4. Chat records which revision it executed, so the conversation remains reproducible even after the agent is edited or deleted.
+
+```ts
+const revision = agents.getAgentRevision('reviewer');
+// revision.definition is the frozen, normalized definition:
+// pass it to Chat to start or continue a conversation as this agent.
+```
+
+The division of labor is strict by design: Agents answers "what is this agent, exactly?", and Chat owns everything about running it — the conversation, turns, streams, usage, interrupts, and reconnects. Editing an agent never changes a Chat execution that already names a revision.