@amalgm/agents 0.2.1 → 0.2.2

package/docs/REST.md

@@ -1,103 +1,20 @@
 # REST API
 
-Create an embeddable server with `createRestServer` from
-`@amalgm/agents/http`, or run `amalgm-agents-rest`.
+Create an embeddable server with `createRestServer` from `@amalgm/agents/http`,
+or run `amalgm-agents-rest`. The CLI binds `127.0.0.1:4317` by default.
 
-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.
-
-## Agent configuration
-
-| Method | Path | Result |
-|---|---|---|
-| `GET` | `/agent-config` | List normalized configs from live agent revisions |
-| `POST` | `/agent-config/get` | Read `{ agent_id }` |
-| `POST` | `/agent-config/update` | Atomically apply `{ agent_id, config }` |
-| `POST` | `/agent-config/import-native` | Import safe native fields for `{ agent_id, replace? }` |
-
-Set `nativeHomeDir` when embedding the server or `--native-home`/
-`AMALGM_NATIVE_HOME` with the REST binary. Native import intentionally ignores
-auth files, secrets, and MCP server configuration.
-
-## Agent bundles
-
-| Method | Path | Result |
-|---|---|---|
-| `GET` | `/agent-bundles` | Read bundle-v2 capability and available agent heads |
-| `POST` | `/agent-bundles/preview` | Export requested agent/app/automation/tool heads |
-| `POST` | `/agent-bundles/install` | Validate and install `{ bundle, auth_ref? }` |
-
-Embedding hosts inject `bundlePort` for resources owned by Apps, Automations,
-and Toolbox. Agent-only bundles need no port. Bundles with external resources
-fail explicitly when the owner port is absent.
-
-## Agents
+When configured, authentication uses `Authorization: Bearer <token>` or the
+`x-amalgm-runtime-token` header. `/healthz` is unauthenticated. JSON bodies
+default to a 512 KB limit.
 
 | 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": {}
-  }
-}
-```
+| `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 |
+
+Use `?include_deleted=true` on list or get to include tombstones. The same
+server also exposes agent configuration, installed skills, and bundle routes
+documented by their SDK modules. It exposes no conversation routes.

package/docs/SDK.md

@@ -1,72 +1,23 @@
 # SDK reference
 
-The `Agents` class is the sole public behavior boundary. All mutations are
-durable before a method returns.
-
-## Construction
+`Agents` is the public behavior boundary for the local agent registry. Every
+mutation is durable before it returns.
 
 ```ts
-const agents = new Agents({
-  stateDir: './state',
-  drivers: [codexDriver],
-  maxInputBytes: 256_000,
-  maxEventBytes: 256_000,
-  turnTimeoutMs: 600_000,
-});
+const agents = new Agents({ stateDir: './state' });
 ```
 
-`databasePath` overrides the database location directly. `turnTimeoutMs: 0`
-disables the service timeout. Call `close()` to abort owned executions, wait
-for them to settle, and close SQLite.
-
-## Agent methods
+`databasePath` overrides the database location directly. Call `close()` when
+the embedding process releases the registry.
 
 | Method | Behavior |
 |---|---|
-| `createAgent(definition)` | Create identity and revision 1; conflicts on any reused id |
-| `updateAgent(id, patch)` | Merge a patch and apply the resulting definition |
-| `deleteAgent(id)` | Tombstone the identity while retaining history |
+| `createAgent(definition)` | Create an identity and immutable revision 1 |
+| `updateAgent(id, patch)` | Apply a patch, appending a revision when content changes |
+| `deleteAgent(id)` | Tombstone the identity while retaining its revisions |
 | `getAgent(id, includeDeleted?)` | Read the current definition |
-| `listAgents(includeDeleted?)` | List live agents by default |
-
-## Session methods
-
-| Method | Behavior |
-|---|---|
-| `startSession(input)` | Pin a new session to the current or named revision |
-| `talk(agentId, input)` | Start or continue a session, then enqueue a turn |
-| `enqueue(sessionId, input)` | Return immediately with the turn and completion promise |
-| `send(sessionId, input)` | Wait for the turn's terminal state |
-| `cancelSession(id)` | Persist cancellation intent and signal its active driver |
-| `archiveSession(id)` | Archive an inactive session |
-| `listSessions(agentId?, includeArchived?)` | Discover durable sessions |
-| `listTurns(sessionId)` | Read accepted inputs and outcomes |
-| `listEvents(sessionId, after?, limit?)` | Read ordered events |
-
-`enqueue` returns `{ turn, completion, duplicate }`. If an idempotency key was
-already accepted, `duplicate` is true and the original turn is returned.
-
-## Event subscription
-
-```ts
-const unsubscribe = agents.subscribe(session.id, (event) => {
-  console.log(event.sequence, event.type, event.data);
-});
-
-await agents.send(session.id, { message: 'Hello' });
-unsubscribe();
-```
-
-Listeners receive events only after commit. To build a reconnectable consumer,
-read `listEvents(after)` before subscribing and de-duplicate by sequence, as
-the packaged SSE adapter does.
-
-## Errors
-
-Expected failures use `AgentError` with a stable code:
-
-`invalid_input`, `not_found`, `conflict`, `deleted`, `driver_unavailable`,
-`too_large`, or `cancelled`.
+| `listAgents(includeDeleted?)` | List available agents by default |
+| `getAgentRevision(agentId, revisionId?)` | Resolve the current or exact immutable revision |
 
-Driver failures become durable failed turns rather than escaping as transient
-transport errors. Inspect `turn.error` and the session event ledger.
+Expected failures use `AgentError` with stable codes: `invalid_input`,
+`not_found`, `conflict`, `deleted`, and `too_large`.

package/docs/SECURITY.md

@@ -1,38 +1,9 @@
 # Security model
 
-Agents stores executable configuration and conversation history, so its state
-directory should be treated as user-private data.
+Agent definitions contain `authRef`, never credentials. Toolbox ids, skill ids,
+file references, and subagent ids are requests, not authority; Shell resolves
+and authorizes them while preparing a Chat execution.
 
-## Secrets
-
-Agent definitions contain `authRef`, not credentials. Drivers resolve that
-reference at execution time through the host's credential boundary. Do not put
-tokens, cookies, private keys, or passwords in `driver.config`, `metadata`,
-messages, or events.
-
-## Capability references
-
-Toolbox ids and subagent ids are requests, not authority. The composing host
-must resolve them against the caller's allowed Toolbox view and agent policy.
-Agents never infers permission merely because an id appears in a definition.
-
-## REST exposure
-
-The REST CLI binds `127.0.0.1` by default. Configure a bearer token before
-binding to a LAN, container bridge, tunnel, or public interface. The packaged
-server intentionally does not implement browser sessions, CORS, TLS, user
-accounts, or cloud authorization; Engine supplies those outer boundaries.
-
-## Driver trust
-
-Drivers execute inside the hosting process and are trusted code. A driver can
-read its process environment and access the filesystem with that process's
-permissions. Load only reviewed modules. Native process drivers should avoid a
-shell, pass explicit arguments, bound output, and kill their child on abort.
-
-## Stored data
-
-SQLite files are created beneath a mode-`0700` state directory. Application
-packaging and backups must preserve appropriate filesystem permissions.
-Messages and driver events may contain sensitive user content; retention and
-export policies belong to the embedding product.
+The REST CLI binds loopback by default. Configure a bearer token before
+binding it to a shared interface. SQLite state is created beneath a private
+state directory and should be backed up with equivalent file permissions.

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/examples/basic.ts

@@ -1,31 +1,17 @@
-import { Agents, defineDriver, messageText } from '@amalgm/agents';
+import { Agents } from '@amalgm/agents';
 
-const echo = defineDriver({
-  id: 'echo',
-  async run(request) {
-    return {
-      driverSessionId: request.driverSessionId || `echo-${request.session.id}`,
-      message: {
-        role: 'assistant',
-        parts: [{ type: 'text', text: `Echo: ${messageText(request.input)}` }],
-      },
-    };
-  },
-});
+const agents = new Agents({ stateDir: './example-state' });
 
-async function main(): Promise<void> {
-  const agents = new Agents({ stateDir: './example-state', drivers: [echo] });
+try {
   agents.createAgent({
     id: 'reviewer',
     name: 'Reviewer',
-    driver: 'echo',
+    driver: 'codex',
     instructions: 'Review carefully.',
   });
 
-  const call = agents.talk('reviewer', { message: 'Check this design.' });
-  console.log(await call.completion);
-  console.log(agents.listEvents(call.session.id));
-  await agents.close();
+  const revision = agents.getAgentRevision('reviewer');
+  console.log(revision.id, revision.definition);
+} finally {
+  agents.close();
 }
-
-void main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amalgm/agents",
-  "version": "0.2.1",
-  "description": "Local-first agent definitions, immutable revisions, and durable sessions.",
+  "version": "0.2.2",
+  "description": "Local-first agent identities, installations, and immutable revisions.",
   "license": "UNLICENSED",
   "private": false,
   "repository": {

package/skills/amalgm-agents/SKILL.md

@@ -1,30 +1,241 @@
 ---
 name: amalgm-agents
-description: Create, inspect, edit, delete, and talk to persistent Amalgm agents and their existing sessions. Use when a user wants to manage an agent definition, discover available agents, delegate work to an agent, continue an agent session, or inspect its transcript. Agents are separate from Chat conversations.
+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.
 
-## Talk to an agent
+```bash
+npm install @amalgm/agents
+```
 
-1. Resolve the agent with `agents_list` or `agents_get` when its identity is
-   ambiguous.
-2. Call `talk_to_agent` without a session ID to start a session.
-3. Preserve and return the resulting session ID.
-4. Pass that ID to continue the same session.
-5. Use conversation/session inspection to recover durable results or history.
-6. Use background execution for work likely to outlive one MCP request.
+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`.
 
-Never create a Chat conversation merely to represent an Agents session.
+```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.

package/skills/amalgm-agents/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Amalgm Agents"
-  short_description: "Create, manage, and talk to Amalgm agents"
-  default_prompt: "Use $amalgm-agents to create or talk to an agent."
+  short_description: "Create and manage Amalgm agents"
+  default_prompt: "Use $amalgm-agents to create or manage an agent."

package/dist/cli/session-commands.d.ts

@@ -1,4 +0,0 @@
-import type { Agents } from '../agents.js';
-import type { ParsedArgs } from './args.js';
-export declare function runSessionCommand(agents: Agents, args: ParsedArgs): Promise<unknown>;
-export declare function runTalkCommand(agents: Agents, args: ParsedArgs): Promise<unknown>;

package/dist/cli/session-commands.js

@@ -1,54 +0,0 @@
-import { AgentError } from '../errors.js';
-import { enabled, flag } from './args.js';
-export async function runSessionCommand(agents, args) {
-    const [, action, first, second] = args.words;
-    if (action === 'list') {
-        return { sessions: agents.listSessions(flag(args, 'agent'), enabled(args, 'include-archived')) };
-    }
-    if (action === 'start' && first) {
-        const sessionId = flag(args, 'id');
-        const revisionId = flag(args, 'revision');
-        return { session: agents.startSession({
-                agentId: first,
-                ...(sessionId ? { sessionId } : {}),
-                ...(revisionId ? { revisionId } : {}),
-            }) };
-    }
-    if (action === 'show' && first) {
-        const session = agents.getSession(first);
-        if (!session)
-            throw new AgentError('not_found', `Session not found: ${first}`);
-        return { session, turns: agents.listTurns(first), events: agents.listEvents(first) };
-    }
-    if (action === 'events' && first) {
-        return { events: agents.listEvents(first, Number(flag(args, 'after') || 0)) };
-    }
-    if (action === 'send' && first && second) {
-        const idempotencyKey = flag(args, 'key');
-        return { turn: await agents.send(first, {
-                message: second,
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-            }) };
-    }
-    if (action === 'cancel' && first)
-        return { turn: agents.cancelSession(first) };
-    if (action === 'archive' && first)
-        return { session: agents.archiveSession(first) };
-    throw new AgentError('invalid_input', 'Unknown or incomplete session command. Run with --help.');
-}
-export async function runTalkCommand(agents, args) {
-    const [, agentId, message] = args.words;
-    if (!agentId || !message)
-        throw new AgentError('invalid_input', 'talk requires agent id and message.');
-    const sessionId = flag(args, 'session');
-    const idempotencyKey = flag(args, 'key');
-    const call = agents.talk(agentId, {
-        message,
-        ...(sessionId ? { sessionId } : {}),
-        ...(idempotencyKey ? { idempotencyKey } : {}),
-    });
-    if (enabled(args, 'background')) {
-        return { session: call.session, turn: call.turn, duplicate: call.duplicate };
-    }
-    return { session: call.session, turn: await call.completion, duplicate: call.duplicate };
-}