@amalgm/agents 0.2.3-preview.37556893493 → 0.2.3-preview.44182699998
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.
- package/PURPOSE.md +21 -19
- package/README.md +25 -36
- package/dist/agent-folder.d.ts +32 -0
- package/dist/agent-folder.js +100 -0
- package/dist/agent-store.d.ts +23 -12
- package/dist/agent-store.js +144 -117
- package/dist/agents.d.ts +10 -10
- package/dist/agents.js +14 -26
- package/dist/bundles/create.d.ts +1 -0
- package/dist/bundles/create.js +1 -1
- package/dist/bundles/graph.d.ts +1 -0
- package/dist/bundles/graph.js +1 -1
- package/dist/bundles/install.d.ts +1 -0
- package/dist/bundles/install.js +1 -2
- package/dist/bundles/validate.d.ts +1 -0
- package/dist/bundles/validate.js +1 -1
- package/dist/config/import.d.ts +1 -1
- package/dist/config/import.js +2 -2
- package/dist/config/native.d.ts +5 -1
- package/dist/config/native.js +12 -11
- package/dist/config/schema.d.ts +1 -0
- package/dist/config/schema.js +1 -1
- package/dist/config/store.js +7 -7
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +0 -1
- package/dist/http/agent-routes.js +2 -4
- package/dist/http/bundle-routes.js +2 -23
- package/dist/http/config-routes.js +1 -4
- package/dist/http/server.d.ts +1 -1
- package/dist/http/server.js +3 -9
- package/dist/http/skill-routes.d.ts +0 -1
- package/dist/http/skill-routes.js +2 -3
- package/dist/http-types.d.ts +2 -8
- package/dist/ids.d.ts +0 -4
- package/dist/ids.js +0 -23
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -1
- package/dist/json.d.ts +1 -4
- package/dist/json.js +0 -23
- package/dist/mcp/agent-tools.js +11 -12
- package/dist/mcp/server.d.ts +3 -4
- package/dist/mcp/server.js +3 -41
- package/dist/mcp/types.d.ts +0 -1
- package/dist/revisions.d.ts +9 -0
- package/dist/revisions.js +39 -0
- package/dist/skills/roots.d.ts +6 -7
- package/dist/skills/roots.js +16 -29
- package/dist/skills/scanner.d.ts +2 -2
- package/dist/skills/scanner.js +2 -2
- package/dist/types.d.ts +9 -6
- package/docs/ARCHITECTURE.md +24 -25
- package/docs/DATA_MODEL.md +27 -21
- package/docs/DEFINITIONS.md +11 -9
- package/docs/MCP.md +5 -5
- package/docs/REST.md +7 -7
- package/docs/SDK.md +17 -13
- package/docs/SECURITY.md +4 -3
- package/docs/SHELL_INTEGRATION.md +22 -2
- package/examples/basic.ts +15 -11
- package/package.json +9 -20
- package/skills/amalgm-agents/SKILL.md +69 -171
- package/dist/bin/agents.d.ts +0 -2
- package/dist/bin/agents.js +0 -5
- package/dist/bin/fatal.d.ts +0 -1
- package/dist/bin/fatal.js +0 -5
- package/dist/bin/mcp.d.ts +0 -2
- package/dist/bin/mcp.js +0 -19
- package/dist/bin/rest.d.ts +0 -2
- package/dist/bin/rest.js +0 -26
- package/dist/bundles/copy.d.ts +0 -12
- package/dist/bundles/copy.js +0 -144
- package/dist/cli/agent-commands.d.ts +0 -3
- package/dist/cli/agent-commands.js +0 -27
- package/dist/cli/args.d.ts +0 -7
- package/dist/cli/args.js +0 -31
- package/dist/cli/files.d.ts +0 -2
- package/dist/cli/files.js +0 -21
- package/dist/cli/help.d.ts +0 -1
- package/dist/cli/help.js +0 -15
- package/dist/cli/open.d.ts +0 -3
- package/dist/cli/open.js +0 -8
- package/dist/cli/run.d.ts +0 -1
- package/dist/cli/run.js +0 -33
- package/dist/cli.d.ts +0 -2
- package/dist/cli.js +0 -2
- package/dist/database.d.ts +0 -9
- package/dist/database.js +0 -35
- package/dist/rows.d.ts +0 -4
- package/dist/rows.js +0 -28
- package/dist/schema.d.ts +0 -2
- package/dist/schema.js +0 -162
- package/docs/CLI.md +0 -23
- package/docs/ENGINE_INTEGRATION.md +0 -12
|
@@ -1,85 +1,54 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: amalgm-agents
|
|
3
|
-
description: Manage
|
|
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
|
|
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
|
-
##
|
|
10
|
+
## Reaching Agents
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
On an Amalgm computer, use the running runtime. Never open or write agent files from a second process.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
-
const record = agents.getAgent('reviewer');
|
|
51
|
-
console.log(record?.definition.instructions);
|
|
30
|
+
### The agent folder
|
|
52
31
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
+
```ts
|
|
110
|
+
import { Agents } from '@amalgm/agents';
|
|
211
111
|
|
|
212
|
-
|
|
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
|
-
|
|
215
|
-
|
|
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
|
-
|
|
219
|
-
|
|
220
|
-
|
|
|
221
|
-
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
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
|
|
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
|
|
236
|
-
2.
|
|
237
|
-
3. Project that
|
|
238
|
-
4. Chat records which revision it executed, so the conversation remains reproducible
|
|
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
|
-
|
|
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.
|
package/dist/bin/agents.d.ts
DELETED
package/dist/bin/agents.js
DELETED
package/dist/bin/fatal.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export declare function fatal(error: unknown): void;
|
package/dist/bin/fatal.js
DELETED
package/dist/bin/mcp.d.ts
DELETED
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);
|
package/dist/bin/rest.d.ts
DELETED
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);
|
package/dist/bundles/copy.d.ts
DELETED
|
@@ -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;
|
package/dist/bundles/copy.js
DELETED
|
@@ -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,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
|
-
}
|
package/dist/cli/args.d.ts
DELETED
|
@@ -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
|
-
}
|
package/dist/cli/files.d.ts
DELETED