amalgm 0.1.146 → 0.1.147

package/runtime/scripts/amalgm-mcp/agent-bundles/bundles.js

@@ -1,1004 +1,11 @@
 'use strict';
 
-const crypto = require('crypto');
-
-const { getAgentConfig, upsertAgentConfig, agentFieldsFromConfig } = require('../agent-config/store');
-const { normalizeAgentConfig } = require('../agent-config/schema');
-const { createAgent, getAllAgentsWithBuiltins, resolveAgent } = require('../agents/store');
-const { hydrateConfigSkills } = require('../skills/store');
-const { defaultToolboxService } = require('../toolbox/service');
-const { getApp } = require('../apps/store');
-const { exportAutomationEntry, installAutomationEntry } = require('./automation-entries');
-const { exportAppEntry, installAppEntry } = require('./app-entries');
-const { annotateAppBoundPaths, rewriteAppBoundPaths } = require('./tool-bindings');
-
-// Agent-only bundles keep the legacy kind so older runtimes can still install
-// them; bundles that carry automations or apps use the general kind so older
-// runtimes reject them outright instead of silently dropping primitives.
-const BUNDLE_KIND = 'amalgm.bundle';
-const LEGACY_AGENT_BUNDLE_KIND = 'amalgm.agent.bundle';
-const BUNDLE_SCHEMA_VERSION = 1;
-const GRAPH_ELEMENT_ORDER = {
-  agent: 0,
-  automation: 1,
-  app: 2,
-  tool: 3,
-  tool_action: 4,
-  skill: 5,
-};
-
-const SECRET_KEY_PATTERN = /(api[_-]?key|authorization|bearer|cookie|password|passwd|secret|token|credential|private[_-]?key)/i;
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function isObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function cloneJson(value) {
-  if (value == null) return value;
-  return JSON.parse(JSON.stringify(value));
-}
-
-function uniqueStrings(values) {
-  if (!Array.isArray(values)) return [];
-  return [...new Set(values
-    .filter((value) => typeof value === 'string')
-    .map((value) => value.trim())
-    .filter(Boolean))];
-}
-
-function addUnique(target, value) {
-  if (!value) return;
-  if (!target.includes(value)) target.push(value);
-}
-
-function bundleId() {
-  return `agent-bundle-${crypto.randomUUID()}`;
-}
-
-function stableDigest(value) {
-  return crypto.createHash('sha256')
-    .update(typeof value === 'string' ? value : JSON.stringify(value))
-    .digest('hex')
-    .slice(0, 16);
-}
-
-function graphElementId(type, id) {
-  return `${type}:${id}`;
-}
-
-function skillFingerprint(skill) {
-  if (typeof skill === 'string') {
-    const value = skill.trim();
-    return value ? `string:${value}` : '';
-  }
-  if (!isObject(skill)) return '';
-  const id = typeof skill.id === 'string' ? skill.id.trim() : '';
-  if (id) return `id:${id}`;
-  const path = typeof skill.path === 'string' ? skill.path.trim() : '';
-  if (path) return `path:${path}`;
-  const name = typeof skill.name === 'string' ? skill.name.trim() : '';
-  const content = typeof skill.content === 'string' ? skill.content.trim() : '';
-  if (name && content) return `name-content:${name}:${content}`;
-  if (name) return `name:${name}`;
-  if (content) return `content:${content}`;
-  return `json:${JSON.stringify(skill)}`;
-}
-
-function skillElementId(skill) {
-  const fingerprint = skillFingerprint(skill);
-  return fingerprint ? graphElementId('skill', stableDigest(fingerprint)) : '';
-}
-
-function skillLabel(skill) {
-  if (typeof skill === 'string') return skill.trim() || 'Skill';
-  if (!isObject(skill)) return 'Skill';
-  const id = typeof skill.id === 'string' ? skill.id.trim() : '';
-  const name = typeof skill.name === 'string' ? skill.name.trim() : '';
-  const path = typeof skill.path === 'string' ? skill.path.trim() : '';
-  if (name) return name;
-  if (path) return path.split('/').filter(Boolean).pop() || path;
-  if (id) return id;
-  const content = typeof skill.content === 'string' ? skill.content.trim() : '';
-  return content.slice(0, 60) || 'Skill';
-}
-
-function compareGraphElements(left, right) {
-  const order = (GRAPH_ELEMENT_ORDER[left.type] || 99) - (GRAPH_ELEMENT_ORDER[right.type] || 99);
-  if (order !== 0) return order;
-  return String(left.id).localeCompare(String(right.id));
-}
-
-function compareGraphEdges(left, right) {
-  return String(left.from).localeCompare(String(right.from))
-    || String(left.kind).localeCompare(String(right.kind))
-    || String(left.to).localeCompare(String(right.to));
-}
-
-function pushGraphElement(elements, element) {
-  if (!element?.id) return;
-  if (!elements.has(element.id)) elements.set(element.id, element);
-}
-
-function pushGraphEdge(edges, edge) {
-  if (!edge?.from || !edge?.to || !edge?.kind) return;
-  const key = `${edge.from}::${edge.kind}::${edge.to}`;
-  if (!edges.has(key)) edges.set(key, edge);
-}
-
-function portableAgent(agent) {
-  return {
-    sourceAgentId: agent.id,
-    name: agent.name || agent.id,
-    description: agent.description || '',
-    baseHarnessId: agent.baseHarnessId || agent.adapter || 'codex',
-    baseModelId: agent.baseModelId || '',
-    modelSettings: isObject(agent.modelSettings) ? cloneJson(agent.modelSettings) : null,
-    authMethod: agent.authMethod || 'amalgm',
-  };
-}
-
-function scrubSecrets(value, path, requires) {
-  if (Array.isArray(value)) {
-    return value.map((entry, index) => scrubSecrets(entry, `${path}[${index}]`, requires));
-  }
-  if (!isObject(value)) return value;
-
-  const out = {};
-  for (const [key, child] of Object.entries(value)) {
-    const childPath = path ? `${path}.${key}` : key;
-    if (SECRET_KEY_PATTERN.test(key)) {
-      addUnique(requires.secrets, childPath);
-      continue;
-    }
-    out[key] = scrubSecrets(child, childPath, requires);
-  }
-  return out;
-}
-
-function portableTool(tool, requires) {
-  return scrubSecrets(cloneJson(tool), `tools.${tool.id}`, requires);
-}
-
-function portableAction(action, requires) {
-  return scrubSecrets(cloneJson(action), `toolActions.${action.id}`, requires);
-}
-
-function countHooks(bundleAgents) {
-  return bundleAgents.reduce((count, entry) => (
-    count + (Array.isArray(entry.config?.hooks) ? entry.config.hooks.length : 0)
-  ), 0);
-}
-
-function collectSkillRecords(bundleAgents) {
-  const byKey = new Map();
-  for (const entry of bundleAgents) {
-    for (const skill of entry.config.skills || []) {
-      const key = skillFingerprint(skill);
-      if (!key) continue;
-      byKey.set(key, cloneJson(skill));
-    }
-  }
-  return [...byKey.values()];
-}
-
-function automationEntryId(entry) {
-  return isObject(entry) ? cleanEntryId(entry.sourceAutomationId) : '';
-}
-
-function appEntryId(entry) {
-  return isObject(entry) ? cleanEntryId(entry.sourceAppId) : '';
-}
-
-function cleanEntryId(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-/**
- * Tools shared as top-level primitives (not just dependencies of agents or
- * automations). The bundle's explicit heads are the single source of truth.
- */
-function standaloneToolIds(bundle) {
-  const heads = Array.isArray(bundle?.heads) ? bundle.heads : [];
-  return uniqueStrings(heads
-    .filter((head) => isObject(head) && cleanEntryId(head.type) === 'tool')
-    .map((head) => cleanEntryId(head.id)));
-}
-
-/**
- * App elements carry the portable record and a file manifest; file contents
- * stay in bundle.apps[] so the graph remains cheap to render.
- */
-function appElementData(entry) {
-  return {
-    sourceAppId: appEntryId(entry),
-    app: cloneJson(entry.app || {}),
-    files: (Array.isArray(entry.files) ? entry.files : []).map((file) => ({
-      path: file.path,
-      size: file.size,
-      encoding: file.encoding,
-      ...(file.executable ? { executable: true } : {}),
-    })),
-    totalBytes: entry.totalBytes || 0,
-    skipped: cloneJson(entry.skipped || []),
-  };
-}
-
-function buildFlatAgentBundleGraph(bundle) {
-  const elements = new Map();
-  const edges = new Map();
-  const toolMap = new Map((Array.isArray(bundle.tools) ? bundle.tools : []).map((tool) => [tool.id, tool]));
-  const toolActionMap = new Map((Array.isArray(bundle.toolActions) ? bundle.toolActions : []).map((action) => [action.id, action]));
-  const systemToolIds = new Set(uniqueStrings(bundle.requires?.systemTools));
-  const missingToolIds = new Set(uniqueStrings(bundle.requires?.missingTools));
-  const skills = collectSkillRecords(bundle.agents || []);
-
-  for (const entry of bundle.agents || []) {
-    const currentAgentId = agentEntryId(entry);
-    if (!currentAgentId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('agent', currentAgentId),
-      type: 'agent',
-      label: entry.agent?.name || currentAgentId,
-      data: {
-        sourceAgentId: currentAgentId,
-        agent: cloneJson(entry.agent || {}),
-        config: cloneJson(normalizeAgentConfig(entry.config || {})),
-      },
-    });
-  }
-
-  for (const entry of bundle.automations || []) {
-    const currentAutomationId = automationEntryId(entry);
-    if (!currentAutomationId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('automation', currentAutomationId),
-      type: 'automation',
-      label: entry.automation?.name || currentAutomationId,
-      data: cloneJson(entry),
-    });
-  }
-
-  for (const entry of bundle.apps || []) {
-    const currentAppId = appEntryId(entry);
-    if (!currentAppId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('app', currentAppId),
-      type: 'app',
-      label: entry.app?.name || currentAppId,
-      data: appElementData(entry),
-    });
-  }
-
-  for (const skill of skills) {
-    const elementId = skillElementId(skill);
-    if (!elementId) continue;
-    pushGraphElement(elements, {
-      id: elementId,
-      type: 'skill',
-      label: skillLabel(skill),
-      data: typeof skill === 'string' ? { value: skill } : cloneJson(skill),
-    });
-  }
-
-  const includedToolIds = new Set();
-  const includedActionIds = new Set();
-
-  for (const entry of bundle.automations || []) {
-    const currentAutomationId = automationEntryId(entry);
-    if (!currentAutomationId) continue;
-    for (const toolId of uniqueStrings(entry.toolIds)) {
-      includedToolIds.add(toolId);
-      pushGraphEdge(edges, {
-        from: graphElementId('automation', currentAutomationId),
-        to: graphElementId('tool', toolId),
-        kind: 'uses-tool',
-      });
-    }
-  }
-  // Tools that belong to an app render nested under it in the share sidebar;
-  // the canonical tool record still appears exactly once.
-  for (const entry of bundle.apps || []) {
-    const currentAppId = appEntryId(entry);
-    if (!currentAppId) continue;
-    for (const toolId of uniqueStrings(entry.toolIds)) {
-      includedToolIds.add(toolId);
-      pushGraphEdge(edges, {
-        from: graphElementId('app', currentAppId),
-        to: graphElementId('tool', toolId),
-        kind: 'uses-tool',
-      });
-    }
-  }
-  for (const entry of bundle.agents || []) {
-    const currentAgentId = agentEntryId(entry);
-    if (!currentAgentId) continue;
-    const currentConfig = normalizeAgentConfig(entry.config || {});
-
-    for (const subagent of currentConfig.subagents || []) {
-      if (!subagent?.agentId) continue;
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: graphElementId('agent', subagent.agentId),
-        kind: 'uses-subagent',
-      });
-    }
-
-    for (const selectedId of uniqueStrings(currentConfig.loadout?.toolIds)) {
-      const selectedAction = toolActionMap.get(selectedId);
-      if (selectedAction) {
-        includedActionIds.add(selectedAction.id);
-        includedToolIds.add(selectedAction.toolId);
-        pushGraphEdge(edges, {
-          from: graphElementId('agent', currentAgentId),
-          to: graphElementId('tool_action', selectedAction.id),
-          kind: 'uses-tool-action',
-        });
-        continue;
-      }
-
-      includedToolIds.add(selectedId);
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: graphElementId('tool', selectedId),
-        kind: 'uses-tool',
-      });
-    }
-
-    for (const skill of currentConfig.skills || []) {
-      const targetId = skillElementId(skill);
-      if (!targetId) continue;
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: targetId,
-        kind: 'uses-skill',
-      });
-    }
-  }
-
-  // Every tool in bundle.tools gets an element — standalone tool heads are
-  // not referenced by any agent or automation edge but must still resolve.
-  const toolElementIds = new Set([...includedToolIds, ...toolMap.keys()]);
-  for (const toolId of toolElementIds) {
-    const tool = toolMap.get(toolId);
-    pushGraphElement(elements, {
-      id: graphElementId('tool', toolId),
-      type: 'tool',
-      label: tool?.name || toolId,
-      data: tool
-        ? cloneJson(tool)
-        : {
-            id: toolId,
-            name: toolId,
-            origin: systemToolIds.has(toolId) ? 'system' : missingToolIds.has(toolId) ? 'missing' : 'unknown',
-          },
-    });
-  }
-
-  for (const action of Array.isArray(bundle.toolActions) ? bundle.toolActions : []) {
-    if (!toolElementIds.has(action.toolId)) continue;
-    includedActionIds.add(action.id);
-    pushGraphElement(elements, {
-      id: graphElementId('tool_action', action.id),
-      type: 'tool_action',
-      label: action.name || action.id,
-      data: cloneJson(action),
-    });
-    pushGraphEdge(edges, {
-      from: graphElementId('tool_action', action.id),
-      to: graphElementId('tool', action.toolId),
-      kind: 'action-of',
-    });
-  }
-
-  return {
-    headIds: bundleHeadIds(bundle, elements),
-    elements: [...elements.values()].sort(compareGraphElements),
-    edges: [...edges.values()].sort(compareGraphEdges),
-  };
-}
-
-/**
- * Heads are the user-facing roots of the bundle. Explicit bundle.heads win;
- * otherwise fall back to the legacy single agent root plus every automation
- * and app entry (those are always top-level).
- */
-function bundleHeadIds(bundle, elements) {
-  const headIds = [];
-  const explicitHeads = Array.isArray(bundle.heads) ? bundle.heads : [];
-  for (const head of explicitHeads) {
-    const type = cleanEntryId(head?.type);
-    const id = cleanEntryId(head?.id);
-    if (!type || !id) continue;
-    const elementId = graphElementId(type, id);
-    if (elements.has(elementId) && !headIds.includes(elementId)) headIds.push(elementId);
-  }
-  if (headIds.length > 0) return headIds;
-
-  const firstAgentId = agentEntryId(bundle.agents?.[0]);
-  const rootAgentId = cleanEntryId(bundle.rootAgentId) || firstAgentId;
-  if (rootAgentId && elements.has(graphElementId('agent', rootAgentId))) {
-    headIds.push(graphElementId('agent', rootAgentId));
-  }
-  for (const entry of bundle.automations || []) {
-    const id = automationEntryId(entry);
-    if (id) headIds.push(graphElementId('automation', id));
-  }
-  for (const entry of bundle.apps || []) {
-    const id = appEntryId(entry);
-    if (id) headIds.push(graphElementId('app', id));
-  }
-  return [...new Set(headIds)];
-}
-
-function assertClosedFlatBundleGraph(bundle) {
-  if (!Array.isArray(bundle.headIds) || bundle.headIds.length === 0) {
-    throw new Error('bundle graph must include at least one head');
-  }
-
-  const elementIds = new Set();
-  for (const element of Array.isArray(bundle.elements) ? bundle.elements : []) {
-    if (!isObject(element) || typeof element.id !== 'string' || !element.id.trim()) {
-      throw new Error('bundle graph elements must include non-empty ids');
-    }
-    if (elementIds.has(element.id)) {
-      throw new Error(`bundle graph contains duplicate element id: ${element.id}`);
-    }
-    elementIds.add(element.id);
-  }
-
-  for (const headId of bundle.headIds) {
-    if (typeof headId !== 'string' || !elementIds.has(headId)) {
-      throw new Error(`bundle graph head is missing element: ${headId}`);
-    }
-  }
-
-  for (const edge of Array.isArray(bundle.edges) ? bundle.edges : []) {
-    if (!isObject(edge) || typeof edge.from !== 'string' || typeof edge.to !== 'string' || typeof edge.kind !== 'string') {
-      throw new Error('bundle graph edges must include from, to, and kind');
-    }
-    if (!elementIds.has(edge.from)) throw new Error(`bundle graph edge source is missing element: ${edge.from}`);
-    if (!elementIds.has(edge.to)) throw new Error(`bundle graph edge target is missing element: ${edge.to}`);
-  }
-}
-
-function withBundleGraph(bundle) {
-  const graph = buildFlatAgentBundleGraph(bundle);
-  const nextBundle = {
-    ...bundle,
-    headIds: graph.headIds,
-    elements: graph.elements,
-    edges: graph.edges,
-  };
-  assertClosedFlatBundleGraph(nextBundle);
-  return nextBundle;
-}
-
-function collectToolRecords(toolIds, requires) {
-  const catalog = defaultToolboxService.readCatalog();
-  const tools = new Map();
-  const actions = new Map();
-  const selected = uniqueStrings(toolIds);
-
-  for (const selectedId of selected) {
-    const selectedTool = catalog.tools?.[selectedId];
-    const selectedAction = catalog.toolActions?.[selectedId];
-    const tool = selectedTool || (selectedAction ? catalog.tools?.[selectedAction.toolId] : null);
-
-    if (!tool) {
-      addUnique(requires.missingTools, selectedId);
-      continue;
-    }
-
-    if (tool.origin === 'system') {
-      addUnique(requires.systemTools, tool.id);
-    }
-
-    if (!tools.has(tool.id)) tools.set(tool.id, portableTool(tool, requires));
-
-    if (selectedAction) {
-      actions.set(selectedAction.id, portableAction(selectedAction, requires));
-    }
-
-    for (const action of Object.values(catalog.toolActions || {})) {
-      if (action?.toolId === tool.id) actions.set(action.id, portableAction(action, requires));
-    }
-  }
-
-  return {
-    tools: [...tools.values()],
-    toolActions: [...actions.values()],
-  };
-}
-
-function collectAgentGraph(rootAgentId) {
-  const seen = new Set();
-  const ordered = [];
-
-  function visit(agentId) {
-    if (!agentId || seen.has(agentId)) return;
-    seen.add(agentId);
-    const agent = resolveAgent(agentId);
-    if (!agent) throw new Error(`Agent not found: ${agentId}`);
-    const config = hydrateConfigSkills(getAgentConfig(agent));
-    ordered.push({
-      sourceAgentId: agent.id,
-      agent: portableAgent(agent),
-      config: normalizeAgentConfig(config),
-    });
-    for (const subagent of config.subagents || []) {
-      if (subagent?.agentId) visit(subagent.agentId);
-    }
-  }
-
-  visit(rootAgentId);
-  return ordered;
-}
-
-function bundleTitleAndDescription(agents, automations, apps, sharedTools) {
-  const firstAgent = agents[0]?.agent;
-  if (firstAgent) {
-    return { title: firstAgent.name || 'Shared agent', description: firstAgent.description || '' };
-  }
-  const firstAutomation = automations[0]?.automation;
-  if (firstAutomation) {
-    return { title: firstAutomation.name || 'Shared automation', description: firstAutomation.description || '' };
-  }
-  const firstApp = apps[0]?.app;
-  if (firstApp) {
-    return { title: firstApp.name || 'Shared app', description: firstApp.description || '' };
-  }
-  const firstTool = sharedTools?.[0];
-  if (firstTool) {
-    return { title: firstTool.name || 'Shared tool', description: firstTool.description || '' };
-  }
-  return { title: 'Shared bundle', description: '' };
-}
-
-function bundleWarnings({ hooks, tools, automations, apps, skippedAppFiles }) {
-  return [
-    'Instructions, skill text, tool descriptions, and hook commands are shared as plain text.',
-    'Secrets pasted into free-text instructions or files are not automatically detected.',
-    ...(hooks > 0 ? ['This bundle includes executable hook definitions. Review commands before importing.'] : []),
-    ...(tools > 0 ? ['Tools can call external services or local commands. Recipients should reconnect credentials on their own machine.'] : []),
-    ...(automations > 0 ? ['This bundle includes automations. Their workflows run code and call tools on the importing machine — review workflow scripts before importing.'] : []),
-    ...(apps > 0 ? ['This bundle includes apps. Their build and start commands execute on install — review commands before importing.'] : []),
-    ...(skippedAppFiles > 0 ? [`${skippedAppFiles} app file${skippedAppFiles === 1 ? ' was' : 's were'} excluded from the bundle (dependencies, build outputs, env files, or size limits). Builds re-run on install.`] : []),
-  ];
-}
-
-/**
- * Build a portable bundle from any mix of top-level primitives. Each requested
- * id becomes a head; agents pull in their full subagent graph, and agents and
- * automations pull in the toolbox tools they reference.
- */
-function createBundle(input = {}, options = {}) {
-  const agentIds = uniqueStrings(input.agentIds);
-  const automationIds = uniqueStrings(input.automationIds);
-  const appIds = uniqueStrings(input.appIds);
-  const toolIds = uniqueStrings(input.toolIds);
-  if (agentIds.length === 0 && automationIds.length === 0 && appIds.length === 0 && toolIds.length === 0) {
-    throw new Error('At least one agent, automation, app, or tool is required');
-  }
-
-  const requires = {
-    runtimes: [],
-    auth: [],
-    secrets: [],
-    bindings: [],
-    systemTools: [],
-    systemActions: [],
-    missingTools: [],
-  };
-
-  const agents = [];
-  const seenAgentIds = new Set();
-  for (const agentId of agentIds) {
-    for (const entry of collectAgentGraph(agentId)) {
-      if (seenAgentIds.has(entry.sourceAgentId)) continue;
-      seenAgentIds.add(entry.sourceAgentId);
-      agents.push(entry);
-    }
-  }
-
-  const loadoutToolIds = [];
-  for (const entry of agents) {
-    addUnique(requires.runtimes, entry.agent.baseHarnessId);
-    addUnique(requires.auth, `${entry.agent.baseHarnessId}:${entry.agent.authMethod || 'amalgm'}`);
-    loadoutToolIds.push(...(entry.config.loadout?.toolIds || []));
-  }
-
-  const automations = [];
-  for (const automationId of automationIds) {
-    const exported = exportAutomationEntry(automationId);
-    automations.push(exported.entry);
-    loadoutToolIds.push(...exported.toolboxToolIds);
-    for (const ref of exported.systemRefs) addUnique(requires.systemActions, ref);
-    for (const ref of exported.missingRefs) addUnique(requires.missingTools, ref);
-  }
-
-  // Tool → app closure: an app-owned tool only works next to its app, so any
-  // requested tool whose record points at an app pulls that app in as a
-  // dependency (not a head). Stale pointers degrade to a warning.
-  const appLinkWarnings = [];
-  const dependencyAppIds = [];
-  const catalog = defaultToolboxService.readCatalog();
-  for (const selectedId of uniqueStrings([...loadoutToolIds, ...toolIds])) {
-    const selectedAction = catalog.toolActions?.[selectedId];
-    const tool = catalog.tools?.[selectedId]
-      || (selectedAction ? catalog.tools?.[selectedAction.toolId] : null);
-    const owningAppId = typeof tool?.appId === 'string' ? tool.appId.trim() : '';
-    if (!owningAppId || appIds.includes(owningAppId) || dependencyAppIds.includes(owningAppId)) continue;
-    if (!getApp(owningAppId)) {
-      appLinkWarnings.push(`Tool ${tool.id} belongs to app ${owningAppId}, which no longer exists; the app was not bundled.`);
-      continue;
-    }
-    dependencyAppIds.push(owningAppId);
-  }
-
-  const apps = [];
-  const appCwdBySourceId = new Map();
-  let skippedAppFiles = 0;
-  const appToolIds = [];
-  for (const appId of [...appIds, ...dependencyAppIds]) {
-    const exported = exportAppEntry(appId);
-    apps.push(exported.entry);
-    appCwdBySourceId.set(exported.entry.sourceAppId, exported.sourceCwd);
-    skippedAppFiles += exported.skipped.length;
-    // App → tool closure: tools that belong to a bundled app travel with it.
-    appToolIds.push(...(exported.entry.toolIds || []));
-  }
-
-  const { tools, toolActions } = collectToolRecords([...loadoutToolIds, ...appToolIds, ...toolIds], requires);
-
-  // Tool files that live inside a shared app travel with that app: record
-  // app-relative bindings so install rewrites them to the recipient's copy.
-  // Absolute paths no shared app covers stay machine-bound requirements.
-  for (const record of [...tools, ...toolActions]) {
-    if (record.origin === 'system') continue;
-    const kind = record.toolId ? 'toolAction' : 'tool';
-    const { unbound } = annotateAppBoundPaths(record, appCwdBySourceId);
-    for (const label of unbound) addUnique(requires.bindings, `${kind}:${record.id}:${label}`);
-  }
-  // Standalone tool heads must resolve to a real catalog tool — a dependency
-  // tool that is missing degrades to a placeholder, but a head cannot.
-  const sharedToolIds = toolIds.filter((toolId) => tools.some((tool) => tool.id === toolId));
-  const missingSharedToolIds = toolIds.filter((toolId) => !sharedToolIds.includes(toolId));
-  if (missingSharedToolIds.length > 0) {
-    throw new Error(`Tool not found: ${missingSharedToolIds.join(', ')}`);
-  }
-  const sharedTools = sharedToolIds.map((toolId) => tools.find((tool) => tool.id === toolId));
-  const skills = collectSkillRecords(agents);
-  const hooks = countHooks(agents);
-  const warnings = [
-    ...bundleWarnings({
-      hooks,
-      tools: tools.length,
-      automations: automations.length,
-      apps: apps.length,
-      skippedAppFiles,
-    }),
-    ...appLinkWarnings,
-  ];
-  // Title comes from what the user deliberately shared: dependency apps
-  // pulled in by an app-owned tool must not name the bundle.
-  const headApps = apps.filter((entry) => appIds.includes(entry.sourceAppId));
-  const { title, description } = bundleTitleAndDescription(agents, automations, headApps, sharedTools);
-  const heads = [
-    ...agentIds.map((id) => ({ type: 'agent', id })),
-    ...automationIds.map((id) => ({ type: 'automation', id })),
-    ...appIds.map((id) => ({ type: 'app', id })),
-    ...sharedToolIds.map((id) => ({ type: 'tool', id })),
-  ];
-
-  const bundle = withBundleGraph({
-    kind: automations.length > 0 || apps.length > 0 || sharedToolIds.length > 0
-      ? BUNDLE_KIND
-      : LEGACY_AGENT_BUNDLE_KIND,
-    schemaVersion: BUNDLE_SCHEMA_VERSION,
-    bundleId: options.bundleId || bundleId(),
-    createdAt: nowIso(),
-    rootAgentId: agents[0]?.sourceAgentId || null,
-    heads,
-    title,
-    description,
-    agents,
-    automations,
-    apps,
-    tools,
-    toolActions,
-    skills,
-    assets: [],
-    requires,
-    warnings,
-    summary: {
-      agents: agents.length,
-      automations: automations.length,
-      apps: apps.length,
-      tools: tools.length,
-      toolActions: toolActions.length,
-      skills: skills.length,
-      hooks,
-      assets: 0,
-    },
-  });
-
-  const bytes = Buffer.byteLength(JSON.stringify(bundle));
-  return {
-    bundle,
-    preview: {
-      bundleId: bundle.bundleId,
-      title: bundle.title,
-      description: bundle.description,
-      summary: bundle.summary,
-      requires,
-      warnings,
-      agents: agents.map((entry) => ({
-        sourceAgentId: entry.sourceAgentId,
-        name: entry.agent.name,
-        description: entry.agent.description,
-        baseHarnessId: entry.agent.baseHarnessId,
-        baseModelId: entry.agent.baseModelId,
-        tools: entry.config.loadout?.toolIds?.length || 0,
-        skills: entry.config.skills?.length || 0,
-        subagents: entry.config.subagents?.length || 0,
-        hooks: entry.config.hooks?.length || 0,
-      })),
-      automations: automations.map((entry) => ({
-        sourceAutomationId: entry.sourceAutomationId,
-        name: entry.automation.name,
-        description: entry.automation.description,
-        triggers: entry.triggers.length,
-        workflows: entry.workflows.length,
-        tools: entry.toolIds.length,
-      })),
-      apps: apps.map((entry) => ({
-        sourceAppId: entry.sourceAppId,
-        name: entry.app.name,
-        description: entry.app.description,
-        files: entry.files.length,
-        totalBytes: entry.totalBytes,
-        skippedFiles: entry.skipped.length,
-      })),
-      tools: tools.map((tool) => ({
-        id: tool.id,
-        name: tool.name,
-        type: tool.type,
-        origin: tool.origin,
-        actionCount: toolActions.filter((action) => action.toolId === tool.id).length,
-      })),
-      sizeBytes: bytes,
-    },
-  };
-}
-
-function createAgentBundle(agentId, options = {}) {
-  if (!agentId) throw new Error('agent_id is required');
-  return createBundle({ agentIds: [agentId] }, options);
-}
-
-function uniqueAgentName(name) {
-  const base = String(name || 'Imported agent').trim() || 'Imported agent';
-  const existing = new Set(
-    getAllAgentsWithBuiltins().map((agent) => String(agent.name || '').trim().toLowerCase()),
-  );
-  if (!existing.has(base.toLowerCase())) return base;
-  const imported = `${base} (imported)`;
-  if (!existing.has(imported.toLowerCase())) return imported;
-  for (let index = 2; index < 1000; index += 1) {
-    const candidate = `${base} (imported ${index})`;
-    if (!existing.has(candidate.toLowerCase())) return candidate;
-  }
-  return `${base} (${crypto.randomUUID().slice(0, 8)})`;
-}
-
-function externalMcpToolIdsForLoadout(toolIds, tools) {
-  const toolMap = new Map((Array.isArray(tools) ? tools : []).map((tool) => [tool.id, tool]));
-  return uniqueStrings(toolIds)
-    .map((toolId) => toolMap.get(toolId))
-    .filter((tool) => tool?.type === 'mcp' && tool?.origin !== 'system')
-    .map((tool) => tool.id);
-}
-
-function agentEntryId(entry) {
-  if (!isObject(entry)) return '';
-  const sourceAgentId = typeof entry.sourceAgentId === 'string' ? entry.sourceAgentId.trim() : '';
-  if (sourceAgentId) return sourceAgentId;
-  return typeof entry.agent?.sourceAgentId === 'string' ? entry.agent.sourceAgentId.trim() : '';
-}
-
-function referencedSubagentIds(entry) {
-  if (!isObject(entry)) return [];
-  const subagents = Array.isArray(entry.config?.subagents) ? entry.config.subagents : [];
-  return subagents
-    .map((subagent) => (typeof subagent?.agentId === 'string' ? subagent.agentId.trim() : ''))
-    .filter(Boolean);
-}
-
-function assertClosedAgentBundleGraph(bundle) {
-  const agentIds = new Set(bundle.agents.map(agentEntryId).filter(Boolean));
-  const missing = new Set();
-  for (const entry of bundle.agents) {
-    for (const agentId of referencedSubagentIds(entry)) {
-      if (!agentIds.has(agentId)) missing.add(agentId);
-    }
-  }
-
-  if (missing.size > 0) {
-    throw new Error(`Bundle is missing shared subagents: ${Array.from(missing).join(', ')}`);
-  }
-}
-
-function validateBundle(bundle) {
-  if (!isObject(bundle)) throw new Error('bundle must be an object');
-  if (bundle.kind !== BUNDLE_KIND && bundle.kind !== LEGACY_AGENT_BUNDLE_KIND) {
-    throw new Error(`Unsupported bundle kind: ${bundle.kind || 'unknown'}`);
-  }
-  if (bundle.schemaVersion !== BUNDLE_SCHEMA_VERSION) {
-    throw new Error(`Unsupported bundle schema version: ${bundle.schemaVersion || 'unknown'}`);
-  }
-  const agents = Array.isArray(bundle.agents) ? bundle.agents : [];
-  const automations = Array.isArray(bundle.automations) ? bundle.automations : [];
-  const apps = Array.isArray(bundle.apps) ? bundle.apps : [];
-  const toolHeads = standaloneToolIds(bundle);
-  if (agents.length === 0 && automations.length === 0 && apps.length === 0 && toolHeads.length === 0) {
-    throw new Error('bundle must include at least one agent, automation, app, or tool');
-  }
-  if (agents.length > 0) assertClosedAgentBundleGraph(bundle);
-  return withBundleGraph(bundle);
-}
-
-function installTools(bundle, appDirBySourceId = new Map(), appIdBySourceId = new Map()) {
-  const warnings = [];
-  const rewrite = (record) => {
-    const result = rewriteAppBoundPaths(record, appDirBySourceId);
-    warnings.push(...result.warnings);
-    return result.record;
-  };
-
-  const toolActionsByToolId = new Map();
-  for (const action of Array.isArray(bundle.toolActions) ? bundle.toolActions : []) {
-    if (!action?.toolId) continue;
-    const existing = toolActionsByToolId.get(action.toolId) || [];
-    existing.push(rewrite(action));
-    toolActionsByToolId.set(action.toolId, existing);
-  }
-
-  const installed = [];
-  for (const tool of Array.isArray(bundle.tools) ? bundle.tools : []) {
-    if (!tool?.id || tool.origin === 'system') continue;
-    const record = rewrite(tool);
-    // The app link travels by source app id; point it at the recipient's
-    // installed copy, or drop it if that app was not part of the install.
-    if (typeof record.appId === 'string' && record.appId) {
-      const installedAppId = appIdBySourceId.get(record.appId);
-      if (installedAppId) {
-        record.appId = installedAppId;
-      } else {
-        delete record.appId;
-        warnings.push(`Tool ${tool.id} belongs to an app that was not installed with this bundle; the app link was removed.`);
-      }
-    }
-    const result = defaultToolboxService.registerTool({
-      ...record,
-      origin: tool.origin === 'catalog' ? 'catalog' : 'user',
-      actions: toolActionsByToolId.get(tool.id) || [],
-    });
-    installed.push(result.tool);
-  }
-  return { installed, warnings };
-}
-
-function installBundleAgents(bundle, options = {}) {
-  const idMap = new Map();
-  const createdAgents = [];
-  const createdAt = nowIso();
-
-  for (const entry of Array.isArray(bundle.agents) ? bundle.agents : []) {
-    const config = normalizeAgentConfig(entry.config || {});
-    const fields = agentFieldsFromConfig(config);
-    const agent = createAgent({
-      name: uniqueAgentName(entry.agent?.name),
-      description: entry.agent?.description || '',
-      baseHarnessId: entry.agent?.baseHarnessId || 'codex',
-      baseModelId: entry.agent?.baseModelId || '',
-      modelSettings: isObject(entry.agent?.modelSettings) ? entry.agent.modelSettings : null,
-      systemPrompt: fields.systemPrompt,
-      skills: fields.skills,
-      loadout: config.loadout || { toolIds: [] },
-      mcpAppIds: externalMcpToolIdsForLoadout(config.loadout?.toolIds || [], bundle.tools),
-      authMethod: options.authMethod || 'amalgm',
-      status: 'ready',
-      installStatus: 'external',
-      createdAt,
-    }, { source: 'agent-bundles:install' });
-    idMap.set(entry.sourceAgentId || entry.agent?.sourceAgentId, agent.id);
-    createdAgents.push({ sourceAgentId: entry.sourceAgentId, agent, config });
-  }
-
-  const installedAgents = [];
-  for (const created of createdAgents) {
-    const rewrittenConfig = normalizeAgentConfig({
-      ...created.config,
-      agentId: created.agent.id,
-      runtimeHomeLayout: 'per-agent',
-      subagents: (created.config.subagents || [])
-        .map((subagent) => {
-          const mappedAgentId = idMap.get(subagent.agentId);
-          if (!mappedAgentId) return null;
-          return {
-            ...subagent,
-            id: `subagent-${mappedAgentId}`,
-            agentId: mappedAgentId,
-          };
-        })
-        .filter(Boolean),
-    });
-    const savedConfig = upsertAgentConfig(created.agent.id, rewrittenConfig, {
-      source: 'agent-bundles:install',
-    });
-    installedAgents.push({
-      ...created.agent,
-      ...agentFieldsFromConfig(savedConfig),
-      config: savedConfig,
-    });
-  }
-
-  return { idMap, installedAgents };
-}
-
-function defaultAppsInstallRoot() {
-  // Installed apps are Amalgm-owned state: they live under the user's apps
-  // primitive root (<user dir>/apps), not in the projects workspace.
-  return require('../config').APPS_DIR;
-}
-
-/**
- * Install every primitive in a validated bundle. Apps first — they
- * materialize into the user's apps root, build, and start, and their
- * installed directories anchor the app-bound tool path rewrites. Then tools
- * (agents and automations reference them), agents, and automations.
- */
-async function installBundle(input, options = {}) {
-  const bundle = validateBundle(input);
-
-  const installedApps = [];
-  const appDirBySourceId = new Map();
-  const appIdBySourceId = new Map();
-  const appEntries = Array.isArray(bundle.apps) ? bundle.apps : [];
-  if (appEntries.length > 0) {
-    const rootDir = options.appsRootDir || defaultAppsInstallRoot();
-    for (const entry of appEntries) {
-      const installed = await installAppEntry(entry, { rootDir, register: options.registerApp });
-      appDirBySourceId.set(appEntryId(entry), installed.cwd);
-      if (installed.id) appIdBySourceId.set(appEntryId(entry), installed.id);
-      installedApps.push(installed);
-    }
-  }
-
-  const { installed: installedTools, warnings: bindingWarnings } = installTools(bundle, appDirBySourceId, appIdBySourceId);
-  const { idMap, installedAgents } = installBundleAgents(bundle, options);
-
-  const installedAutomations = [];
-  for (const entry of Array.isArray(bundle.automations) ? bundle.automations : []) {
-    installedAutomations.push(installAutomationEntry(entry, { source: 'agent-bundles:install' }));
-  }
-
-  return {
-    ok: true,
-    bundleId: bundle.bundleId,
-    rootAgentId: idMap.get(bundle.rootAgentId) || installedAgents[0]?.id || null,
-    idMap: Object.fromEntries(idMap.entries()),
-    installedAgents,
-    installedTools,
-    installedAutomations,
-    installedApps,
-    warnings: [...(bundle.warnings || []), ...bindingWarnings],
-  };
-}
+// Facade over the agent-bundle modules so existing require paths keep working.
+// The implementation lives in graph.js (flat share graph), export.js
+// (createBundle and its collectors), and install.js (validate + install).
+const { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION, LEGACY_AGENT_BUNDLE_KIND } = require('./graph');
+const { createAgentBundle, createBundle } = require('./export');
+const { installBundle, validateBundle } = require('./install');
 
 module.exports = {
   BUNDLE_KIND,