@amalgm/agents 0.1.1 → 0.1.3

package/PURPOSE.md

@@ -13,6 +13,10 @@ and UI. This package stores references to those products and delegates
 execution to an injected driver; it does not duplicate their state.
 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
 
@@ -37,11 +41,17 @@ harness roots so every transport presents the same available skill catalog.
    none is a second implementation.
 7. An unchanged current definition is idempotent; every actual change creates
    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

@@ -83,6 +83,40 @@ The scanner reads the same canonical project, shared, Codex, Claude Code, and
 OpenCode roots as Engine. Hosts inject `skillRoots` when they need a selected
 project or an isolated home.
 
+Rich harness configuration remains part of the agent's immutable definition:
+
+```ts
+import { updateAgentConfig } from '@amalgm/agents';
+
+const { config } = updateAgentConfig(agents, 'reviewer', {
+  instructions: 'Review against the measured contract.',
+  skills: [{ name: 'parity', content: 'Run the parity meter.' }],
+  hooks: [{ event: 'Stop', type: 'command', command: 'npm test' }],
+});
+```
+
+The REST adapter also serves `/agent-config`, `/agent-config/get`,
+`/agent-config/update`, and `/agent-config/import-native`. Native import reads
+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/bin/rest.js

@@ -6,12 +6,17 @@ import { fatal } from './fatal.js';
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.flags.has('help')) {
-        process.stdout.write('Usage: amalgm-agents-rest [--host 127.0.0.1] [--port 4317] [--token value]\n');
+        process.stdout.write('Usage: amalgm-agents-rest [--host 127.0.0.1] [--port 4317] [--token value] [--native-home dir]\n');
         return;
     }
     const agents = await openAgents(args);
     const token = flag(args, 'token') || process.env.AMALGM_AGENTS_TOKEN;
-    const rest = createRestServer({ agents, ...(token ? { token } : {}) });
+    const nativeHomeDir = flag(args, 'native-home') || process.env.AMALGM_NATIVE_HOME;
+    const rest = createRestServer({
+        agents,
+        ...(token ? { token } : {}),
+        ...(nativeHomeDir ? { nativeHomeDir } : {}),
+    });
     const address = await rest.listen(Number(flag(args, 'port') || 4317), flag(args, 'host') || '127.0.0.1');
     process.stderr.write(`amalgm-agents REST listening on http://${address.address}:${address.port}\n`);
     const close = () => void rest.close().then(() => agents.close()).catch(fatal);

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;