@amalgm/agents 0.2.3-preview.37556893493 → 0.2.3-preview.39017157677

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/PURPOSE.md +21 -19
  2. package/README.md +25 -36
  3. package/dist/agent-folder.d.ts +32 -0
  4. package/dist/agent-folder.js +100 -0
  5. package/dist/agent-store.d.ts +23 -12
  6. package/dist/agent-store.js +144 -117
  7. package/dist/agents.d.ts +10 -10
  8. package/dist/agents.js +14 -26
  9. package/dist/bundles/create.d.ts +1 -0
  10. package/dist/bundles/create.js +1 -1
  11. package/dist/bundles/graph.d.ts +1 -0
  12. package/dist/bundles/graph.js +1 -1
  13. package/dist/bundles/install.d.ts +1 -0
  14. package/dist/bundles/install.js +1 -2
  15. package/dist/bundles/validate.d.ts +1 -0
  16. package/dist/bundles/validate.js +1 -1
  17. package/dist/config/import.d.ts +1 -1
  18. package/dist/config/import.js +2 -2
  19. package/dist/config/native.d.ts +5 -1
  20. package/dist/config/native.js +12 -11
  21. package/dist/config/schema.d.ts +1 -0
  22. package/dist/config/schema.js +1 -1
  23. package/dist/config/store.js +7 -7
  24. package/dist/errors.d.ts +1 -1
  25. package/dist/errors.js +0 -1
  26. package/dist/http/agent-routes.js +2 -4
  27. package/dist/http/bundle-routes.js +2 -23
  28. package/dist/http/config-routes.js +1 -4
  29. package/dist/http/server.d.ts +1 -1
  30. package/dist/http/server.js +3 -9
  31. package/dist/http/skill-routes.d.ts +0 -1
  32. package/dist/http/skill-routes.js +2 -3
  33. package/dist/http-types.d.ts +2 -8
  34. package/dist/ids.d.ts +0 -4
  35. package/dist/ids.js +0 -23
  36. package/dist/index.d.ts +0 -2
  37. package/dist/index.js +0 -1
  38. package/dist/json.d.ts +1 -4
  39. package/dist/json.js +0 -23
  40. package/dist/mcp/agent-tools.js +11 -12
  41. package/dist/mcp/server.d.ts +3 -4
  42. package/dist/mcp/server.js +3 -41
  43. package/dist/mcp/types.d.ts +0 -1
  44. package/dist/revisions.d.ts +9 -0
  45. package/dist/revisions.js +39 -0
  46. package/dist/skills/roots.d.ts +6 -7
  47. package/dist/skills/roots.js +16 -29
  48. package/dist/skills/scanner.d.ts +2 -2
  49. package/dist/skills/scanner.js +2 -2
  50. package/dist/types.d.ts +9 -6
  51. package/docs/ARCHITECTURE.md +24 -25
  52. package/docs/DATA_MODEL.md +27 -21
  53. package/docs/DEFINITIONS.md +11 -9
  54. package/docs/MCP.md +5 -5
  55. package/docs/REST.md +7 -7
  56. package/docs/SDK.md +17 -13
  57. package/docs/SECURITY.md +4 -3
  58. package/docs/SHELL_INTEGRATION.md +22 -2
  59. package/examples/basic.ts +15 -11
  60. package/package.json +9 -20
  61. package/skills/amalgm-agents/SKILL.md +69 -171
  62. package/dist/bin/agents.d.ts +0 -2
  63. package/dist/bin/agents.js +0 -5
  64. package/dist/bin/fatal.d.ts +0 -1
  65. package/dist/bin/fatal.js +0 -5
  66. package/dist/bin/mcp.d.ts +0 -2
  67. package/dist/bin/mcp.js +0 -19
  68. package/dist/bin/rest.d.ts +0 -2
  69. package/dist/bin/rest.js +0 -26
  70. package/dist/bundles/copy.d.ts +0 -12
  71. package/dist/bundles/copy.js +0 -144
  72. package/dist/cli/agent-commands.d.ts +0 -3
  73. package/dist/cli/agent-commands.js +0 -27
  74. package/dist/cli/args.d.ts +0 -7
  75. package/dist/cli/args.js +0 -31
  76. package/dist/cli/files.d.ts +0 -2
  77. package/dist/cli/files.js +0 -21
  78. package/dist/cli/help.d.ts +0 -1
  79. package/dist/cli/help.js +0 -15
  80. package/dist/cli/open.d.ts +0 -3
  81. package/dist/cli/open.js +0 -8
  82. package/dist/cli/run.d.ts +0 -1
  83. package/dist/cli/run.js +0 -33
  84. package/dist/cli.d.ts +0 -2
  85. package/dist/cli.js +0 -2
  86. package/dist/database.d.ts +0 -9
  87. package/dist/database.js +0 -35
  88. package/dist/rows.d.ts +0 -4
  89. package/dist/rows.js +0 -28
  90. package/dist/schema.d.ts +0 -2
  91. package/dist/schema.js +0 -162
  92. package/docs/CLI.md +0 -23
  93. package/docs/ENGINE_INTEGRATION.md +0 -12
@@ -1,85 +1,54 @@
1
1
  ---
2
2
  name: amalgm-agents
3
- 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.
3
+ description: Manage the user's Amalgm agents with the Agents MCP tools, the `amalgm agents` CLI, or the @amalgm/agents SDK. 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.
4
4
  ---
5
5
 
6
6
  # Agents
7
7
 
8
- 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.
8
+ Agents keeps the user's agents. Each agent is one folder in the user's agents folder, and that folder is the only copy of it. You define an agent once — its harness, model, instructions, tools, skills, and workspace — and every surface (the MCP tools, the `amalgm agents` CLI, REST, the SDK, and the Amalgm apps) reads and writes the same folders through the one running `Agents` service. Agents does not run conversations: it resolves an exact revision, and Chat executes it.
9
9
 
10
- ## Installation
10
+ ## Reaching Agents
11
11
 
12
- Install the package from npm. It requires Node 20 or later.
12
+ On an Amalgm computer, use the running runtime. Never open or write agent files from a second process.
13
13
 
14
- ```bash
15
- npm install @amalgm/agents
16
- ```
17
-
18
- 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`.
19
-
20
- ```bash
21
- npx amalgm-agents --help
22
- ```
14
+ - **MCP tools.** The runtime serves `agents_list`, `agents_get`, `agents_create`, `agents_update`, `agents_set_pinned`, and `agents_delete` at `/mcp/agents`.
15
+ - **CLI.** Shell's `amalgm agents …` calls those same tools on the running runtime, with the same JSON inputs and results. Run `amalgm agents --help` for its commands.
23
16
 
24
- ## Quickstart
25
-
26
- 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.
17
+ | Tool | Arguments | Behavior |
18
+ |---|---|---|
19
+ | `agents_list` | — | List the agents in this user's agents folder |
20
+ | `agents_get` | `agent_id` | Read one agent: definition, pinned state, current revision id |
21
+ | `agents_create` | `definition` | Create from a definition; without `definition.id` the agent gets a new UUID |
22
+ | `agents_update` | `agent_id`, `patch` | Patch the definition; a new name renames the folder once the agent is idle |
23
+ | `agents_set_pinned` | `agent_id`, `pinned` | Show or hide the agent in every agent picker |
24
+ | `agents_delete` | `agent_id` | Delete the agent and its folder; built-ins cannot be deleted, unpin them instead |
27
25
 
28
- ```ts
29
- import { Agents } from '@amalgm/agents';
26
+ 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.
30
27
 
31
- const agents = new Agents({ stateDir: './state' });
32
-
33
- try {
34
- // Define and create an agent. `id`, `name`, and `driver` are required;
35
- // everything else has a sensible empty default.
36
- agents.createAgent({
37
- id: 'reviewer',
38
- name: 'Reviewer',
39
- description: 'Reviews implementation work',
40
- driver: 'codex',
41
- instructions: 'Find correctness risks before style issues.',
42
- });
43
-
44
- // List every available (non-deleted) agent.
45
- for (const agent of agents.listAgents()) {
46
- console.log(agent.id, agent.definition.name, `rev ${agent.currentRevision}`);
47
- }
28
+ ## Core concepts
48
29
 
49
- // Inspect one agent's current definition.
50
- const record = agents.getAgent('reviewer');
51
- console.log(record?.definition.instructions);
30
+ ### The agent folder
52
31
 
53
- // Resolve the exact immutable revision a host such as Chat would execute.
54
- const revision = agents.getAgentRevision('reviewer');
55
- console.log(revision.id, revision.number, revision.hash);
56
- } finally {
57
- agents.close();
58
- }
32
+ ```text
33
+ <agents folder>/Reviewer/
34
+ .amalgm-agent.json id, the definition (minus the texts below), pinned, built-in state
35
+ instructions.md the definition's instructions
36
+ skills/<skill>/SKILL.md the text of each skill in the agent's config
37
+ .private/ computer-only: harness homes and resolved revisions
59
38
  ```
60
39
 
61
- 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.
62
-
63
- ## Core concepts
64
-
65
- Agents separates three ideas that most agent frameworks blur together. Keeping them distinct is what makes agent executions reproducible.
40
+ Every call reads the folder fresh, so an edit to `instructions.md` or a `SKILL.md` is the agent's new definition. The folder name follows the agent's `name` (`Reviewer`, then `Reviewer-2` for a second agent with the same name). `.private/` never syncs; deleting an agent parks it outside the agents folder.
66
41
 
67
42
  ### Identity
68
43
 
69
- 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.
44
+ An agent's `id` is its permanent identity: a UUID by default, or 1–128 lowercase letters, numbers, dots, underscores, or hyphens when you pass one. Renaming the agent never changes it, and other products reference agents by this id.
70
45
 
71
46
  ### Revision
72
47
 
73
- 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.
48
+ A revision is one exact definition, named by its hash (`revision-<16 hex>`). Chat records the revision used by each execution, so a conversation always names precisely the instructions, model, and tool references that produced it.
74
49
 
75
- Two consequences follow from the append-only design:
76
-
77
- - **Idempotent edits.** Submitting a patch that produces identical content keeps the current revision; nothing is appended.
78
- - **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.
79
-
80
- ### Installation
81
-
82
- 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.
50
+ - **Idempotent edits.** A patch that produces identical content keeps the current revision.
51
+ - **Same content, same revision.** Returning to an earlier definition returns to its revision.
83
52
 
84
53
  ## Agent definitions
85
54
 
@@ -87,7 +56,6 @@ A definition is complete, portable execution configuration. It holds *references
87
56
 
88
57
  ```json
89
58
  {
90
- "id": "reviewer",
91
59
  "name": "Reviewer",
92
60
  "description": "Reviews implementation work",
93
61
  "instructions": "Find correctness risks before style issues.",
@@ -110,137 +78,67 @@ A definition is complete, portable execution configuration. It holds *references
110
78
 
111
79
  Field notes:
112
80
 
113
- - `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.
81
+ - `name` and `driver` are required. `driver` names the harness that will run the agent; a plain string (`"driver": "codex"`) becomes `{ "id": "codex", "config": {} }`. `driver.config` is non-secret harness configuration interpreted at execution time.
114
82
  - `model` and `authRef` are nullable. `authRef` names a credential that the host resolves when the agent runs; the secret itself never enters the definition.
115
- - `resources` and `toolbox` are lists of opaque ids resolved by the host. Arrays are de-duplicated and order-normalized.
83
+ - `resources` and `toolbox` are lists of opaque ids resolved by the host. Arrays are de-duplicated.
116
84
  - `metadata` is free-form JSON for your own annotations (icons, tags, owners).
117
85
 
118
- ## SDK reference
119
-
120
- `Agents` is the single behavior boundary — the CLI, REST, and MCP surfaces are thin adapters over these same methods, so behavior is identical everywhere.
121
-
122
- | Method | Behavior |
123
- |---|---|
124
- | `createAgent(definition, { pinned? })` | Create an identity and immutable revision 1; pinned unless `pinned: false` |
125
- | `updateAgent(id, patch)` | Merge a patch; append a revision only when content changes |
126
- | `setAgentPinned(id, pinned)` | Show or hide the agent in every agent picker; never a revision |
127
- | `deleteAgent(id)` | Tombstone the identity, retaining all revisions; built-ins raise `conflict` |
128
- | `getAgent(id, includeDeleted?)` | Read the current record, or `null` if absent |
129
- | `listAgents(includeDeleted?)` | List available agents (tombstones excluded by default) |
130
- | `getAgentRevision(agentId, revisionId?)` | Resolve the current or one exact immutable revision |
131
- | `health()` | Liveness summary for the open registry |
132
- | `close()` | Release the underlying database |
133
-
134
86
  ### Patching
135
87
 
136
- 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.
137
-
138
- ```ts
139
- const updated = agents.updateAgent('reviewer', {
140
- instructions: 'Review for correctness first, style second.',
141
- resources: { skills: ['code-review', 'security-review'] },
142
- model: null, // clear the chosen model; the host default applies
143
- });
144
- console.log(updated.currentRevision); // bumped, because content changed
145
- ```
146
-
147
- ### Errors
88
+ Patches are partial definitions: top-level fields replace their prior values, while `driver`, `resources`, `toolbox`, and `workspace` merge field by field. A patch touching only `resources.skills` preserves `resources.files` and `resources.subagents`. Set a nullable field to `null` to clear it.
148
89
 
149
- 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.
150
-
151
- ```ts
152
- import { Agents, AgentError } from '@amalgm/agents';
153
-
154
- try {
155
- agents.updateAgent('missing-id', { name: 'Nope' });
156
- } catch (error) {
157
- if (error instanceof AgentError && error.code === 'not_found') {
158
- console.log('No such agent.');
159
- } else {
160
- throw error;
90
+ ```json
91
+ {
92
+ "agent_id": "reviewer",
93
+ "patch": {
94
+ "instructions": "Review for correctness first, style second.",
95
+ "resources": { "skills": ["code-review", "security-review"] },
96
+ "model": null
161
97
  }
162
98
  }
163
99
  ```
164
100
 
165
- ## CLI
166
-
167
- 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.
168
-
169
- ```bash
170
- amalgm-agents agent list [--include-deleted]
171
- amalgm-agents agent show <id> [--include-deleted]
172
- amalgm-agents agent create <definition.json>
173
- amalgm-agents agent update <id> <patch.json>
174
- amalgm-agents agent pin <id>
175
- amalgm-agents agent unpin <id>
176
- amalgm-agents agent delete <id>
177
- ```
178
-
179
- `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`.
180
-
181
- ```bash
182
- # Create from a file, then confirm the revision advanced after an edit.
183
- amalgm-agents agent create reviewer.json
184
- echo '{"instructions": "Be terse."}' > patch.json
185
- amalgm-agents agent update reviewer patch.json
186
- amalgm-agents agent show reviewer | jq .currentRevision
187
- ```
188
-
189
- ## REST API
190
-
191
- For non-Node hosts, run the loopback REST server or embed it with `createRestServer` from `@amalgm/agents/http`.
192
-
193
- ```bash
194
- amalgm-agents-rest --host 127.0.0.1 --port 4317 --token "$TOKEN"
195
- ```
101
+ ### Errors
196
102
 
197
- When a token is configured, authenticate with `Authorization: Bearer <token>`; `/healthz` stays unauthenticated. JSON bodies are limited to 512 KB by default.
103
+ Expected failures carry a stable `code` — `invalid_input`, `not_found`, `conflict`, or `too_large` — with a matching HTTP status. Branch on the code rather than the message.
198
104
 
199
- | Method | Path | Result |
200
- |---|---|---|
201
- | `GET` | `/v1/agents` | List available agents |
202
- | `POST` | `/v1/agents` | Create from a complete definition |
203
- | `GET` | `/v1/agents/:id` | Read the current definition |
204
- | `PATCH` | `/v1/agents/:id` | Apply a definition patch |
205
- | `PUT` | `/v1/agents/:id/pinned` | Set `{ "pinned": boolean }`; no revision |
206
- | `DELETE` | `/v1/agents/:id` | Tombstone an identity; `409` for built-ins |
105
+ ## Embedding the SDK
207
106
 
208
- Add `?include_deleted=true` to list or get requests to include tombstones. There are no conversation routes — execution belongs to Chat.
107
+ A host such as Shell builds one `Agents` and hands it every folder it uses; there are no defaults. Pass that one instance to `createMcpServer({ agents })` and `createRestServer({ agents })`.
209
108
 
210
- ## MCP tools
109
+ ```ts
110
+ import { Agents } from '@amalgm/agents';
211
111
 
212
- `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.
112
+ const agents = new Agents({
113
+ root, // the user's agents folder
114
+ parked, // where a deleted agent's .private/ is moved
115
+ osHome, // the OS account home, read only: harness skills and native config
116
+ isBusy, // (agentId) => boolean; a running agent's folder is not renamed
117
+ });
213
118
 
214
- ```bash
215
- amalgm-agents-mcp --state-dir ./state
119
+ const reviewer = agents.createAgent({ name: 'Reviewer', driver: 'codex', instructions: 'Find correctness risks.' });
120
+ const revision = agents.getAgentRevision(reviewer.id);
121
+ const home = agents.harnessHome(reviewer.id, 'codex', authKey); // <agent folder>/.private/codex-<authKey>
216
122
  ```
217
123
 
218
- It exposes six tools, each a direct projection of an SDK method:
219
-
220
- | Tool | Arguments | Behavior |
221
- |---|---|---|
222
- | `agents_list` | `include_deleted?` | List persistent agent definitions |
223
- | `agents_get` | `agent_id`, `include_deleted?` | Read one agent and its current revision |
224
- | `agents_create` | `definition` | Create from a complete definition |
225
- | `agents_update` | `agent_id`, `patch` | Patch; content changes append a revision |
226
- | `agents_set_pinned` | `agent_id`, `pinned` | Show or hide the agent in every agent picker |
227
- | `agents_delete` | `agent_id` | Tombstone an identity; built-ins cannot be deleted, unpin them instead |
228
-
229
- 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.
124
+ | Method | Behavior |
125
+ |---|---|
126
+ | `createAgent(definition, { pinned? })` | Create an agent folder; pinned unless `pinned: false` |
127
+ | `updateAgent(id, patch)` | Merge a patch |
128
+ | `setAgentPinned(id, pinned)` | Show or hide the agent in every agent picker; never a revision |
129
+ | `deleteAgent(id)` | Park `.private/` and remove the folder; built-ins raise `conflict` |
130
+ | `getAgent(id)` | Read the current record, or `null` |
131
+ | `listAgents()` | List every agent |
132
+ | `getAgentRevision(agentId, revisionId?)` | Resolve the current or one exact revision |
133
+ | `harnessHome(agentId, harness, authKey)` | Make and return the harness home in the agent's `.private/` |
230
134
 
231
135
  ## Running agents with Chat
232
136
 
233
- 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:
137
+ Agents contains no conversation, execution, transcript, interrupt, or reconnect operation. To run an agent, resolve it here and hand the result to Chat:
234
138
 
235
- 1. Select an installed agent identity (from `listAgents` or a known id).
236
- 2. Call `getAgentRevision(agentId, revisionId?)` — you get the current revision, or one exact historical revision if you pass its id.
237
- 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.
238
- 4. Chat records which revision it executed, so the conversation remains reproducible even after the agent is edited or deleted.
239
-
240
- ```ts
241
- const revision = agents.getAgentRevision('reviewer');
242
- // revision.definition is the frozen, normalized definition:
243
- // pass it to Chat to start or continue a conversation as this agent.
244
- ```
139
+ 1. Select an agent (from `agents_list` or a known id).
140
+ 2. Resolve its revision — the current one, or one exact revision if you pass its id.
141
+ 3. Project that definition into Chat's execution contract. Chat resolves the `toolbox`, `resources`, and `authRef` references into concrete values, freezes them, and then accepts the turn.
142
+ 4. Chat records which revision it executed, so the conversation remains reproducible after the agent is edited.
245
143
 
246
- 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.
144
+ 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.
@@ -1,2 +0,0 @@
1
- #!/usr/bin/env node
2
- export {};
@@ -1,5 +0,0 @@
1
- #!/usr/bin/env node
2
- import { runCli } from '../cli/run.js';
3
- void runCli().then((code) => {
4
- process.exitCode = code;
5
- });
@@ -1 +0,0 @@
1
- export declare function fatal(error: unknown): void;
package/dist/bin/fatal.js DELETED
@@ -1,5 +0,0 @@
1
- export function fatal(error) {
2
- const message = error instanceof Error ? error.message : String(error);
3
- process.stderr.write(`amalgm-agents: ${message}\n`);
4
- process.exitCode = 1;
5
- }
package/dist/bin/mcp.d.ts DELETED
@@ -1,2 +0,0 @@
1
- #!/usr/bin/env node
2
- export {};
package/dist/bin/mcp.js DELETED
@@ -1,19 +0,0 @@
1
- #!/usr/bin/env node
2
- import { parseArgs } from '../cli/args.js';
3
- import { openAgents } from '../cli/open.js';
4
- import { createMcpServer } from '../mcp/server.js';
5
- import { fatal } from './fatal.js';
6
- async function main() {
7
- const args = parseArgs(process.argv.slice(2));
8
- if (args.flags.has('help')) {
9
- process.stdout.write('Usage: amalgm-agents-mcp [--state-dir <path>]\n');
10
- return;
11
- }
12
- const agents = await openAgents(args);
13
- const server = createMcpServer({ agents });
14
- const stop = await server.start();
15
- const close = () => void stop().then(() => agents.close()).catch(fatal);
16
- process.once('SIGTERM', close);
17
- process.once('SIGINT', close);
18
- }
19
- void main().catch(fatal);
@@ -1,2 +0,0 @@
1
- #!/usr/bin/env node
2
- export {};
package/dist/bin/rest.js DELETED
@@ -1,26 +0,0 @@
1
- #!/usr/bin/env node
2
- import { parseArgs, flag } from '../cli/args.js';
3
- import { openAgents } from '../cli/open.js';
4
- import { createRestServer } from '../http/server.js';
5
- import { fatal } from './fatal.js';
6
- async function main() {
7
- const args = parseArgs(process.argv.slice(2));
8
- if (args.flags.has('help')) {
9
- process.stdout.write('Usage: amalgm-agents-rest [--host 127.0.0.1] [--port 4317] [--token value] [--native-home dir]\n');
10
- return;
11
- }
12
- const agents = await openAgents(args);
13
- const token = flag(args, 'token') || process.env.AMALGM_AGENTS_TOKEN;
14
- const nativeHomeDir = flag(args, 'native-home') || process.env.AMALGM_NATIVE_HOME;
15
- const rest = createRestServer({
16
- agents,
17
- ...(token ? { token } : {}),
18
- ...(nativeHomeDir ? { nativeHomeDir } : {}),
19
- });
20
- const address = await rest.listen(Number(flag(args, 'port') || 4317), flag(args, 'host') || '127.0.0.1');
21
- process.stderr.write(`amalgm-agents REST listening on http://${address.address}:${address.port}\n`);
22
- const close = () => void rest.close().then(() => agents.close()).catch(fatal);
23
- process.once('SIGTERM', close);
24
- process.once('SIGINT', close);
25
- }
26
- void main().catch(fatal);
@@ -1,12 +0,0 @@
1
- import type { AgentBundle, BundleHeadType } from './types.js';
2
- export interface CopyBundleOptions {
3
- /** Fresh identity for one construct; the default is random. */
4
- freshId?: (type: BundleHeadType) => string;
5
- now?: () => string;
6
- }
7
- /**
8
- * A copy is the same content under fresh identities: no construct of the
9
- * source is named anywhere in it, and its graph is rebuilt around the new
10
- * names. It is how a published copy cuts lineage.
11
- */
12
- export declare function copyAgentBundle(source: AgentBundle, options?: CopyBundleOptions): AgentBundle;
@@ -1,144 +0,0 @@
1
- import crypto from 'node:crypto';
2
- import { buildBundleGraph } from './graph.js';
3
- import { actionEntryId, agentEntryId, appEntryId, automationEntryId, toolEntryId } from './graph-records.js';
4
- import { bundleId, clean, clone, object } from './util.js';
5
- /**
6
- * The identity map of one copy: every construct of the source bundle to its
7
- * fresh identity. Tool action ids follow their tool: `<tool>.<action>`.
8
- */
9
- class IdentityMap {
10
- #ids = new Map();
11
- #fresh;
12
- constructor(fresh) {
13
- this.#fresh = fresh;
14
- }
15
- assign(type, id) {
16
- if (!id)
17
- throw new Error(`bundle ${type} entries must include ids`);
18
- const next = this.#fresh(type);
19
- this.#ids.set(id, next);
20
- return next;
21
- }
22
- assignAction(id, toolId) {
23
- const tool = this.#ids.get(toolId);
24
- if (!tool)
25
- throw new Error(`tool action ${id} references missing tool: ${toolId}`);
26
- const separator = id.lastIndexOf('.');
27
- const next = `${tool}${separator >= 0 ? id.slice(separator) : `.${id}`}`;
28
- this.#ids.set(id, next);
29
- return next;
30
- }
31
- of(id) {
32
- return this.#ids.get(id) ?? id;
33
- }
34
- strings(value) {
35
- return Array.isArray(value) ? value.filter((item) => typeof item === 'string').map((item) => this.of(item)) : [];
36
- }
37
- /** Rewrite every `actionId` in a compiled plan; keys are the plan's own. */
38
- plan(value) {
39
- if (Array.isArray(value))
40
- return value.map((item) => this.plan(item));
41
- const record = object(value);
42
- if (!record)
43
- return value;
44
- return Object.fromEntries(Object.entries(record).map(([key, child]) => [
45
- key,
46
- (key === 'actionId' || key === 'action_id') && typeof child === 'string' ? this.of(child) : this.plan(child),
47
- ]));
48
- }
49
- /** `automation:<id>:field` bindings and `tools.<id>.path` secret paths; ids may contain dots. */
50
- requirement(value) {
51
- const binding = value.match(/^(automation|tool|toolAction):([^:]+):(.*)$/);
52
- if (binding)
53
- return `${binding[1]}:${this.of(binding[2])}:${binding[3]}`;
54
- const secret = value.match(/^(tools|toolActions)\.(.*)$/);
55
- if (!secret)
56
- return value;
57
- for (const [id, next] of this.#ids) {
58
- if (secret[2].startsWith(`${id}.`))
59
- return `${secret[1]}.${next}${secret[2].slice(id.length)}`;
60
- }
61
- return value;
62
- }
63
- }
64
- function defaultFreshId(type) {
65
- const id = crypto.randomUUID();
66
- return type === 'tool' ? `tool-${id.replace(/-/g, '').slice(0, 16)}` : `${type}-${id}`;
67
- }
68
- function isSystemTool(tool) {
69
- return tool.origin === 'system';
70
- }
71
- /**
72
- * A copy is the same content under fresh identities: no construct of the
73
- * source is named anywhere in it, and its graph is rebuilt around the new
74
- * names. It is how a published copy cuts lineage.
75
- */
76
- export function copyAgentBundle(source, options = {}) {
77
- const bundle = clone(source);
78
- const ids = new IdentityMap(options.freshId ?? defaultFreshId);
79
- for (const entry of bundle.agents)
80
- ids.assign('agent', agentEntryId(entry));
81
- for (const entry of bundle.automations)
82
- ids.assign('automation', automationEntryId(entry));
83
- for (const entry of bundle.apps)
84
- ids.assign('app', appEntryId(entry));
85
- for (const tool of bundle.tools)
86
- if (!isSystemTool(tool))
87
- ids.assign('tool', toolEntryId(tool));
88
- for (const action of bundle.toolActions) {
89
- const toolId = clean(action.toolId);
90
- const tool = bundle.tools.find((candidate) => toolEntryId(candidate) === toolId);
91
- if (tool && !isSystemTool(tool))
92
- ids.assignAction(actionEntryId(action), toolId);
93
- }
94
- for (const entry of bundle.agents) {
95
- entry.sourceAgentId = ids.of(entry.sourceAgentId);
96
- entry.config = {
97
- ...entry.config,
98
- ...(entry.config.agentId ? { agentId: entry.sourceAgentId } : {}),
99
- loadout: { toolIds: ids.strings(entry.config.loadout.toolIds), ...(entry.config.loadout.exposure ? {
100
- exposure: Object.fromEntries(Object.entries(entry.config.loadout.exposure).map(([id, mode]) => [ids.of(id), mode])),
101
- } : {}) },
102
- subagents: entry.config.subagents.map((subagent) => ({ ...subagent, agentId: ids.of(subagent.agentId) })),
103
- };
104
- }
105
- for (const entry of bundle.automations) {
106
- entry.sourceAutomationId = ids.of(clean(entry.sourceAutomationId));
107
- entry.toolIds = ids.strings(entry.toolIds);
108
- if (Array.isArray(entry.workflows)) {
109
- entry.workflows = entry.workflows.map((workflow) => {
110
- const record = object(workflow);
111
- return record ? { ...record, compiled: ids.plan(record.compiled ?? null) } : workflow;
112
- });
113
- }
114
- }
115
- for (const entry of bundle.apps) {
116
- entry.sourceAppId = ids.of(clean(entry.sourceAppId));
117
- entry.toolIds = ids.strings(entry.toolIds);
118
- const manifest = object(entry.manifest);
119
- if (manifest && Array.isArray(manifest.toolIds))
120
- entry.manifest = { ...manifest, toolIds: ids.strings(manifest.toolIds) };
121
- }
122
- for (const tool of bundle.tools) {
123
- tool.id = ids.of(toolEntryId(tool));
124
- if (clean(tool.appId))
125
- tool.appId = ids.of(clean(tool.appId));
126
- }
127
- for (const action of bundle.toolActions) {
128
- action.id = ids.of(actionEntryId(action));
129
- action.toolId = ids.of(clean(action.toolId));
130
- if (clean(action.appId))
131
- action.appId = ids.of(clean(action.appId));
132
- }
133
- bundle.heads = bundle.heads.map((head) => ({ ...head, id: ids.of(head.id) }));
134
- bundle.rootAgentId = bundle.rootAgentId ? ids.of(bundle.rootAgentId) : null;
135
- bundle.requires = {
136
- ...bundle.requires,
137
- bindings: bundle.requires.bindings.map((value) => ids.requirement(value)),
138
- secrets: bundle.requires.secrets.map((value) => ids.requirement(value)),
139
- };
140
- bundle.bundleId = bundleId();
141
- bundle.createdAt = options.now?.() || new Date().toISOString();
142
- Object.assign(bundle, buildBundleGraph(bundle));
143
- return bundle;
144
- }
@@ -1,3 +0,0 @@
1
- import type { Agents } from '../agents.js';
2
- import type { ParsedArgs } from './args.js';
3
- export declare function runAgentCommand(agents: Agents, args: ParsedArgs): unknown;
@@ -1,27 +0,0 @@
1
- import { AgentError } from '../errors.js';
2
- import { enabled } from './args.js';
3
- import { readObjectFile } from './files.js';
4
- export function runAgentCommand(agents, args) {
5
- const [, action, first, second] = args.words;
6
- if (action === 'list')
7
- return { agents: agents.listAgents(enabled(args, 'include-deleted')) };
8
- if (action === 'show' && first) {
9
- const agent = agents.getAgent(first, enabled(args, 'include-deleted'));
10
- if (!agent)
11
- throw new AgentError('not_found', `Agent not found: ${first}`);
12
- return { agent };
13
- }
14
- if (action === 'create' && first) {
15
- return { agent: agents.createAgent(readObjectFile(first)) };
16
- }
17
- if (action === 'update' && first && second) {
18
- return { agent: agents.updateAgent(first, readObjectFile(second)) };
19
- }
20
- if (action === 'pin' && first)
21
- return { agent: agents.setAgentPinned(first, true) };
22
- if (action === 'unpin' && first)
23
- return { agent: agents.setAgentPinned(first, false) };
24
- if (action === 'delete' && first)
25
- return { agent: agents.deleteAgent(first) };
26
- throw new AgentError('invalid_input', 'Unknown or incomplete agent command. Run with --help.');
27
- }
@@ -1,7 +0,0 @@
1
- export interface ParsedArgs {
2
- words: string[];
3
- flags: Map<string, string | boolean>;
4
- }
5
- export declare function parseArgs(argv: string[]): ParsedArgs;
6
- export declare function flag(args: ParsedArgs, name: string): string | undefined;
7
- export declare function enabled(args: ParsedArgs, name: string): boolean;
package/dist/cli/args.js DELETED
@@ -1,31 +0,0 @@
1
- export function parseArgs(argv) {
2
- const words = [];
3
- const flags = new Map();
4
- for (let index = 0; index < argv.length; index += 1) {
5
- const item = argv[index];
6
- if (!item?.startsWith('--')) {
7
- if (item !== undefined)
8
- words.push(item);
9
- continue;
10
- }
11
- const [rawName, inline] = item.slice(2).split('=', 2);
12
- const next = argv[index + 1];
13
- if (inline !== undefined)
14
- flags.set(rawName || '', inline);
15
- else if (next !== undefined && !next.startsWith('--')) {
16
- flags.set(rawName || '', next);
17
- index += 1;
18
- }
19
- else
20
- flags.set(rawName || '', true);
21
- }
22
- return { words, flags };
23
- }
24
- export function flag(args, name) {
25
- const value = args.flags.get(name);
26
- return typeof value === 'string' ? value : undefined;
27
- }
28
- export function enabled(args, name) {
29
- const value = args.flags.get(name);
30
- return value === true || value === 'true';
31
- }
@@ -1,2 +0,0 @@
1
- export declare function readObjectFile(file: string): Record<string, unknown>;
2
- export declare function writeJson(value: unknown): void;