@nodiusxyz/solana-agent-kit 0.0.0-stage → 0.1.1

package/dist/internal/v2-policy.js

@@ -0,0 +1,168 @@
+import { PublicKey, TransactionMessage, ComputeBudgetProgram, SystemProgram, } from "@solana/web3.js";
+const PUMP = new PublicKey("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P");
+const FEE = new PublicKey("pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ");
+const ATA = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+const TOKEN = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+const TOKEN22 = new PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+const WSOL = new PublicKey("So11111111111111111111111111111111111111112");
+const SYSTEM = SystemProgram.programId;
+const pda = (program, seed, ...keys) => PublicKey.findProgramAddressSync([Buffer.from(seed), ...keys.map((k) => k.toBuffer())], program)[0];
+const ata = (owner, mint, token) => PublicKey.findProgramAddressSync([owner.toBuffer(), token.toBuffer(), mint.toBuffer()], ATA)[0];
+function requirePolicy(ok, reason) {
+    if (!ok)
+        throw new Error("V2 policy: " + reason);
+}
+/** Offline instruction policy only. Never signs, mutates or fetches account state. */
+export function verifyV2(tx, wallet, p) {
+    requirePolicy(p.side === "buy" || p.side === "sell", "unknown side");
+    requirePolicy(p.maxPriority >= 0n && p.maxSol >= 0n, "negative budget");
+    const m = tx.message;
+    requirePolicy(m.version === 0 && m.addressTableLookups.length === 0, "requires v0 without ALTs");
+    requirePolicy(m.header.numRequiredSignatures === 1 &&
+        m.staticAccountKeys[0]?.equals(wallet) &&
+        m.isAccountWritable(0), "payer/signer mismatch");
+    requirePolicy(tx.signatures.length <= 1 &&
+        tx.signatures.every((s) => s.length === 64 && s.every((b) => b === 0)), "must be unsigned");
+    // Account for the one 64-byte signing placeholder even when builder omits it.
+    requirePolicy(1 + 64 + m.serialize().length <= 1232, "signed envelope exceeds packet size");
+    const instructions = TransactionMessage.decompile(m).instructions;
+    const buy = p.side === "buy";
+    requirePolicy(buy
+        ? instructions.length === 8
+        : instructions.length === 3 || instructions.length === 4, "unexpected instruction sequence");
+    let price = 0n, limit = 0n;
+    for (let i = 0; i < 2; i++) {
+        const ix = instructions[i], d = Buffer.from(ix.data);
+        requirePolicy(ix.programId.equals(ComputeBudgetProgram.programId) &&
+            ix.keys.length === 0, "compute program/accounts");
+        if (i === 0) {
+            requirePolicy(d.length === 9 && d[0] === 3, "canonical compute price required first");
+            price = d.readBigUInt64LE(1);
+            requirePolicy(price <= p.maxPriority, "CU price exceeds explicit cap");
+        }
+        else {
+            requirePolicy((d.length === 5 || d.length === 9) && d[0] === 2, "canonical compute limit required second");
+            requirePolicy(d.length === 5 || d.readUInt32LE(5) === 0, "legacy CU high bytes nonzero");
+            limit = BigInt(d.readUInt32LE(1));
+            requirePolicy(limit >= 1n && limit <= 1400000n, "CU limit outside runtime bounds");
+        }
+    }
+    if (p.requestedPriority !== undefined)
+        requirePolicy(price === p.requestedPriority, "priority price differs from explicit request");
+    if (p.maxPriorityLamports !== undefined)
+        requirePolicy(p.maxPriorityLamports >= 0n &&
+            (price * limit + 999999n) / 1000000n <= p.maxPriorityLamports, "total priority fee exceeds lamport cap");
+    const trade = instructions[buy ? 7 : 2], d = Buffer.from(trade.data);
+    requirePolicy(trade.programId.equals(PUMP) && trade.keys.length === (buy ? 27 : 26), "one Pump trade layout required");
+    requirePolicy(d.length === 24 &&
+        d
+            .subarray(0, 8)
+            .equals(Buffer.from(buy ? "b817ee6167c5d33d" : "5df6823ce7e940b2", "hex")), "trade discriminator/payload");
+    const quantity = d.readBigUInt64LE(8), bound = d.readBigUInt64LE(16);
+    requirePolicy(quantity > 0n && bound > 0n && bound === p.reportedCost, "zero or reported trade bound mismatch");
+    if (buy)
+        requirePolicy(quantity === p.tokensOut && bound <= p.maxSol, "buy tokensOut/trade cap mismatch");
+    else
+        requirePolicy(quantity === p.amountRaw, "sell exact raw quantity mismatch");
+    const k = trade.keys;
+    const baseToken = k[3].pubkey;
+    requirePolicy(baseToken.equals(TOKEN) || baseToken.equals(TOKEN22), "unsupported base token program");
+    const curve = pda(PUMP, "bonding-curve", p.mint), userVolume = pda(PUMP, "user_volume_accumulator", wallet);
+    const baseAta = ata(wallet, p.mint, baseToken), wsolAta = ata(wallet, WSOL, TOKEN);
+    const volumeIndex = buy ? 20 : 19, feeIndex = buy ? 22 : 21;
+    const expected = new Map([
+        [0, pda(PUMP, "global")],
+        [1, p.mint],
+        [2, WSOL],
+        [3, baseToken],
+        [4, TOKEN],
+        [5, ATA],
+        [7, ata(k[6].pubkey, WSOL, TOKEN)],
+        [9, ata(k[8].pubkey, WSOL, TOKEN)],
+        [10, curve],
+        [11, ata(curve, p.mint, baseToken)],
+        [12, ata(curve, WSOL, TOKEN)],
+        [13, wallet],
+        [14, baseAta],
+        [15, wsolAta],
+        [17, ata(k[16].pubkey, WSOL, TOKEN)],
+        [18, pda(FEE, "sharing-config", p.mint)],
+        [volumeIndex, userVolume],
+        [volumeIndex + 1, ata(userVolume, WSOL, TOKEN)],
+        // Source execute_snipe.rs: ["fee_config", pump_program_id] under pfee.
+        [feeIndex, pda(FEE, "fee_config", PUMP)],
+        [feeIndex + 1, FEE],
+        [feeIndex + 2, SYSTEM],
+        [feeIndex + 3, pda(PUMP, "__event_authority")],
+        [feeIndex + 4, PUMP],
+    ]);
+    if (buy)
+        expected.set(19, pda(PUMP, "global_volume_accumulator"));
+    for (const [i, address] of expected)
+        requirePolicy(k[i].pubkey.equals(address), "trade account/PDA mismatch at " + i);
+    const readonly = new Set([
+        0,
+        1,
+        2,
+        3,
+        4,
+        5,
+        18,
+        feeIndex,
+        feeIndex + 1,
+        feeIndex + 2,
+        feeIndex + 3,
+        feeIndex + 4,
+    ]);
+    k.forEach((key, i) => requirePolicy(key.isSigner === (i === 13) && key.isWritable === !readonly.has(i), "trade privilege mismatch at " + i));
+    // Privileges are message-global: wallet aliases in ATA/close authority positions
+    // are also writable signers. Exact comparison rejects elevation of fixed programs.
+    function keys(ix, addresses, writable, signer) {
+        requirePolicy(ix.keys.length === addresses.length &&
+            ix.keys.every((key, i) => key.pubkey.equals(addresses[i]) &&
+                key.isWritable === writable[i] &&
+                key.isSigner === signer[i]), "auxiliary accounts/privileges");
+    }
+    function create(ix, mint, token, address) {
+        requirePolicy(ix.programId.equals(ATA) && ix.data.length === 1 && ix.data[0] === 1, "idempotent ATA required");
+        keys(ix, [wallet, address, wallet, mint, SYSTEM, token], [true, true, true, false, false, false], [true, false, true, false, false, false]);
+    }
+    function close(ix, token, address) {
+        requirePolicy(ix.programId.equals(token) && ix.data.length === 1 && ix.data[0] === 9, "exact token close required");
+        keys(ix, [address, wallet, wallet], [true, true, true], [false, true, true]);
+    }
+    if (buy) {
+        // This current server order was simulated successfully; closing after buy is
+        // NOT equivalent in that test. This order is not a funding-lock proof.
+        create(instructions[2], WSOL, TOKEN, wsolAta);
+        const transfer = instructions[3], td = Buffer.from(transfer.data);
+        requirePolicy(transfer.programId.equals(SYSTEM) &&
+            td.length === 12 &&
+            td.readUInt32LE(0) === 2, "exact System transfer required");
+        keys(transfer, [wallet, wsolAta], [true, true], [true, false]);
+        requirePolicy(td.readBigUInt64LE(4) <= bound, "funding exceeds decoded buy bound");
+        const sync = instructions[4];
+        requirePolicy(sync.programId.equals(TOKEN) &&
+            sync.data.length === 1 &&
+            sync.data[0] === 17, "exact SyncNative required");
+        keys(sync, [wsolAta], [true], [false]);
+        close(instructions[5], TOKEN, wsolAta);
+        create(instructions[6], p.mint, baseToken, baseAta);
+    }
+    else if (instructions.length === 4)
+        close(instructions[3], baseToken, baseAta);
+    return {
+        tradeCost: buy ? bound : 0n,
+        ataCount: buy ? 2 : 0,
+        instructions: instructions.map((ix) => ({
+            program: ix.programId.toBase58(),
+            accounts: ix.keys.map((k) => ({
+                address: k.pubkey.toBase58(),
+                writable: k.isWritable,
+                signer: k.isSigner,
+            })),
+            data_hex: Buffer.from(ix.data).toString("hex"),
+        })),
+        limitations: "Partial offline policy, not a complete protocol safety proof. Dynamic fee recipients and creator vault are trusted builder/state inputs; only their associated WSOL derivations are checked. Account ownership/state, dynamic fees, rent, inventory/full-sell eligibility and program/CPI behavior are not proven. Buy maxSol is a trade cap, not an aggregate CPI-fee/rent/network-spend cap; the observed pre-buy refund does not lock funds. Caller must separately bound exact message fees/rent and require explicit --ack-incomplete-policy consent before signing.",
+    };
+}

package/examples/readonly.ts

@@ -0,0 +1,42 @@
+import { SolanaAgentKit, type BaseWallet } from "solana-agent-kit";
+import { PublicKey } from "@solana/web3.js";
+import { pathToFileURL } from "node:url";
+import { createNodiusPlugin } from "../src/index.js";
+export async function readonlyExample(env: NodeJS.ProcessEnv = process.env) {
+  const forbidden = async (): Promise<never> => {
+    throw new Error("Read-only wallet cannot sign or send");
+  };
+  const wallet: BaseWallet = {
+    publicKey: new PublicKey(
+      env.NODIUS_PUBLIC_KEY ?? "11111111111111111111111111111111",
+    ),
+    signTransaction: forbidden,
+    signAllTransactions: forbidden,
+    signAndSendTransaction: forbidden,
+    signMessage: forbidden,
+  };
+  const endpoint = env.NODIUS_ENDPOINT ?? "https://rpc.nodius.xyz";
+  const agent = new SolanaAgentKit(wallet, endpoint + "/rpc", {}).use(
+    createNodiusPlugin({
+      apiKey: env.NODIUS_API_KEY,
+      endpoint,
+      journalDir: env.NODIUS_JOURNAL ?? ".nodius-journal",
+      allowExecution: false,
+      ackIncompletePolicy: false,
+    }),
+  );
+  return agent.methods.nodiusRecent({ limit: 5 });
+}
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  readonlyExample()
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch(() => {
+      console.error(
+        "Read-only request failed; verify host endpoint/API key. No signing or sending occurred.",
+      );
+      process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@nodiusxyz/solana-agent-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Opt-in bounded nodius.xyz plugin for Solana Agent Kit",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.20.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "example:readonly": "tsx examples/readonly.ts"
+  },
+  "dependencies": {
+    "@nodiusxyz/sdk": "0.2.15",
+    "@solana/web3.js": "1.99.0",
+    "@solana/spl-token": "0.4.15",
+    "bs58": "6.0.0",
+    "tweetnacl": "1.0.3",
+    "ws": "8.22.0",
+    "zod": "3.25.76"
+  },
+  "peerDependencies": {
+    "solana-agent-kit": "2.0.10"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.11",
+    "@types/ws": "8.18.1",
+    "solana-agent-kit": "2.0.10",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3"
+  },
+  "overrides": {
+    "jayson": "5.0.0"
+  },
+  "homepage": "https://nodius.xyz/docs/solana-agent-kit.html",
+  "author": "nodius.xyz",
+  "keywords": [
+    "solana-agent-kit",
+    "solana",
+    "pumpfun",
+    "trading",
+    "agent",
+    "plugin",
+    "nodius"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,297 @@
+import type { SolanaAgentKit, Plugin } from "solana-agent-kit";
+import { z } from "zod";
+import { run } from "./internal/app.js";
+import { endpoint as validateEndpoint, type Args } from "./internal/config.js";
+export { decodeBuilderUnsigned } from "./internal/safety.js";
+export interface NodiusOptions {
+  apiKey?: string;
+  endpoint?: string;
+  journalDir: string;
+  allowExecution?: boolean;
+  ackIncompletePolicy?: boolean;
+}
+const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const decimal = z.string().regex(/^(0|[1-9]\d*)(\.\d{1,9})?$/);
+const base = {
+  mint: z.string().min(32).max(44),
+  maxSol: decimal,
+  maxFeeCredits: integer,
+  slippageBps: integer.max(9999),
+  priorityFee: integer,
+  maxPriorityFee: integer,
+  maxPriorityLamports: integer.optional(),
+  execute: z.boolean().default(false),
+  buildOnly: z.boolean().default(false),
+  operationId: z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,80}$/)
+    .optional(),
+  acceptUnquotedBuildCharge: z.boolean().default(false),
+};
+export const tradeSchema = z.discriminatedUnion("side", [
+  z.object({ ...base, side: z.literal("buy"), amountSol: decimal }).strict(),
+  z
+    .object({
+      ...base,
+      side: z.literal("sell"),
+      amountRaw: z.string().regex(/^[1-9]\d*$/),
+    })
+    .strict(),
+]);
+const tradeActionSchema = z
+  .object({
+    ...base,
+    side: z.enum(["buy", "sell"]),
+    amountSol: decimal.optional(),
+    amountRaw: z
+      .string()
+      .regex(/^[1-9]\d*$/)
+      .optional(),
+  })
+  .strict();
+export const monitorSchema = z
+  .object({
+    maxFeeCredits: integer,
+    seconds: integer.min(1).max(300).default(30),
+    maxEvents: integer.min(1).max(1000).default(100),
+    mint: z.string().min(32).max(44).optional(),
+    kinds: z
+      .array(z.enum(["newPair", "graduation", "walletActivity", "largeSwap"]))
+      .min(1)
+      .max(4)
+      .optional(),
+  })
+  .strict();
+export const statusSchema = z
+  .object({ operationId: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/) })
+  .strict();
+export const sendSchema = z
+  .object({
+    signedTxBase64: z.string().min(1).max(1644),
+    maxFeeCredits: integer,
+    execute: z.boolean().default(false),
+    operationId: z
+      .string()
+      .regex(/^[A-Za-z0-9_-]{1,80}$/)
+      .optional(),
+  })
+  .strict();
+export type SendInput = z.input<typeof sendSchema>;
+export type StatusInput = z.input<typeof statusSchema>;
+export type MonitorInput = z.input<typeof monitorSchema>;
+export type TradeInput = z.input<typeof tradeSchema>;
+export type NodiusResult = Record<string, unknown>;
+export function createNodiusPlugin(options: NodiusOptions) {
+  const parsed = z
+    .object({
+      apiKey: z
+        .string()
+        .min(1)
+        .regex(/^[^\r\n]+$/)
+        .optional(),
+      endpoint: z.string().optional(),
+      journalDir: z.string().min(1),
+      allowExecution: z.boolean().default(false),
+      ackIncompletePolicy: z.boolean().default(false),
+    })
+    .strict()
+    .parse(options);
+  const o = Object.freeze({
+    ...parsed,
+    endpoint: validateEndpoint(parsed.endpoint ?? "https://rpc.nodius.xyz"),
+  });
+  let owner: SolanaAgentKit | undefined;
+  const recent = z
+    .object({ limit: integer.min(1).max(50).default(20) })
+    .strict();
+  function clean(value: unknown): any {
+    const text = (s: string) =>
+      o.apiKey ? s.split(o.apiKey).join("[REDACTED]") : s;
+    if (typeof value === "string") return text(value);
+    if (typeof value === "bigint") return value.toString();
+    if (Array.isArray(value)) return value.map(clean);
+    if (value && typeof value === "object")
+      return Object.fromEntries(
+        Object.entries(value)
+          .filter(([, v]) => v !== undefined)
+          .map(([k, v]) => [text(k), clean(v)]),
+      );
+    return value;
+  }
+  async function invoke(
+    agent: SolanaAgentKit,
+    input: unknown,
+    kind: "recent" | "trade" | "monitor" | "status" | "send",
+  ): Promise<NodiusResult> {
+    try {
+      return clean(await dispatch(agent, input, kind));
+    } catch (e) {
+      throw new Error(clean(e instanceof Error ? e.message : String(e)));
+    }
+  }
+  async function dispatch(
+    agent: SolanaAgentKit,
+    input: unknown,
+    kind: "recent" | "trade" | "monitor" | "status" | "send",
+  ): Promise<NodiusResult> {
+    if (!owner || agent !== owner) throw Error("Plugin agent mismatch");
+    let args: Args = {
+      command: kind,
+      endpoint: o.endpoint ?? "https://rpc.nodius.xyz",
+      journal: o.journalDir,
+    };
+    if (kind === "recent") {
+      const v = recent.parse(input);
+      args.limit = String(v.limit);
+    } else if (kind === "send") {
+      const v = sendSchema.parse(input);
+      if (v.execute && o.allowExecution !== true)
+        throw Error("Host execution is disabled");
+      if (v.execute && o.ackIncompletePolicy !== true)
+        throw Error("Host incomplete policy acknowledgement required");
+      args["signed-tx-base64"] = v.signedTxBase64;
+      args.wallet = owner.wallet.publicKey.toBase58();
+      args["max-fee-credits"] = String(v.maxFeeCredits);
+      args.execute = v.execute;
+      if (v.operationId) args["operation-id"] = v.operationId;
+    } else if (kind === "status") {
+      const v = statusSchema.parse(input);
+      args["operation-id"] = v.operationId;
+    } else if (kind === "monitor") {
+      const v = monitorSchema.parse(input);
+      args["max-fee-credits"] = String(v.maxFeeCredits);
+      args.seconds = String(v.seconds);
+      args["max-events"] = String(v.maxEvents);
+      if (v.mint) args.mint = v.mint;
+      if (v.kinds) args.kinds = v.kinds.join(",");
+    } else {
+      const v = tradeSchema.parse(input);
+      if (v.execute && o.allowExecution !== true)
+        throw Error("Host execution is disabled");
+      if (v.execute && !v.buildOnly && o.ackIncompletePolicy !== true)
+        throw Error("Host incomplete policy acknowledgement required");
+      args.command = v.side;
+      args.wallet = owner.wallet.publicKey.toBase58();
+      const map: Record<string, string> = {
+        amountSol: "amount-sol",
+        amountRaw: "amount-raw",
+        maxSol: "max-sol",
+        maxFeeCredits: "max-fee-credits",
+        slippageBps: "slippage-bps",
+        priorityFee: "priority-fee",
+        maxPriorityFee: "max-priority-fee",
+        maxPriorityLamports: "max-priority-lamports",
+        operationId: "operation-id",
+        buildOnly: "build-only",
+        acceptUnquotedBuildCharge: "accept-unquoted-build-charge",
+      };
+      for (const [k, value] of Object.entries(v)) {
+        if (k === "side") continue;
+        args[map[k] ?? k] = typeof value === "boolean" ? value : String(value);
+      }
+      args["ack-incomplete-policy"] = o.ackIncompletePolicy === true;
+    }
+    const notifications: unknown[] = [];
+    let monitorPlan: Record<string, unknown> = {};
+    const result = await run(
+      args,
+      { NODIUS_API_KEY: o.apiKey },
+      (v) => {
+        if (kind === "monitor") {
+          if (v.state === "monitor-plan") monitorPlan = v;
+          else notifications.push(v);
+        }
+      },
+      {
+        publicKey: owner.wallet.publicKey,
+        signTransaction: (tx) => owner!.wallet.signTransaction(tx),
+      },
+    );
+    return kind === "monitor"
+      ? { ...monitorPlan, ...result, notifications }
+      : result;
+  }
+  const plugin = {
+    name: "nodius",
+    methods: {
+      nodiusSend: (input: SendInput) => invoke(owner!, input, "send"),
+      nodiusStatus: (input: StatusInput) => invoke(owner!, input, "status"),
+      nodiusMonitor: (input: MonitorInput) => invoke(owner!, input, "monitor"),
+      nodiusRecent: (input: { limit?: number } = {}) =>
+        invoke(owner!, input, "recent"),
+      nodiusTrade: (input: TradeInput) => invoke(owner!, input, "trade"),
+    },
+    actions: [
+      {
+        name: "nodiusSend",
+        similes: [],
+        description:
+          "Submit independently reviewed, already signed own-wallet transaction. Defaults plan; no trade instruction proof. Requires both host permissions.",
+        examples: [],
+        schema: sendSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "send"),
+      },
+      {
+        name: "nodiusStatus",
+        similes: [],
+        description:
+          "Reconcile local operation status; never rebuild or rebroadcast",
+        examples: [],
+        schema: statusSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "status"),
+      },
+      {
+        name: "nodiusMonitor",
+        similes: [],
+        description:
+          "Paid bounded signal monitor (<=300s, <=1000 events); no autonomous trading",
+        examples: [],
+        schema: monitorSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "monitor"),
+      },
+      {
+        name: "nodiusRecent",
+        similes: [],
+        description: "Read recent Nodius signals; never trades",
+        examples: [],
+        schema: recent,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "recent"),
+      },
+      {
+        name: "nodiusTrade",
+        similes: [],
+        description:
+          "Buy/sell defaults to read-only plan. Host must separately authorize charged execution and partial policy.",
+        examples: [],
+        schema: tradeActionSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "trade"),
+      },
+    ],
+    initialize(agent: SolanaAgentKit) {
+      if (owner && owner !== agent)
+        throw Error("Plugin instance already bound to another agent");
+      owner = agent;
+    },
+  } satisfies Plugin;
+  // Keep ZodObject identity for the published tool converters, but sanitize
+  // validation issues before the framework's pre-handler executor surfaces them.
+  for (const action of plugin.actions) {
+    const schema: z.AnyZodObject = action.schema.strict();
+    const sync = schema.safeParse.bind(schema),
+      asyncParse = schema.safeParseAsync.bind(schema);
+    schema.safeParse = (data, params) => {
+      const r = sync(data, params);
+      return r.success
+        ? r
+        : { success: false, error: new z.ZodError(clean(r.error.issues)) };
+    };
+    schema.safeParseAsync = async (data, params) => {
+      const r = await asyncParse(data, params);
+      return r.success
+        ? r
+        : { success: false, error: new z.ZodError(clean(r.error.issues)) };
+    };
+    action.schema = schema as typeof action.schema;
+  }
+  return plugin;
+}