@amalgm/agents 0.1.2 → 0.1.3

package/PURPOSE.md

@@ -15,6 +15,8 @@ It also discovers installed agent skills across the canonical project and
 harness roots so every transport presents the same available skill catalog.
 Rich harness configuration is stored inside the same immutable definition and
 projected onto its executable fields; it is not a second agent registry.
+Portable bundle-v2 documents close an agent's subagent, skill, and tool graph;
+hosts supply explicit ports for resources owned by other products.
 
 ## Primitives
 
@@ -41,11 +43,15 @@ projected onto its executable fields; it is not a second agent registry.
    a new immutable revision, even when its content matches an earlier revision.
 8. Agent configuration and its executable projection change atomically in one
    immutable revision; native imports never ingest credentials or MCP config.
+9. A portable bundle is accepted only when its flat graph is derivable from
+   its canonical records and every element is reachable from a declared head.
 
 ## Consequences
 
 The package needs no cloud command inbox, scheduler, trigger relay, Chat
 record, or general event-routing system. Engine and other hosts may call the
 SDK whenever they need to route work, but routing is outside the Agents
-product. Internal revisions, ordered events, idempotency, and cancellation
-exist only to make the six behaviors above durable and predictable.
+product. Bundle ports call Apps, Automations, and Toolbox public APIs; Agents
+never imports their stores or duplicates their lifecycle behavior. Internal
+revisions, ordered events, idempotency, and cancellation exist only to make
+the behaviors above durable and predictable.

package/README.md

@@ -100,6 +100,23 @@ The REST adapter also serves `/agent-config`, `/agent-config/get`,
 only instructions, skills, command hooks, and agent markdown from an injected
 home; credentials and MCP configuration never enter Agents.
 
+Portable bundle-v2 documents use the same SDK law as the REST surface:
+
+```ts
+const { bundle, preview } = await createAgentBundle(
+  agents,
+  { agentIds: ['reviewer'] },
+  { port: hostResourcePort },
+);
+
+await installAgentBundle(agents, bundle, { port: hostResourcePort });
+```
+
+Agents closes recursive subagents, skills, tools, and the canonical flat
+graph. The injected port exports and installs Apps, Automations, and Toolbox
+records through their owning SDKs. A missing port or graph mismatch fails
+explicitly; dependencies are never omitted to make a bundle look portable.
+
 ## CLI
 
 ```bash

package/dist/bundles/create.d.ts

@@ -0,0 +1,13 @@
+import type { Agents } from '../agents.js';
+import type { InstalledSkill } from '../skills/scanner.js';
+import type { AgentBundle, AgentBundlePort, BundleCreateInput } from './types.js';
+export interface CreateBundleOptions {
+    port?: AgentBundlePort;
+    installedSkills?: InstalledSkill[];
+    bundleId?: string;
+    now?: () => string;
+}
+export declare function createAgentBundle(agents: Agents, input: BundleCreateInput, options?: CreateBundleOptions): Promise<{
+    bundle: AgentBundle;
+    preview: Record<string, unknown>;
+}>;

package/dist/bundles/create.js

@@ -0,0 +1,125 @@
+import { configFromAgent } from '../config/store.js';
+import { buildBundleGraph } from './graph.js';
+import { collectSkillRecords } from './graph-records.js';
+import { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION, addUnique, bundleId, emptyRequirements, mergeRequirements, scrubSecrets, uniqueStrings, } from './util.js';
+function hydratedSkill(skill, installed) {
+    if (skill.content)
+        return skill;
+    const sourcePath = typeof skill.source.path === 'string' ? skill.source.path : '';
+    const match = installed.find((item) => item.id === skill.id || item.name === skill.name
+        || (sourcePath && item.source.path === sourcePath));
+    return match ? {
+        ...skill,
+        name: match.name,
+        description: skill.description || match.description,
+        content: match.content || '',
+        source: match.source,
+    } : skill;
+}
+function collectAgents(agents, roots, installed) {
+    const seen = new Set();
+    const entries = [];
+    const visit = (id) => {
+        if (!id || seen.has(id))
+            return;
+        seen.add(id);
+        const record = agents.getAgent(id);
+        if (!record)
+            throw new Error(`Agent not found: ${id}`);
+        const config = configFromAgent(record);
+        config.skills = config.skills.map((skill) => hydratedSkill(skill, installed));
+        entries.push({
+            sourceAgentId: record.id,
+            agent: {
+                name: record.definition.name,
+                description: record.definition.description,
+                driverId: record.definition.driver.id,
+                modelId: record.definition.model?.id || '',
+                modelSettings: record.definition.model?.settings || null,
+            },
+            config,
+        });
+        config.subagents.forEach((subagent) => visit(subagent.agentId));
+    };
+    roots.forEach(visit);
+    return entries;
+}
+function title(entries, external) {
+    const agent = entries[0]?.agent;
+    if (agent)
+        return { title: agent.name || 'Shared agent', description: agent.description || '' };
+    for (const records of [external.automations, external.apps, external.tools]) {
+        const first = records?.[0];
+        const summary = first && typeof first === 'object'
+            ? (first.automation || first.app || first) : null;
+        if (summary)
+            return {
+                title: typeof summary.name === 'string' ? summary.name : 'Shared bundle',
+                description: typeof summary.description === 'string' ? summary.description : '',
+            };
+    }
+    return { title: 'Shared bundle', description: '' };
+}
+// Engine reference: amalgm-mcp/agent-bundles/export.js createBundle.
+export async function createAgentBundle(agents, input, options = {}) {
+    const agentIds = uniqueStrings(input.agentIds);
+    const automationIds = uniqueStrings(input.automationIds);
+    const appIds = uniqueStrings(input.appIds);
+    const requestedToolIds = uniqueStrings(input.toolIds);
+    if (![agentIds, automationIds, appIds, requestedToolIds].some((ids) => ids.length)) {
+        throw new Error('At least one agent, automation, app, or tool is required');
+    }
+    const bundleAgents = collectAgents(agents, agentIds, options.installedSkills || []);
+    const agentToolIds = bundleAgents.flatMap((entry) => entry.config.loadout.toolIds);
+    const needsPort = automationIds.length || appIds.length || requestedToolIds.length || agentToolIds.length;
+    if (needsPort && !options.port)
+        throw new Error('A bundle resource port is required for tools, apps, or automations');
+    const external = options.port ? await options.port.exportResources({
+        automationIds, appIds, toolIds: uniqueStrings([...requestedToolIds, ...agentToolIds]),
+    }) : {};
+    const requires = mergeRequirements(emptyRequirements(), external.requires);
+    for (const entry of bundleAgents) {
+        addUnique(requires.runtimes, entry.agent.driverId);
+        addUnique(requires.auth, entry.agent.driverId);
+    }
+    const tools = (external.tools || []).map((tool) => {
+        if (tool.origin === 'system')
+            addUnique(requires.systemTools, String(tool.id || ''));
+        return scrubSecrets(tool, `tools.${String(tool.id || '')}`, requires);
+    });
+    const toolActions = (external.toolActions || []).map((action) => scrubSecrets(action, `toolActions.${String(action.id || '')}`, requires));
+    if (requires.missingTools.length)
+        throw new Error(`Tool not found: ${requires.missingTools.join(', ')}`);
+    const skills = collectSkillRecords(bundleAgents);
+    const hooks = bundleAgents.reduce((count, entry) => count + entry.config.hooks.length, 0);
+    const warnings = [
+        '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 ? ['This bundle includes executable hook definitions. Review commands before importing.'] : []),
+        ...(tools.length ? ['Tools can call external services or local commands. Reconnect credentials locally.'] : []),
+        ...(external.warnings || []),
+    ];
+    const named = title(bundleAgents, external);
+    const headToolIds = external.headToolIds || requestedToolIds;
+    const heads = [
+        ...agentIds.map((id) => ({ type: 'agent', id })),
+        ...automationIds.map((id) => ({ type: 'automation', id })),
+        ...appIds.map((id) => ({ type: 'app', id })),
+        ...headToolIds.map((id) => ({ type: 'tool', id })),
+    ];
+    const summary = {
+        agents: bundleAgents.length, automations: external.automations?.length || 0,
+        apps: external.apps?.length || 0, tools: tools.length, toolActions: toolActions.length,
+        skills: skills.length, hooks, assets: 0,
+    };
+    const bundle = {
+        kind: BUNDLE_KIND, schemaVersion: BUNDLE_SCHEMA_VERSION,
+        bundleId: options.bundleId || bundleId(), createdAt: options.now?.() || new Date().toISOString(),
+        rootAgentId: agentIds[0] || null, heads, headIds: [], ...named,
+        agents: bundleAgents, automations: external.automations || [], apps: external.apps || [],
+        tools, toolActions, skills, assets: [], requires, warnings, summary, elements: [], edges: [],
+    };
+    Object.assign(bundle, buildBundleGraph(bundle));
+    const bytes = Buffer.byteLength(JSON.stringify(bundle));
+    return { bundle, preview: { bundleId: bundle.bundleId, ...named, summary, requires, warnings, bytes } };
+}

package/dist/bundles/graph-records.d.ts

@@ -0,0 +1,10 @@
+import type { AgentBundle, BundleAgentEntry } from './types.js';
+export declare function agentEntryId(entry: unknown): string;
+export declare function automationEntryId(entry: unknown): string;
+export declare function appEntryId(entry: unknown): string;
+export declare function toolEntryId(entry: unknown): string;
+export declare function actionEntryId(entry: unknown): string;
+export declare function skillFingerprint(skill: unknown): string;
+export declare function skillElementId(skill: unknown): string;
+export declare function skillLabel(skill: unknown): string;
+export declare function collectSkillRecords(agents: BundleAgentEntry[]): AgentBundle['skills'];

package/dist/bundles/graph-records.js

@@ -0,0 +1,61 @@
+import { clean, digest, object } from './util.js';
+export function agentEntryId(entry) {
+    const record = object(entry);
+    return clean(record?.sourceAgentId) || clean(object(record?.agent)?.sourceAgentId);
+}
+export function automationEntryId(entry) {
+    return clean(object(entry)?.sourceAutomationId);
+}
+export function appEntryId(entry) {
+    return clean(object(entry)?.sourceAppId);
+}
+export function toolEntryId(entry) {
+    return clean(object(entry)?.id);
+}
+export function actionEntryId(entry) {
+    return clean(object(entry)?.id);
+}
+export function skillFingerprint(skill) {
+    if (typeof skill === 'string')
+        return clean(skill) ? `string:${clean(skill)}` : '';
+    const record = object(skill);
+    if (!record)
+        return '';
+    if (clean(record.id))
+        return `id:${clean(record.id)}`;
+    if (clean(record.path))
+        return `path:${clean(record.path)}`;
+    const name = clean(record.name);
+    const content = clean(record.content);
+    if (name && content)
+        return `name-content:${name}:${content}`;
+    if (name)
+        return `name:${name}`;
+    if (content)
+        return `content:${content}`;
+    return `json:${JSON.stringify(skill)}`;
+}
+export function skillElementId(skill) {
+    const fingerprint = skillFingerprint(skill);
+    return fingerprint ? `skill:${digest(fingerprint)}` : '';
+}
+export function skillLabel(skill) {
+    if (typeof skill === 'string')
+        return clean(skill) || 'Skill';
+    const record = object(skill);
+    if (!record)
+        return 'Skill';
+    return clean(record.name) || clean(record.path).split('/').filter(Boolean).pop()
+        || clean(record.id) || clean(record.content).slice(0, 60) || 'Skill';
+}
+export function collectSkillRecords(agents) {
+    const records = new Map();
+    for (const entry of agents) {
+        for (const skill of entry.config.skills) {
+            const key = skillFingerprint(skill);
+            if (key && !records.has(key))
+                records.set(key, JSON.parse(JSON.stringify(skill)));
+        }
+    }
+    return [...records.values()];
+}

package/dist/bundles/graph.d.ts

@@ -0,0 +1,6 @@
+import type { AgentBundle, BundleGraphEdge, BundleGraphElement } from './types.js';
+export declare function buildBundleGraph(bundle: AgentBundle): {
+    headIds: string[];
+    elements: BundleGraphElement[];
+    edges: BundleGraphEdge[];
+};

package/dist/bundles/graph.js

@@ -0,0 +1,121 @@
+import { actionEntryId, agentEntryId, appEntryId, automationEntryId, skillElementId, skillLabel, toolEntryId, } from './graph-records.js';
+import { clean, object, uniqueStrings } from './util.js';
+const ORDER = {
+    agent: 0, automation: 1, app: 2, tool: 3, tool_action: 4, skill: 5,
+};
+function elementId(type, id) {
+    return `${type}:${id}`;
+}
+function graphRecords(bundle) {
+    return {
+        agent: new Map(bundle.agents.map((entry) => [agentEntryId(entry), entry])),
+        automation: new Map(bundle.automations.map((entry) => [automationEntryId(entry), entry])),
+        app: new Map(bundle.apps.map((entry) => [appEntryId(entry), entry])),
+        tool: new Map(bundle.tools.map((entry) => [toolEntryId(entry), entry])),
+        tool_action: new Map(bundle.toolActions.map((entry) => [actionEntryId(entry), entry])),
+        skill: new Map(bundle.skills.map((entry) => [skillElementId(entry), entry])),
+    };
+}
+// Engine reference: amalgm-mcp/agent-bundles/graph.js buildFlatAgentBundleGraph.
+export function buildBundleGraph(bundle) {
+    const records = graphRecords(bundle);
+    const elements = new Map();
+    const edges = new Map();
+    const addElement = (type, id, label) => {
+        const key = elementId(type, id);
+        elements.set(key, { id: key, type, label: label || id });
+    };
+    const addEdge = (fromType, fromId, toType, toId, kind) => {
+        const edge = { from: elementId(fromType, fromId), to: elementId(toType, toId), kind };
+        edges.set(`${edge.from}::${kind}::${edge.to}`, edge);
+    };
+    const requireRecord = (type, id, owner) => {
+        if (!records[type].has(id))
+            throw new Error(`${owner} references missing ${type.replace('_', ' ')}: ${id}`);
+    };
+    const addToolSelection = (ownerType, ownerId, selectedId) => {
+        if (records.tool_action.has(selectedId))
+            addEdge(ownerType, ownerId, 'tool_action', selectedId, 'uses-tool-action');
+        else {
+            requireRecord('tool', selectedId, `${ownerType} ${ownerId}`);
+            addEdge(ownerType, ownerId, 'tool', selectedId, 'uses-tool');
+        }
+    };
+    for (const entry of bundle.agents)
+        addElement('agent', agentEntryId(entry), entry.agent.name);
+    for (const entry of bundle.automations) {
+        addElement('automation', automationEntryId(entry), clean(object(entry.automation)?.name));
+    }
+    for (const entry of bundle.apps)
+        addElement('app', appEntryId(entry), clean(object(entry.app)?.name));
+    for (const entry of bundle.tools)
+        addElement('tool', toolEntryId(entry), clean(entry.name));
+    for (const entry of bundle.toolActions)
+        addElement('tool_action', actionEntryId(entry), clean(entry.name));
+    for (const skill of bundle.skills) {
+        const id = skillElementId(skill);
+        elements.set(id, { id, type: 'skill', label: skillLabel(skill) });
+    }
+    for (const entry of bundle.agents) {
+        const id = agentEntryId(entry);
+        for (const subagent of entry.config.subagents) {
+            if (!subagent.agentId)
+                continue;
+            requireRecord('agent', subagent.agentId, `agent ${id}`);
+            addEdge('agent', id, 'agent', subagent.agentId, 'uses-subagent');
+        }
+        for (const selectedId of entry.config.loadout.toolIds)
+            addToolSelection('agent', id, selectedId);
+        for (const skill of entry.config.skills) {
+            const skillId = skillElementId(skill);
+            if (!records.skill.has(skillId))
+                throw new Error(`agent ${id} references missing skill: ${skillLabel(skill)}`);
+            addEdge('agent', id, 'skill', skillId.slice('skill:'.length), 'uses-skill');
+        }
+    }
+    for (const entry of bundle.automations) {
+        const id = automationEntryId(entry);
+        for (const selectedId of uniqueStrings(entry.toolIds))
+            addToolSelection('automation', id, selectedId);
+    }
+    for (const entry of bundle.apps) {
+        const id = appEntryId(entry);
+        for (const toolId of uniqueStrings(entry.toolIds)) {
+            requireRecord('tool', toolId, `app ${id}`);
+            addEdge('app', id, 'tool', toolId, 'provides-tool');
+        }
+    }
+    for (const tool of bundle.tools) {
+        const id = toolEntryId(tool);
+        const appId = clean(tool.appId);
+        if (appId) {
+            requireRecord('app', appId, `tool ${id}`);
+            addEdge('tool', id, 'app', appId, 'requires-app');
+        }
+    }
+    for (const action of bundle.toolActions) {
+        const id = actionEntryId(action);
+        const toolId = clean(action.toolId);
+        requireRecord('tool', toolId, `tool action ${id}`);
+        addEdge('tool', toolId, 'tool_action', id, 'has-action');
+        addEdge('tool_action', id, 'tool', toolId, 'action-of');
+        const appId = clean(action.appId);
+        if (appId) {
+            requireRecord('app', appId, `tool action ${id}`);
+            addEdge('tool_action', id, 'app', appId, 'requires-app');
+        }
+    }
+    const headIds = bundle.heads.map((head) => {
+        const id = elementId(head.type, head.id);
+        if (!elements.has(id))
+            throw new Error(`bundle head references missing element: ${id}`);
+        return id;
+    });
+    return {
+        headIds,
+        elements: [...elements.values()].sort((left, right) => (ORDER[left.type] ?? 99) - (ORDER[right.type] ?? 99)
+            || left.id.localeCompare(right.id)),
+        edges: [...edges.values()].sort((left, right) => left.from.localeCompare(right.from)
+            || left.kind.localeCompare(right.kind) || left.to.localeCompare(right.to)),
+    };
+}

package/dist/bundles/install.d.ts

@@ -0,0 +1,6 @@
+import type { Agents } from '../agents.js';
+import type { AgentBundlePort, BundleInstallResult } from './types.js';
+export declare function installAgentBundle(agents: Agents, input: unknown, options?: {
+    port?: AgentBundlePort;
+    authRef?: string;
+}): Promise<BundleInstallResult>;

package/dist/bundles/install.js

@@ -0,0 +1,64 @@
+import crypto from 'node:crypto';
+import { normalizeAgentConfig } from '../config/schema.js';
+import { updateAgentConfig } from '../config/store.js';
+import { validateAgentBundle } from './validate.js';
+function uniqueName(agents, value) {
+    const base = value.trim() || 'Imported agent';
+    const names = new Set(agents.listAgents().map((item) => item.definition.name.toLowerCase()));
+    if (!names.has(base.toLowerCase()))
+        return base;
+    if (!names.has(`${base} (imported)`.toLowerCase()))
+        return `${base} (imported)`;
+    for (let index = 2; index < 1000; index += 1) {
+        const candidate = `${base} (imported ${index})`;
+        if (!names.has(candidate.toLowerCase()))
+            return candidate;
+    }
+    return `${base} (${crypto.randomUUID().slice(0, 8)})`;
+}
+// Engine reference: amalgm-mcp/agent-bundles/install.js installBundleAgents.
+export async function installAgentBundle(agents, input, options = {}) {
+    const bundle = validateAgentBundle(input);
+    const hasExternal = bundle.automations.length || bundle.apps.length || bundle.tools.length;
+    if (hasExternal && !options.port)
+        throw new Error('A bundle resource port is required to install external resources');
+    const external = options.port ? await options.port.installResources(bundle) : {};
+    const idMap = new Map();
+    const created = [];
+    for (const entry of bundle.agents) {
+        const agent = agents.createAgent({
+            id: `imported-${crypto.randomUUID()}`,
+            name: uniqueName(agents, entry.agent.name),
+            description: entry.agent.description,
+            driver: { id: entry.agent.driverId, config: {} },
+            model: entry.agent.modelId ? { id: entry.agent.modelId, settings: entry.agent.modelSettings || {} } : null,
+            authRef: options.authRef || null,
+            instructions: entry.config.instructions,
+            resources: { files: [], skills: [], subagents: [] },
+            toolbox: { toolIds: entry.config.loadout.toolIds, actionIds: [] },
+            metadata: { installedFromBundle: bundle.bundleId },
+        });
+        idMap.set(entry.sourceAgentId, agent.id);
+        created.push({ sourceId: entry.sourceAgentId, agent, config: entry.config });
+    }
+    const installedAgents = created.map(({ agent, config }) => {
+        const rewritten = normalizeAgentConfig({
+            ...config,
+            agentId: agent.id,
+            subagents: config.subagents.map((subagent) => ({
+                ...subagent,
+                agentId: idMap.get(subagent.agentId) || '',
+            })).filter((subagent) => subagent.agentId),
+        });
+        return updateAgentConfig(agents, agent.id, rewritten).agent;
+    });
+    return {
+        ok: true,
+        bundleId: bundle.bundleId,
+        rootAgentId: bundle.rootAgentId ? idMap.get(bundle.rootAgentId) || null : installedAgents[0]?.id || null,
+        idMap: Object.fromEntries(idMap),
+        installedAgents,
+        ...external,
+        warnings: [...(bundle.warnings || []), ...(external.warnings || [])],
+    };
+}

package/dist/bundles/types.d.ts

@@ -0,0 +1,97 @@
+import type { AgentConfig } from '../config/types.js';
+import type { AgentRecord, JsonObject } from '../types.js';
+export type BundleHeadType = 'agent' | 'automation' | 'app' | 'tool';
+export interface BundleHead {
+    type: BundleHeadType;
+    id: string;
+}
+export interface BundleAgentEntry {
+    sourceAgentId: string;
+    agent: {
+        name: string;
+        description: string;
+        driverId: string;
+        modelId: string;
+        modelSettings: JsonObject | null;
+    };
+    config: AgentConfig;
+}
+export interface BundleGraphElement {
+    id: string;
+    type: string;
+    label: string;
+}
+export interface BundleGraphEdge {
+    from: string;
+    to: string;
+    kind: string;
+}
+export interface BundleRequirements {
+    runtimes: string[];
+    auth: string[];
+    secrets: string[];
+    bindings: string[];
+    systemTools: string[];
+    systemActions: string[];
+    missingTools: string[];
+}
+export interface AgentBundle {
+    kind: 'amalgm.bundle';
+    schemaVersion: 2;
+    bundleId: string;
+    createdAt: string;
+    rootAgentId: string | null;
+    heads: BundleHead[];
+    headIds: string[];
+    title: string;
+    description: string;
+    agents: BundleAgentEntry[];
+    automations: JsonObject[];
+    apps: JsonObject[];
+    tools: JsonObject[];
+    toolActions: JsonObject[];
+    skills: JsonObject[];
+    assets: JsonObject[];
+    requires: BundleRequirements;
+    warnings: string[];
+    summary: JsonObject;
+    elements: BundleGraphElement[];
+    edges: BundleGraphEdge[];
+}
+export interface BundleExternalExport {
+    headToolIds?: string[];
+    automations?: JsonObject[];
+    apps?: JsonObject[];
+    tools?: JsonObject[];
+    toolActions?: JsonObject[];
+    requires?: Partial<BundleRequirements>;
+    warnings?: string[];
+}
+export interface BundleExternalInstall {
+    installedAutomations?: JsonObject[];
+    installedApps?: JsonObject[];
+    installedTools?: JsonObject[];
+    warnings?: string[];
+}
+export interface AgentBundlePort {
+    exportResources(input: {
+        automationIds: string[];
+        appIds: string[];
+        toolIds: string[];
+    }): Promise<BundleExternalExport> | BundleExternalExport;
+    installResources(bundle: AgentBundle): Promise<BundleExternalInstall> | BundleExternalInstall;
+}
+export interface BundleCreateInput {
+    agentIds?: string[];
+    automationIds?: string[];
+    appIds?: string[];
+    toolIds?: string[];
+}
+export interface BundleInstallResult extends BundleExternalInstall {
+    ok: true;
+    bundleId: string;
+    rootAgentId: string | null;
+    idMap: Record<string, string>;
+    installedAgents: AgentRecord[];
+    warnings: string[];
+}

package/dist/bundles/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bundles/util.d.ts

@@ -0,0 +1,14 @@
+import type { JsonObject, JsonValue } from '../types.js';
+import type { BundleRequirements } from './types.js';
+export declare const BUNDLE_KIND: "amalgm.bundle";
+export declare const BUNDLE_SCHEMA_VERSION: 2;
+export declare function clean(value: unknown): string;
+export declare function object(value: unknown): JsonObject | null;
+export declare function clone<T>(value: T): T;
+export declare function uniqueStrings(value: unknown): string[];
+export declare function addUnique(target: string[], value: string): void;
+export declare function bundleId(): string;
+export declare function digest(value: unknown): string;
+export declare function emptyRequirements(): BundleRequirements;
+export declare function mergeRequirements(target: BundleRequirements, incoming?: Partial<BundleRequirements>): BundleRequirements;
+export declare function scrubSecrets(value: JsonValue, path: string, requires: BundleRequirements): JsonValue;

package/dist/bundles/util.js

@@ -0,0 +1,56 @@
+import crypto from 'node:crypto';
+export const BUNDLE_KIND = 'amalgm.bundle';
+export const BUNDLE_SCHEMA_VERSION = 2;
+export function clean(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+export function object(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+export function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function uniqueStrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map(clean).filter(Boolean))];
+}
+export function addUnique(target, value) {
+    if (value && !target.includes(value))
+        target.push(value);
+}
+export function bundleId() {
+    return `agent-bundle-${crypto.randomUUID()}`;
+}
+export function digest(value) {
+    return crypto.createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value))
+        .digest('hex').slice(0, 16);
+}
+export function emptyRequirements() {
+    return { runtimes: [], auth: [], secrets: [], bindings: [], systemTools: [],
+        systemActions: [], missingTools: [] };
+}
+export function mergeRequirements(target, incoming = {}) {
+    for (const key of Object.keys(target)) {
+        for (const value of incoming[key] || [])
+            addUnique(target[key], value);
+    }
+    return target;
+}
+const SECRET = /(api[_-]?key|authorization|bearer|cookie|password|passwd|secret|token|credential|private[_-]?key)/i;
+export function scrubSecrets(value, path, requires) {
+    if (Array.isArray(value))
+        return value.map((item, index) => scrubSecrets(item, `${path}[${index}]`, requires));
+    const record = object(value);
+    if (!record)
+        return value;
+    const output = {};
+    for (const [key, child] of Object.entries(record)) {
+        const childPath = path ? `${path}.${key}` : key;
+        if (SECRET.test(key))
+            addUnique(requires.secrets, childPath);
+        else
+            output[key] = scrubSecrets(child, childPath, requires);
+    }
+    return output;
+}

package/dist/bundles/validate.d.ts

@@ -0,0 +1,2 @@
+import type { AgentBundle } from './types.js';
+export declare function validateAgentBundle(input: unknown): AgentBundle;

package/dist/bundles/validate.js

@@ -0,0 +1,92 @@
+import { actionEntryId, agentEntryId, appEntryId, automationEntryId, skillFingerprint, toolEntryId } from './graph-records.js';
+import { buildBundleGraph } from './graph.js';
+import { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION, clean, object } from './util.js';
+function unique(label, records, identify) {
+    const seen = new Set();
+    for (const record of records) {
+        const id = identify(record);
+        if (!id)
+            throw new Error(`${label} entries must include ids`);
+        if (seen.has(id))
+            throw new Error(`Bundle contains duplicate ${label} id: ${id}`);
+        seen.add(id);
+    }
+}
+function assertClosed(bundle) {
+    const elements = new Set();
+    for (const element of bundle.elements) {
+        if (!clean(element.id) || !clean(element.type))
+            throw new Error('bundle graph elements must include id and type');
+        if (object(element)?.data !== undefined)
+            throw new Error(`bundle graph element must not copy data: ${element.id}`);
+        if (elements.has(element.id))
+            throw new Error(`bundle graph contains duplicate element id: ${element.id}`);
+        elements.add(element.id);
+    }
+    const outgoing = new Map();
+    const edgeKeys = new Set();
+    for (const edge of bundle.edges) {
+        if (!elements.has(edge.from) || !elements.has(edge.to))
+            throw new Error('bundle graph edge references missing element');
+        const key = `${edge.from}::${edge.kind}::${edge.to}`;
+        if (edgeKeys.has(key))
+            throw new Error(`bundle graph contains duplicate edge: ${key}`);
+        edgeKeys.add(key);
+        outgoing.set(edge.from, [...(outgoing.get(edge.from) || []), edge.to]);
+    }
+    const reachable = new Set();
+    const pending = [...bundle.headIds];
+    while (pending.length) {
+        const id = pending.pop();
+        if (reachable.has(id))
+            continue;
+        reachable.add(id);
+        pending.push(...(outgoing.get(id) || []));
+    }
+    const unreachable = [...elements].filter((id) => !reachable.has(id));
+    if (unreachable.length)
+        throw new Error(`bundle graph contains unreachable elements: ${unreachable.join(', ')}`);
+}
+// Engine reference: amalgm-mcp/agent-bundles/install.js validateBundle.
+export function validateAgentBundle(input) {
+    const raw = object(input);
+    if (!raw)
+        throw new Error('bundle must be an object');
+    if (raw.kind !== BUNDLE_KIND)
+        throw new Error(`Unsupported bundle kind: ${clean(raw.kind) || 'unknown'}`);
+    if (raw.schemaVersion !== BUNDLE_SCHEMA_VERSION) {
+        throw new Error(`Unsupported bundle schema version: ${String(raw.schemaVersion || 'unknown')}`);
+    }
+    const bundle = input;
+    const arrays = ['agents', 'automations', 'apps', 'tools', 'toolActions', 'skills', 'heads'];
+    if (arrays.some((key) => !Array.isArray(bundle[key])))
+        throw new Error('bundle canonical records must be arrays');
+    if (!bundle.heads.length)
+        throw new Error('bundle must include at least one head');
+    unique('agent', bundle.agents, agentEntryId);
+    unique('automation', bundle.automations, automationEntryId);
+    unique('app', bundle.apps, appEntryId);
+    unique('tool', bundle.tools, toolEntryId);
+    unique('tool action', bundle.toolActions, actionEntryId);
+    unique('skill', bundle.skills, skillFingerprint);
+    unique('head', bundle.heads, (value) => {
+        const head = object(value);
+        return ['agent', 'automation', 'app', 'tool'].includes(clean(head?.type))
+            ? `${clean(head?.type)}:${clean(head?.id)}` : '';
+    });
+    if (bundle.requires?.missingTools?.length) {
+        throw new Error(`Bundle is missing tools: ${bundle.requires.missingTools.join(', ')}`);
+    }
+    const expected = buildBundleGraph(bundle);
+    const expectedRoot = bundle.heads.find((head) => head.type === 'agent')?.id || null;
+    if (bundle.rootAgentId !== expectedRoot) {
+        throw new Error('bundle rootAgentId does not match its canonical records and connections');
+    }
+    for (const key of ['headIds', 'elements', 'edges']) {
+        if (JSON.stringify(bundle[key]) !== JSON.stringify(expected[key])) {
+            throw new Error(`bundle ${key} does not match its canonical records and connections`);
+        }
+    }
+    assertClosed(bundle);
+    return bundle;
+}

package/dist/http/bundle-routes.d.ts

@@ -0,0 +1,2 @@
+import type { RouteContext } from '../http-types.js';
+export declare function routeAgentBundles(context: RouteContext): Promise<boolean>;

package/dist/http/bundle-routes.js

@@ -0,0 +1,67 @@
+import { createAgentBundle } from '../bundles/create.js';
+import { installAgentBundle } from '../bundles/install.js';
+import { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from '../bundles/util.js';
+import { scanInstalledSkills } from '../skills/scanner.js';
+function ids(...values) {
+    const result = [];
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            result.push(value.trim());
+        if (Array.isArray(value))
+            value.forEach((item) => {
+                if (typeof item === 'string' && item.trim())
+                    result.push(item.trim());
+            });
+    }
+    return [...new Set(result)];
+}
+export async function routeAgentBundles(context) {
+    const [resource, action, child] = context.path;
+    if (resource !== 'agent-bundles')
+        return false;
+    if (!action && context.method === 'GET') {
+        context.json(200, {
+            kind: BUNDLE_KIND,
+            schemaVersion: BUNDLE_SCHEMA_VERSION,
+            available: { agents: context.agents.listAgents().map((agent) => ({
+                    id: agent.id, name: agent.definition.name, description: agent.definition.description,
+                })) },
+        });
+        return true;
+    }
+    if (child || context.method !== 'POST')
+        return false;
+    const body = await context.body();
+    try {
+        if (action === 'preview') {
+            const installedSkills = scanInstalledSkills({ ...context.skillRoots, includeContent: true }).skills;
+            const result = await createAgentBundle(context.agents, {
+                agentIds: ids(body.agent_id, body.agent_ids),
+                automationIds: ids(body.automation_id, body.automation_ids),
+                appIds: ids(body.app_id, body.app_ids),
+                toolIds: ids(body.tool_id, body.tool_ids),
+            }, { ...(context.bundlePort ? { port: context.bundlePort } : {}), installedSkills });
+            context.json(200, { ok: true, ...result });
+            return true;
+        }
+        if (action === 'install') {
+            if (!body.bundle) {
+                context.json(400, { error: 'bundle is required' });
+                return true;
+            }
+            const authRef = typeof body.auth_ref === 'string' ? body.auth_ref
+                : typeof body.authMethod === 'string' ? body.authMethod : undefined;
+            const result = await installAgentBundle(context.agents, body.bundle, {
+                ...(context.bundlePort ? { port: context.bundlePort } : {}),
+                ...(authRef ? { authRef } : {}),
+            });
+            context.json(200, result);
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        context.json(400, { error: error instanceof Error ? error.message : 'Bundle operation failed' });
+        return true;
+    }
+}

package/dist/http/server.js

@@ -2,6 +2,7 @@ import http from 'node:http';
 import { Agents } from '../agents.js';
 import { asAgentError } from '../errors.js';
 import { routeAgentConfig } from './config-routes.js';
+import { routeAgentBundles } from './bundle-routes.js';
 import { routeAgents } from './agent-routes.js';
 import { guardRequest, readJson, sendJson } from './request.js';
 import { routeSessions } from './session-routes.js';
@@ -46,10 +47,11 @@ export function createRestServer(options = {}) {
             url,
             skillRoots: options.skillRoots || {},
             ...(options.nativeHomeDir ? { nativeHomeDir: options.nativeHomeDir } : {}),
+            ...(options.bundlePort ? { bundlePort: options.bundlePort } : {}),
             body: () => readJson(request, bodyLimit),
             json: (status, value) => sendJson(response, status, value),
         };
-        if (await routeAgentConfig(context) || await routeSkills(context))
+        if (await routeAgentBundles(context) || await routeAgentConfig(context) || await routeSkills(context))
             return;
         if (path.shift() !== 'v1') {
             sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });

package/dist/http-types.d.ts

@@ -3,12 +3,14 @@ import type { AddressInfo } from 'node:net';
 import type { Agents } from './agents.js';
 import type { AgentsOptions } from './types.js';
 import type { SkillRootOptions } from './skills/roots.js';
+import type { AgentBundlePort } from './bundles/types.js';
 export interface RestServerOptions extends AgentsOptions {
     agents?: Agents;
     token?: string;
     bodyLimitBytes?: number;
     skillRoots?: SkillRootOptions;
     nativeHomeDir?: string;
+    bundlePort?: AgentBundlePort;
 }
 export interface RestServer {
     agents: Agents;
@@ -23,6 +25,7 @@ export interface RouteContext {
     url: URL;
     skillRoots: SkillRootOptions;
     nativeHomeDir?: string;
+    bundlePort?: AgentBundlePort;
     body(): Promise<Record<string, unknown>>;
     json(status: number, value: unknown): void;
 }

package/dist/index.d.ts

@@ -13,3 +13,10 @@ export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/s
 export { importAgentConfig } from './config/import.js';
 export { importNativeConfig } from './config/native.js';
 export type * from './config/types.js';
+export { createAgentBundle } from './bundles/create.js';
+export type { CreateBundleOptions } from './bundles/create.js';
+export { installAgentBundle } from './bundles/install.js';
+export { buildBundleGraph } from './bundles/graph.js';
+export { validateAgentBundle } from './bundles/validate.js';
+export { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from './bundles/util.js';
+export type * from './bundles/types.js';

package/dist/index.js

@@ -9,3 +9,8 @@ export { normalizeAgentConfig, stableConfigId } from './config/schema.js';
 export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/store.js';
 export { importAgentConfig } from './config/import.js';
 export { importNativeConfig } from './config/native.js';
+export { createAgentBundle } from './bundles/create.js';
+export { installAgentBundle } from './bundles/install.js';
+export { buildBundleGraph } from './bundles/graph.js';
+export { validateAgentBundle } from './bundles/validate.js';
+export { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from './bundles/util.js';

package/dist/mcp/server.js

@@ -16,7 +16,7 @@ export function createMcpServer(options = {}) {
             return {
                 protocolVersion: message.params?.protocolVersion || '2024-11-05',
                 capabilities: { tools: { listChanged: false } },
-                serverInfo: { name: 'amalgm-agents', version: '0.1.2' },
+                serverInfo: { name: 'amalgm-agents', version: '0.1.3' },
             };
         }
         if (message.method === 'ping')

package/docs/ENGINE_INTEGRATION.md

@@ -18,9 +18,9 @@ that domain.
 | credential adapter | `authRef` resolver inside drivers |
 | Supabase Chat session creation | Chat/cloud adapter observing Agents events |
 
-Agent bundles currently mix agents, apps, automations, and tool bindings. That
-cross-product packaging concern should remain outside this repository. A bundle
-installer may call each product's public apply method.
+Agent bundle-v2 graph and agent install laws live here. Engine supplies the
+`AgentBundlePort` that exports and installs apps, automations, and tools through
+their public SDKs; neither side imports another product's store.
 
 ## Required driver adapter
 

package/docs/REST.md

@@ -23,6 +23,18 @@ Set `nativeHomeDir` when embedding the server or `--native-home`/
 `AMALGM_NATIVE_HOME` with the REST binary. Native import intentionally ignores
 auth files, secrets, and MCP server configuration.
 
+## Agent bundles
+
+| Method | Path | Result |
+|---|---|---|
+| `GET` | `/agent-bundles` | Read bundle-v2 capability and available agent heads |
+| `POST` | `/agent-bundles/preview` | Export requested agent/app/automation/tool heads |
+| `POST` | `/agent-bundles/install` | Validate and install `{ bundle, auth_ref? }` |
+
+Embedding hosts inject `bundlePort` for resources owned by Apps, Automations,
+and Toolbox. Agent-only bundles need no port. Bundles with external resources
+fail explicitly when the owner port is absent.
+
 ## Agents
 
 | Method | Path | Result |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local-first agent definitions, immutable revisions, and durable sessions.",
   "license": "UNLICENSED",
   "private": false,