@amalgm/agents 0.2.3-main.35541618842 → 0.2.3-main.35795496700

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 CHANGED
@@ -70,6 +70,13 @@ locked dependency graph on the supported Node toolchain.
70
70
  10. An agent revision owns its exact tool/action selection and direct, search,
71
71
  or hidden exposure overrides. Configuration, export, import, and execution
72
72
  preserve that selection; editing it never mutates the parent Toolbox.
73
+ 11. Pinned is identity state and the one source for every agent picker.
74
+ Pinning never creates a revision. New agents are pinned; a bundle install
75
+ or native config import pins only the parent agent, never the subagents it
76
+ creates.
77
+ 12. Built-in agents are fully editable and unpinnable but never deletable. The
78
+ platform advances a built-in's stock definition only while the user has
79
+ not edited it.
73
80
 
74
81
  ## Consequences
75
82
 
package/README.md CHANGED
@@ -70,9 +70,14 @@ const { config } = updateAgentConfig(agents, 'reviewer', {
70
70
  instructions: 'Review against the measured contract.',
71
71
  skills: [{ name: 'parity', content: 'Run the parity meter.' }],
72
72
  hooks: [{ event: 'Stop', type: 'command', command: 'npm test' }],
73
+ subagents: [{ agentId: 'security-reviewer' }],
73
74
  });
74
75
  ```
75
76
 
77
+ A config's subagents are stored only as ids in `resources.subagents`;
78
+ `configFromAgent(agent, agents)` reads each one's name and description from
79
+ the agent it names.
80
+
76
81
  The REST adapter also serves `/agent-config`, `/agent-config/get`,
77
82
  `/agent-config/update`, and `/agent-config/import-native`. Native import reads
78
83
  only instructions, skills, command hooks, and agent markdown from an injected
@@ -1,17 +1,26 @@
1
1
  import type Database from 'better-sqlite3';
2
- import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision } from './types.js';
2
+ import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, CreateAgentOptions } from './types.js';
3
3
  export declare class AgentStore {
4
4
  private readonly database;
5
5
  private readonly now;
6
6
  constructor(database: Database.Database, now: () => string);
7
- create(input: AgentDefinitionInput): AgentRecord;
7
+ create(input: AgentDefinitionInput, options?: CreateAgentOptions): AgentRecord;
8
8
  apply(input: AgentDefinitionInput): AgentRecord;
9
9
  update(id: string, patch: AgentPatch): AgentRecord;
10
+ /** Pinning is identity state, so it never mints a revision. */
11
+ setPinned(id: string, pinned: boolean): AgentRecord;
12
+ /**
13
+ * Install or advance one platform agent. The stock definition replaces the
14
+ * current one only while the current revision is still the one this
15
+ * installer last wrote, so a user's edit always survives.
16
+ */
17
+ installBuiltin(input: AgentDefinitionInput): AgentRecord;
10
18
  delete(id: string): AgentRecord;
11
19
  get(id: string, includeDeleted?: boolean): AgentRecord | null;
12
20
  require(id: string, includeDeleted?: boolean): AgentRecord;
13
21
  list(includeDeleted?: boolean): AgentRecord[];
14
22
  revision(agentId: string, revisionId?: string): AgentRevision;
15
23
  private rawAgent;
24
+ private insert;
16
25
  private insertRevision;
17
26
  }
@@ -15,23 +15,8 @@ export class AgentStore {
15
15
  this.database = database;
16
16
  this.now = now;
17
17
  }
18
- create(input) {
19
- const definition = normalizeDefinition(input);
20
- if (this.rawAgent(definition.id)) {
21
- throw new AgentError('conflict', `Agent id already exists: ${definition.id}`);
22
- }
23
- const timestamp = this.now();
24
- const revisionId = newId('revision');
25
- this.database.transaction(() => {
26
- this.database.prepare(`
27
- INSERT INTO agents (id, created_at, updated_at) VALUES (?, ?, ?)
28
- `).run(definition.id, timestamp, timestamp);
29
- this.insertRevision(revisionId, definition.id, 1, definition, timestamp);
30
- this.database.prepare(`
31
- UPDATE agents SET current_revision_id = ?, current_revision_number = 1 WHERE id = ?
32
- `).run(revisionId, definition.id);
33
- })();
34
- return this.require(definition.id);
18
+ create(input, options = {}) {
19
+ return this.insert(normalizeDefinition(input), options.pinned !== false, null);
35
20
  }
36
21
  apply(input) {
37
22
  const definition = normalizeDefinition(input);
@@ -62,10 +47,48 @@ export class AgentStore {
62
47
  const existing = this.require(id);
63
48
  return this.apply(patchDefinition(existing.definition, patch));
64
49
  }
50
+ /** Pinning is identity state, so it never mints a revision. */
51
+ setPinned(id, pinned) {
52
+ if (typeof pinned !== 'boolean')
53
+ 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);
57
+ }
58
+ /**
59
+ * Install or advance one platform agent. The stock definition replaces the
60
+ * current one only while the current revision is still the one this
61
+ * installer last wrote, so a user's edit always survives.
62
+ */
63
+ installBuiltin(input) {
64
+ const definition = normalizeDefinition(input);
65
+ const stock = definitionHash(definition);
66
+ const row = this.database.prepare(`${AGENT_SELECT} WHERE a.id = ?`).get(definition.id);
67
+ if (!row)
68
+ 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);
84
+ }
65
85
  delete(id) {
66
86
  const existing = this.require(id, true);
67
87
  if (existing.deletedAt)
68
88
  return existing;
89
+ if (existing.builtin) {
90
+ throw new AgentError('conflict', `Built-in agents cannot be deleted; unpin it instead: ${existing.id}`);
91
+ }
69
92
  const timestamp = this.now();
70
93
  this.database.prepare(`UPDATE agents SET deleted_at = ?, updated_at = ? WHERE id = ?`)
71
94
  .run(timestamp, timestamp, existing.id);
@@ -85,7 +108,7 @@ export class AgentStore {
85
108
  }
86
109
  list(includeDeleted = false) {
87
110
  const where = includeDeleted ? '' : ' WHERE a.deleted_at IS NULL';
88
- return this.database.prepare(`${AGENT_SELECT}${where} ORDER BY a.updated_at DESC`).all()
111
+ return this.database.prepare(`${AGENT_SELECT}${where} ORDER BY a.updated_at DESC, a.id`).all()
89
112
  .map(agentFromRow);
90
113
  }
91
114
  revision(agentId, revisionId) {
@@ -101,6 +124,24 @@ export class AgentStore {
101
124
  rawAgent(id) {
102
125
  return this.database.prepare('SELECT 1 FROM agents WHERE id = ?').get(id);
103
126
  }
127
+ insert(definition, pinned, builtinHash) {
128
+ if (this.rawAgent(definition.id)) {
129
+ throw new AgentError('conflict', `Agent id already exists: ${definition.id}`);
130
+ }
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
+ }
104
145
  insertRevision(id, agentId, number, definition, timestamp) {
105
146
  this.database.prepare(`
106
147
  INSERT INTO agent_revisions
package/dist/agents.d.ts CHANGED
@@ -1,12 +1,15 @@
1
- import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, JsonObject } from './types.js';
1
+ import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, CreateAgentOptions, JsonObject } from './types.js';
2
2
  export declare class Agents {
3
3
  readonly databasePath: string;
4
4
  private readonly opened;
5
5
  private readonly agentStore;
6
6
  private closed;
7
7
  constructor(options?: AgentsOptions);
8
- createAgent(input: AgentDefinitionInput): AgentRecord;
8
+ createAgent(input: AgentDefinitionInput, options?: CreateAgentOptions): AgentRecord;
9
9
  updateAgent(id: string, patch: AgentPatch): AgentRecord;
10
+ setAgentPinned(id: string, pinned: boolean): AgentRecord;
11
+ /** Host-only: install or advance a platform agent without overwriting user edits. */
12
+ installBuiltinAgent(input: AgentDefinitionInput): AgentRecord;
10
13
  deleteAgent(id: string): AgentRecord;
11
14
  getAgent(id: string, includeDeleted?: boolean): AgentRecord | null;
12
15
  listAgents(includeDeleted?: boolean): AgentRecord[];
package/dist/agents.js CHANGED
@@ -12,12 +12,19 @@ export class Agents {
12
12
  const now = options.now || (() => new Date().toISOString());
13
13
  this.agentStore = new AgentStore(this.opened.database, now);
14
14
  }
15
- createAgent(input) {
16
- return this.agentStore.create(input);
15
+ createAgent(input, options = {}) {
16
+ return this.agentStore.create(input, options);
17
17
  }
18
18
  updateAgent(id, patch) {
19
19
  return this.agentStore.update(id, patch);
20
20
  }
21
+ setAgentPinned(id, pinned) {
22
+ return this.agentStore.setPinned(id, pinned);
23
+ }
24
+ /** Host-only: install or advance a platform agent without overwriting user edits. */
25
+ installBuiltinAgent(input) {
26
+ return this.agentStore.installBuiltin(input);
27
+ }
21
28
  deleteAgent(id) {
22
29
  return this.agentStore.delete(id);
23
30
  }
@@ -26,7 +26,7 @@ function collectAgents(agents, roots, installed) {
26
26
  const record = agents.getAgent(id);
27
27
  if (!record)
28
28
  throw new Error(`Agent not found: ${id}`);
29
- const config = configFromAgent(record);
29
+ const config = configFromAgent(record, agents);
30
30
  config.skills = config.skills.map((skill) => hydratedSkill(skill, installed));
31
31
  entries.push({
32
32
  sourceAgentId: record.id,
@@ -25,6 +25,9 @@ export async function installAgentBundle(agents, input, options = {}) {
25
25
  const external = options.port ? await options.port.installResources(bundle) : {};
26
26
  const idMap = new Map();
27
27
  const created = [];
28
+ // Only agent heads join the user's pinned agents; the subagents they close
29
+ // over stay reachable through them and on the Agents page.
30
+ const headIds = new Set(bundle.heads.filter((head) => head.type === 'agent').map((head) => head.id));
28
31
  for (const entry of bundle.agents) {
29
32
  const agent = agents.createAgent({
30
33
  id: `imported-${crypto.randomUUID()}`,
@@ -37,7 +40,7 @@ export async function installAgentBundle(agents, input, options = {}) {
37
40
  resources: { files: [], skills: [], subagents: [] },
38
41
  toolbox: { toolIds: entry.config.loadout.toolIds, actionIds: [], exposure: entry.config.loadout.exposure ?? {} },
39
42
  metadata: { installedFromBundle: bundle.bundleId },
40
- });
43
+ }, { pinned: headIds.has(entry.sourceAgentId) });
41
44
  idMap.set(entry.sourceAgentId, agent.id);
42
45
  created.push({ sourceId: entry.sourceAgentId, agent, config: entry.config });
43
46
  }
@@ -17,6 +17,10 @@ export function runAgentCommand(agents, args) {
17
17
  if (action === 'update' && first && second) {
18
18
  return { agent: agents.updateAgent(first, readObjectFile(second)) };
19
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) };
20
24
  if (action === 'delete' && first)
21
25
  return { agent: agents.deleteAgent(first) };
22
26
  throw new AgentError('invalid_input', 'Unknown or incomplete agent command. Run with --help.');
@@ -1 +1 @@
1
- export declare const HELP = "amalgm-agents \u2014 local agent identities and immutable revisions\n\nAgents:\n amalgm-agents agent list [--include-deleted]\n amalgm-agents agent show <id>\n amalgm-agents agent create <definition.json>\n amalgm-agents agent update <id> <patch.json>\n amalgm-agents agent delete <id>\n\nGlobal options:\n --state-dir <path> Agents state directory\n --help Show this help\n";
1
+ export declare const HELP = "amalgm-agents \u2014 local agent identities and immutable revisions\n\nAgents:\n amalgm-agents agent list [--include-deleted]\n amalgm-agents agent show <id>\n amalgm-agents agent create <definition.json>\n amalgm-agents agent update <id> <patch.json>\n amalgm-agents agent pin <id>\n amalgm-agents agent unpin <id>\n amalgm-agents agent delete <id>\n\nGlobal options:\n --state-dir <path> Agents state directory\n --help Show this help\n";
package/dist/cli/help.js CHANGED
@@ -5,6 +5,8 @@ Agents:
5
5
  amalgm-agents agent show <id>
6
6
  amalgm-agents agent create <definition.json>
7
7
  amalgm-agents agent update <id> <patch.json>
8
+ amalgm-agents agent pin <id>
9
+ amalgm-agents agent unpin <id>
8
10
  amalgm-agents agent delete <id>
9
11
 
10
12
  Global options:
@@ -27,7 +27,7 @@ function ensureImportedAgent(agents, parent, native) {
27
27
  resources: { files: [], skills: [], subagents: [] },
28
28
  toolbox: { toolIds: [], actionIds: [] }, workspace: parent.definition.workspace,
29
29
  metadata: { importedFrom: native.source },
30
- });
30
+ }, { pinned: false }); // Only the parent is pinned; a subagent is reached through it.
31
31
  updateAgentConfig(agents, agent.id, { instructions: native.instructions });
32
32
  return { agent: agents.getAgent(agent.id), created: true };
33
33
  }
@@ -54,6 +54,6 @@ export function importAgentConfig(agents, agentId, options = {}) {
54
54
  name: agent.definition.name, description: agent.definition.description, enabled: true,
55
55
  source: imported.agents[index]?.source || { kind: 'native-import' },
56
56
  }));
57
- const config = mergedConfig(configFromAgent(parent), imported.config, references, options.replace === true);
57
+ const config = mergedConfig(configFromAgent(parent, agents), imported.config, references, options.replace === true);
58
58
  return { config: updateAgentConfig(agents, agentId, config).config, importedAgents, sources: imported.sources };
59
59
  }
@@ -1,7 +1,9 @@
1
1
  import type { Agents } from '../agents.js';
2
2
  import type { AgentRecord } from '../types.js';
3
3
  import type { AgentConfig, AgentConfigInput } from './types.js';
4
- export declare function configFromAgent(agent: AgentRecord): AgentConfig;
4
+ /** Reads the agents a subagent list points at; deleted agents read as missing. */
5
+ export type AgentLookup = Pick<Agents, 'getAgent'>;
6
+ export declare function configFromAgent(agent: AgentRecord, agents: AgentLookup): AgentConfig;
5
7
  export declare function listAgentConfigs(agents: Agents): AgentConfig[];
6
8
  export declare function updateAgentConfig(agents: Agents, agentId: string, patch: AgentConfigInput): {
7
9
  agent: AgentRecord;
@@ -1,6 +1,6 @@
1
1
  import { AgentError } from '../errors.js';
2
2
  import { isObject } from '../json.js';
3
- import { normalizeAgentConfig } from './schema.js';
3
+ import { normalizeAgentConfig, stableConfigId } from './schema.js';
4
4
  const METADATA_KEY = 'agentConfig';
5
5
  function configDocument(agent) {
6
6
  const value = agent.definition.metadata[METADATA_KEY];
@@ -9,18 +9,32 @@ function configDocument(agent) {
9
9
  function same(left, right) {
10
10
  return left.length === right.length && left.every((value, index) => value === right[index]);
11
11
  }
12
+ /**
13
+ * An agent's subagents are other agents in the registry, listed by id in
14
+ * `resources.subagents` and nowhere else. Names and descriptions are read from
15
+ * those agents, so a rename shows everywhere; an id whose agent was deleted
16
+ * drops out.
17
+ */
18
+ function subagentsOf(agent, agents) {
19
+ return agent.definition.resources.subagents.flatMap((agentId) => {
20
+ const subagent = agentId === agent.id ? null : agents.getAgent(agentId);
21
+ return subagent ? [{
22
+ id: stableConfigId('subagent', agentId), agentId,
23
+ name: subagent.definition.name, description: subagent.definition.description,
24
+ enabled: true, source: { kind: 'amalgm' },
25
+ }] : [];
26
+ });
27
+ }
12
28
  // Engine reference: amalgm-mcp/agent-config/store.js. The immutable Agent
13
29
  // revision is the store here; no second agent_configs database is introduced.
14
- export function configFromAgent(agent) {
30
+ export function configFromAgent(agent, agents) {
15
31
  const stored = normalizeAgentConfig(configDocument(agent), {
16
32
  agentId: agent.id,
17
33
  instructions: agent.definition.instructions,
18
34
  skills: agent.definition.resources.skills,
19
35
  loadout: { toolIds: [...agent.definition.toolbox.toolIds, ...agent.definition.toolbox.actionIds], exposure: agent.definition.toolbox.exposure },
20
- subagents: agent.definition.resources.subagents,
21
36
  });
22
37
  const skillRefs = stored.skills.filter((item) => item.enabled).map((item) => item.name || item.id);
23
- const subagentRefs = stored.subagents.filter((item) => item.enabled).map((item) => item.agentId);
24
38
  return normalizeAgentConfig({
25
39
  ...stored,
26
40
  agentId: agent.id,
@@ -29,28 +43,30 @@ export function configFromAgent(agent) {
29
43
  skills: same(skillRefs, agent.definition.resources.skills)
30
44
  ? stored.skills : agent.definition.resources.skills,
31
45
  loadout: { toolIds: [...agent.definition.toolbox.toolIds, ...agent.definition.toolbox.actionIds], exposure: agent.definition.toolbox.exposure },
32
- subagents: same(subagentRefs, agent.definition.resources.subagents)
33
- ? stored.subagents : agent.definition.resources.subagents,
46
+ subagents: subagentsOf(agent, agents),
34
47
  }, stored);
35
48
  }
36
49
  export function listAgentConfigs(agents) {
37
- return agents.listAgents().map(configFromAgent);
50
+ return agents.listAgents().map((agent) => configFromAgent(agent, agents));
38
51
  }
39
52
  export function updateAgentConfig(agents, agentId, patch) {
40
53
  const current = agents.getAgent(agentId);
41
54
  if (!current)
42
55
  throw new AgentError('not_found', `Agent not found: ${agentId}`);
43
- const existing = configFromAgent(current);
44
- const config = normalizeAgentConfig({ ...existing, ...patch, agentId }, existing);
45
- const metadata = { ...current.definition.metadata, [METADATA_KEY]: config };
56
+ const existing = configFromAgent(current, agents);
57
+ const { subagents, ...document } = normalizeAgentConfig({ ...existing, ...patch, agentId }, existing);
58
+ const metadata = { ...current.definition.metadata, [METADATA_KEY]: document };
46
59
  const projected = {
47
- instructions: config.instructions,
60
+ instructions: document.instructions,
48
61
  resources: {
49
- skills: config.skills.filter((item) => item.enabled).map((item) => item.name || item.id),
50
- subagents: config.subagents.filter((item) => item.enabled).map((item) => item.agentId),
62
+ skills: document.skills.filter((item) => item.enabled).map((item) => item.name || item.id),
63
+ subagents: subagents
64
+ .filter((item) => item.enabled && item.agentId !== agentId && agents.getAgent(item.agentId))
65
+ .map((item) => item.agentId),
51
66
  },
52
- toolbox: { toolIds: config.loadout.toolIds, actionIds: [], exposure: config.loadout.exposure ?? {} },
67
+ toolbox: { toolIds: document.loadout.toolIds, actionIds: [], exposure: document.loadout.exposure ?? {} },
53
68
  metadata,
54
69
  };
55
- return { agent: agents.updateAgent(agentId, projected), config };
70
+ const agent = agents.updateAgent(agentId, projected);
71
+ return { agent, config: configFromAgent(agent, agents) };
56
72
  }
@@ -15,6 +15,11 @@ export async function routeAgents(context) {
15
15
  }
16
16
  if (!id)
17
17
  throw new AgentError('not_found', 'Route not found.');
18
+ if (child === 'pinned' && context.method === 'PUT') {
19
+ const body = await context.body();
20
+ context.json(200, { agent: context.agents.setAgentPinned(id, body.pinned) });
21
+ return true;
22
+ }
18
23
  if (child)
19
24
  return false;
20
25
  if (context.method === 'GET') {
@@ -26,7 +26,7 @@ export async function routeAgentConfig(context) {
26
26
  return true;
27
27
  }
28
28
  if (action === 'get') {
29
- context.json(200, { config: configFromAgent(agent) });
29
+ context.json(200, { config: configFromAgent(agent, context.agents) });
30
30
  return true;
31
31
  }
32
32
  if (action === 'update') {
@@ -39,9 +39,19 @@ export function agentTools(agents) {
39
39
  });
40
40
  },
41
41
  },
42
+ {
43
+ name: 'agents_set_pinned',
44
+ description: 'Pin or unpin an agent. Pinned agents appear wherever a user picks an agent; this creates no revision.',
45
+ inputSchema: objectSchema({ agent_id: string, pinned: { type: 'boolean' } }, ['agent_id', 'pinned']),
46
+ handler(input) {
47
+ return toolResult({
48
+ agent: agents.setAgentPinned(stringArg(input, 'agent_id'), input.pinned),
49
+ });
50
+ },
51
+ },
42
52
  {
43
53
  name: 'agents_delete',
44
- description: 'Tombstone an agent identity while retaining its immutable revisions.',
54
+ description: 'Tombstone an agent identity while retaining its immutable revisions. Built-in agents cannot be deleted; unpin them instead.',
45
55
  inputSchema: objectSchema({ agent_id: string }, ['agent_id']),
46
56
  handler(input) {
47
57
  return toolResult({ agent: agents.deleteAgent(stringArg(input, 'agent_id')) });
package/dist/rows.js CHANGED
@@ -19,6 +19,8 @@ export function agentFromRow(row) {
19
19
  currentRevisionId: String(row.current_revision_id),
20
20
  currentRevision: Number(row.current_revision_number),
21
21
  definition: revision.definition,
22
+ pinned: row.pinned === 1,
23
+ builtin: row.builtin === 1,
22
24
  createdAt: String(row.created_at),
23
25
  updatedAt: String(row.updated_at),
24
26
  deletedAt: nullable(row.deleted_at),
package/dist/schema.js CHANGED
@@ -1,4 +1,7 @@
1
- const SCHEMA_VERSION = 3;
1
+ import { definitionHash, normalizeDefinition } from './definition.js';
2
+ import { newId } from './ids.js';
3
+ import { isObject } from './json.js';
4
+ const SCHEMA_VERSION = 5;
2
5
  const REGISTRY_SCHEMA = `
3
6
  CREATE TABLE agents (
4
7
  id TEXT PRIMARY KEY,
@@ -6,7 +9,10 @@ const REGISTRY_SCHEMA = `
6
9
  current_revision_number INTEGER NOT NULL DEFAULT 0,
7
10
  created_at TEXT NOT NULL,
8
11
  updated_at TEXT NOT NULL,
9
- deleted_at TEXT
12
+ deleted_at TEXT,
13
+ pinned INTEGER NOT NULL DEFAULT 1,
14
+ builtin INTEGER NOT NULL DEFAULT 0,
15
+ builtin_hash TEXT
10
16
  );
11
17
 
12
18
  CREATE TABLE agent_revisions (
@@ -22,6 +28,67 @@ const REGISTRY_SCHEMA = `
22
28
  CREATE INDEX agent_revisions_agent_idx
23
29
  ON agent_revisions(agent_id, revision_number DESC);
24
30
  `;
31
+ function withoutSubagents(value) {
32
+ const { subagents: _subagents, ...rest } = value;
33
+ return rest;
34
+ }
35
+ function enabledSubagentIds(value) {
36
+ if (!isObject(value) || !Array.isArray(value.subagents))
37
+ return [];
38
+ return value.subagents.flatMap((item) => (isObject(item) && item.enabled !== false && typeof item.agentId === 'string' ? [item.agentId] : []));
39
+ }
40
+ /**
41
+ * `resources.subagents` becomes the only subagent list. Before version 5 the
42
+ * agent editor kept its own list in `driver.config.subagents` and the config
43
+ * view kept one in `metadata.agentConfig.subagents`. Lift the editor's
44
+ * enabled entries into `resources.subagents`, drop both copies, and record the
45
+ * result as a new revision. `updated_at` is left alone: this is not a user
46
+ * edit. An agent whose stored definition no longer normalizes is left as is.
47
+ */
48
+ function liftSubagentLists(database) {
49
+ const rows = database.prepare(`
50
+ SELECT a.id, a.current_revision_number, r.definition_hash, r.definition_json
51
+ FROM agents a JOIN agent_revisions r ON r.id = a.current_revision_id
52
+ WHERE a.deleted_at IS NULL
53
+ `).all();
54
+ const live = new Set(rows.map((row) => row.id));
55
+ const timestamp = new Date().toISOString();
56
+ for (const row of rows) {
57
+ let definition;
58
+ try {
59
+ const stored = JSON.parse(row.definition_json);
60
+ const subagents = [...new Set([
61
+ ...stored.resources.subagents,
62
+ ...enabledSubagentIds(stored.driver.config),
63
+ ])].filter((id) => id !== row.id && live.has(id));
64
+ const agentConfig = stored.metadata.agentConfig;
65
+ definition = normalizeDefinition({
66
+ ...stored,
67
+ driver: { ...stored.driver, config: withoutSubagents(stored.driver.config) },
68
+ resources: { ...stored.resources, subagents },
69
+ metadata: isObject(agentConfig)
70
+ ? { ...stored.metadata, agentConfig: withoutSubagents(agentConfig) }
71
+ : stored.metadata,
72
+ });
73
+ }
74
+ catch {
75
+ continue;
76
+ }
77
+ const hash = definitionHash(definition);
78
+ if (hash === row.definition_hash)
79
+ continue;
80
+ const revisionId = newId('revision');
81
+ const number = row.current_revision_number + 1;
82
+ database.prepare(`
83
+ INSERT INTO agent_revisions
84
+ (id, agent_id, revision_number, definition_hash, definition_json, created_at)
85
+ VALUES (?, ?, ?, ?, ?, ?)
86
+ `).run(revisionId, row.id, number, hash, JSON.stringify(definition), timestamp);
87
+ database.prepare(`
88
+ UPDATE agents SET current_revision_id = ?, current_revision_number = ? WHERE id = ?
89
+ `).run(revisionId, number, row.id);
90
+ }
91
+ }
25
92
  function upgradeRegistry(database, current) {
26
93
  database.pragma('foreign_keys = OFF');
27
94
  try {
@@ -47,6 +114,22 @@ function upgradeRegistry(database, current) {
47
114
  ON agent_revisions(agent_id, revision_number DESC);
48
115
  `);
49
116
  }
117
+ if (current < 4) {
118
+ // Every agent a user already had stays visible; platform agents are
119
+ // recognized by the marker their installer wrote. Their installed hash
120
+ // stays unknown, so an existing edit is never mistaken for stock.
121
+ database.exec(`
122
+ ALTER TABLE agents ADD COLUMN pinned INTEGER NOT NULL DEFAULT 1;
123
+ ALTER TABLE agents ADD COLUMN builtin INTEGER NOT NULL DEFAULT 0;
124
+ ALTER TABLE agents ADD COLUMN builtin_hash TEXT;
125
+ UPDATE agents SET builtin = 1 WHERE current_revision_id IN (
126
+ SELECT id FROM agent_revisions
127
+ WHERE json_extract(definition_json, '$.metadata.builtin') = 1
128
+ );
129
+ `);
130
+ }
131
+ if (current < 5)
132
+ liftSubagentLists(database);
50
133
  database.exec(`
51
134
  DROP TABLE IF EXISTS session_events;
52
135
  DROP TABLE IF EXISTS turns;
package/dist/types.d.ts CHANGED
@@ -60,10 +60,18 @@ export interface AgentRecord {
60
60
  currentRevisionId: string;
61
61
  currentRevision: number;
62
62
  definition: AgentDefinition;
63
+ /** Shown wherever a user picks an agent. Identity state; never a revision. */
64
+ pinned: boolean;
65
+ /** Installed by the platform. Editable and unpinnable, never deletable. */
66
+ builtin: boolean;
63
67
  createdAt: string;
64
68
  updatedAt: string;
65
69
  deletedAt: string | null;
66
70
  }
71
+ export interface CreateAgentOptions {
72
+ /** Defaults to true: a new agent appears in every agent picker. */
73
+ pinned?: boolean;
74
+ }
67
75
  export interface AgentsOptions {
68
76
  stateDir?: string;
69
77
  databasePath?: string;
package/docs/CLI.md CHANGED
@@ -8,6 +8,8 @@ amalgm-agents agent list [--include-deleted]
8
8
  amalgm-agents agent show <id> [--include-deleted]
9
9
  amalgm-agents agent create <definition.json>
10
10
  amalgm-agents agent update <id> <patch.json>
11
+ amalgm-agents agent pin <id>
12
+ amalgm-agents agent unpin <id>
11
13
  amalgm-agents agent delete <id>
12
14
  ```
13
15
 
@@ -8,10 +8,24 @@ The registry has two tables:
8
8
 
9
9
  | Table | Role |
10
10
  |---|---|
11
- | `agents` | stable identity, current revision pointer, tombstone |
11
+ | `agents` | stable identity, current revision pointer, pin, built-in marker, tombstone |
12
12
  | `agent_revisions` | immutable normalized definitions |
13
13
 
14
14
  Repeating the current definition is idempotent. Returning to content used by
15
15
  an earlier revision creates a new revision number, keeping the definition
16
16
  timeline complete and append-only. Conversations and turns are stored only by
17
17
  Chat.
18
+
19
+ `pinned` and `builtin` are identity state, not definition content: changing
20
+ either never mints a revision, and no edit to a definition can clear them.
21
+ Every agent picker shows exactly the pinned agents. New agents are pinned; a
22
+ bundle install pins only its agent heads, and a native config import leaves the
23
+ subagents it creates unpinned. `builtin_hash` records the stock
24
+ definition the platform last installed, so the installer advances a built-in
25
+ only while its current revision is still that stock definition. Version 3
26
+ registries upgrade with every agent pinned and built-ins recognized by their
27
+ installer marker, their stock hash unknown until it matches again. Version 4
28
+ registries upgrade to one subagent list per agent: the enabled entries the
29
+ agent editor kept in `driver.config.subagents` join `resources.subagents`, and
30
+ that copy and the config view's `metadata.agentConfig.subagents` are dropped,
31
+ as a new revision that leaves `updated_at` alone.
@@ -59,7 +59,10 @@ authoritative and de-duplicated. Set nullable fields such as `model` or
59
59
  - `toolbox` matches the selection concepts in `@amalgm/tools` but does not
60
60
  import or mutate a Toolbox.
61
61
  - `resources.skills` and `resources.files` are resolved by the host.
62
- - `resources.subagents` describes intended relationships; the host still
62
+ - `resources.subagents` is an agent's one subagent list: ids of other agents
63
+ in this registry. Nothing else stores a subagent list, not `driver.config`
64
+ and not the config view; names and descriptions are read from the agents
65
+ the ids name, and an id whose agent was deleted drops out. The host still
63
66
  authorizes every agent-to-agent call.
64
67
  - `driver.config` is non-secret harness configuration interpreted only by
65
68
  Chat's host runtime.
package/docs/MCP.md CHANGED
@@ -3,6 +3,7 @@
3
3
  `amalgm-agents-mcp` is the standalone stdio server. `createMcpServer` from
4
4
  `@amalgm/agents/mcp` embeds the same server.
5
5
 
6
- It exposes five registry tools: `agents_list`, `agents_get`, `agents_create`,
7
- `agents_update`, and `agents_delete`. Their handlers call the injected
8
- `Agents` service; MCP contains no second registry and no conversation runtime.
6
+ It exposes six registry tools: `agents_list`, `agents_get`, `agents_create`,
7
+ `agents_update`, `agents_set_pinned`, and `agents_delete`. Their handlers call
8
+ the injected `Agents` service; MCP contains no second registry and no
9
+ conversation runtime.
package/docs/REST.md CHANGED
@@ -13,7 +13,8 @@ default to a 512 KB limit.
13
13
  | `POST` | `/v1/agents` | Create from a complete definition |
14
14
  | `GET` | `/v1/agents/:id` | Read the current definition |
15
15
  | `PATCH` | `/v1/agents/:id` | Apply a definition patch |
16
- | `DELETE` | `/v1/agents/:id` | Tombstone an identity |
16
+ | `PUT` | `/v1/agents/:id/pinned` | Set `{ "pinned": boolean }`; no revision |
17
+ | `DELETE` | `/v1/agents/:id` | Tombstone an identity; `409` for built-ins |
17
18
 
18
19
  Use `?include_deleted=true` on list or get to include tombstones. The same
19
20
  server also exposes agent configuration, installed skills, and bundle routes
package/docs/SDK.md CHANGED
@@ -12,9 +12,11 @@ the embedding process releases the registry.
12
12
 
13
13
  | Method | Behavior |
14
14
  |---|---|
15
- | `createAgent(definition)` | Create an identity and immutable revision 1 |
15
+ | `createAgent(definition, { pinned? })` | Create an identity and immutable revision 1; pinned unless `pinned: false` |
16
16
  | `updateAgent(id, patch)` | Apply a patch, appending a revision when content changes |
17
- | `deleteAgent(id)` | Tombstone the identity while retaining its revisions |
17
+ | `setAgentPinned(id, pinned)` | Show or hide the agent in every picker; never a revision |
18
+ | `installBuiltinAgent(definition)` | Host-only: install a platform agent pinned, or advance its stock definition while unedited |
19
+ | `deleteAgent(id)` | Tombstone the identity while retaining its revisions; built-ins raise `conflict` |
18
20
  | `getAgent(id, includeDeleted?)` | Read the current definition |
19
21
  | `listAgents(includeDeleted?)` | List available agents by default |
20
22
  | `getAgentRevision(agentId, revisionId?)` | Resolve the current or exact immutable revision |
@@ -3,6 +3,14 @@
3
3
  Shell is the composition root. Agents supplies the canonical registry and Chat
4
4
  supplies the canonical conversation runtime.
5
5
 
6
+ ## Built-in agents
7
+
8
+ Shell owns the platform agent catalog and installs it on every start with
9
+ `installBuiltinAgent`. A missing built-in is created pinned. An existing one
10
+ advances to the new stock definition only while the user has not edited it;
11
+ the user's edits, pin, and unpin always survive a restart. Built-ins cannot be
12
+ deleted, so the catalog never has to recreate an identity the user removed.
13
+
6
14
  ## Resolver boundary
7
15
 
8
16
  Shell gives Chat a resolver with one job: map an installed agent id and optional
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/agents",
3
- "version": "0.2.3-main.35541618842",
3
+ "version": "0.2.3-main.35795496700",
4
4
  "description": "Local-first agent identities, installations, and immutable revisions.",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
@@ -89,11 +89,11 @@
89
89
  "@amalgm/core"
90
90
  ]
91
91
  },
92
- "gitHead": "41f86f6925ed66286b2a5fc02582f71e48d71078",
92
+ "gitHead": "9cd499c07bd8c5fdae5949db444e85c8eb6d81e4",
93
93
  "amalgmSource": {
94
94
  "repository": "amalgm-inc/amalgm-agents",
95
95
  "branch": "main",
96
- "commit": "41f86f6925ed66286b2a5fc02582f71e48d71078",
97
- "occurrence": "35541618842"
96
+ "commit": "9cd499c07bd8c5fdae5949db444e85c8eb6d81e4",
97
+ "occurrence": "35795496700"
98
98
  }
99
99
  }
@@ -121,9 +121,10 @@ Field notes:
121
121
 
122
122
  | Method | Behavior |
123
123
  |---|---|
124
- | `createAgent(definition)` | Create an identity and immutable revision 1 |
124
+ | `createAgent(definition, { pinned? })` | Create an identity and immutable revision 1; pinned unless `pinned: false` |
125
125
  | `updateAgent(id, patch)` | Merge a patch; append a revision only when content changes |
126
- | `deleteAgent(id)` | Tombstone the identity, retaining all revisions |
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` |
127
128
  | `getAgent(id, includeDeleted?)` | Read the current record, or `null` if absent |
128
129
  | `listAgents(includeDeleted?)` | List available agents (tombstones excluded by default) |
129
130
  | `getAgentRevision(agentId, revisionId?)` | Resolve the current or one exact immutable revision |
@@ -138,7 +139,7 @@ Patches are partial definitions with predictable merge rules: top-level fields r
138
139
  const updated = agents.updateAgent('reviewer', {
139
140
  instructions: 'Review for correctness first, style second.',
140
141
  resources: { skills: ['code-review', 'security-review'] },
141
- model: null, // clear the pinned model; the host default applies
142
+ model: null, // clear the chosen model; the host default applies
142
143
  });
143
144
  console.log(updated.currentRevision); // bumped, because content changed
144
145
  ```
@@ -170,6 +171,8 @@ amalgm-agents agent list [--include-deleted]
170
171
  amalgm-agents agent show <id> [--include-deleted]
171
172
  amalgm-agents agent create <definition.json>
172
173
  amalgm-agents agent update <id> <patch.json>
174
+ amalgm-agents agent pin <id>
175
+ amalgm-agents agent unpin <id>
173
176
  amalgm-agents agent delete <id>
174
177
  ```
175
178
 
@@ -199,7 +202,8 @@ When a token is configured, authenticate with `Authorization: Bearer <token>`; `
199
202
  | `POST` | `/v1/agents` | Create from a complete definition |
200
203
  | `GET` | `/v1/agents/:id` | Read the current definition |
201
204
  | `PATCH` | `/v1/agents/:id` | Apply a definition patch |
202
- | `DELETE` | `/v1/agents/:id` | Tombstone an identity |
205
+ | `PUT` | `/v1/agents/:id/pinned` | Set `{ "pinned": boolean }`; no revision |
206
+ | `DELETE` | `/v1/agents/:id` | Tombstone an identity; `409` for built-ins |
203
207
 
204
208
  Add `?include_deleted=true` to list or get requests to include tombstones. There are no conversation routes — execution belongs to Chat.
205
209
 
@@ -211,7 +215,7 @@ Add `?include_deleted=true` to list or get requests to include tombstones. There
211
215
  amalgm-agents-mcp --state-dir ./state
212
216
  ```
213
217
 
214
- It exposes five tools, each a direct projection of an SDK method:
218
+ It exposes six tools, each a direct projection of an SDK method:
215
219
 
216
220
  | Tool | Arguments | Behavior |
217
221
  |---|---|---|
@@ -219,7 +223,8 @@ It exposes five tools, each a direct projection of an SDK method:
219
223
  | `agents_get` | `agent_id`, `include_deleted?` | Read one agent and its current revision |
220
224
  | `agents_create` | `definition` | Create from a complete definition |
221
225
  | `agents_update` | `agent_id`, `patch` | Patch; content changes append a revision |
222
- | `agents_delete` | `agent_id` | Tombstone an identity, retaining revisions |
226
+ | `agents_set_pinned` | `agent_id`, `pinned` | Show or hide the agent in every agent picker |
227
+ | `agents_delete` | `agent_id` | Tombstone an identity; built-ins cannot be deleted, unpin them instead |
223
228
 
224
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.
225
230