@wowok/agent-mcp 2.6.1 → 2.6.3

package/dist/schema/call/treasury.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TypedPermissionObjectSchema, CoinParamSchema, NamedObjectSchema, SubmissionCallSchema, CallEnvSchema } from "./base.js";
 import { AmountFromDepositGuardSchema, AmountFromWithdrawGuardSchema, PaymentInfoSchema } from "../query/index.js";
-import { AccountOrMark_AddressSchema, DescriptionSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema, NameOrAddressSchema } from "../common/index.js";
+import { AccountOrMark_AddressSchema, DescriptionSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema, NameOrAddressSchema, RECEIVE_FORMAT_BLOCK_OBJECTS, RECEIVE_FORMAT_BLOCK_BALANCE } from "../common/index.js";
 import { BalanceTypeSchema } from "../common/index.js";
 export const DepositSchema = z.object({
     coin: CoinParamSchema.describe("Asset to deposit"),
@@ -56,12 +56,12 @@ export const ExternalWithdrawGuardSchema = z.discriminatedUnion("op", [
 export const CallTreasury_DataSchema = z.object({
     object: TypedPermissionObjectSchema,
     description: DescriptionSchema.optional(),
-    receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive CoinWrapper objects received by the object and deposit them into its balance."),
+    receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive CoinWrapper objects received by this Treasury object and deposit them into its balance." + RECEIVE_FORMAT_BLOCK_BALANCE),
     deposit: DepositSchema.optional().describe("Deposit to Treasury object"),
     withdraw: WithdrawSchema.optional().describe("Withdraw from Treasury object"),
     external_deposit_guard: ExternalDepositGuardSchema.optional().describe("Set external deposit Guard for Treasury object"),
     external_withdraw_guard: ExternalWithdrawGuardSchema.optional().describe("Set external withdrawal Guard for Treasury object"),
-    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this object and send them to the owner of its Permission object."),
+    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this Treasury object and send them to the owner of its Permission object." + RECEIVE_FORMAT_BLOCK_OBJECTS),
     um: z.union([NameOrAddressSchema, z.null()]).optional().describe("Contact object ID or name."),
 }).strict().describe("On-chain Treasury operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create a Treasury. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation.");
 export const CallTreasury_InputSchema = z.object({

package/dist/schema/common/index.d.ts

@@ -715,6 +715,8 @@ export declare const ReceivedObjectsOrRecentlySchema: z.ZodUnion<[z.ZodArray<z.Z
     balance: string | number;
     token_type: string;
 }>, z.ZodLiteral<"recently">]>;
+export declare const RECEIVE_FORMAT_BLOCK_OBJECTS: string;
+export declare const RECEIVE_FORMAT_BLOCK_BALANCE: string;
 export declare const QueryReceivedResultSchema: z.ZodObject<{
     result: z.ZodUnion<[z.ZodObject<{
         balance: z.ZodUnion<[z.ZodNumber, z.ZodString]>;

package/dist/schema/common/index.js

@@ -222,15 +222,18 @@ export const ObjectTypeSchema = z.enum([
     WowObjectType.TableItem_AddressMark,
     WowObjectType.TableItem_EntityRegistrar,
 ]).describe("Wowok object type");
-export const BalanceTypeSchema = z.union([z.number(), z.string()]).describe("A coin/balance amount in the smallest on-chain unit (u64). " +
-    "Accepts a JS number OR a numeric string. " +
-    "PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), " +
-    "ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — " +
-    "JS numbers lose precision above 2^53. " +
-    "UNIT: this is the smallest unit, NOT the display unit. " +
-    "For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. " +
-    "For custom tokens: use the token's native smallest unit (decimals from coin metadata). " +
-    "Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). " +
+export const BalanceTypeSchema = z.union([z.number(), z.string()]).describe("A coin/balance amount. Accepts three formats: " +
+    "(1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — " +
+    "auto-converted to smallest units via the Fund Processing Layer (token precision resolved " +
+    "from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. " +
+    "(2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. " +
+    "(3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). " +
+    "PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. " +
+    "Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). " +
+    "For custom tokens: use display format with the token's symbol, or pass smallest units directly. " +
+    "MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. " +
+    "If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. " +
+    "Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). " +
     "Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities.");
 export const QueryIdSchema = z.number().int().min(0).describe("Query ID");
 export const CacheExpireTypeSchema = z.union([z.number(), z.literal("INFINITE")]).describe("Cache expiration time type");
@@ -253,7 +256,18 @@ export const SupportedValueSchema = SupportedValueUserSchema.or(ValueContainerSc
 export const GuardIdentifierSchema = z.number().int().min(0).max(255).describe("Identifier (0-255) for data lookup in Guard table.");
 export const GuardTableItemBaseSchema = z.object({
     identifier: GuardIdentifierSchema,
-    b_submission: z.boolean().describe("Whether user submission is required for this data"),
+    b_submission: z.boolean().describe("Whether this table item's value is submitted dynamically at Guard trigger time (alloc_by_guard call). " +
+        "\n\n" +
+        "true = value is submitted by the caller when triggering the Guard. " +
+        "Use for runtime-context-dependent values like order address, user address. " +
+        "The 'value' field is ignored when b_submission=true; the caller must provide it via submissions[]. " +
+        "\n\n" +
+        "false = value is static, set at Guard creation time. " +
+        "Use for values known when the Guard is created: expected node names, expected merchant address, expected service address. " +
+        "The 'value' field must be populated and will be stored on-chain permanently. " +
+        "\n\n" +
+        "Rule of thumb: if the value is the SAME for all future Guard triggers, use false. " +
+        "If the value DIFFERS per trigger (e.g., which order to release funds for), use true."),
     value_type: ValueTypeUserSchema.describe("Type of the value stored in `value`. One of: Bool(0), Address(1), String(2), U8(3), U16(4), U32(5), U64(6), U128(7), U256(8), VecBool(9), VecAddress(10), VecString(11), VecU8(12), VecU16(13), VecU32(14), VecU64(15), VecU128(16), VecU256(17), VecVecU8(18). " +
         "When value_type=Address (1), the `value` field accepts a hex address string, a LocalMark name, or an AccountOrMark_Address object — see `value` field description for details."),
     value: SupportedValueUserSchema.optional().describe("The actual value data. Format depends on `value_type`:\n" +
@@ -363,6 +377,28 @@ export const ReceivedObjectsOrRecentlySchema = z.union([
     ReceivedBalanceSchema,
     z.literal("recently"),
 ]).describe("Specified received object records or all recently received object records");
+export const RECEIVE_FORMAT_BLOCK_OBJECTS = "\n\nACCEPTED FORMATS (F-06 unified receive operation block):\n" +
+    "• 'recently' (string literal) — auto-query and receive ALL recently received objects.\n" +
+    "  Use this for the common case: \"withdraw everything the object has received.\"\n" +
+    "  Example: receive: 'recently'\n" +
+    "• ReceivedNormal[] (array) — explicit list of received objects to unwrap.\n" +
+    "  Use this when you want to receive specific objects only (not all).\n" +
+    "  Example: receive: [{id: '0xobj1', type: '0x2::coin::Coin<0x2::sui::SUI>'}]\n" +
+    "• ReceivedBalance ({token_type, balance, received: [{id, balance, payment}]}) —\n" +
+    "  receive a balance record from a specific Payment/payer.\n" +
+    "  Use this for precise balance targeting (advanced — usually after querying\n" +
+    "  the object's received history via query_received).\n" +
+    "  Example: receive: {token_type: '0x2::sui::SUI', balance: 1000000, received: [{id: '0xrec1', balance: 1000000, payment: '0xpay1'}]}\n" +
+    "ANTI-PATTERN: do NOT wrap in {result: ...} — pass the value directly.";
+export const RECEIVE_FORMAT_BLOCK_BALANCE = "\n\nACCEPTED FORMATS (F-06 unified receive operation block):\n" +
+    "• 'recently' (string literal) — auto-query and receive ALL recently received balance.\n" +
+    "  Use this for the common case: \"deposit all recently received coins into pending balance.\"\n" +
+    "  Example: receive: 'recently'\n" +
+    "• ReceivedBalance ({token_type, balance, received: [{id, balance, payment}]}) —\n" +
+    "  receive a specific balance record from a Payment/payer.\n" +
+    "  Use this when targeting a specific received balance (advanced).\n" +
+    "  Example: receive: {token_type: '0x2::sui::SUI', balance: 1000000, received: [{id: '0xrec1', balance: 1000000, payment: '0xpay1'}]}\n" +
+    "ANTI-PATTERN: do NOT wrap in {result: ...} — pass the value directly.";
 export const QueryReceivedResultSchema = z.object({
     result: z.union([
         ReceivedBalanceSchema,

package/dist/schema/local/index.js

@@ -568,7 +568,11 @@ export const AccountOperationSchema = z
 })
     .strict()
     .refine((data) => Object.keys(data).length > 0, "At least one operation (gen/faucet/suspend/resume/rename/swap_name/transfer/get/signData/messenger) must be specified")
-    .describe("Account operations. Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected.");
+    .describe("Account operations (mutations only: gen/faucet/suspend/resume/rename/swap_name/transfer/get/signData/messenger). " +
+    "Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected. " +
+    "TO LIST ALL ACCOUNTS: use the query_toolkit tool with query_type='account_list' (returns name, address, suspended status, messenger status for all local accounts). " +
+    "This separation follows CQRS: account_operation = mutations, query_toolkit = queries. " +
+    "Common workflow after MCP restart: (1) query_toolkit query_type='account_list' to see all accounts, (2) account_operation with the appropriate mutation.");
 export const AccountOperationResultSchema = z
     .object({
     gen: z