@amalgm/agents 0.2.3-preview.37556574617 → 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.
- 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
package/dist/types.d.ts
CHANGED
|
@@ -47,10 +47,10 @@ export type AgentDefinitionInput = Partial<Omit<AgentDefinition, 'driver' | 'mod
|
|
|
47
47
|
workspace?: Partial<AgentWorkspace>;
|
|
48
48
|
};
|
|
49
49
|
export type AgentPatch = Omit<Partial<AgentDefinitionInput>, 'id'>;
|
|
50
|
+
/** One exact definition an agent has had, kept so a turn can resolve it after later edits. */
|
|
50
51
|
export interface AgentRevision {
|
|
51
52
|
id: string;
|
|
52
53
|
agentId: string;
|
|
53
|
-
number: number;
|
|
54
54
|
hash: string;
|
|
55
55
|
definition: AgentDefinition;
|
|
56
56
|
createdAt: string;
|
|
@@ -58,7 +58,6 @@ export interface AgentRevision {
|
|
|
58
58
|
export interface AgentRecord {
|
|
59
59
|
id: string;
|
|
60
60
|
currentRevisionId: string;
|
|
61
|
-
currentRevision: number;
|
|
62
61
|
definition: AgentDefinition;
|
|
63
62
|
/** Shown wherever a user picks an agent. Identity state; never a revision. */
|
|
64
63
|
pinned: boolean;
|
|
@@ -66,14 +65,18 @@ export interface AgentRecord {
|
|
|
66
65
|
builtin: boolean;
|
|
67
66
|
createdAt: string;
|
|
68
67
|
updatedAt: string;
|
|
69
|
-
deletedAt: string | null;
|
|
70
68
|
}
|
|
71
69
|
export interface CreateAgentOptions {
|
|
72
70
|
/** Defaults to true: a new agent appears in every agent picker. */
|
|
73
71
|
pinned?: boolean;
|
|
74
72
|
}
|
|
75
73
|
export interface AgentsOptions {
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
74
|
+
/** The user's agents folder. Each agent is one folder inside it. */
|
|
75
|
+
root: string;
|
|
76
|
+
/** Where a deleted agent's `.private/` folder is moved. */
|
|
77
|
+
parked: string;
|
|
78
|
+
/** The OS account home, read only: where harness CLIs keep their own skills and config. */
|
|
79
|
+
osHome: string;
|
|
80
|
+
/** True while the agent is running; its folder is not renamed then. */
|
|
81
|
+
isBusy(agentId: string): boolean;
|
|
79
82
|
}
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -4,24 +4,23 @@
|
|
|
4
4
|
|
|
5
5
|
The Agents service owns three facts:
|
|
6
6
|
|
|
7
|
-
1. which
|
|
8
|
-
2. the
|
|
9
|
-
3.
|
|
7
|
+
1. which agents exist, each as one folder in the user's agents folder;
|
|
8
|
+
2. the revisions of each agent that callers have been handed; and
|
|
9
|
+
3. each agent's computer-only `.private/` folder, including its harness homes.
|
|
10
10
|
|
|
11
11
|
Everything else crosses an adapter boundary.
|
|
12
12
|
|
|
13
13
|
```text
|
|
14
14
|
SDK
|
|
15
15
|
│
|
|
16
|
-
|
|
17
|
-
├── Agents ───┤
|
|
18
|
-
MCP ───┘ │ └─── Engine adapter
|
|
16
|
+
MCP ───── Agents ───── REST
|
|
19
17
|
│
|
|
20
|
-
|
|
18
|
+
<agents folder>/<Agent>/
|
|
21
19
|
```
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
|
|
21
|
+
MCP and REST are thin adapters over the one `Agents` instance the host passes
|
|
22
|
+
them; neither opens a file. The `amalgm agents …` CLI in Shell calls the
|
|
23
|
+
running runtime's `/mcp/agents` mount, so it is the MCP adapter too.
|
|
25
24
|
|
|
26
25
|
## Product boundaries
|
|
27
26
|
|
|
@@ -31,30 +30,30 @@ public service; the stores below it are implementation details.
|
|
|
31
30
|
| Tools | tools, actions, drivers, loadouts | opaque tool/action ids |
|
|
32
31
|
| Skills | skill content and installation | opaque skill ids |
|
|
33
32
|
| Credentials | secret material and authorization | opaque `authRef` |
|
|
34
|
-
| Shell | native harness processes, auth, machine effects, exact SDK composition | resolved revision projection |
|
|
35
|
-
| Agents |
|
|
33
|
+
| Shell | folders, native harness processes, auth, machine effects, exact SDK composition | resolved revision projection |
|
|
34
|
+
| Agents | agent folders, revisions, harness homes | the agents folder Shell hands it |
|
|
36
35
|
|
|
37
|
-
A Chat conversation is executable history. It names one
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
36
|
+
A Chat conversation is executable history. It names one agent and the exact
|
|
37
|
+
revision used by each prepared execution. Agents never imports Chat and Chat
|
|
38
|
+
never imports the Agents store; Shell composes their public capabilities
|
|
39
|
+
through an explicit resolver.
|
|
41
40
|
|
|
42
41
|
## Mutation path
|
|
43
42
|
|
|
44
|
-
`createAgent`
|
|
45
|
-
merges a typed patch into the current definition and
|
|
46
|
-
|
|
47
|
-
|
|
43
|
+
`createAgent` writes a new folder; without an id the agent gets a new UUID.
|
|
44
|
+
`updateAgent` merges a typed patch into the current definition and writes the
|
|
45
|
+
files that changed. Equal content is idempotent. Renaming an idle agent renames
|
|
46
|
+
its folder; a running agent (`isBusy`) keeps its folder until it is idle.
|
|
48
47
|
|
|
49
|
-
Deleting an agent
|
|
50
|
-
Chat conversations that already name
|
|
51
|
-
|
|
48
|
+
Deleting an agent moves its `.private/` to the parked folder and removes its
|
|
49
|
+
folder. Chat conversations that already name one of its revisions keep their
|
|
50
|
+
own record of what ran.
|
|
52
51
|
|
|
53
52
|
## Resolution path
|
|
54
53
|
|
|
55
|
-
1. A caller selects an
|
|
56
|
-
2. Agents returns the requested
|
|
57
|
-
|
|
54
|
+
1. A caller selects an agent.
|
|
55
|
+
2. Agents returns the requested revision, or the current revision when no
|
|
56
|
+
revision was requested.
|
|
58
57
|
3. Shell projects that revision into Chat's execution-preparation resolver.
|
|
59
58
|
4. Chat freezes the resolved facts before accepting a turn.
|
|
60
59
|
|
package/docs/DATA_MODEL.md
CHANGED
|
@@ -1,31 +1,37 @@
|
|
|
1
1
|
# Persistence
|
|
2
2
|
|
|
3
|
-
The
|
|
4
|
-
|
|
5
|
-
`$AMALGAM_DIR/agents`, otherwise `~/.amalgm/users/local/agents`.
|
|
3
|
+
The host hands `Agents` the user's agents folder as `root`. Each agent is one
|
|
4
|
+
folder inside it, and that folder is the only copy of the agent:
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
```text
|
|
7
|
+
<root>/Reviewer/
|
|
8
|
+
.amalgm-agent.json id, the definition (minus the texts below), pinned, built-in state
|
|
9
|
+
instructions.md the definition's instructions
|
|
10
|
+
skills/<skill>/SKILL.md the text of each skill in the agent's config
|
|
11
|
+
.private/ computer-only: harness homes and resolved revisions
|
|
12
|
+
<harness>-<authKey>/ one harness home, from harnessHome()
|
|
13
|
+
revisions/<id>.json every revision a caller has been handed
|
|
14
|
+
```
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
16
|
+
Every call reads the folders fresh, so a hand edit to `instructions.md` or a
|
|
17
|
+
`SKILL.md` is the agent's new definition. The folder name follows the agent's
|
|
18
|
+
`name` through Core `entityFolderName`, with `-2`, `-3` for equal names. The
|
|
19
|
+
id never changes. A running agent keeps its folder until `Agents` next sees it
|
|
20
|
+
idle: on its next write or list, or when `Agents` starts.
|
|
13
21
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
Chat.
|
|
22
|
+
A revision is one exact definition, named by its hash
|
|
23
|
+
(`revision-<16 hex>`). Repeating the current definition is idempotent, and
|
|
24
|
+
returning to an earlier definition returns to that revision. Conversations and
|
|
25
|
+
turns are stored only by Chat.
|
|
18
26
|
|
|
19
27
|
`pinned` and `builtin` are identity state, not definition content: changing
|
|
20
28
|
either never mints a revision, and no edit to a definition can clear them.
|
|
21
29
|
Every agent picker shows exactly the pinned agents. New agents are pinned; a
|
|
22
30
|
bundle install pins only its agent heads, and a native config import leaves the
|
|
23
|
-
subagents it creates unpinned. `
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
that copy and the config view's `metadata.agentConfig.subagents` are dropped,
|
|
31
|
-
as a new revision that leaves `updated_at` alone.
|
|
31
|
+
subagents it creates unpinned. `builtinHash` records the stock definition the
|
|
32
|
+
platform last installed, so the installer advances a built-in only while its
|
|
33
|
+
current definition is still that stock definition.
|
|
34
|
+
|
|
35
|
+
Deleting an agent moves its `.private/` to Core `parkedDir(parked, 'agent', id)`
|
|
36
|
+
and removes its folder. Its revisions go with `.private/`, so they no longer
|
|
37
|
+
resolve.
|
package/docs/DEFINITIONS.md
CHANGED
|
@@ -36,14 +36,16 @@ products.
|
|
|
36
36
|
## Identity
|
|
37
37
|
|
|
38
38
|
`id` is a stable machine identity: 1–128 lowercase letters, numbers, dots,
|
|
39
|
-
underscores, or hyphens.
|
|
40
|
-
|
|
39
|
+
underscores, or hyphens. Without one, a new agent gets a UUID. Renaming `name`
|
|
40
|
+
never changes it; the agent's folder follows the name instead.
|
|
41
41
|
|
|
42
42
|
## Revisions
|
|
43
43
|
|
|
44
|
-
The normalized complete definition is hashed
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
The normalized complete definition is hashed, and the hash names the revision.
|
|
45
|
+
An edit with equal content keeps the current revision, and returning to an
|
|
46
|
+
earlier definition returns to its revision. A revision's file is never
|
|
47
|
+
rewritten. Chat records the exact revision selected for every prepared
|
|
48
|
+
execution.
|
|
47
49
|
|
|
48
50
|
## PATCH behavior
|
|
49
51
|
|
|
@@ -60,9 +62,9 @@ authoritative and de-duplicated. Set nullable fields such as `model` or
|
|
|
60
62
|
import or mutate a Toolbox.
|
|
61
63
|
- `resources.skills` and `resources.files` are resolved by the host.
|
|
62
64
|
- `resources.subagents` is an agent's one subagent list: ids of other agents
|
|
63
|
-
in
|
|
64
|
-
and not the config view; names and descriptions are read
|
|
65
|
-
the ids name, and an id whose agent was deleted drops out.
|
|
66
|
-
authorizes every agent-to-agent call.
|
|
65
|
+
in the same agents folder. Nothing else stores a subagent list, not
|
|
66
|
+
`driver.config` and not the config view; names and descriptions are read
|
|
67
|
+
from the agents the ids name, and an id whose agent was deleted drops out.
|
|
68
|
+
The host still authorizes every agent-to-agent call.
|
|
67
69
|
- `driver.config` is non-secret harness configuration interpreted only by
|
|
68
70
|
Chat's host runtime.
|
package/docs/MCP.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# MCP server
|
|
2
2
|
|
|
3
|
-
`amalgm
|
|
4
|
-
|
|
3
|
+
`createMcpServer({ agents })` from `@amalgm/agents/mcp` serves the one
|
|
4
|
+
`Agents` instance it is given. The runtime mounts it at `/mcp/agents`, and
|
|
5
|
+
Shell's `amalgm agents …` CLI calls that mount.
|
|
5
6
|
|
|
6
|
-
It exposes six
|
|
7
|
+
It exposes six tools: `agents_list`, `agents_get`, `agents_create`,
|
|
7
8
|
`agents_update`, `agents_set_pinned`, and `agents_delete`. Their handlers call
|
|
8
|
-
the injected `Agents` service; MCP
|
|
9
|
-
conversation runtime.
|
|
9
|
+
the injected `Agents` service; MCP opens no file and runs no conversation.
|
package/docs/REST.md
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# REST API
|
|
2
2
|
|
|
3
|
-
Create an embeddable server with `createRestServer` from
|
|
4
|
-
|
|
3
|
+
Create an embeddable server with `createRestServer({ agents })` from
|
|
4
|
+
`@amalgm/agents/http`. It serves the one `Agents` instance it is given; the
|
|
5
|
+
host chooses where it listens.
|
|
5
6
|
|
|
6
7
|
When configured, authentication uses `Authorization: Bearer <token>` or the
|
|
7
8
|
`x-amalgm-runtime-token` header. `/healthz` is unauthenticated. JSON bodies
|
|
@@ -9,13 +10,12 @@ default to a 512 KB limit.
|
|
|
9
10
|
|
|
10
11
|
| Method | Path | Result |
|
|
11
12
|
|---|---|---|
|
|
12
|
-
| `GET` | `/v1/agents` | List
|
|
13
|
+
| `GET` | `/v1/agents` | List the agents |
|
|
13
14
|
| `POST` | `/v1/agents` | Create from a complete definition |
|
|
14
15
|
| `GET` | `/v1/agents/:id` | Read the current definition |
|
|
15
16
|
| `PATCH` | `/v1/agents/:id` | Apply a definition patch |
|
|
16
17
|
| `PUT` | `/v1/agents/:id/pinned` | Set `{ "pinned": boolean }`; no revision |
|
|
17
|
-
| `DELETE` | `/v1/agents/:id` |
|
|
18
|
+
| `DELETE` | `/v1/agents/:id` | Delete the agent and its folder; `409` for built-ins |
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
documented by their SDK modules. It exposes no conversation routes.
|
|
20
|
+
The same server also exposes agent configuration, installed skills, and bundle
|
|
21
|
+
routes documented by their SDK modules. It exposes no conversation routes.
|
package/docs/SDK.md
CHANGED
|
@@ -1,25 +1,29 @@
|
|
|
1
1
|
# SDK reference
|
|
2
2
|
|
|
3
|
-
`Agents` is the public behavior boundary for the
|
|
4
|
-
|
|
3
|
+
`Agents` is the public behavior boundary for the user's agents. Every mutation
|
|
4
|
+
is on disk before it returns. The host hands it every folder it uses; it has
|
|
5
|
+
no defaults.
|
|
5
6
|
|
|
6
7
|
```ts
|
|
7
|
-
const agents = new Agents({
|
|
8
|
+
const agents = new Agents({
|
|
9
|
+
root, // the user's agents folder; each agent is one folder inside it
|
|
10
|
+
parked, // where a deleted agent's .private/ is moved
|
|
11
|
+
osHome, // the OS account home, read only: harness skills and native config
|
|
12
|
+
isBusy, // (agentId) => boolean; a running agent's folder is not renamed
|
|
13
|
+
});
|
|
8
14
|
```
|
|
9
15
|
|
|
10
|
-
`databasePath` overrides the database location directly. Call `close()` when
|
|
11
|
-
the embedding process releases the registry.
|
|
12
|
-
|
|
13
16
|
| Method | Behavior |
|
|
14
17
|
|---|---|
|
|
15
|
-
| `createAgent(definition, { pinned? })` | Create an
|
|
16
|
-
| `updateAgent(id, patch)` | Apply a patch
|
|
18
|
+
| `createAgent(definition, { pinned? })` | Create an agent folder; a new UUID when `definition.id` is absent; pinned unless `pinned: false` |
|
|
19
|
+
| `updateAgent(id, patch)` | Apply a patch; the folder follows a new name once the agent is idle |
|
|
17
20
|
| `setAgentPinned(id, pinned)` | Show or hide the agent in every picker; never a revision |
|
|
18
21
|
| `installBuiltinAgent(definition)` | Host-only: install a platform agent pinned, or advance its stock definition while unedited |
|
|
19
|
-
| `deleteAgent(id)` |
|
|
20
|
-
| `getAgent(id
|
|
21
|
-
| `listAgents(
|
|
22
|
-
| `getAgentRevision(agentId, revisionId?)` | Resolve the current or exact
|
|
22
|
+
| `deleteAgent(id)` | Park `.private/` and remove the folder; built-ins raise `conflict` |
|
|
23
|
+
| `getAgent(id)` | Read the current record, or `null` |
|
|
24
|
+
| `listAgents()` | List every agent |
|
|
25
|
+
| `getAgentRevision(agentId, revisionId?)` | Resolve the current or one exact revision |
|
|
26
|
+
| `harnessHome(agentId, harness, authKey)` | Make and return `<agent folder>/.private/<harness>-<authKey>` |
|
|
23
27
|
|
|
24
28
|
Expected failures use `AgentError` with stable codes: `invalid_input`,
|
|
25
|
-
`not_found`, `conflict`,
|
|
29
|
+
`not_found`, `conflict`, and `too_large`.
|
package/docs/SECURITY.md
CHANGED
|
@@ -4,6 +4,7 @@ Agent definitions contain `authRef`, never credentials. Toolbox ids, skill ids,
|
|
|
4
4
|
file references, and subagent ids are requests, not authority; Shell resolves
|
|
5
5
|
and authorizes them while preparing a Chat execution.
|
|
6
6
|
|
|
7
|
-
The
|
|
8
|
-
binding it to a shared interface.
|
|
9
|
-
state
|
|
7
|
+
The host chooses where the REST server listens. Configure a bearer token before
|
|
8
|
+
binding it to a shared interface. An agent's `.private/` folder holds
|
|
9
|
+
computer-only state such as harness homes; it is never synced, and deleting
|
|
10
|
+
the agent parks it rather than removing it.
|
|
@@ -1,8 +1,28 @@
|
|
|
1
1
|
# Shell integration
|
|
2
2
|
|
|
3
|
-
Shell is the composition root. Agents supplies the
|
|
3
|
+
Shell is the composition root. Agents supplies the user's agents and Chat
|
|
4
4
|
supplies the canonical conversation runtime.
|
|
5
5
|
|
|
6
|
+
## Composition
|
|
7
|
+
|
|
8
|
+
Shell builds one `Agents` from the user's layout and passes that instance to
|
|
9
|
+
every adapter:
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
const agents = new Agents({
|
|
13
|
+
root: user.agents,
|
|
14
|
+
parked: user.computer.parked,
|
|
15
|
+
osHome,
|
|
16
|
+
isBusy: (agentId) => chatIsRunning(agentId),
|
|
17
|
+
});
|
|
18
|
+
createRestServer({ agents, bundlePort });
|
|
19
|
+
createMcpServer({ agents }); // mounted at /mcp/agents; `amalgm agents …` calls it
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`isBusy` must answer before Chat exists, because `Agents` settles folder names
|
|
23
|
+
when it starts. Chat gets `agents.harnessHome(agentId, harness, authKey)` as
|
|
24
|
+
its harness-home function; the home lives in the agent's `.private/` folder.
|
|
25
|
+
|
|
6
26
|
## Built-in agents
|
|
7
27
|
|
|
8
28
|
Shell owns the platform agent catalog and installs it on every start with
|
|
@@ -21,7 +41,7 @@ either product's store.
|
|
|
21
41
|
Chat owns the conversation, accepted prompt, provider session, ordered durable
|
|
22
42
|
updates, transcript, usage, reconnect, and interrupt lifecycle. Agents owns the
|
|
23
43
|
identity and revision selected by that execution. Neither product imports the
|
|
24
|
-
other's
|
|
44
|
+
other's store.
|
|
25
45
|
|
|
26
46
|
Tool and action ids are resolved through `@amalgm/tools`; `authRef` is resolved
|
|
27
47
|
through the credential boundary. The resulting concrete values are frozen by
|
package/examples/basic.ts
CHANGED
|
@@ -1,17 +1,21 @@
|
|
|
1
|
+
import os from 'node:os';
|
|
1
2
|
import { Agents } from '@amalgm/agents';
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
// A host hands over its folders. Each agent becomes one folder in `root`.
|
|
5
|
+
const agents = new Agents({
|
|
6
|
+
root: './example/agents',
|
|
7
|
+
parked: './example/parked',
|
|
8
|
+
osHome: os.homedir(),
|
|
9
|
+
isBusy: () => false,
|
|
10
|
+
});
|
|
4
11
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
instructions: 'Review carefully.',
|
|
11
|
-
});
|
|
12
|
+
agents.createAgent({
|
|
13
|
+
name: 'Reviewer',
|
|
14
|
+
driver: 'codex',
|
|
15
|
+
instructions: 'Review carefully.',
|
|
16
|
+
});
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
for (const agent of agents.listAgents()) {
|
|
19
|
+
const revision = agents.getAgentRevision(agent.id);
|
|
14
20
|
console.log(revision.id, revision.definition);
|
|
15
|
-
} finally {
|
|
16
|
-
agents.close();
|
|
17
21
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@amalgm/agents",
|
|
3
|
-
"version": "0.2.3-preview.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.3-preview.39017157677",
|
|
4
|
+
"description": "The user's agents, one folder each, and the exact revisions Chat runs.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"private": false,
|
|
7
7
|
"repository": {
|
|
@@ -28,11 +28,6 @@
|
|
|
28
28
|
"default": "./dist/mcp.js"
|
|
29
29
|
}
|
|
30
30
|
},
|
|
31
|
-
"bin": {
|
|
32
|
-
"amalgm-agents": "./dist/bin/agents.js",
|
|
33
|
-
"amalgm-agents-mcp": "./dist/bin/mcp.js",
|
|
34
|
-
"amalgm-agents-rest": "./dist/bin/rest.js"
|
|
35
|
-
},
|
|
36
31
|
"files": [
|
|
37
32
|
"docs",
|
|
38
33
|
"dist",
|
|
@@ -42,7 +37,7 @@
|
|
|
42
37
|
"README.md"
|
|
43
38
|
],
|
|
44
39
|
"scripts": {
|
|
45
|
-
"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json
|
|
40
|
+
"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
|
|
46
41
|
"check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
|
|
47
42
|
"test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
|
|
48
43
|
"verify": "npm run check && npm run build && npm test",
|
|
@@ -58,10 +53,8 @@
|
|
|
58
53
|
"node": ">=24"
|
|
59
54
|
},
|
|
60
55
|
"dependencies": {
|
|
61
|
-
"@amalgm/core": "0.5.1-preview.
|
|
62
|
-
"@types/
|
|
63
|
-
"@types/node": "^20.19.43",
|
|
64
|
-
"better-sqlite3": "^12.6.2"
|
|
56
|
+
"@amalgm/core": "0.5.1-preview.39017016854",
|
|
57
|
+
"@types/node": "^20.19.43"
|
|
65
58
|
},
|
|
66
59
|
"devDependencies": {
|
|
67
60
|
"tsx": "^4.23.1",
|
|
@@ -73,13 +66,9 @@
|
|
|
73
66
|
"jobs": [
|
|
74
67
|
"verify"
|
|
75
68
|
],
|
|
76
|
-
"verify": "verify"
|
|
77
|
-
"cli": [
|
|
78
|
-
"amalgm-agents"
|
|
79
|
-
]
|
|
69
|
+
"verify": "verify"
|
|
80
70
|
},
|
|
81
71
|
"allowScripts": {
|
|
82
|
-
"better-sqlite3@12.11.1": true,
|
|
83
72
|
"esbuild@0.28.1": true,
|
|
84
73
|
"fsevents@2.3.3": false
|
|
85
74
|
},
|
|
@@ -89,11 +78,11 @@
|
|
|
89
78
|
"@amalgm/core"
|
|
90
79
|
]
|
|
91
80
|
},
|
|
92
|
-
"gitHead": "
|
|
81
|
+
"gitHead": "30d31affb0c2e1e877f503d95629fdd0fa58f563",
|
|
93
82
|
"amalgmSource": {
|
|
94
83
|
"repository": "amalgm-inc/amalgm-agents",
|
|
95
84
|
"branch": "preview",
|
|
96
|
-
"commit": "
|
|
97
|
-
"occurrence": "
|
|
85
|
+
"commit": "30d31affb0c2e1e877f503d95629fdd0fa58f563",
|
|
86
|
+
"occurrence": "39017157677"
|
|
98
87
|
}
|
|
99
88
|
}
|