@amalgm/agents 0.1.2 → 0.2.0

package/PURPOSE.md

@@ -2,50 +2,57 @@
 
 ## Purpose
 
-Amalgm Agents is the small, standalone product for defining agents and talking
-to them. A user can create, inspect, edit, and delete an agent, then start or
-continue a durable session with it through the SDK, CLI, REST, or MCP. Agents
-are not chats: Chat may present a session, but the agent definition and session
-remain usable without Chat or Amalgm Engine.
-
-Engine composes Agents with harnesses, credentials, Toolbox, files, Realtime,
-and UI. This package stores references to those products and delegates
-execution to an injected driver; it does not duplicate their state.
+Amalgm Agents is the small, standalone registry for agent identities,
+installations, and immutable revisions. A user or another agent can create,
+register, install, list, inspect, edit, and delete an available agent, then
+resolve one exact revision for execution by Chat.
+
+Shell composes Agents with Chat, harnesses, credentials, Toolbox, files, Live,
+and UI. This package stores references to those products; it does not duplicate
+their state or execute a conversation.
 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
 
 - An **agent** is a stable identity with a complete current definition.
-- A **session** is a durable conversation with one agent definition.
-- A **turn** is one accepted input and its driver result.
-- A **driver** runs the agent using a host-provided harness.
+- An **installation** is one locally available agent identity and its Agent
+  Home descriptor.
+- A **resolved agent** is one exact immutable revision selected for execution.
 - The **Agents service** is the behavior shared by every public surface.
 
 ## Axioms
 
 1. A user can create, list, inspect, edit, and delete agents.
-2. A user or another agent can start, inspect, and continue an agent session
-   without creating or depending on a Chat conversation.
+2. A user or another agent can resolve an available agent to one exact
+   immutable revision without starting a conversation.
 3. An agent definition can reference its harness, model, instructions, tools,
    skills, files, credentials, and subagents without Agents owning those
    products.
-4. Any compatible agent harness can be used through the same driver contract.
-5. Agent definitions and sessions survive restart, while uncertain interrupted
-   execution is never silently replayed.
+4. Harness identity is part of an agent revision; provider execution belongs
+   to Chat behind a host runtime port.
+5. Agent definitions, installations, and revisions survive restart.
 6. SDK, CLI, REST, MCP, and skill workflows expose the same Agents behavior;
    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.
+The package needs no conversation, turn, transcript, stream, reconnect,
+interrupt, cloud command inbox, scheduler, trigger relay, or general
+event-routing system. Shell and other hosts resolve Agents revisions while
+preparing a Chat execution. Bundle ports call Apps, Automations, and Toolbox
+public APIs; Agents never imports their stores or duplicates their lifecycle
+behavior.
+
+There is no execution subsystem in Agents. Chat is the single owner of every
+conversation and turn.

package/README.md

@@ -1,12 +1,12 @@
 # Amalgm Agents
 
 `@amalgm/agents` is a local-first TypeScript SDK for persistent agent
-definitions and durable multi-turn sessions. The same service powers its CLI,
-REST API, and MCP server.
+identities, installations, and immutable revisions. The same registry powers
+its CLI, REST API, and MCP server.
 
-It is intentionally not Chat. Chat may present an agent session, but Agents
-owns the agent definition, the pinned execution revision, turns, and ordered
-events.
+It is intentionally not Chat. Agents resolves the exact installed revision;
+`@amalgm/chat` owns the durable conversation, turns, stream, reconnect, and
+interrupt lifecycle that executes it.
 
 ## Install
 
@@ -19,25 +19,9 @@ Node 20 or newer is required.
 ## First agent
 
 ```ts
-import { Agents, defineDriver } from '@amalgm/agents';
-
-const echo = defineDriver({
-  id: 'echo',
-  async run(request) {
-    const text = request.input.parts
-      .filter((part) => part.type === 'text')
-      .map((part) => part.text)
-      .join('');
-    return {
-      message: {
-        role: 'assistant',
-        parts: [{ type: 'text', text: `Received: ${text}` }],
-      },
-    };
-  },
-});
+import { Agents } from '@amalgm/agents';
 
-const agents = new Agents({ stateDir: './state', drivers: [echo] });
+const agents = new Agents({ stateDir: './state' });
 
 agents.createAgent({
   id: 'reviewer',
@@ -47,28 +31,22 @@ agents.createAgent({
   toolbox: { toolIds: ['git'], actionIds: ['git.diff'] },
 });
 
-const session = agents.startSession({ agentId: 'reviewer' });
-const turn = await agents.send(session.id, {
-  message: 'Review the current diff.',
-  idempotencyKey: 'review-001',
-});
-
-console.log(turn.status);
-console.log(agents.listEvents(session.id));
-await agents.close();
+const revision = agents.getAgentRevision('reviewer');
+console.log(revision.id, revision.definition.driver.id);
+agents.close();
 ```
 
-An agent definition is normalized into a complete immutable revision. A
-session stays pinned to that revision even after the agent is edited.
+An agent definition is normalized into a complete immutable revision. Chat
+records the resolved revision id in every prepared execution.
 
 ## Product surfaces
 
 | Surface | Entry point | Purpose |
 |---|---|---|
-| SDK | `@amalgm/agents` | Embed the canonical service and supply drivers |
-| CLI | `amalgm-agents` | Manage definitions and sessions |
-| REST | `@amalgm/agents/http`, `amalgm-agents-rest` | Local HTTP and SSE integration |
-| MCP | `@amalgm/agents/mcp`, `amalgm-agents-mcp` | Agent CRUD and agent-to-agent calls |
+| SDK | `@amalgm/agents` | Embed the canonical registry and resolve revisions |
+| CLI | `amalgm-agents` | Manage agent identities and installations |
+| REST | `@amalgm/agents/http`, `amalgm-agents-rest` | Local registry integration |
+| MCP | `@amalgm/agents/mcp`, `amalgm-agents-mcp` | Agent registry tools |
 | Skill | `skills/amalgm-agents` | Minimal workflow over the Agents tools |
 
 Installed skills are available from the REST surface without introducing a
@@ -100,18 +78,31 @@ 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
 amalgm-agents agent create ./agent.json
 amalgm-agents agent list
-amalgm-agents session start reviewer
-amalgm-agents session send <session-id> "Review the diff"
-amalgm-agents talk reviewer "Review the diff"
 ```
 
-The CLI reads the same SQLite database as the SDK. Driver modules are loaded
-with `--drivers ./dist/codex-driver.js` or `AMALGM_AGENT_DRIVERS`.
+The CLI reads the same SQLite registry as the SDK.
 
 ## Documentation
 
@@ -119,11 +110,10 @@ with `--drivers ./dist/codex-driver.js` or `AMALGM_AGENT_DRIVERS`.
 - [Architecture and boundaries](./docs/ARCHITECTURE.md)
 - [Agent definitions](./docs/DEFINITIONS.md)
 - [SDK reference](./docs/SDK.md)
-- [Driver contract](./docs/DRIVERS.md)
 - [CLI reference](./docs/CLI.md)
 - [REST API](./docs/REST.md)
 - [MCP server](./docs/MCP.md)
-- [Persistence and recovery](./docs/DATA_MODEL.md)
+- [Persistence](./docs/DATA_MODEL.md)
 - [Security model](./docs/SECURITY.md)
 - [Engine integration](./docs/ENGINE_INTEGRATION.md)
 
@@ -136,4 +126,4 @@ npm run verify
 
 `verify` runs strict typechecking for source, tests, and examples; enforces the
 220-line source-file limit; builds JavaScript and declarations; and runs the
-real SQLite, process-restart, TCP/SSE, stdio MCP, and CLI tests.
+real SQLite, TCP, stdio MCP, and CLI tests.

package/dist/agents.d.ts

@@ -1,14 +1,8 @@
-import type { AgentDefinitionInput, AgentDriver, AgentPatch, AgentRecord, AgentSession, AgentsOptions, AgentTurn, EnqueuedTurn, EventListener, JsonObject, SendInput, SessionEvent, StartSessionInput } from './types.js';
+import type { AgentDefinitionInput, AgentPatch, AgentRecord, AgentRevision, AgentsOptions, JsonObject } from './types.js';
 export declare class Agents {
     readonly databasePath: string;
-    readonly recoveredTurns: number;
     private readonly opened;
     private readonly agentStore;
-    private readonly eventStore;
-    private readonly sessionStore;
-    private readonly turnStore;
-    private readonly runtime;
-    private readonly listeners;
     private closed;
     constructor(options?: AgentsOptions);
     createAgent(input: AgentDefinitionInput): AgentRecord;
@@ -16,24 +10,8 @@ export declare class Agents {
     deleteAgent(id: string): AgentRecord;
     getAgent(id: string, includeDeleted?: boolean): AgentRecord | null;
     listAgents(includeDeleted?: boolean): AgentRecord[];
-    startSession(input: StartSessionInput): AgentSession;
-    getSession(id: string): AgentSession | null;
-    listSessions(agentId?: string, includeArchived?: boolean): AgentSession[];
-    archiveSession(id: string): AgentSession;
-    enqueue(id: string, input: SendInput): EnqueuedTurn;
-    send(id: string, input: SendInput): Promise<AgentTurn>;
-    talk(agentId: string, input: SendInput & {
-        sessionId?: string;
-    }): EnqueuedTurn & {
-        session: AgentSession;
-    };
-    cancelSession(id: string): AgentTurn;
-    listTurns(sessionId: string): AgentTurn[];
-    listEvents(sessionId: string, after?: number, limit?: number): SessionEvent[];
-    registerDriver(driver: AgentDriver): void;
-    driverIds(): string[];
-    subscribe(sessionId: string, listener: EventListener): () => void;
+    /** Resolve one exact immutable revision for a host such as Chat. */
+    getAgentRevision(agentId: string, revisionId?: string): AgentRevision;
     health(): JsonObject;
-    close(): Promise<void>;
-    private publish;
+    close(): void;
 }

package/dist/agents.js

@@ -1,36 +1,16 @@
 import path from 'node:path';
 import { AgentStore } from './agent-store.js';
 import { openDatabase } from './database.js';
-import { EventStore } from './event-store.js';
-import { AgentError } from './errors.js';
-import { AgentRuntime } from './runtime.js';
-import { SessionStore } from './session-store.js';
-import { TurnStore } from './turn-store.js';
 export class Agents {
     databasePath;
-    recoveredTurns;
     opened;
     agentStore;
-    eventStore;
-    sessionStore;
-    turnStore;
-    runtime;
-    listeners = new Map();
     closed = false;
     constructor(options = {}) {
         this.opened = openDatabase(options);
         this.databasePath = this.opened.databasePath;
         const now = options.now || (() => new Date().toISOString());
-        this.eventStore = new EventStore(this.opened.database, now, (event) => this.publish(event));
         this.agentStore = new AgentStore(this.opened.database, now);
-        this.sessionStore = new SessionStore(this.opened.database, this.eventStore, now);
-        this.turnStore = new TurnStore(this.opened.database, this.sessionStore, this.eventStore, now);
-        this.recoveredTurns = this.turnStore.recoverInterrupted();
-        this.runtime = new AgentRuntime(this.agentStore, this.sessionStore, this.turnStore, this.eventStore, {
-            maxInputBytes: options.maxInputBytes || 256_000,
-            maxEventBytes: options.maxEventBytes || 256_000,
-            turnTimeoutMs: options.turnTimeoutMs ?? 600_000,
-        }, options.drivers);
     }
     createAgent(input) {
         return this.agentStore.create(input);
@@ -47,83 +27,20 @@ export class Agents {
     listAgents(includeDeleted = false) {
         return this.agentStore.list(includeDeleted);
     }
-    startSession(input) {
-        const agent = this.agentStore.require(input.agentId);
-        const revision = this.agentStore.revision(agent.id, input.revisionId);
-        return this.sessionStore.create(revision, input.sessionId, input.metadata || {});
-    }
-    getSession(id) {
-        return this.sessionStore.get(id);
-    }
-    listSessions(agentId, includeArchived = false) {
-        return this.sessionStore.list(agentId, includeArchived);
-    }
-    archiveSession(id) {
-        return this.sessionStore.archive(id, Boolean(this.turnStore.active(id)));
-    }
-    enqueue(id, input) {
-        this.sessionStore.require(id);
-        return this.runtime.enqueue(id, input);
-    }
-    send(id, input) {
-        this.sessionStore.require(id);
-        return this.runtime.send(id, input);
-    }
-    talk(agentId, input) {
-        const session = input.sessionId
-            ? this.sessionStore.require(input.sessionId)
-            : this.startSession({ agentId });
-        if (session.agentId !== agentId) {
-            throw new AgentError('conflict', `Session ${session.id} belongs to agent ${session.agentId}.`);
-        }
-        return { session, ...this.enqueue(session.id, input) };
-    }
-    cancelSession(id) {
-        this.sessionStore.require(id);
-        return this.runtime.cancel(id);
-    }
-    listTurns(sessionId) {
-        return this.turnStore.list(sessionId);
-    }
-    listEvents(sessionId, after = 0, limit = 200) {
-        this.sessionStore.require(sessionId);
-        return this.eventStore.list(sessionId, after, limit);
-    }
-    registerDriver(driver) {
-        this.runtime.register(driver);
-    }
-    driverIds() {
-        return this.runtime.driverIds();
-    }
-    subscribe(sessionId, listener) {
-        this.sessionStore.require(sessionId);
-        const listeners = this.listeners.get(sessionId) || new Set();
-        listeners.add(listener);
-        this.listeners.set(sessionId, listeners);
-        return () => {
-            listeners.delete(listener);
-            if (listeners.size === 0)
-                this.listeners.delete(sessionId);
-        };
+    /** Resolve one exact immutable revision for a host such as Chat. */
+    getAgentRevision(agentId, revisionId) {
+        return this.agentStore.revision(agentId, revisionId);
     }
     health() {
         return {
             ok: !this.closed,
             database: path.basename(this.databasePath),
-            recoveredTurns: this.recoveredTurns,
-            drivers: this.driverIds(),
         };
     }
-    async close() {
+    close() {
         if (this.closed)
             return;
         this.closed = true;
-        await this.runtime.shutdown();
-        this.listeners.clear();
         this.opened.close();
     }
-    publish(event) {
-        for (const listener of this.listeners.get(event.sessionId) || [])
-            listener(event);
-    }
 }

package/dist/bin/mcp.js

@@ -6,7 +6,7 @@ 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-mcp [--state-dir <path>] [--drivers <a.js,b.js>]\n');
+        process.stdout.write('Usage: amalgm-agents-mcp [--state-dir <path>]\n');
         return;
     }
     const agents = await openAgents(args);

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[];
+};