@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,152 +1,179 @@
1
+ import crypto from 'node:crypto';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { entityFolderName, parkedDir } from '@amalgm/core/identity';
5
+ import { agentLayout, readAgentFolder, writeAgentFolder } from './agent-folder.js';
1
6
  import { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
2
7
  import { AgentError } from './errors.js';
3
- import { newId, requireId } from './ids.js';
4
- import { agentFromRow, revisionFromRow } from './rows.js';
5
- const AGENT_SELECT = `
6
- SELECT a.*, r.id AS revision_id, r.revision_number, r.definition_hash,
7
- r.definition_json, r.created_at AS revision_created_at
8
- FROM agents a
9
- JOIN agent_revisions r ON r.id = a.current_revision_id
10
- `;
8
+ import { requireId } from './ids.js';
9
+ import { keepRevision, readRevision } from './revisions.js';
10
+ const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
11
+ /** The agents in the folder Shell hands over: one folder per agent, read fresh on every call. */
11
12
  export class AgentStore {
12
- database;
13
- now;
14
- constructor(database, now) {
15
- this.database = database;
16
- this.now = now;
13
+ options;
14
+ constructor(options) {
15
+ this.options = options;
16
+ for (const key of ['root', 'parked', 'osHome']) {
17
+ if (typeof options?.[key] !== 'string' || !options[key]) {
18
+ throw new AgentError('invalid_input', `Agents needs options.${key}.`);
19
+ }
20
+ }
21
+ if (typeof options.isBusy !== 'function')
22
+ throw new AgentError('invalid_input', 'Agents needs options.isBusy.');
23
+ fs.mkdirSync(options.root, { recursive: true });
24
+ this.agents();
17
25
  }
18
26
  create(input, options = {}) {
19
- return this.insert(normalizeDefinition(input), options.pinned !== false, null);
20
- }
21
- apply(input) {
22
- const definition = normalizeDefinition(input);
23
- const existing = this.get(definition.id, true);
24
- if (!existing)
25
- return this.create(definition);
26
- if (existing.deletedAt)
27
- throw new AgentError('deleted', `Agent is deleted: ${definition.id}`);
28
- const hash = definitionHash(definition);
29
- const equal = this.database.prepare(`
30
- SELECT 1 FROM agent_revisions WHERE id = ? AND definition_hash = ?
31
- `).get(existing.currentRevisionId, hash);
32
- if (equal)
33
- return existing;
34
- const timestamp = this.now();
35
- const revisionId = newId('revision');
36
- const number = existing.currentRevision + 1;
37
- this.database.transaction(() => {
38
- this.insertRevision(revisionId, existing.id, number, definition, timestamp);
39
- this.database.prepare(`
40
- UPDATE agents SET current_revision_id = ?, current_revision_number = ?, updated_at = ?
41
- WHERE id = ? AND deleted_at IS NULL
42
- `).run(revisionId, number, timestamp, existing.id);
43
- })();
44
- return this.require(existing.id);
27
+ const definition = normalizeDefinition({ ...input, id: input.id || crypto.randomUUID() });
28
+ return this.insert(definition, options.pinned !== false, null);
45
29
  }
46
30
  update(id, patch) {
47
- const existing = this.require(id);
48
- return this.apply(patchDefinition(existing.definition, patch));
31
+ const agent = this.require(id);
32
+ return this.write(agent, { definition: patchDefinition(agent.definition, patch) });
49
33
  }
50
34
  /** Pinning is identity state, so it never mints a revision. */
51
35
  setPinned(id, pinned) {
52
36
  if (typeof pinned !== 'boolean')
53
37
  throw new AgentError('invalid_input', 'pinned must be a boolean.');
54
- const existing = this.require(id);
55
- this.database.prepare('UPDATE agents SET pinned = ? WHERE id = ?').run(pinned ? 1 : 0, existing.id);
56
- return this.require(existing.id);
38
+ return this.write(this.require(id), { pinned });
57
39
  }
58
40
  /**
59
41
  * Install or advance one platform agent. The stock definition replaces the
60
- * current one only while the current revision is still the one this
42
+ * current one only while the current one is still the stock definition this
61
43
  * installer last wrote, so a user's edit always survives.
62
44
  */
63
45
  installBuiltin(input) {
64
46
  const definition = normalizeDefinition(input);
65
47
  const stock = definitionHash(definition);
66
- const row = this.database.prepare(`${AGENT_SELECT} WHERE a.id = ?`).get(definition.id);
67
- if (!row)
48
+ const agent = this.find(definition.id);
49
+ if (!agent)
68
50
  return this.insert(definition, true, stock);
69
- this.database.transaction(() => {
70
- if (row.deleted_at) {
71
- // Built-ins were deletable before they could be unpinned; keep the
72
- // user's intent to hide one without leaving the platform set broken.
73
- this.database.prepare('UPDATE agents SET deleted_at = NULL, pinned = 0, updated_at = ? WHERE id = ?')
74
- .run(this.now(), definition.id);
75
- }
76
- const untouched = row.builtin_hash !== null && row.definition_hash === row.builtin_hash;
77
- if (untouched)
78
- this.apply(definition);
79
- const installed = untouched || row.definition_hash === stock ? stock : row.builtin_hash;
80
- this.database.prepare('UPDATE agents SET builtin = 1, builtin_hash = ? WHERE id = ?')
81
- .run(installed, definition.id);
82
- })();
83
- return this.require(definition.id);
51
+ const current = definitionHash(agent.definition);
52
+ const untouched = agent.builtinHash !== null && current === agent.builtinHash;
53
+ return this.write(agent, {
54
+ ...(untouched ? { definition } : {}),
55
+ builtin: true,
56
+ builtinHash: untouched || current === stock ? stock : agent.builtinHash,
57
+ });
84
58
  }
59
+ /** Moves the agent's `.private/` to the parked folder, then removes its folder. */
85
60
  delete(id) {
86
- const existing = this.require(id, true);
87
- if (existing.deletedAt)
88
- return existing;
89
- if (existing.builtin) {
90
- throw new AgentError('conflict', `Built-in agents cannot be deleted; unpin it instead: ${existing.id}`);
61
+ const agent = this.require(id);
62
+ if (agent.builtin) {
63
+ throw new AgentError('conflict', `Built-in agents cannot be deleted; unpin it instead: ${agent.definition.id}`);
91
64
  }
92
- const timestamp = this.now();
93
- this.database.prepare(`UPDATE agents SET deleted_at = ?, updated_at = ? WHERE id = ?`)
94
- .run(timestamp, timestamp, existing.id);
95
- return this.require(existing.id, true);
96
- }
97
- get(id, includeDeleted = false) {
98
- const clean = requireId(id, 'agent id');
99
- const deleted = includeDeleted ? '' : ' AND a.deleted_at IS NULL';
100
- const row = this.database.prepare(`${AGENT_SELECT} WHERE a.id = ?${deleted}`).get(clean);
101
- return row ? agentFromRow(row) : null;
102
- }
103
- require(id, includeDeleted = false) {
104
- const agent = this.get(id, includeDeleted);
65
+ const layout = agentLayout(this.options.root, agent.folder);
66
+ const record = this.record(agent);
67
+ if (fs.existsSync(layout.private)) {
68
+ let parked = parkedDir(this.options.parked, 'agent', agent.definition.id);
69
+ for (let n = 2; fs.existsSync(parked); n += 1)
70
+ parked = parkedDir(this.options.parked, 'agent', `${agent.definition.id}-${n}`);
71
+ fs.mkdirSync(path.dirname(parked), { recursive: true });
72
+ fs.renameSync(layout.private, parked);
73
+ }
74
+ fs.rmSync(layout.dir, { recursive: true, force: true });
75
+ return record;
76
+ }
77
+ get(id) {
78
+ const agent = this.find(requireId(id, 'agent id'));
79
+ return agent ? this.record(agent) : null;
80
+ }
81
+ list() {
82
+ return this.agents()
83
+ .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)
84
+ || left.definition.id.localeCompare(right.definition.id))
85
+ .map((agent) => this.record(agent));
86
+ }
87
+ revision(agentId, revisionId) {
88
+ const agent = this.require(agentId);
89
+ const privateDir = agentLayout(this.options.root, agent.folder).private;
90
+ return readRevision(privateDir, revisionId || keepRevision(privateDir, agent.definition));
91
+ }
92
+ /** `<agent folder>/.private/<harness>-<authKey>`, made on first use. */
93
+ harnessHome(agentId, harness, authKey) {
94
+ const agent = this.require(agentId);
95
+ for (const [value, field] of [[harness, 'harness'], [authKey, 'authKey']]) {
96
+ if (!SEGMENT.test(String(value))) {
97
+ throw new AgentError('invalid_input', `${field} must be letters, numbers, dots, underscores, or hyphens.`);
98
+ }
99
+ }
100
+ const home = path.join(agentLayout(this.options.root, agent.folder).private, `${harness}-${authKey}`);
101
+ fs.mkdirSync(home, { recursive: true });
102
+ return home;
103
+ }
104
+ find(id) {
105
+ return this.agents().find((agent) => agent.definition.id === id);
106
+ }
107
+ require(id) {
108
+ const agent = this.find(requireId(id, 'agent id'));
105
109
  if (!agent)
106
110
  throw new AgentError('not_found', `Agent not found: ${id}`);
107
111
  return agent;
108
112
  }
109
- list(includeDeleted = false) {
110
- const where = includeDeleted ? '' : ' WHERE a.deleted_at IS NULL';
111
- return this.database.prepare(`${AGENT_SELECT}${where} ORDER BY a.updated_at DESC, a.id`).all()
112
- .map(agentFromRow);
113
+ /** Every readable agent folder; a copied folder whose id is already taken is skipped. */
114
+ agents() {
115
+ const seen = new Set();
116
+ const agents = this.entries().flatMap((folder) => {
117
+ const agent = readAgentFolder(this.options.root, folder);
118
+ if (!agent || seen.has(agent.definition.id))
119
+ return [];
120
+ seen.add(agent.definition.id);
121
+ return [agent];
122
+ });
123
+ return this.settle(agents);
113
124
  }
114
- revision(agentId, revisionId) {
115
- const agent = this.require(agentId, true);
116
- const id = revisionId || agent.currentRevisionId;
117
- const row = this.database.prepare(`
118
- SELECT * FROM agent_revisions WHERE id = ? AND agent_id = ?
119
- `).get(id, agent.id);
120
- if (!row)
121
- throw new AgentError('not_found', `Agent revision not found: ${id}`);
122
- return revisionFromRow(row);
123
- }
124
- rawAgent(id) {
125
- return this.database.prepare('SELECT 1 FROM agents WHERE id = ?').get(id);
125
+ entries() {
126
+ return fs.readdirSync(this.options.root, { withFileTypes: true })
127
+ .filter((entry) => entry.isDirectory())
128
+ .map((entry) => entry.name)
129
+ .sort();
130
+ }
131
+ /**
132
+ * Moves each idle agent to the folder its name asks for. A running agent
133
+ * keeps its folder until a later call finds it idle.
134
+ */
135
+ settle(agents) {
136
+ const names = fs.readdirSync(this.options.root);
137
+ for (const agent of agents) {
138
+ const others = names.filter((name) => name !== agent.folder);
139
+ const wanted = entityFolderName(agent.definition.name, others);
140
+ if (wanted === agent.folder || this.options.isBusy(agent.definition.id))
141
+ continue;
142
+ fs.renameSync(path.join(this.options.root, agent.folder), path.join(this.options.root, wanted));
143
+ names.splice(names.indexOf(agent.folder), 1, wanted);
144
+ agent.folder = wanted;
145
+ }
146
+ return agents;
126
147
  }
127
148
  insert(definition, pinned, builtinHash) {
128
- if (this.rawAgent(definition.id)) {
149
+ if (this.find(definition.id))
129
150
  throw new AgentError('conflict', `Agent id already exists: ${definition.id}`);
151
+ const timestamp = new Date().toISOString();
152
+ const folder = entityFolderName(definition.name, fs.readdirSync(this.options.root));
153
+ writeAgentFolder(agentLayout(this.options.root, folder), {
154
+ definition, pinned, builtin: builtinHash !== null, builtinHash, createdAt: timestamp, updatedAt: timestamp,
155
+ });
156
+ return this.record(this.require(definition.id));
157
+ }
158
+ write(agent, changes) {
159
+ const next = { ...agent, ...changes };
160
+ if (definitionHash(next.definition) !== definitionHash(agent.definition)) {
161
+ next.updatedAt = new Date().toISOString();
130
162
  }
131
- const timestamp = this.now();
132
- const revisionId = newId('revision');
133
- this.database.transaction(() => {
134
- this.database.prepare(`
135
- INSERT INTO agents (id, created_at, updated_at, pinned, builtin, builtin_hash)
136
- VALUES (?, ?, ?, ?, ?, ?)
137
- `).run(definition.id, timestamp, timestamp, pinned ? 1 : 0, builtinHash ? 1 : 0, builtinHash);
138
- this.insertRevision(revisionId, definition.id, 1, definition, timestamp);
139
- this.database.prepare(`
140
- UPDATE agents SET current_revision_id = ?, current_revision_number = 1 WHERE id = ?
141
- `).run(revisionId, definition.id);
142
- })();
143
- return this.require(definition.id);
144
- }
145
- insertRevision(id, agentId, number, definition, timestamp) {
146
- this.database.prepare(`
147
- INSERT INTO agent_revisions
148
- (id, agent_id, revision_number, definition_hash, definition_json, created_at)
149
- VALUES (?, ?, ?, ?, ?, ?)
150
- `).run(id, agentId, number, definitionHash(definition), JSON.stringify(definition), timestamp);
163
+ writeAgentFolder(agentLayout(this.options.root, agent.folder), next, agent.definition);
164
+ return this.record(this.require(agent.definition.id));
165
+ }
166
+ /** The agent as callers see it. Its current revision is kept so its id stays resolvable. */
167
+ record(agent) {
168
+ const privateDir = agentLayout(this.options.root, agent.folder).private;
169
+ return {
170
+ id: agent.definition.id,
171
+ currentRevisionId: keepRevision(privateDir, agent.definition),
172
+ definition: agent.definition,
173
+ pinned: agent.pinned,
174
+ builtin: agent.builtin,
175
+ createdAt: agent.createdAt,
176
+ updatedAt: agent.updatedAt,
177
+ };
151
178
  }
152
179
  }
package/dist/agents.d.ts CHANGED
@@ -1,20 +1,20 @@
1
- import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, CreateAgentOptions, JsonObject } from './types.js';
1
+ import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, CreateAgentOptions } from './types.js';
2
2
  export declare class Agents {
3
- readonly databasePath: string;
4
- private readonly opened;
3
+ /** The OS account home, read only: harness skills and native config are read from it. */
4
+ readonly osHome: string;
5
5
  private readonly agentStore;
6
- private closed;
7
- constructor(options?: AgentsOptions);
6
+ constructor(options: AgentsOptions);
7
+ /** Creates an agent folder. Without an id the agent gets a new UUID. */
8
8
  createAgent(input: AgentDefinitionInput, options?: CreateAgentOptions): AgentRecord;
9
9
  updateAgent(id: string, patch: AgentPatch): AgentRecord;
10
10
  setAgentPinned(id: string, pinned: boolean): AgentRecord;
11
11
  /** Host-only: install or advance a platform agent without overwriting user edits. */
12
12
  installBuiltinAgent(input: AgentDefinitionInput): AgentRecord;
13
13
  deleteAgent(id: string): AgentRecord;
14
- getAgent(id: string, includeDeleted?: boolean): AgentRecord | null;
15
- listAgents(includeDeleted?: boolean): AgentRecord[];
16
- /** Resolve one exact immutable revision for a host such as Chat. */
14
+ getAgent(id: string): AgentRecord | null;
15
+ listAgents(): AgentRecord[];
16
+ /** Resolve one exact revision for a host such as Chat; the current one when no id is given. */
17
17
  getAgentRevision(agentId: string, revisionId?: string): AgentRevision;
18
- health(): JsonObject;
19
- close(): void;
18
+ /** The folder a harness CLI keeps its home in for this agent and auth: `.private/<harness>-<authKey>`. */
19
+ harnessHome(agentId: string, harness: string, authKey: string): string;
20
20
  }
package/dist/agents.js CHANGED
@@ -1,17 +1,13 @@
1
- import path from 'node:path';
2
1
  import { AgentStore } from './agent-store.js';
3
- import { openDatabase } from './database.js';
4
2
  export class Agents {
5
- databasePath;
6
- opened;
3
+ /** The OS account home, read only: harness skills and native config are read from it. */
4
+ osHome;
7
5
  agentStore;
8
- closed = false;
9
- constructor(options = {}) {
10
- this.opened = openDatabase(options);
11
- this.databasePath = this.opened.databasePath;
12
- const now = options.now || (() => new Date().toISOString());
13
- this.agentStore = new AgentStore(this.opened.database, now);
6
+ constructor(options) {
7
+ this.agentStore = new AgentStore(options);
8
+ this.osHome = options.osHome;
14
9
  }
10
+ /** Creates an agent folder. Without an id the agent gets a new UUID. */
15
11
  createAgent(input, options = {}) {
16
12
  return this.agentStore.create(input, options);
17
13
  }
@@ -28,26 +24,18 @@ export class Agents {
28
24
  deleteAgent(id) {
29
25
  return this.agentStore.delete(id);
30
26
  }
31
- getAgent(id, includeDeleted = false) {
32
- return this.agentStore.get(id, includeDeleted);
27
+ getAgent(id) {
28
+ return this.agentStore.get(id);
33
29
  }
34
- listAgents(includeDeleted = false) {
35
- return this.agentStore.list(includeDeleted);
30
+ listAgents() {
31
+ return this.agentStore.list();
36
32
  }
37
- /** Resolve one exact immutable revision for a host such as Chat. */
33
+ /** Resolve one exact revision for a host such as Chat; the current one when no id is given. */
38
34
  getAgentRevision(agentId, revisionId) {
39
35
  return this.agentStore.revision(agentId, revisionId);
40
36
  }
41
- health() {
42
- return {
43
- ok: !this.closed,
44
- database: path.basename(this.databasePath),
45
- };
46
- }
47
- close() {
48
- if (this.closed)
49
- return;
50
- this.closed = true;
51
- this.opened.close();
37
+ /** The folder a harness CLI keeps its home in for this agent and auth: `.private/<harness>-<authKey>`. */
38
+ harnessHome(agentId, harness, authKey) {
39
+ return this.agentStore.harnessHome(agentId, harness, authKey);
52
40
  }
53
41
  }
@@ -7,6 +7,7 @@ export interface CreateBundleOptions {
7
7
  bundleId?: string;
8
8
  now?: () => string;
9
9
  }
10
+ /** Exports the agents and everything they use; the port exports resources other products own. */
10
11
  export declare function createAgentBundle(agents: Agents, input: BundleCreateInput, options?: CreateBundleOptions): Promise<{
11
12
  bundle: AgentBundle;
12
13
  preview: Record<string, unknown>;
@@ -60,7 +60,7 @@ function title(entries, external) {
60
60
  }
61
61
  return { title: 'Shared bundle', description: '' };
62
62
  }
63
- // Engine reference: amalgm-mcp/agent-bundles/export.js createBundle.
63
+ /** Exports the agents and everything they use; the port exports resources other products own. */
64
64
  export async function createAgentBundle(agents, input, options = {}) {
65
65
  const agentIds = uniqueStrings(input.agentIds);
66
66
  const automationIds = uniqueStrings(input.automationIds);
@@ -1,4 +1,5 @@
1
1
  import type { AgentBundle, BundleGraphEdge, BundleGraphElement } from './types.js';
2
+ /** The bundle's flat graph: its heads, every element, and the edges between them. */
2
3
  export declare function buildBundleGraph(bundle: AgentBundle): {
3
4
  headIds: string[];
4
5
  elements: BundleGraphElement[];
@@ -16,7 +16,7 @@ function graphRecords(bundle) {
16
16
  skill: new Map(bundle.skills.map((entry) => [skillElementId(entry), entry])),
17
17
  };
18
18
  }
19
- // Engine reference: amalgm-mcp/agent-bundles/graph.js buildFlatAgentBundleGraph.
19
+ /** The bundle's flat graph: its heads, every element, and the edges between them. */
20
20
  export function buildBundleGraph(bundle) {
21
21
  const records = graphRecords(bundle);
22
22
  const elements = new Map();
@@ -1,5 +1,6 @@
1
1
  import type { Agents } from '../agents.js';
2
2
  import type { AgentBundlePort, BundleInstallResult } from './types.js';
3
+ /** Installs a bundle's agents as new agents, each with a new id, and its other resources through the port. */
3
4
  export declare function installAgentBundle(agents: Agents, input: unknown, options?: {
4
5
  port?: AgentBundlePort;
5
6
  authRef?: string;
@@ -16,7 +16,7 @@ function uniqueName(agents, value) {
16
16
  }
17
17
  return `${base} (${crypto.randomUUID().slice(0, 8)})`;
18
18
  }
19
- // Engine reference: amalgm-mcp/agent-bundles/install.js installBundleAgents.
19
+ /** Installs a bundle's agents as new agents, each with a new id, and its other resources through the port. */
20
20
  export async function installAgentBundle(agents, input, options = {}) {
21
21
  const bundle = validateAgentBundle(input);
22
22
  const hasExternal = bundle.automations.length || bundle.apps.length || bundle.tools.length;
@@ -30,7 +30,6 @@ export async function installAgentBundle(agents, input, options = {}) {
30
30
  const headIds = new Set(bundle.heads.filter((head) => head.type === 'agent').map((head) => head.id));
31
31
  for (const entry of bundle.agents) {
32
32
  const agent = agents.createAgent({
33
- id: `imported-${crypto.randomUUID()}`,
34
33
  name: uniqueName(agents, entry.agent.name),
35
34
  description: entry.agent.description,
36
35
  driver: { id: entry.agent.driverId, config: {} },
@@ -1,2 +1,3 @@
1
1
  import type { AgentBundle } from './types.js';
2
+ /** Accepts a bundle only when its flat graph matches its records and every element is reachable from a head. */
2
3
  export declare function validateAgentBundle(input: unknown): AgentBundle;
@@ -47,7 +47,7 @@ function assertClosed(bundle) {
47
47
  if (unreachable.length)
48
48
  throw new Error(`bundle graph contains unreachable elements: ${unreachable.join(', ')}`);
49
49
  }
50
- // Engine reference: amalgm-mcp/agent-bundles/install.js validateBundle.
50
+ /** Accepts a bundle only when its flat graph matches its records and every element is reachable from a head. */
51
51
  export function validateAgentBundle(input) {
52
52
  const raw = object(input);
53
53
  if (!raw)
@@ -1,8 +1,8 @@
1
1
  import type { Agents } from '../agents.js';
2
2
  import type { AgentRecord } from '../types.js';
3
3
  import type { AgentConfig } from './types.js';
4
+ /** Imports the parent agent's harness config from the OS home, creating an agent per native subagent. */
4
5
  export declare function importAgentConfig(agents: Agents, agentId: string, options?: {
5
- homeDir?: string;
6
6
  replace?: boolean;
7
7
  }): {
8
8
  config: AgentConfig;
@@ -42,12 +42,12 @@ function mergedConfig(existing, imported, subagents, replace) {
42
42
  subagents: mergeSubagents(existing.subagents, subagents),
43
43
  }, existing);
44
44
  }
45
- // Engine reference: amalgm-mcp/agent-config/rest.js handleImportNative.
45
+ /** Imports the parent agent's harness config from the OS home, creating an agent per native subagent. */
46
46
  export function importAgentConfig(agents, agentId, options = {}) {
47
47
  const parent = agents.getAgent(agentId);
48
48
  if (!parent)
49
49
  throw new AgentError('not_found', `Agent not found: ${agentId}`);
50
- const imported = importNativeConfig(parent.definition.driver.id, options.homeDir);
50
+ const imported = importNativeConfig(parent.definition.driver.id, agents.osHome);
51
51
  const importedAgents = imported.agents.map((native) => ensureImportedAgent(agents, parent, native));
52
52
  const references = importedAgents.map(({ agent }, index) => ({
53
53
  id: stableConfigId('subagent', agent.id), agentId: agent.id,
@@ -1,2 +1,6 @@
1
1
  import type { NativeConfigImport } from './types.js';
2
- export declare function importNativeConfig(driverId: string, homeDir?: string): NativeConfigImport;
2
+ /**
3
+ * Reads a harness CLI's own config from the OS home: instructions, skills,
4
+ * command hooks, and agent markdown. Nothing else crosses this boundary.
5
+ */
6
+ export declare function importNativeConfig(driverId: string, osHome: string): NativeConfigImport;
@@ -1,5 +1,4 @@
1
1
  import fs from 'node:fs';
2
- import os from 'node:os';
3
2
  import path from 'node:path';
4
3
  import { parseSkillFrontmatter } from '../skills/scanner.js';
5
4
  import { stableConfigId } from './schema.js';
@@ -125,11 +124,13 @@ function hooksFrom(files, provider) {
125
124
  }
126
125
  return hooks;
127
126
  }
128
- // Engine references: agent-config/importers/* and agents/hooks.js. Only
129
- // instructions, skills, command hooks, and agent markdown cross this boundary.
130
- export function importNativeConfig(driverId, homeDir = os.homedir()) {
127
+ /**
128
+ * Reads a harness CLI's own config from the OS home: instructions, skills,
129
+ * command hooks, and agent markdown. Nothing else crosses this boundary.
130
+ */
131
+ export function importNativeConfig(driverId, osHome) {
131
132
  if (driverId === 'codex') {
132
- const root = path.join(homeDir, '.codex');
133
+ const root = path.join(osHome, '.codex');
133
134
  const instructions = readText(path.join(root, 'AGENTS.md'));
134
135
  const hooksFile = path.join(root, 'hooks.json');
135
136
  const skills = skillsFrom(path.join(root, 'skills'), driverId);
@@ -141,13 +142,13 @@ export function importNativeConfig(driverId, homeDir = os.homedir()) {
141
142
  };
142
143
  }
143
144
  if (driverId === 'claude_code') {
144
- const root = path.join(homeDir, '.claude');
145
+ const root = path.join(osHome, '.claude');
145
146
  const settings = ['settings.json', 'settings.local.json'].map((name) => path.join(root, name));
146
- const instructions = readText(path.join(root, 'CLAUDE.md')) || readText(path.join(homeDir, 'CLAUDE.md'));
147
- const configRoot = path.join(homeDir, '.config', 'claude');
147
+ const instructions = readText(path.join(root, 'CLAUDE.md')) || readText(path.join(osHome, 'CLAUDE.md'));
148
+ const configRoot = path.join(osHome, '.config', 'claude');
148
149
  const skills = [...skillsFrom(path.join(root, 'skills'), driverId),
149
150
  ...skillsFrom(path.join(configRoot, 'skills'), driverId)];
150
- const hooks = hooksFrom([...settings, path.join(homeDir, '.claude.json')], driverId);
151
+ const hooks = hooksFrom([...settings, path.join(osHome, '.claude.json')], driverId);
151
152
  const agents = [...agentsFrom(path.join(root, 'agents'), driverId),
152
153
  ...agentsFrom(path.join(configRoot, 'agents'), driverId)];
153
154
  return {
@@ -158,8 +159,8 @@ export function importNativeConfig(driverId, homeDir = os.homedir()) {
158
159
  };
159
160
  }
160
161
  if (driverId === 'opencode') {
161
- const config = path.join(homeDir, '.config', 'opencode');
162
- const dot = path.join(homeDir, '.opencode');
162
+ const config = path.join(osHome, '.config', 'opencode');
163
+ const dot = path.join(osHome, '.opencode');
163
164
  const data = readJson(path.join(config, 'opencode.json')) || readJson(path.join(config, 'config.json'))
164
165
  || readJson(path.join(dot, 'opencode.json')) || {};
165
166
  const instructions = ['instructions', 'systemPrompt', 'prompt']
@@ -1,3 +1,4 @@
1
1
  import type { AgentConfig, AgentConfigInput } from './types.js';
2
2
  export declare function stableConfigId(prefix: string, seed: string): string;
3
+ /** The complete config view of an agent; `fallback` fills what `input` leaves out. */
3
4
  export declare function normalizeAgentConfig(input?: AgentConfigInput, fallback?: AgentConfigInput): AgentConfig;
@@ -117,7 +117,7 @@ function loadout(value, fallback) {
117
117
  const exposure = normalizeToolExposure(raw.exposure ?? prior.exposure);
118
118
  return { toolIds: uniqueStrings(explicit ? aliases(raw) : aliases(prior)), ...(exposure ? { exposure } : {}) };
119
119
  }
120
- // Engine reference: amalgm-mcp/agent-config/schema.js.
120
+ /** The complete config view of an agent; `fallback` fills what `input` leaves out. */
121
121
  export function normalizeAgentConfig(input = {}, fallback = {}) {
122
122
  const raw = isObject(input) ? input : {};
123
123
  const prior = isObject(fallback) ? fallback : {};
@@ -10,7 +10,7 @@ function same(left, right) {
10
10
  return left.length === right.length && left.every((value, index) => value === right[index]);
11
11
  }
12
12
  /**
13
- * An agent's subagents are other agents in the registry, listed by id in
13
+ * An agent's subagents are other agents in the same folder, listed by id in
14
14
  * `resources.subagents` and nowhere else. Names and descriptions are read from
15
15
  * those agents, so a rename shows everywhere; an id whose agent was deleted
16
16
  * drops out.
@@ -25,8 +25,9 @@ function subagentsOf(agent, agents) {
25
25
  }] : [];
26
26
  });
27
27
  }
28
- // Engine reference: amalgm-mcp/agent-config/store.js. The immutable Agent
29
- // revision is the store here; no second agent_configs database is introduced.
28
+ // The config view lives in the agent's folder: metadata.agentConfig in
29
+ // .amalgm-agent.json, the instructions in instructions.md, and each skill's
30
+ // text in skills/<skill>/SKILL.md.
30
31
  export function configFromAgent(agent, agents) {
31
32
  const stored = normalizeAgentConfig(configDocument(agent), {
32
33
  agentId: agent.id,
@@ -38,8 +39,7 @@ export function configFromAgent(agent, agents) {
38
39
  return normalizeAgentConfig({
39
40
  ...stored,
40
41
  agentId: agent.id,
41
- instructions: stored.instructions.trim() === agent.definition.instructions
42
- ? stored.instructions : agent.definition.instructions,
42
+ instructions: agent.definition.instructions,
43
43
  skills: same(skillRefs, agent.definition.resources.skills)
44
44
  ? stored.skills : agent.definition.resources.skills,
45
45
  loadout: { toolIds: [...agent.definition.toolbox.toolIds, ...agent.definition.toolbox.actionIds], exposure: agent.definition.toolbox.exposure },
@@ -54,10 +54,10 @@ export function updateAgentConfig(agents, agentId, patch) {
54
54
  if (!current)
55
55
  throw new AgentError('not_found', `Agent not found: ${agentId}`);
56
56
  const existing = configFromAgent(current, agents);
57
- const { subagents, ...document } = normalizeAgentConfig({ ...existing, ...patch, agentId }, existing);
57
+ const { subagents, instructions, ...document } = normalizeAgentConfig({ ...existing, ...patch, agentId }, existing);
58
58
  const metadata = { ...current.definition.metadata, [METADATA_KEY]: document };
59
59
  const projected = {
60
- instructions: document.instructions,
60
+ instructions,
61
61
  resources: {
62
62
  skills: document.skills.filter((item) => item.enabled).map((item) => item.name || item.id),
63
63
  subagents: subagents
package/dist/errors.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { JsonObject } from './types.js';
2
- export type AgentErrorCode = 'invalid_input' | 'not_found' | 'conflict' | 'deleted' | 'too_large' | 'internal';
2
+ export type AgentErrorCode = 'invalid_input' | 'not_found' | 'conflict' | 'too_large' | 'internal';
3
3
  export declare class AgentError extends Error {
4
4
  readonly code: AgentErrorCode;
5
5
  readonly details: JsonObject;
package/dist/errors.js CHANGED
@@ -2,7 +2,6 @@ const statusByCode = {
2
2
  invalid_input: 400,
3
3
  not_found: 404,
4
4
  conflict: 409,
5
- deleted: 410,
6
5
  too_large: 413,
7
6
  internal: 500,
8
7
  };