@wowok/agent-mcp 2.6.0 → 2.6.1

package/dist/schema/query/index.js

@@ -5,14 +5,23 @@ import { SemanticSummarySchema } from "../call/index.js";
 import { isValidPermissionIndex } from '../utils/permission-index-utils.js';
 import { isValidGuardQueryId, isValidGuardQueryIdOrName, isValidWitnessType } from '../utils/guard-query-utils.js';
 import { ENTITY_LINKER_ADDRESS, ENTITY_REGISTRAR_ADDRESS, isWitnessType, } from "@wowok/wowok";
-import { DiscountType as WDiscountType } from "@wowok/wowok";
 import { QueryEnvSchema } from "../common/index.js";
 const MAX_MULTI_OPERANDS = 8;
 const VALUE_TYPE_DESCRIPTION = "Value type: can be specified as a string name (e.g., 'U64', 'Address', 'String') or a number (0-18). Supported types: Bool=0/'Bool', Address=1/'Address', String=2/'String', U8=3/'U8', U16=4/'U16', U32=5/'U32', U64=6/'U64', U128=7/'U128', U256=8/'U256', VecBool=9/'VecBool', VecAddress=10/'VecAddress', VecString=11/'VecString', VecU8=12/'VecU8', VecU16=13/'VecU16', VecU32=14/'VecU32', VecU64=15/'VecU64', VecU128=16/'VecU128', VecU256=17/'VecU256', VecVecU8=18/'VecVecU8'. Note: Value=19 is an INTERNAL type for wowok system use only and should NOT be used directly by users. String format is recommended for better readability.";
 const tolerantNumber = z.union([z.number(), z.string()]);
 const tolerantStringNullable = z.union([z.string(), z.null(), z.undefined()]);
 const tolerantNumberNullable = z.union([z.number(), z.string(), z.null(), z.undefined()]);
-export const AmountTypeSchema = z.enum(["GuardU64Identifier", "Fixed"]).describe("Amount type. GuardU64Identifier indicates the amount comes from U64 type data defined in Guard table (Identifier index), Fixed indicates using a fixed amount.");
+export const AmountTypeSchema = z.union([
+    z.enum(["GuardU64Identifier", "Fixed"]),
+    z.number().int().min(0).max(1).transform((n) => n === 0 ? "GuardU64Identifier" :
+        n === 1 ? "Fixed" :
+            "GuardU64Identifier"),
+]).describe("Amount type — determines how a payment amount is resolved. " +
+    "Accepts string ('GuardU64Identifier' or 'Fixed') or number (0='GuardU64Identifier', 1='Fixed'). String form is recommended for readability. " +
+    "• 'GuardU64Identifier' (0): the amount is NOT fixed — it is dynamically read from a U64 value stored in the Guard table at the specified Identifier index. Use this when the amount varies per order (e.g. milestone-based pricing, negotiated price). The Guard must have a matching U64 entry. " +
+    "• 'Fixed' (1): the amount is a fixed value set in the sale/price field. Use this for products with a static price (e.g. service fee = 50 SUI). " +
+    "Example: {price: 50000000000, stock: 100, amount_type: 'Fixed'} → fixed 50 SUI price. " +
+    "Example: {price: 0, stock: 100, amount_type: 'GuardU64Identifier'} → price read from Guard table U64 entry.");
 export const GuardQuerySchema = z.object({
     id: QueryIdSchema,
     name: z.string().describe("Name of the query instruction."),
@@ -29,9 +38,13 @@ export const GuardSubmissionSchema = z.object({
 }).describe("Guard submission");
 export const RecipientSchema = z.union([
     z.object({ GuardIdentifier: GuardIdentifierSchema }).describe("Guard verified recipient ID. Get recipient ID from specified data index in Guard table. The ID must be of address type."),
-    z.object({ Entity: AccountOrMark_AddressSchema }).describe("Determined ID"),
+    z.object({ Entity: AccountOrMark_AddressSchema }).describe("Static address resolved via LocalMark. " +
+        "Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."),
     z.object({ Signer: z.literal("signer") }).describe("Current transaction signer ID"),
-]).describe("Recipient ID");
+]).describe("Recipient ID. Three forms:\n" +
+    "  - {GuardIdentifier: u8}  — resolved from Passport at allocation time\n" +
+    "  - {Entity: {name_or_address: 'mark_name'}}  — static address via LocalMark (recommended)\n" +
+    "  - {Signer: 'signer'}  — transaction sender (e.g. self-refund)");
 export const RecordsInEntitySchema = z.object({
     name: z.string().describe("Record name"),
     value_type: ValueTypeSchema.describe("Value type"),
@@ -104,8 +117,11 @@ export const ServiceSaleSchema = z.object({
     price: BalanceTypeSchema.describe("Price of the product or service"),
     stock: BalanceTypeSchema.describe("Stock of the product or service"),
     suspension: z.boolean().describe("Whether sale is suspended"),
-    wip: z.string().describe("HTTP URL of wip file"),
-    wip_hash: z.string().describe(`Hash of WIP. If EMPTY string, the hash within wip will be automatically used; else, the consistency of the hash within wip will be verified with the provided hash.`),
+    wip: z.string().describe("WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). " +
+        "Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. " +
+        "Example: \"https://cdn.example.com/products/phone_v1.wip\""),
+    wip_hash: z.string().describe("WIP file hash (hex string). EMPTY string \"\" skips hash comparison (TESTING ONLY). " +
+        "Production: fill with the hash you saw when viewing the product, to prevent merchant replacing the WIP file before order."),
 }).describe("Service sale");
 export const PurchasedItemSchema = z.object({
     name: LongNameSchema.describe("Name of the product or service"),
@@ -182,23 +198,91 @@ export const ObjectRewardSchema = ObjectBaseSchema.extend({
     um: z.union([z.string(), z.null()]).describe("Contact object"),
     permission: z.string().describe("Permission object ID"),
 }).describe("Reward object");
-export const AllocationModeSchema = z.enum(["Amount", "Rate", "Surplus"]).describe("Reward allocation mode. Amount indicates allocation by amount, Rate indicates allocation by proportion, Surplus indicates allocation by remaining amount. In a fund allocator, Amount will be allocated first, then remaining funds will be allocated by Rate (if no Surplus is defined, sum of all Rates must be 10000), and finally Surplus gets remaining amount (maximum one per fund allocator).");
+export const AllocationModeSchema = z.union([
+    z.enum(["Amount", "Rate", "Surplus"]),
+    z.number().int().min(0).max(2).transform((n) => n === 0 ? "Amount" :
+        n === 1 ? "Rate" :
+            n === 2 ? "Surplus" :
+                "Amount"),
+]).describe("Allocation mode — determines how the `sharing` field is interpreted. " +
+    "Three modes can be used individually OR combined within a single Allocator; " +
+    "when combined, allocation order is strictly: Amount first, then Rate, then Surplus. " +
+    "Understanding these modes allows modeling almost any fund distribution pattern.\n" +
+    "• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). " +
+    "Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. " +
+    "Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); " +
+    "when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n" +
+    "• Rate (1): `sharing` is a basis-points rate (10000 = 100%). " +
+    "Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, " +
+    "where total_rates = balance - fix (or max - fix if `max` is set). " +
+    "Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); " +
+    "when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n" +
+    "• Surplus (2): `sharing` is IGNORED (contract forces it to 0). " +
+    "Allocated LAST; receives the remaining balance after Amount + Rate allocations. " +
+    "Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). " +
+    "When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n" +
+    "ALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate items (proportional to balance-fix) → Surplus item (remaining).\n" +
+    "RECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). " +
+    "Use Rate mode for proportional splits (requires sum == 10000 unless Surplus present). " +
+    "Use Surplus to capture remainder (e.g., platform fee + host gets rest). " +
+    "Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2).");
 export const AllocationSharingSchema = z.object({
-    who: RecipientSchema.describe("Recipient ID"),
-    sharing: BalanceTypeSchema.describe("Reward allocation value"),
-    mode: AllocationModeSchema.describe("Reward allocation mode"),
-}).describe("Fund allocation item");
+    who: RecipientSchema.describe("Recipient of this allocation. Three forms:\n" +
+        "• { GuardIdentifier: u8 } — resolved from Passport at allocation time. " +
+        "Use 0 for Order owner in Service-integrated mode (Customer who created the Order). " +
+        "The identifier must match a Guard table entry with b_submission=true. " +
+        "If Passport has no matching submission, contract aborts with E_VERIFY_FAILED.\n" +
+        "• { Entity: { name_or_address: '...' } } — static address resolved via LocalMark. " +
+        "Use for known recipients (e.g., 'turo_host', or a Treasury object address).\n" +
+        "• 'Signer' — the transaction sender (tx_context::sender). " +
+        "Use when the recipient is the current signer (e.g., self-refund scenarios)."),
+    sharing: BalanceTypeSchema.describe("Allocation value. SEMANTICS DEPEND ON `mode`:\n" +
+        "• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). " +
+        "Allocated first; sum of Amount items cached as `fix`.\n" +
+        "• mode='Rate': basis-points rate, 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). " +
+        "When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n" +
+        "• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. " +
+        "Receives remaining balance after Amount + Rate allocations."),
+    mode: AllocationModeSchema,
+}).describe("Fund allocation item — one recipient's share of the Allocation balance. " +
+    "The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). " +
+    "Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last.");
 export const AllocatorSchema = z.object({
-    guard: NameOrAddressSchema.describe("Guard object ID. If Guard verification passes, fund allocation will start automatically."),
-    sharing: z.array(AllocationSharingSchema).describe("Fund allocation item list. Each item represents a recipient and their corresponding reward allocation value."),
-    fix: BalanceTypeSchema.optional().describe("Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."),
-    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation amount. If specified, allocation amount cannot exceed maximum allocation amount."),
-}).describe("Fund allocator");
+    guard: NameOrAddressSchema.describe("Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. " +
+        "Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. " +
+        "This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."),
+    sharing: z.array(AllocationSharingSchema).describe("Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. " +
+        "Items can mix modes (Amount + Rate + Surplus) within the same Allocator. " +
+        "ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). " +
+        "CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); " +
+        "Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."),
+    fix: BalanceTypeSchema.optional().describe("OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. " +
+        "Computed by the contract during `allocator_add` — DO NOT set this field at creation. " +
+        "Used internally to compute `total_rates = balance - fix` for Rate allocation."),
+    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation cap (optional). Has THREE effects:\n" +
+        "1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n" +
+        "2. Rate execution: total_rates = max - fix (instead of balance - fix)\n" +
+        "3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\n" +
+        "Use when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount)."),
+}).describe("Fund allocator — a complete allocation strategy triggered by a Guard. " +
+    "Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. " +
+    "When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus.");
 export const AllocatorsSchema = z.object({
     description: DescriptionSchema.describe("Description of fund allocator list"),
-    threshold: BalanceTypeSchema.default(0).describe("Threshold. If defined, fund allocation will be triggered when amount in Allocation object reaches this threshold."),
-    allocators: z.array(AllocatorSchema).describe("Fund allocator list. Each fund allocator represents a fund allocation strategy."),
-}).describe("Fund allocator list");
+    threshold: BalanceTypeSchema.default(0).describe("Minimum balance required for allocation to fire. " +
+        "When the Allocation object's balance < threshold, allocation aborts with EINSUFFICIENT_BALANCE=7. " +
+        "Also: when an Allocator has only Amount items (no Rate, no Surplus), the sum of Amount items must be >= threshold (EAMOUNT_BELOW_THRESHOLD=12). " +
+        "Set to 0 (default) to allow any balance."),
+    allocators: z.array(AllocatorSchema).describe("Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. " +
+        "This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."),
+}).describe("Fund allocator list — the top-level allocation configuration attached to an Order. " +
+    "Contains a threshold and a list of Allocators. When funds arrive at the Order, " +
+    "the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. " +
+    "MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). " +
+    "For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: " +
+    "(1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); " +
+    "(2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). " +
+    "Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus).");
 export const ObjectServiceSchema = ObjectBaseSchema.extend({
     description: z.string().describe("Service object description"),
     location: z.string().describe("Service object location"),
@@ -210,7 +294,11 @@ export const ObjectServiceSchema = ObjectBaseSchema.extend({
     bPaused: z.boolean().describe("Whether service purchase is paused"),
     customer_required: z.array(z.string()).describe("Information required from customer. Such as phone, email, etc."),
     arbitrations: z.array(z.string()).describe("List of Arbitration objects supported by service. When order user needs arbitration, they can apply for arbitration with any Arbitration object in the list."),
-    compensation_fund: BalanceTypeSchema.describe("Compensation fund pool for arbitration results. Order users can receive compensation from this fund based on arbitration results."),
+    compensation_fund: BalanceTypeSchema.describe("Compensation fund BALANCE (NOT a Treasury address). " +
+        "This field reports the total amount of funds currently held in the Service's compensation pool. " +
+        "To ADD funds, use `service.compensation_fund_add`. To RECEIVE funds (as order owner after arbitration), use `service.compensation_fund_receive`. " +
+        "P2-03 clarification: this is a balance value (e.g. {balance: '1000000000', token_type: '0x2::wow::WOW'}), NOT the Treasury object address. " +
+        "The Treasury address (if bound) is queried separately via the Service's `repositories` or `order_allocators` configuration."),
     paused_time: z.union([z.number(), z.null()]).describe("Service purchase pause time. If not paused, it is null."),
     setting_lock_duration: z.union([z.string(), z.number(), z.bigint()]).describe("Lock duration for critical settings. After Service is published, modifications to 'order_allocators', 'rewards', 'arbitrations', 'machine', and withdrawal from 'compensation_fund' must exceed the 'setting_lock_duration' lock time."),
     order_allocators: z.union([AllocatorsSchema, z.null()]).describe("Order fund allocator list."),
@@ -257,9 +345,11 @@ export const ObjectArbSchema = ObjectBaseSchema.extend({
     time: z.number().describe("Arbitration time"),
 }).describe("Arb object");
 export const DiscountTypeSchema = z.union([
-    z.literal(WDiscountType.RATES).describe("Rate discount type"),
-    z.literal(WDiscountType.FIXED).describe("Fixed discount type")
-]).describe("Discount type");
+    z.enum(["RATES", "FIXED"]),
+    z.number().int().min(0).max(1).transform((n) => n === 0 ? "RATES" :
+        n === 1 ? "FIXED" :
+            "RATES"),
+]).describe("Discount type. Accepts string ('RATES' or 'FIXED') or number (0='RATES', 1='FIXED'). If rate(0/RATES), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1/FIXED), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount). String form is recommended.");
 export const ObjectDiscountSchema = ObjectBaseSchema.extend({
     name: z.string().describe("Discount name"),
     discount_type: DiscountTypeSchema.describe("Discount type. If rate(0), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount)."),
@@ -462,11 +552,17 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
     z.object({
         type: z.literal('logic_and'),
         nodes: z.array(GuardNodeSchema),
-    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical AND on all child node values. Returns true if ALL are true, otherwise false.`),
+    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical AND on all child node values. Returns true if ALL are true, otherwise false.`)
+        .refine((v) => v.nodes.length >= 2 && v.nodes.length <= MAX_MULTI_OPERANDS, {
+        message: `logic_and requires 2-${MAX_MULTI_OPERANDS} child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_and.`,
+    }),
     z.object({
         type: z.literal('logic_or'),
         nodes: z.array(GuardNodeSchema),
-    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical OR on all child node values. Returns true if ANY is true, otherwise false.`),
+    }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical OR on all child node values. Returns true if ANY is true, otherwise false.`)
+        .refine((v) => v.nodes.length >= 2 && v.nodes.length <= MAX_MULTI_OPERANDS, {
+        message: `logic_or requires 2-${MAX_MULTI_OPERANDS} child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_or.`,
+    }),
     z.object({
         type: z.literal('logic_string_contains'),
         nodes: z.array(GuardNodeSchema),
@@ -842,21 +938,58 @@ export const TableItem_DemandPresenterSchema = ObjectBaseSchema.extend({
     feedback_time: tolerantNumber.describe("Demand object feedback time"),
 }).describe("Demand object's Service recommendation record");
 export const MachineForwardGuardSchema = z.object({
-    guard: z.string().describe("Guard object ID"),
+    guard: z.string().describe("Guard object name or address (string). Example: 'my_attendance_guard' or '0x1234...'"),
     retained_submission: z.array(tolerantNumber).nullable().optional().describe("Data submitted by user during Guard object verification"),
-}).strict().describe("Record of Guard object in MachineForwardGuard object");
+}).strict().describe("Record of Guard object in MachineForwardGuard object. ALWAYS an OBJECT {guard: string, retained_submission?: number[]} — never a plain string. The inner 'guard' field is the Guard's name or address as a string.");
 export const MachineForwardSchema = z.object({
     name: z.string().describe("Forward name"),
     namedOperator: tolerantStringNullable.describe("Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders)."),
     permissionIndex: tolerantNumberNullable.describe("Forward operation permission 2: Permission index (one of the two must be specified); recommended if all Progress object operators are the same (e.g., same reward reviewers for all orders)."),
     weight: tolerantNumber.describe("Forward weight"),
-    guard: MachineForwardGuardSchema.nullable().optional().describe("Guard object ID, if defined, Guard verification must also pass to complete Forward (e.g., completed promised supply chain sub-order)."),
+    guard: z.preprocess((val) => {
+        if (typeof val === "string") {
+            return { guard: val };
+        }
+        return val;
+    }, z.union([
+        MachineForwardGuardSchema.describe("OBJECT form: {guard: '<guard_name_or_address>', retained_submission?: number[]}. " +
+            "Use this form when you need to pass retained_submission data alongside the Guard reference."),
+        z.string().describe("STRING form (shorthand): the Guard object's name or address as a plain string. " +
+            "Auto-wrapped to {guard: <string>} at runtime. Use this when you only need to reference a Guard without retained_submission."),
+    ]).nullable().optional()).describe("Guard reference for this forward. Accepts TWO formats:\n" +
+        "• STRING (preferred): \"my_guard_name\" — the Guard's name or address as a plain string.\n" +
+        "• OBJECT (only when retained_submission is needed): {guard: \"my_guard_name\", retained_submission: [1,2,3]}.\n" +
+        "FOLLOW THE SCHEMA FIELD STRUCTURE: A Guard reference is fundamentally a STRING (the Guard object's name or address). " +
+        "Provide a string when you only need to reference a Guard — do NOT wrap a bare string in an object structure. " +
+        "The OBJECT form {guard: \"...\", retained_submission: [...]} exists ONLY to carry additional `retained_submission` data " +
+        "alongside the string reference; inside the object, the `guard` field is STILL a string. " +
+        "In short: string-in for a string reference, object-in only when you need to pass extra data.\n" +
+        "COGNITIVE PRINCIPLE: Guard validation ALWAYS occurs BEFORE the forward operation. " +
+        "A Guard that queries state of the SAME Progress object this forward operates on " +
+        "(e.g. progress.current) will see the PRE-transition value (source node), NOT the target node. " +
+        "If the Guard checks progress.current == target_node, it will ALWAYS FAIL. " +
+        "Querying a DIFFERENT Progress object (cross-machine) is safe and reasonable — " +
+        "that progress is not modified by this forward. " +
+        "For target-node verification after transition, bind the Guard to the Allocator instead " +
+        "(allocation.alloc runs AFTER the state transition completes)."),
 }).strict().describe("Forward in Machine object");
 export const MachineNodePairSchema = z.object({
-    prev_node: z.string().describe("Previous node name"),
+    prev_node: z.string().describe("Previous node name. Empty string '' means initial entry node (the first node in the workflow)."),
     threshold: tolerantNumber.default(0).describe("Threshold to trigger node advancement. If total Forward weight is greater than or equal to threshold, node advancement is triggered."),
-    forwards: z.array(MachineForwardSchema).describe("Forward list"),
-}).strict().describe("Node pair in Machine object");
+    forwards: z.array(MachineForwardSchema).describe("Forward list — operations to ENTER THIS NODE from prev_node. " +
+        "Example: pair {prev_node:'A', forwards:[{name:'Go'}]} means 'use Go to advance FROM A TO THIS NODE'. " +
+        "For initial node (prev_node=''), forwards are operations to enter this node from the start state. " +
+        "WARNING: forwards belong to the DESTINATION node's pair, NOT the source node. " +
+        "Placing a forward on the wrong pair will cause Progress to get stuck."),
+}).strict().describe("Node pair in Machine object")
+    .refine((pair) => {
+    if (pair.prev_node === "" && pair.forwards.length === 0) {
+        return false;
+    }
+    return true;
+}, {
+    message: "Initial node (prev_node='') must have at least one forward. Without a forward, Progress cannot advance from '' to this node, causing the order workflow to be permanently stuck.",
+});
 export const MachineNodeSchema = z.object({
     name: z.string().describe("Node name"),
     pairs: z.array(MachineNodePairSchema).describe("Node pair list"),

package/dist/schema/schema-query/index.d.ts

@@ -1,16 +1,25 @@
 import { z } from "zod";
 export declare const SchemaQueryInputSchema: z.ZodObject<{
-    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations"]>;
+    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations", "get_guard_templates", "get_field"]>;
     name: z.ZodOptional<z.ZodString>;
     query: z.ZodOptional<z.ZodString>;
+    field_path: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    output_file: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations";
+    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field";
     name?: string | undefined;
     query?: string | undefined;
+    field_path?: string | undefined;
+    template?: string | undefined;
+    output_file?: string | undefined;
 }, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations";
+    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field";
     name?: string | undefined;
     query?: string | undefined;
+    field_path?: string | undefined;
+    template?: string | undefined;
+    output_file?: string | undefined;
 }>;
 export declare const SchemaQueryOutputSchema: z.ZodObject<{
     success: z.ZodBoolean;
@@ -30,6 +39,7 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
     }>, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>;
     message: z.ZodString;
     suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    output_file_path: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     message: string;
     data: Record<string, unknown> | {
@@ -40,6 +50,7 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
     success: boolean;
     action: string;
     suggestions?: string[] | undefined;
+    output_file_path?: string | undefined;
 }, {
     message: string;
     data: Record<string, unknown> | {
@@ -50,4 +61,5 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
     success: boolean;
     action: string;
     suggestions?: string[] | undefined;
+    output_file_path?: string | undefined;
 }>;

package/dist/schema/schema-query/index.js

@@ -8,16 +8,30 @@ export const SchemaQueryInputSchema = z
         "get_output",
         "search",
         "list_operations",
+        "get_guard_templates",
+        "get_field",
     ])
-        .describe("Action to perform: 'list' to see all available schemas, 'get' to retrieve a specific input schema, 'get_output' to retrieve a tool's output schema, 'search' to find schemas by keyword, 'list_operations' to list all on-chain operations"),
+        .describe("Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices)."),
     name: z
         .string()
         .optional()
-        .describe("Schema/tool name for 'get'/'get_output' action (e.g., 'onchain_operations', 'account_operation', 'onchain_operations_permission')"),
+        .describe("Schema/tool name for 'get'/'get_output'/'get_field' action (e.g., 'onchain_operations', 'onchain_operations_machine')."),
     query: z
         .string()
         .optional()
         .describe("Search query for 'search' action"),
+    field_path: z
+        .string()
+        .optional()
+        .describe("Dot-separated field path for 'get_field' action (e.g. 'data.node', 'data.node.nodes.0.pairs'). Navigates schema.properties.* and schema.items.*."),
+    template: z
+        .string()
+        .optional()
+        .describe("Guard template name for 'get_guard_templates' action. Omit to list all available templates. Available: signer_verification, progress_node_check, order_owner_verification, service_belonging_check, reward_not_claimed, combined_reward_guard."),
+    output_file: z
+        .string()
+        .optional()
+        .describe("When set, writes the response data to this file path (relative to cwd) and returns the path instead of inline data. Use for large schemas that would be truncated. Prefer workspace paths like '.trae/tmp/schema.json' so the Read tool can access them."),
 })
     .strict();
 const SchemaListItemSchema = z
@@ -34,14 +48,18 @@ export const SchemaQueryOutputSchema = z
     data: z
         .union([
         z.array(SchemaListItemSchema).describe("List of schema summaries (list/search/list_operations)."),
-        z.record(z.unknown()).describe("JSON Schema object (get/get_output)."),
-        z.null().describe("No data — lookup failed or returned nothing."),
+        z.record(z.unknown()).describe("JSON Schema object (get/get_output/get_field) or Guard template data."),
+        z.null().describe("No data — lookup failed or returned nothing, or data was written to output_file."),
     ])
-        .describe("Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output, null on failure."),
+        .describe("Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."),
     message: z.string().describe("Human-readable message describing the result"),
     suggestions: z
         .array(z.string())
         .optional()
         .describe("Suggested next steps or alternatives"),
+    output_file_path: z
+        .string()
+        .optional()
+        .describe("When output_file is used, contains the absolute file path where data was written."),
 })
     .strict();

package/dist/schema/utils/node-parser.js

@@ -1,5 +1,5 @@
 import { NodeSchema } from '../call/machine.js';
-import { MachineNodeSchema } from '../query/index.js';
+import { MachineNodeSchema, MachineNodePairSchema, MachineForwardSchema } from '../query/index.js';
 import { writeFileSync } from 'fs';
 function detectFormat(text) {
     const trimmed = text.trim();
@@ -265,7 +265,7 @@ export function validateMachineNode(node) {
     return validateWithZod(MachineNodeSchema, node);
 }
 export function validateMachineNodePair(pair) {
-    const result = MachineNodeSchema.shape.pairs.element.safeParse(pair);
+    const result = MachineNodePairSchema.safeParse(pair);
     if (result.success) {
         return { success: true, errors: [] };
     }
@@ -276,7 +276,7 @@ export function validateMachineNodePair(pair) {
     return { success: false, errors };
 }
 export function validateMachineForward(forward) {
-    const result = MachineNodeSchema.shape.pairs.element.shape.forwards.element.safeParse(forward);
+    const result = MachineForwardSchema.safeParse(forward);
     if (result.success) {
         return { success: true, errors: [] };
     }
@@ -325,7 +325,10 @@ export function machineNodesToMarkdown(nodes, options = {}) {
                 for (const forward of pair.forwards) {
                     const namedOp = forward.namedOperator || '';
                     const permIdx = forward.permissionIndex?.toString() || '';
-                    const guard = forward.guard?.guard || '';
+                    const guardRaw = forward.guard;
+                    const guard = typeof guardRaw === 'string'
+                        ? guardRaw
+                        : (guardRaw?.guard || '');
                     md += `| ${forward.name} | ${forward.weight} | ${namedOp} | ${permIdx} | ${guard} |\n`;
                 }
                 md += `\n`;

package/dist/schema-query/index.d.ts

@@ -6,9 +6,12 @@ export interface SchemaInfo {
     outputPath?: string;
 }
 export interface SchemaQueryRequest {
-    action: "list" | "get" | "search" | "list_operations" | "get_output";
+    action: "list" | "get" | "search" | "list_operations" | "get_output" | "get_guard_templates" | "get_field";
     name?: string;
     query?: string;
+    field_path?: string;
+    template?: string;
+    output_file?: string;
 }
 export interface SchemaQueryResponse {
     [key: string]: unknown;
@@ -17,6 +20,7 @@ export interface SchemaQueryResponse {
     data: any;
     message: string;
     suggestions?: string[];
+    output_file_path?: string;
 }
 export declare function areSchemasAvailable(): boolean;
 export declare function getSchemaIndex(): {
@@ -26,6 +30,8 @@ export declare function getSchemaIndex(): {
 export declare function listSchemas(): SchemaInfo[];
 export declare function getSchema(name: string): any | null;
 export declare function getOutputSchema(name: string): any | null;
+export declare function getGuardTemplates(templateName?: string): any | null;
+export declare function getSchemaField(name: string, fieldPath: string): any | null;
 export declare function searchSchemas(query: string): SchemaInfo[];
 export declare function listOperations(): SchemaInfo[];
 export declare function processSchemaQuery(request: SchemaQueryRequest): SchemaQueryResponse;