@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.0

package/dist/esm/registries/metaplex-bridge.js

@@ -0,0 +1,706 @@
+/**
+ * @module registries/metaplex-bridge
+ * @description Bridge between Synapse Agent Protocol (SAP) and Metaplex
+ * Core's `AgentIdentity` external plugin adapter (mpl-core ≥ 1.9.0).
+ *
+ * ## Why this design (verified against mpl-core PR #258, v1.9.0)
+ *
+ * The MPL Core `AgentIdentity` plugin has exactly one field:
+ *
+ * ```ts
+ * type AgentIdentity = { uri: string };
+ * ```
+ *
+ * The URI must point to an **EIP-8004** agent registration JSON. There is
+ * no on-chain executive list, no `addExecutive` / `delegateExecutionV1`
+ * instruction. Capabilities, services, executives, and reputation live
+ * off-chain in that JSON. The plugin only hooks the `Execute` lifecycle
+ * event, allowing the URI's authority to gate execution.
+ *
+ * The most efficient SAP × MPL integration therefore is:
+ *
+ *   1. SAP serves a **live EIP-8004 JSON** at a deterministic URL derived
+ *      from the SAP `AgentAccount` PDA (e.g.
+ *      `https://explorer.oobeprotocol.ai/agents/<sapAgentPda>/eip-8004.json`).
+ *   2. The MPL Core asset attaches an `AgentIdentity` adapter whose `uri`
+ *      points to that URL.
+ *   3. Every SAP write (capability change, vault delegate add/revoke, x402
+ *      tier update) is reflected in the JSON automatically — **no second
+ *      transaction required, on either chain or for any wallet.**
+ *
+ * One SAP transaction = both protocols updated. That is the efficiency
+ * win that motivated the Phase 1 redesign on 2026-04-22.
+ *
+ * @category Registries
+ * @since v0.9.0
+ * @see https://github.com/metaplex-foundation/mpl-core/pull/258
+ * @see https://eips.ethereum.org/EIPS/eip-8004
+ */
+import { PublicKey, } from "@solana/web3.js";
+import { deriveAgent, deriveAgentStats, deriveVault } from "../pda";
+// ═══════════════════════════════════════════════════════════════════
+//  Lazy peer-dep loader
+// ═══════════════════════════════════════════════════════════════════
+const PEER_DEP_INSTALL_HINT = "MetaplexBridge requires @metaplex-foundation/mpl-core (>=1.9.0) and " +
+    "@metaplex-foundation/umi-bundle-defaults. " +
+    "Install: npm i @metaplex-foundation/mpl-core @metaplex-foundation/umi-bundle-defaults";
+let cachedRuntime = null;
+async function loadMplCore() {
+    if (cachedRuntime)
+        return cachedRuntime;
+    try {
+        const [mplCore, umiBundle, umiCore] = await Promise.all([
+            import("@metaplex-foundation/mpl-core"),
+            import("@metaplex-foundation/umi-bundle-defaults"),
+            import("@metaplex-foundation/umi"),
+        ]);
+        cachedRuntime = { mplCore, umiBundle, umiCore };
+        return cachedRuntime;
+    }
+    catch (cause) {
+        throw Object.assign(new Error(PEER_DEP_INSTALL_HINT), { cause });
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  MetaplexBridge
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name MetaplexBridge
+ * @description Read-side merger and write-side instruction composer for
+ * SAP × Metaplex Core `AgentIdentity` integration.
+ *
+ * Linking is **single-transaction**: the MPL `addExternalPluginAdapterV1`
+ * instruction sets a URI that points at SAP's live registration host.
+ * Subsequent SAP state changes propagate automatically — no extra MPL
+ * transaction required.
+ *
+ * @category Registries
+ * @since v0.9.0
+ */
+export class MetaplexBridge {
+    program;
+    constructor(program) {
+        this.program = program;
+    }
+    // ─────────────────────────────────────────────────────
+    //  Pure helpers
+    // ─────────────────────────────────────────────────────
+    /**
+     * @name deriveRegistrationUrl
+     * @description Compute the deterministic EIP-8004 registration URL for
+     * a SAP agent. Hosts MUST serve the JSON at exactly this path so that
+     * {@link MetaplexBridge.verifyLink} validates without external config.
+     *
+     * @since v0.9.0
+     */
+    deriveRegistrationUrl(sapAgentPda, baseUrl) {
+        const trimmed = baseUrl.replace(/\/+$/, "");
+        return `${trimmed}/agents/${sapAgentPda.toBase58()}/eip-8004.json`;
+    }
+    /**
+     * @name buildEip8004Registration
+     * @description Build a canonical EIP-8004 JSON document for a SAP agent.
+     * Designed to be called server-side by a registry host.
+     *
+     * @since v0.9.0
+     */
+    async buildEip8004Registration(args) {
+        const [sapPda] = deriveAgent(args.sapAgentOwner);
+        const identity = await this.fetchAgentNullable(sapPda);
+        if (!identity) {
+            throw new Error(`buildEip8004Registration: SAP agent not found for owner ${args.sapAgentOwner.toBase58()}`);
+        }
+        const delegates = await this.fetchActiveVaultDelegates(sapPda);
+        return {
+            version: "0.1",
+            name: this.readString(identity, "name") ?? "Synapse Agent",
+            description: this.readString(identity, "description") ?? undefined,
+            synapseAgent: sapPda.toBase58(),
+            authority: args.sapAgentOwner.toBase58(),
+            capabilities: this.readCapabilities(identity),
+            services: args.services ?? [],
+            executives: delegates,
+            updatedAt: new Date().toISOString(),
+            extra: args.extra,
+        };
+    }
+    // ─────────────────────────────────────────────────────
+    //  Write side — build MPL instructions only
+    // ─────────────────────────────────────────────────────
+    /**
+     * @name buildAttachAgentIdentityIx
+     * @description Build the MPL Core `addExternalPluginAdapterV1`
+     * `TransactionInstruction` that attaches an `AgentIdentity` plugin
+     * pointing at SAP's live EIP-8004 registration URL.
+     *
+     * @since v0.9.0
+     */
+    async buildAttachAgentIdentityIx(opts) {
+        const [sapPda] = deriveAgent(opts.sapAgentOwner);
+        const uri = this.deriveRegistrationUrl(sapPda, opts.registrationBaseUrl);
+        return this.buildAddExternalPluginIx({
+            asset: opts.asset,
+            authority: opts.authority,
+            payer: opts.payer ?? opts.authority,
+            uri,
+            rpcUrl: opts.rpcUrl,
+        });
+    }
+    /**
+     * @name buildUpdateAgentIdentityUriIx
+     * @description Build the MPL Core `updateExternalPluginAdapterV1`
+     * instruction that re-points an existing `AgentIdentity` plugin.
+     *
+     * @since v0.9.0
+     */
+    async buildUpdateAgentIdentityUriIx(opts) {
+        const { mplCore, umiBundle, umiCore } = await loadMplCore();
+        const umi = umiBundle.createUmi(opts.rpcUrl).use(mplCore.mplCore());
+        const authority = umiCore.createNoopSigner(umiCore.publicKey(opts.authority.toBase58()));
+        const payer = umiCore.createNoopSigner(umiCore.publicKey((opts.payer ?? opts.authority).toBase58()));
+        const builder = mplCore.updateExternalPluginAdapterV1(umi, {
+            asset: umiCore.publicKey(opts.asset.toBase58()),
+            authority,
+            payer,
+            key: { __kind: "AgentIdentity" },
+            updateInfo: {
+                __kind: "AgentIdentity",
+                fields: [
+                    {
+                        uri: opts.newUri,
+                        lifecycleChecks: null,
+                    },
+                ],
+            },
+        });
+        return this.firstWeb3Ix(builder, "updateExternalPluginAdapterV1");
+    }
+    // ─────────────────────────────────────────────────────
+    //  Write side — combined SAP × MPL register flows (v0.9.3)
+    // ─────────────────────────────────────────────────────
+    /**
+     * @name buildMintAndAttachIxs
+     * @description Build the two MPL Core instructions needed to mint a new
+     * asset for an existing SAP agent and immediately bind it via the
+     * `AgentIdentity` plugin (URI = canonical EIP-8004 URL).
+     *
+     * Flow:
+     *   1. Generate a fresh asset keypair (returned as `assetSecretKey`).
+     *   2. Build `mpl_core::create` with the new asset as signer.
+     *   3. Build `addExternalPluginAdapterV1` for the AgentIdentity URI.
+     *
+     * The returned `instructions` are deterministic order. The caller
+     * partial-signs the assembled transaction with `assetSecretKey` and the
+     * authority/payer wallet.
+     *
+     * @since v0.9.3
+     */
+    async buildMintAndAttachIxs(opts) {
+        const { mplCore, umiBundle, umiCore } = await loadMplCore();
+        const umi = umiBundle.createUmi(opts.rpcUrl).use(mplCore.mplCore());
+        const [sapPda] = deriveAgent(opts.sapAgentOwner);
+        const registrationUrl = this.deriveRegistrationUrl(sapPda, opts.registrationBaseUrl);
+        const assetUmiSigner = umiCore.generateSigner(umi);
+        const assetAddress = new PublicKey(assetUmiSigner.publicKey.toString());
+        const assetSecretKey = assetUmiSigner.secretKey;
+        const authority = umiCore.createNoopSigner(umiCore.publicKey(opts.authority.toBase58()));
+        const payer = umiCore.createNoopSigner(umiCore.publicKey((opts.payer ?? opts.authority).toBase58()));
+        const ownerUmi = opts.owner
+            ? umiCore.publicKey(opts.owner.toBase58())
+            : umiCore.publicKey(opts.authority.toBase58());
+        const createBuilder = mplCore.create(umi, {
+            asset: assetUmiSigner,
+            collection: opts.collection
+                ? { publicKey: umiCore.publicKey(opts.collection.toBase58()) }
+                : undefined,
+            authority,
+            payer,
+            owner: ownerUmi,
+            name: opts.name,
+            uri: opts.metadataUri,
+        });
+        const mintIx = await this.firstWeb3Ix(createBuilder, "mpl_core::create");
+        const attachIx = await this.buildAddExternalPluginIx({
+            asset: assetAddress,
+            authority: opts.authority,
+            payer: opts.payer ?? opts.authority,
+            uri: registrationUrl,
+            rpcUrl: opts.rpcUrl,
+        });
+        return {
+            assetAddress,
+            assetSecretKey,
+            registrationUrl,
+            instructions: [mintIx, attachIx],
+        };
+    }
+    /**
+     * @name buildRegisterSapForMplOwnerIx
+     * @description Given an existing MPL Core asset, resolve its on-chain
+     * owner and build the SAP `registerAgent` instruction the owner must
+     * sign. Idempotent: if a SAP agent already exists for that owner the
+     * method returns `instruction: null` with `alreadyRegistered: true`.
+     *
+     * Use after a wallet has minted (or holds) an MPL Core agent NFT and
+     * wants to back-fill a SAP identity at the canonical PDA so the bridge's
+     * EIP-8004 URL becomes resolvable.
+     *
+     * @since v0.9.3
+     */
+    async buildRegisterSapForMplOwnerIx(opts) {
+        const snap = await this.fetchMplSnapshot(opts.asset, opts.rpcUrl);
+        if (!snap) {
+            throw new Error(`buildRegisterSapForMplOwnerIx: MPL Core asset ${opts.asset.toBase58()} not readable`);
+        }
+        const [sapPda] = deriveAgent(snap.owner);
+        const existing = await this.fetchAgentNullable(sapPda);
+        if (existing) {
+            return {
+                assetOwner: snap.owner,
+                sapAgentPda: sapPda,
+                alreadyRegistered: true,
+                currentAgentIdentityUri: snap.agentIdentityUri,
+                instruction: null,
+            };
+        }
+        const ix = await this.buildRegisterAgentIx({
+            wallet: snap.owner,
+            args: opts.registerArgs,
+        });
+        return {
+            assetOwner: snap.owner,
+            sapAgentPda: sapPda,
+            alreadyRegistered: false,
+            currentAgentIdentityUri: snap.agentIdentityUri,
+            instruction: ix,
+        };
+    }
+    /**
+     * @name buildRegisterBothIxs
+     * @description Atomic 3-instruction bundle for a wallet that owns
+     * neither side: `[SAP registerAgent, MPL Core create, MPL AgentIdentity attach]`.
+     * Single transaction, single user signature (plus the ephemeral asset
+     * keypair returned in `assetSecretKey`).
+     *
+     * Throws if a SAP agent already exists for `wallet` — callers should
+     * fall through to {@link MetaplexBridge.buildMintAndAttachIxs} instead.
+     *
+     * @since v0.9.3
+     */
+    async buildRegisterBothIxs(opts) {
+        const [sapPda] = deriveAgent(opts.wallet);
+        const existing = await this.fetchAgentNullable(sapPda);
+        if (existing) {
+            throw new Error(`buildRegisterBothIxs: SAP agent already exists at ${sapPda.toBase58()}; ` +
+                `use buildMintAndAttachIxs instead`);
+        }
+        const sapIx = await this.buildRegisterAgentIx({
+            wallet: opts.wallet,
+            args: opts.registerArgs,
+        });
+        const mint = await this.buildMintAndAttachIxs({
+            sapAgentOwner: opts.wallet,
+            authority: opts.wallet,
+            payer: opts.payer ?? opts.wallet,
+            owner: opts.wallet,
+            name: opts.mintName,
+            metadataUri: opts.mintMetadataUri,
+            registrationBaseUrl: opts.registrationBaseUrl,
+            rpcUrl: opts.rpcUrl,
+            collection: opts.collection,
+        });
+        return {
+            sapAgentPda: sapPda,
+            assetAddress: mint.assetAddress,
+            assetSecretKey: mint.assetSecretKey,
+            registrationUrl: mint.registrationUrl,
+            instructions: [sapIx, ...mint.instructions],
+        };
+    }
+    // ─────────────────────────────────────────────────────
+    //  Read side
+    // ─────────────────────────────────────────────────────
+    /**
+     * @name getUnifiedProfile
+     * @description Fetch a merged view of an agent across SAP and Metaplex.
+     * Provide `wallet` (SAP-first) or `asset` (MPL-first), or both.
+     *
+     * @since v0.9.0
+     */
+    async getUnifiedProfile(input) {
+        if (!input.wallet && !input.asset) {
+            throw new Error("getUnifiedProfile: provide `wallet` or `asset`");
+        }
+        let sapPda = null;
+        let identity = null;
+        let stats = null;
+        if (input.wallet) {
+            [sapPda] = deriveAgent(input.wallet);
+            identity = await this.fetchAgentNullable(sapPda);
+            stats = await this.fetchStatsNullable(sapPda);
+        }
+        let mpl = null;
+        if (input.asset) {
+            mpl = await this.fetchMplSnapshot(input.asset, input.rpcUrl, input.rpcHeaders);
+            if (!sapPda && mpl?.registration?.synapseAgent) {
+                try {
+                    sapPda = new PublicKey(mpl.registration.synapseAgent);
+                    identity = await this.fetchAgentNullable(sapPda);
+                    stats = await this.fetchStatsNullable(sapPda);
+                }
+                catch {
+                    /* invalid PDA in JSON */
+                }
+            }
+        }
+        if (!sapPda) {
+            throw new Error("getUnifiedProfile: failed to resolve SAP agent PDA");
+        }
+        return {
+            sap: { pda: sapPda, identity, stats },
+            mpl,
+            linked: this.detectLink(sapPda, mpl),
+        };
+    }
+    /**
+     * @name resolveAgentIdentifier
+     * @description Resolve a generic agent identifier to canonical SAP routing
+     * keys. Useful when callers may receive either owner wallets or Metaplex
+     * Core asset IDs (e.g. metaplex.com/agents/<core-asset-id>).
+     *
+     * Resolution order:
+     *   1) Treat input as wallet and check if a SAP agent exists.
+     *   2) If not found, treat input as MPL Core asset and resolve owner wallet.
+     *
+     * @since v0.9.2
+     */
+    async resolveAgentIdentifier(input) {
+        let asPubkey;
+        try {
+            asPubkey = new PublicKey(input.identifier);
+        }
+        catch {
+            return {
+                input: input.identifier,
+                kind: "unknown",
+                wallet: null,
+                sapAgentPda: null,
+                asset: null,
+                hasSapAgent: false,
+                error: "Invalid public key",
+            };
+        }
+        // 1) Wallet-first resolution (SAP-native)
+        const [walletSapPda] = deriveAgent(asPubkey);
+        const walletIdentity = await this.fetchAgentNullable(walletSapPda);
+        if (walletIdentity) {
+            return {
+                input: input.identifier,
+                kind: "wallet",
+                wallet: asPubkey,
+                sapAgentPda: walletSapPda,
+                asset: null,
+                hasSapAgent: true,
+                error: null,
+            };
+        }
+        // 2) MPL Core asset resolution
+        const mpl = await this.fetchMplSnapshot(asPubkey, input.rpcUrl, input.rpcHeaders);
+        if (!mpl) {
+            return {
+                input: input.identifier,
+                kind: "unknown",
+                wallet: null,
+                sapAgentPda: null,
+                asset: null,
+                hasSapAgent: false,
+                error: "Not a SAP wallet and not a readable MPL Core asset",
+            };
+        }
+        const [sapPdaFromOwner] = deriveAgent(mpl.owner);
+        const ownerIdentity = await this.fetchAgentNullable(sapPdaFromOwner);
+        return {
+            input: input.identifier,
+            kind: "core-asset",
+            wallet: mpl.owner,
+            sapAgentPda: sapPdaFromOwner,
+            asset: asPubkey,
+            hasSapAgent: !!ownerIdentity,
+            error: ownerIdentity ? null : "Core asset owner has no SAP agent profile",
+        };
+    }
+    /**
+     * @name verifyLink
+     * @description Verify the bidirectional link between an MPL Core asset
+     * and a SAP agent. Returns `true` only when both URL and JSON sides
+     * reference the SAP agent PDA.
+     *
+     * @since v0.9.0
+     */
+    async verifyLink(args) {
+        const snap = await this.fetchMplSnapshot(args.asset, args.rpcUrl, args.rpcHeaders);
+        if (!snap?.agentIdentityUri || !snap.registration)
+            return false;
+        const expectedSuffix = `/agents/${args.sapAgentPda.toBase58()}/eip-8004.json`;
+        if (!snap.agentIdentityUri.endsWith(expectedSuffix))
+            return false;
+        return snap.registration.synapseAgent === args.sapAgentPda.toBase58();
+    }
+    /**
+     * @name tripleCheckLink
+     * @description Explicit 3-layer verification for explorer/host badges.
+     * Returns one struct enumerating each check independently so UIs can
+     * present partial trust states (e.g. "MPL plugin present, JSON pending").
+     *
+     * Layers:
+     *   1. **mplOnChain** — Asset + AgentIdentity URI fetched on-chain.
+     *   2. **eip8004Json** — JSON fetched and `synapseAgent` matches PDA.
+     *   3. **sapOnChain** — `AgentAccount` PDA exists on the SAP program.
+     *
+     * @since v0.9.3
+     */
+    async tripleCheckLink(args) {
+        const snap = await this.fetchMplSnapshot(args.asset, args.rpcUrl, args.rpcHeaders);
+        if (!snap) {
+            const fallbackPda = args.expectedOwner
+                ? deriveAgent(args.expectedOwner)[0]
+                : args.asset;
+            return {
+                asset: args.asset,
+                sapAgentPda: fallbackPda,
+                mplOnChain: false,
+                eip8004Json: false,
+                sapOnChain: false,
+                linked: false,
+                agentIdentityUri: null,
+                registration: null,
+                identity: null,
+                error: "MPL Core asset not readable on-chain",
+            };
+        }
+        const owner = args.expectedOwner ?? snap.owner;
+        const [sapPda] = deriveAgent(owner);
+        const expectedSuffix = `/agents/${sapPda.toBase58()}/eip-8004.json`;
+        const mplOnChain = !!snap.agentIdentityUri;
+        const eip8004Json = !!snap.registration &&
+            !!snap.agentIdentityUri &&
+            snap.agentIdentityUri.endsWith(expectedSuffix) &&
+            snap.registration.synapseAgent === sapPda.toBase58();
+        const identity = await this.fetchAgentNullable(sapPda);
+        const sapOnChain = !!identity;
+        return {
+            asset: args.asset,
+            sapAgentPda: sapPda,
+            mplOnChain,
+            eip8004Json,
+            sapOnChain,
+            linked: mplOnChain && eip8004Json && sapOnChain,
+            agentIdentityUri: snap.agentIdentityUri,
+            registration: snap.registration,
+            identity,
+            error: null,
+        };
+    }
+    // ═════════════════════════════════════════════════════
+    //  Private — SAP fetching
+    // ═════════════════════════════════════════════════════
+    get accounts() {
+        return this.program.account;
+    }
+    async fetchAgentNullable(pda) {
+        try {
+            return await this.accounts.agentAccount.fetch(pda);
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchStatsNullable(agentPda) {
+        try {
+            const [statsPda] = deriveAgentStats(agentPda);
+            return await this.accounts.agentStats.fetch(statsPda);
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchActiveVaultDelegates(agentPda) {
+        try {
+            const [vaultPda] = deriveVault(agentPda);
+            // VaultDelegate layout: [discriminator(8) | bump(1) | vault(32) | ...]
+            const all = await this.accounts.vaultDelegate.all([
+                { memcmp: { offset: 8 + 1, bytes: vaultPda.toBase58() } },
+            ]);
+            const now = Math.floor(Date.now() / 1000);
+            return all
+                .map(({ account }) => {
+                const expiresRaw = account.expiresAt.toString();
+                const expiresAt = expiresRaw === "0" ? null : expiresRaw;
+                return { wallet: account.delegate.toBase58(), expiresAt };
+            })
+                .filter((d) => d.expiresAt === null || Number(d.expiresAt) > now);
+        }
+        catch {
+            return [];
+        }
+    }
+    // ═════════════════════════════════════════════════════
+    //  Private — MPL fetching
+    // ═════════════════════════════════════════════════════
+    async buildUmi(rpcUrl, rpcHeaders) {
+        const { mplCore, umiBundle } = await loadMplCore();
+        // umi-bundle-defaults.createUmi accepts an options object with httpHeaders
+        // since umi 1.x — required for gated providers like Synapse RPC that
+        // enforce `x-api-key`. Without it `getAccountInfo` returns 401 silently.
+        const umi = umiBundle.createUmi(rpcUrl, rpcHeaders ? { httpHeaders: rpcHeaders } : undefined).use(mplCore.mplCore());
+        return umi;
+    }
+    async fetchMplSnapshot(asset, rpcUrl, rpcHeaders) {
+        const { mplCore, umiCore } = await loadMplCore();
+        const umi = await this.buildUmi(rpcUrl, rpcHeaders);
+        try {
+            const fetched = await mplCore.fetchAsset(umi, umiCore.publicKey(asset.toBase58()));
+            const owner = new PublicKey(fetched.owner.toString());
+            const uri = this.extractAgentIdentityUri(fetched);
+            const registration = uri ? await this.fetchEip8004Safe(uri) : null;
+            return {
+                asset,
+                owner,
+                name: fetched.name ?? null,
+                agentIdentityUri: uri,
+                registration,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    extractAgentIdentityUri(asset) {
+        const adapters = asset.agentIdentities;
+        if (!adapters || adapters.length === 0)
+            return null;
+        const first = adapters[0];
+        if (!first)
+            return null;
+        return typeof first.uri === "string" ? first.uri : null;
+    }
+    async fetchEip8004Safe(uri) {
+        try {
+            const res = await fetch(uri, { method: "GET" });
+            if (!res.ok)
+                return null;
+            const json = (await res.json());
+            if (typeof json.synapseAgent !== "string" ||
+                typeof json.authority !== "string") {
+                return null;
+            }
+            return {
+                version: json.version ?? "0.1",
+                name: json.name ?? "",
+                description: json.description,
+                synapseAgent: json.synapseAgent,
+                authority: json.authority,
+                capabilities: Array.isArray(json.capabilities) ? json.capabilities : [],
+                services: Array.isArray(json.services) ? json.services : [],
+                executives: Array.isArray(json.executives) ? json.executives : [],
+                updatedAt: json.updatedAt ?? "",
+                extra: json.extra,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // ═════════════════════════════════════════════════════
+    //  Private — MPL instruction building
+    // ═════════════════════════════════════════════════════
+    async buildAddExternalPluginIx(args) {
+        const { mplCore, umiBundle, umiCore } = await loadMplCore();
+        const umi = umiBundle.createUmi(args.rpcUrl).use(mplCore.mplCore());
+        const authority = umiCore.createNoopSigner(umiCore.publicKey(args.authority.toBase58()));
+        const payer = umiCore.createNoopSigner(umiCore.publicKey(args.payer.toBase58()));
+        // HookableLifecycleEvent.Execute = 4; ExternalCheckResult { flags: 1 } = CanApprove
+        const ExecuteEvent = mplCore.HookableLifecycleEvent.Execute;
+        const builder = mplCore.addExternalPluginAdapterV1(umi, {
+            asset: umiCore.publicKey(args.asset.toBase58()),
+            authority,
+            payer,
+            initInfo: {
+                __kind: "AgentIdentity",
+                fields: [
+                    {
+                        uri: args.uri,
+                        initPluginAuthority: { __kind: "UpdateAuthority" },
+                        lifecycleChecks: [[ExecuteEvent, { flags: 1 }]],
+                    },
+                ],
+            },
+        });
+        return this.firstWeb3Ix(builder, "addExternalPluginAdapterV1");
+    }
+    // ═════════════════════════════════════════════════════
+    //  Private — SAP instruction building (v0.9.3)
+    // ═════════════════════════════════════════════════════
+    async buildRegisterAgentIx(args) {
+        // Lazy import to avoid a hard cycle with `pda/index.ts`.
+        const { deriveGlobalRegistry } = await import("../pda");
+        const { SystemProgram } = await import("@solana/web3.js");
+        const [agentPda] = deriveAgent(args.wallet);
+        const [statsPda] = deriveAgentStats(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        const a = args.args;
+        // Cast to `any` to sidestep Anchor's deep generic IDL inference, which
+        // otherwise blows TS recursion budget here. Same pattern as BaseModule.
+        const methods = this.program.methods;
+        return await methods
+            .registerAgent(a.name, a.description, a.capabilities, a.pricing, a.protocols, a.agentId ?? null, a.agentUri ?? null, a.x402Endpoint ?? null)
+            .accounts({
+            wallet: args.wallet,
+            agent: agentPda,
+            agentStats: statsPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .instruction();
+    }
+    async firstWeb3Ix(builder, name) {
+        const items = builder.getInstructions();
+        const first = items[0];
+        if (!first) {
+            throw new Error(`MetaplexBridge: ${name} produced no instructions`);
+        }
+        return this.umiIxToWeb3(first);
+    }
+    umiIxToWeb3(ix) {
+        return {
+            programId: new PublicKey(ix.programId.toString()),
+            keys: ix.keys.map((k) => ({
+                pubkey: new PublicKey(k.pubkey.toString()),
+                isSigner: k.isSigner,
+                isWritable: k.isWritable,
+            })),
+            data: Buffer.from(ix.data),
+        };
+    }
+    // ═════════════════════════════════════════════════════
+    //  Private — link detection + duck-typed readers
+    // ═════════════════════════════════════════════════════
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    detectLink(sapPda, mpl) {
+        if (!mpl?.agentIdentityUri || !mpl.registration)
+            return false;
+        const expectedSuffix = `/agents/${sapPda.toBase58()}/eip-8004.json`;
+        if (!mpl.agentIdentityUri.endsWith(expectedSuffix))
+            return false;
+        return mpl.registration.synapseAgent === sapPda.toBase58();
+    }
+    readString(identity, key) {
+        const value = identity[key];
+        return typeof value === "string" ? value : null;
+    }
+    readCapabilities(identity) {
+        const caps = identity.capabilities ?? [];
+        return caps.map((c) => c.id).filter((s) => typeof s === "string");
+    }
+}
+//# sourceMappingURL=metaplex-bridge.js.map