@amalgm/agents 0.1.0

package/docs/SDK.md

@@ -0,0 +1,72 @@
+# SDK reference
+
+The `Agents` class is the sole public behavior boundary. All mutations are
+durable before a method returns.
+
+## Construction
+
+```ts
+const agents = new Agents({
+  stateDir: './state',
+  drivers: [codexDriver],
+  maxInputBytes: 256_000,
+  maxEventBytes: 256_000,
+  turnTimeoutMs: 600_000,
+});
+```
+
+`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
+
+| 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 |
+| `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`.
+
+Driver failures become durable failed turns rather than escaping as transient
+transport errors. Inspect `turn.error` and the session event ledger.

package/docs/SECURITY.md

@@ -0,0 +1,38 @@
+# Security model
+
+Agents stores executable configuration and conversation history, so its state
+directory should be treated as user-private data.
+
+## 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.

package/examples/basic.ts

@@ -0,0 +1,31 @@
+import { Agents, defineDriver, messageText } 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)}` }],
+      },
+    };
+  },
+});
+
+async function main(): Promise<void> {
+  const agents = new Agents({ stateDir: './example-state', drivers: [echo] });
+  agents.createAgent({
+    id: 'reviewer',
+    name: 'Reviewer',
+    driver: 'echo',
+    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();
+}
+
+void main();

package/examples/reviewer.json

@@ -0,0 +1,25 @@
+{
+  "id": "reviewer",
+  "name": "Reviewer",
+  "description": "Reviews implementation work",
+  "instructions": "Find correctness risks before style issues.",
+  "driver": {
+    "id": "echo",
+    "config": {}
+  },
+  "model": null,
+  "authRef": null,
+  "resources": {
+    "files": [],
+    "skills": ["code-review"],
+    "subagents": []
+  },
+  "toolbox": {
+    "toolIds": ["git"],
+    "actionIds": ["git.diff"]
+  },
+  "workspace": {
+    "cwd": null
+  },
+  "metadata": {}
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@amalgm/agents",
+  "version": "0.1.0",
+  "description": "Local-first agent definitions, immutable revisions, and durable sessions.",
+  "license": "UNLICENSED",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amalgm-inc/amalgm-agents.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "bin": {
+    "amalgm-agents": "./dist/bin/agents.js",
+    "amalgm-agents-mcp": "./dist/bin/mcp.js",
+    "amalgm-agents-rest": "./dist/bin/rest.js"
+  },
+  "files": [
+    "docs",
+    "dist",
+    "examples",
+    "skills",
+    "PURPOSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && 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"
+  },
+  "dependencies": {
+    "@amalgm/core": "^0.1.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.19.43",
+    "better-sqlite3": "^12.6.2"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/amalgm-agents/SKILL.md

@@ -0,0 +1,30 @@
+---
+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.
+---
+
+# Amalgm Agents
+
+Use the available Agents MCP tools. If MCP is unavailable, use the equivalent
+`amalgm-agents` CLI command.
+
+## Manage agents
+
+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.
+
+## Talk to an agent
+
+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.
+
+Never create a Chat conversation merely to represent an Agents session.

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

@@ -0,0 +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."