@amalgm/agents 0.2.3-preview.34436242991 → 0.2.3-preview.34938537476

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
@@ -67,6 +67,9 @@ locked dependency graph on the supported Node toolchain.
67
67
  immutable revision; native imports never ingest credentials or MCP config.
68
68
  9. A portable bundle is accepted only when its flat graph is derivable from
69
69
  its canonical records and every element is reachable from a declared head.
70
+ 10. An agent revision owns its exact tool/action selection and direct, search,
71
+ or hidden exposure overrides. Configuration, export, import, and execution
72
+ preserve that selection; editing it never mutates the parent Toolbox.
70
73
 
71
74
  ## Consequences
72
75
 
@@ -0,0 +1,12 @@
1
+ import type { AgentBundle, BundleHeadType } from './types.js';
2
+ export interface CopyBundleOptions {
3
+ /** Fresh identity for one construct; the default is random. */
4
+ freshId?: (type: BundleHeadType) => string;
5
+ now?: () => string;
6
+ }
7
+ /**
8
+ * A copy is the same content under fresh identities: no construct of the
9
+ * source is named anywhere in it, and its graph is rebuilt around the new
10
+ * names. It is how a published copy cuts lineage.
11
+ */
12
+ export declare function copyAgentBundle(source: AgentBundle, options?: CopyBundleOptions): AgentBundle;
@@ -0,0 +1,144 @@
1
+ import crypto from 'node:crypto';
2
+ import { buildBundleGraph } from './graph.js';
3
+ import { actionEntryId, agentEntryId, appEntryId, automationEntryId, toolEntryId } from './graph-records.js';
4
+ import { bundleId, clean, clone, object } from './util.js';
5
+ /**
6
+ * The identity map of one copy: every construct of the source bundle to its
7
+ * fresh identity. Tool action ids follow their tool: `<tool>.<action>`.
8
+ */
9
+ class IdentityMap {
10
+ #ids = new Map();
11
+ #fresh;
12
+ constructor(fresh) {
13
+ this.#fresh = fresh;
14
+ }
15
+ assign(type, id) {
16
+ if (!id)
17
+ throw new Error(`bundle ${type} entries must include ids`);
18
+ const next = this.#fresh(type);
19
+ this.#ids.set(id, next);
20
+ return next;
21
+ }
22
+ assignAction(id, toolId) {
23
+ const tool = this.#ids.get(toolId);
24
+ if (!tool)
25
+ throw new Error(`tool action ${id} references missing tool: ${toolId}`);
26
+ const separator = id.lastIndexOf('.');
27
+ const next = `${tool}${separator >= 0 ? id.slice(separator) : `.${id}`}`;
28
+ this.#ids.set(id, next);
29
+ return next;
30
+ }
31
+ of(id) {
32
+ return this.#ids.get(id) ?? id;
33
+ }
34
+ strings(value) {
35
+ return Array.isArray(value) ? value.filter((item) => typeof item === 'string').map((item) => this.of(item)) : [];
36
+ }
37
+ /** Rewrite every `actionId` in a compiled plan; keys are the plan's own. */
38
+ plan(value) {
39
+ if (Array.isArray(value))
40
+ return value.map((item) => this.plan(item));
41
+ const record = object(value);
42
+ if (!record)
43
+ return value;
44
+ return Object.fromEntries(Object.entries(record).map(([key, child]) => [
45
+ key,
46
+ (key === 'actionId' || key === 'action_id') && typeof child === 'string' ? this.of(child) : this.plan(child),
47
+ ]));
48
+ }
49
+ /** `automation:<id>:field` bindings and `tools.<id>.path` secret paths; ids may contain dots. */
50
+ requirement(value) {
51
+ const binding = value.match(/^(automation|tool|toolAction):([^:]+):(.*)$/);
52
+ if (binding)
53
+ return `${binding[1]}:${this.of(binding[2])}:${binding[3]}`;
54
+ const secret = value.match(/^(tools|toolActions)\.(.*)$/);
55
+ if (!secret)
56
+ return value;
57
+ for (const [id, next] of this.#ids) {
58
+ if (secret[2].startsWith(`${id}.`))
59
+ return `${secret[1]}.${next}${secret[2].slice(id.length)}`;
60
+ }
61
+ return value;
62
+ }
63
+ }
64
+ function defaultFreshId(type) {
65
+ const id = crypto.randomUUID();
66
+ return type === 'tool' ? `tool-${id.replace(/-/g, '').slice(0, 16)}` : `${type}-${id}`;
67
+ }
68
+ function isSystemTool(tool) {
69
+ return tool.origin === 'system';
70
+ }
71
+ /**
72
+ * A copy is the same content under fresh identities: no construct of the
73
+ * source is named anywhere in it, and its graph is rebuilt around the new
74
+ * names. It is how a published copy cuts lineage.
75
+ */
76
+ export function copyAgentBundle(source, options = {}) {
77
+ const bundle = clone(source);
78
+ const ids = new IdentityMap(options.freshId ?? defaultFreshId);
79
+ for (const entry of bundle.agents)
80
+ ids.assign('agent', agentEntryId(entry));
81
+ for (const entry of bundle.automations)
82
+ ids.assign('automation', automationEntryId(entry));
83
+ for (const entry of bundle.apps)
84
+ ids.assign('app', appEntryId(entry));
85
+ for (const tool of bundle.tools)
86
+ if (!isSystemTool(tool))
87
+ ids.assign('tool', toolEntryId(tool));
88
+ for (const action of bundle.toolActions) {
89
+ const toolId = clean(action.toolId);
90
+ const tool = bundle.tools.find((candidate) => toolEntryId(candidate) === toolId);
91
+ if (tool && !isSystemTool(tool))
92
+ ids.assignAction(actionEntryId(action), toolId);
93
+ }
94
+ for (const entry of bundle.agents) {
95
+ entry.sourceAgentId = ids.of(entry.sourceAgentId);
96
+ entry.config = {
97
+ ...entry.config,
98
+ ...(entry.config.agentId ? { agentId: entry.sourceAgentId } : {}),
99
+ loadout: { toolIds: ids.strings(entry.config.loadout.toolIds), ...(entry.config.loadout.exposure ? {
100
+ exposure: Object.fromEntries(Object.entries(entry.config.loadout.exposure).map(([id, mode]) => [ids.of(id), mode])),
101
+ } : {}) },
102
+ subagents: entry.config.subagents.map((subagent) => ({ ...subagent, agentId: ids.of(subagent.agentId) })),
103
+ };
104
+ }
105
+ for (const entry of bundle.automations) {
106
+ entry.sourceAutomationId = ids.of(clean(entry.sourceAutomationId));
107
+ entry.toolIds = ids.strings(entry.toolIds);
108
+ if (Array.isArray(entry.workflows)) {
109
+ entry.workflows = entry.workflows.map((workflow) => {
110
+ const record = object(workflow);
111
+ return record ? { ...record, compiled: ids.plan(record.compiled ?? null) } : workflow;
112
+ });
113
+ }
114
+ }
115
+ for (const entry of bundle.apps) {
116
+ entry.sourceAppId = ids.of(clean(entry.sourceAppId));
117
+ entry.toolIds = ids.strings(entry.toolIds);
118
+ const manifest = object(entry.manifest);
119
+ if (manifest && Array.isArray(manifest.toolIds))
120
+ entry.manifest = { ...manifest, toolIds: ids.strings(manifest.toolIds) };
121
+ }
122
+ for (const tool of bundle.tools) {
123
+ tool.id = ids.of(toolEntryId(tool));
124
+ if (clean(tool.appId))
125
+ tool.appId = ids.of(clean(tool.appId));
126
+ }
127
+ for (const action of bundle.toolActions) {
128
+ action.id = ids.of(actionEntryId(action));
129
+ action.toolId = ids.of(clean(action.toolId));
130
+ if (clean(action.appId))
131
+ action.appId = ids.of(clean(action.appId));
132
+ }
133
+ bundle.heads = bundle.heads.map((head) => ({ ...head, id: ids.of(head.id) }));
134
+ bundle.rootAgentId = bundle.rootAgentId ? ids.of(bundle.rootAgentId) : null;
135
+ bundle.requires = {
136
+ ...bundle.requires,
137
+ bindings: bundle.requires.bindings.map((value) => ids.requirement(value)),
138
+ secrets: bundle.requires.secrets.map((value) => ids.requirement(value)),
139
+ };
140
+ bundle.bundleId = bundleId();
141
+ bundle.createdAt = options.now?.() || new Date().toISOString();
142
+ Object.assign(bundle, buildBundleGraph(bundle));
143
+ return bundle;
144
+ }
@@ -35,7 +35,7 @@ export async function installAgentBundle(agents, input, options = {}) {
35
35
  authRef: options.authRef || null,
36
36
  instructions: entry.config.instructions,
37
37
  resources: { files: [], skills: [], subagents: [] },
38
- toolbox: { toolIds: entry.config.loadout.toolIds, actionIds: [] },
38
+ toolbox: { toolIds: entry.config.loadout.toolIds, actionIds: [], exposure: entry.config.loadout.exposure ?? {} },
39
39
  metadata: { installedFromBundle: bundle.bundleId },
40
40
  });
41
41
  idMap.set(entry.sourceAgentId, agent.id);
@@ -1,3 +1,4 @@
1
+ import { normalizeToolExposure } from '../tool-exposure.js';
1
2
  import crypto from 'node:crypto';
2
3
  import { isObject } from '../json.js';
3
4
  function text(value) {
@@ -113,7 +114,8 @@ function loadout(value, fallback) {
113
114
  || source.selected || source.tools;
114
115
  const explicit = ['toolIds', 'selectedToolIds', 'selected', 'tools']
115
116
  .some((key) => Object.hasOwn(raw, key));
116
- return { toolIds: uniqueStrings(explicit ? aliases(raw) : aliases(prior)) };
117
+ const exposure = normalizeToolExposure(raw.exposure ?? prior.exposure);
118
+ return { toolIds: uniqueStrings(explicit ? aliases(raw) : aliases(prior)), ...(exposure ? { exposure } : {}) };
117
119
  }
118
120
  // Engine reference: amalgm-mcp/agent-config/schema.js.
119
121
  export function normalizeAgentConfig(input = {}, fallback = {}) {
@@ -16,7 +16,7 @@ export function configFromAgent(agent) {
16
16
  agentId: agent.id,
17
17
  instructions: agent.definition.instructions,
18
18
  skills: agent.definition.resources.skills,
19
- loadout: { toolIds: agent.definition.toolbox.toolIds },
19
+ loadout: { toolIds: [...agent.definition.toolbox.toolIds, ...agent.definition.toolbox.actionIds], exposure: agent.definition.toolbox.exposure },
20
20
  subagents: agent.definition.resources.subagents,
21
21
  });
22
22
  const skillRefs = stored.skills.filter((item) => item.enabled).map((item) => item.name || item.id);
@@ -28,7 +28,7 @@ export function configFromAgent(agent) {
28
28
  ? stored.instructions : agent.definition.instructions,
29
29
  skills: same(skillRefs, agent.definition.resources.skills)
30
30
  ? stored.skills : agent.definition.resources.skills,
31
- loadout: { toolIds: agent.definition.toolbox.toolIds },
31
+ loadout: { toolIds: [...agent.definition.toolbox.toolIds, ...agent.definition.toolbox.actionIds], exposure: agent.definition.toolbox.exposure },
32
32
  subagents: same(subagentRefs, agent.definition.resources.subagents)
33
33
  ? stored.subagents : agent.definition.resources.subagents,
34
34
  }, stored);
@@ -49,7 +49,7 @@ export function updateAgentConfig(agents, agentId, patch) {
49
49
  skills: config.skills.filter((item) => item.enabled).map((item) => item.name || item.id),
50
50
  subagents: config.subagents.filter((item) => item.enabled).map((item) => item.agentId),
51
51
  },
52
- toolbox: { toolIds: config.loadout.toolIds },
52
+ toolbox: { toolIds: config.loadout.toolIds, actionIds: [], exposure: config.loadout.exposure ?? {} },
53
53
  metadata,
54
54
  };
55
55
  return { agent: agents.updateAgent(agentId, projected), config };
@@ -1,4 +1,4 @@
1
- import type { JsonObject } from '../types.js';
1
+ import type { JsonObject, ToolboxLoadoutRef } from '../types.js';
2
2
  export interface ConfigSkill {
3
3
  id: string;
4
4
  name: string;
@@ -36,6 +36,7 @@ export interface AgentConfig {
36
36
  skills: ConfigSkill[];
37
37
  loadout: {
38
38
  toolIds: string[];
39
+ exposure?: ToolboxLoadoutRef['exposure'];
39
40
  };
40
41
  hooks: ConfigHook[];
41
42
  subagents: ConfigSubagent[];
@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
2
2
  import { AgentError } from './errors.js';
3
3
  import { canonicalJson, isObject } from './json.js';
4
4
  import { requireId } from './ids.js';
5
+ import { normalizeToolExposure } from './tool-exposure.js';
5
6
  function text(value, fallback = '') {
6
7
  return typeof value === 'string' ? value.trim() : fallback;
7
8
  }
@@ -42,6 +43,7 @@ export function normalizeDefinition(input) {
42
43
  const resources = isObject(input.resources) ? input.resources : {};
43
44
  const toolbox = isObject(input.toolbox) ? input.toolbox : {};
44
45
  const workspace = isObject(input.workspace) ? input.workspace : {};
46
+ const exposure = normalizeToolExposure(toolbox.exposure);
45
47
  return {
46
48
  id,
47
49
  name,
@@ -58,6 +60,7 @@ export function normalizeDefinition(input) {
58
60
  toolbox: {
59
61
  toolIds: strings(toolbox.toolIds),
60
62
  actionIds: strings(toolbox.actionIds),
63
+ ...(exposure ? { exposure } : {}),
61
64
  },
62
65
  workspace: { cwd: text(workspace.cwd) || null },
63
66
  metadata: object(input.metadata),
@@ -1,6 +1,8 @@
1
+ import { copyAgentBundle } from '../bundles/copy.js';
1
2
  import { createAgentBundle } from '../bundles/create.js';
2
3
  import { installAgentBundle } from '../bundles/install.js';
3
4
  import { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from '../bundles/util.js';
5
+ import { validateAgentBundle } from '../bundles/validate.js';
4
6
  import { scanInstalledSkills } from '../skills/scanner.js';
5
7
  function ids(...values) {
6
8
  const result = [];
@@ -44,6 +46,14 @@ export async function routeAgentBundles(context) {
44
46
  context.json(200, { ok: true, ...result });
45
47
  return true;
46
48
  }
49
+ if (action === 'copy') {
50
+ if (!body.bundle) {
51
+ context.json(400, { error: 'bundle is required' });
52
+ return true;
53
+ }
54
+ context.json(200, { ok: true, bundle: copyAgentBundle(validateAgentBundle(body.bundle)) });
55
+ return true;
56
+ }
47
57
  if (action === 'install') {
48
58
  if (!body.bundle) {
49
59
  context.json(400, { error: 'bundle is required' });
package/dist/index.d.ts CHANGED
@@ -11,6 +11,8 @@ export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/s
11
11
  export { importAgentConfig } from './config/import.js';
12
12
  export { importNativeConfig } from './config/native.js';
13
13
  export type * from './config/types.js';
14
+ export { copyAgentBundle } from './bundles/copy.js';
15
+ export type { CopyBundleOptions } from './bundles/copy.js';
14
16
  export { createAgentBundle } from './bundles/create.js';
15
17
  export type { CreateBundleOptions } from './bundles/create.js';
16
18
  export { installAgentBundle } from './bundles/install.js';
package/dist/index.js CHANGED
@@ -7,6 +7,7 @@ export { normalizeAgentConfig, stableConfigId } from './config/schema.js';
7
7
  export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/store.js';
8
8
  export { importAgentConfig } from './config/import.js';
9
9
  export { importNativeConfig } from './config/native.js';
10
+ export { copyAgentBundle } from './bundles/copy.js';
10
11
  export { createAgentBundle } from './bundles/create.js';
11
12
  export { installAgentBundle } from './bundles/install.js';
12
13
  export { buildBundleGraph } from './bundles/graph.js';
@@ -0,0 +1,3 @@
1
+ import type { ToolboxLoadoutRef } from './types.js';
2
+ /** Agents retains exposure references; Tools owns their execution meaning. */
3
+ export declare function normalizeToolExposure(value: unknown): ToolboxLoadoutRef['exposure'];
@@ -0,0 +1,17 @@
1
+ import { AgentError } from './errors.js';
2
+ import { isObject } from './json.js';
3
+ /** Agents retains exposure references; Tools owns their execution meaning. */
4
+ export function normalizeToolExposure(value) {
5
+ if (value === undefined)
6
+ return undefined;
7
+ if (!isObject(value))
8
+ throw new AgentError('invalid_input', 'Tool exposure must be an object');
9
+ const exposure = {};
10
+ for (const [id, mode] of Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) {
11
+ if (!id.trim() || (mode !== 'direct' && mode !== 'search' && mode !== 'hidden')) {
12
+ throw new AgentError('invalid_input', `Invalid tool exposure: ${id}`);
13
+ }
14
+ exposure[id] = mode;
15
+ }
16
+ return Object.keys(exposure).length ? exposure : undefined;
17
+ }
package/dist/types.d.ts CHANGED
@@ -19,6 +19,7 @@ export interface AgentResources {
19
19
  export interface ToolboxLoadoutRef {
20
20
  toolIds: string[];
21
21
  actionIds: string[];
22
+ exposure?: Record<string, 'direct' | 'search' | 'hidden'>;
22
23
  }
23
24
  export interface AgentWorkspace {
24
25
  cwd: string | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/agents",
3
- "version": "0.2.3-preview.34436242991",
3
+ "version": "0.2.3-preview.34938537476",
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
  "package.json"
90
90
  ]
91
91
  },
92
- "gitHead": "97b81b588de8c7e61a48244f8d4aef09dc0ceb75",
92
+ "gitHead": "dd7579fa4371b3c7a402cd18857b6ff1126e26a5",
93
93
  "amalgmSource": {
94
94
  "repository": "amalgm-inc/amalgm-agents",
95
95
  "branch": "preview",
96
- "commit": "97b81b588de8c7e61a48244f8d4aef09dc0ceb75",
97
- "occurrence": "34436242991"
96
+ "commit": "dd7579fa4371b3c7a402cd18857b6ff1126e26a5",
97
+ "occurrence": "34938537476"
98
98
  }
99
99
  }