amalgm 0.1.146 → 0.1.147

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

@@ -0,0 +1,447 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const { normalizeAgentConfig } = require('../agent-config/schema');
+
+// 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,
+};
+
+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 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 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 cleanEntryId(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+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 automationEntryId(entry) {
+  return isObject(entry) ? cleanEntryId(entry.sourceAutomationId) : '';
+}
+
+function appEntryId(entry) {
+  return isObject(entry) ? cleanEntryId(entry.sourceAppId) : '';
+}
+
+/**
+ * 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;
+}
+
+module.exports = {
+  BUNDLE_KIND,
+  BUNDLE_SCHEMA_VERSION,
+  LEGACY_AGENT_BUNDLE_KIND,
+  addUnique,
+  agentEntryId,
+  appEntryId,
+  assertClosedFlatBundleGraph,
+  automationEntryId,
+  buildFlatAgentBundleGraph,
+  cleanEntryId,
+  cloneJson,
+  collectSkillRecords,
+  isObject,
+  nowIso,
+  standaloneToolIds,
+  uniqueStrings,
+  withBundleGraph,
+};

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

@@ -0,0 +1,241 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const { upsertAgentConfig, agentFieldsFromConfig } = require('../agent-config/store');
+const { normalizeAgentConfig } = require('../agent-config/schema');
+const { createAgent, getAllAgentsWithBuiltins } = require('../agents/store');
+const { defaultToolboxService } = require('../toolbox/service');
+const { installAutomationEntry } = require('./automation-entries');
+const { installAppEntry } = require('./app-entries');
+const { rewriteAppBoundPaths } = require('./tool-bindings');
+const {
+  BUNDLE_KIND,
+  BUNDLE_SCHEMA_VERSION,
+  LEGACY_AGENT_BUNDLE_KIND,
+  agentEntryId,
+  appEntryId,
+  isObject,
+  nowIso,
+  standaloneToolIds,
+  uniqueStrings,
+  withBundleGraph,
+} = require('./graph');
+
+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 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],
+  };
+}
+
+module.exports = {
+  installBundle,
+  validateBundle,
+};

package/runtime/scripts/amalgm-mcp/apps/store.js

@@ -163,6 +163,7 @@ function getConnectedRoutes() {
       && app.desiredState === 'running'
       && app.status !== 'stopped'
       && app.status !== 'error'
+      && app.status !== 'degraded'
       && app.port
       && app.appRef,
     )