@ton-agent-kit/plugin-escrow 1.0.3 → 1.1.1

package/README.md

@@ -0,0 +1,61 @@
+# @ton-agent-kit/plugin-escrow
+
+Escrow plugin for on-chain escrow with self-selecting arbiters, staking, and dispute-resolution voting on TON. Manages the full lifecycle of escrow deals from creation through settlement.
+
+Part of [TON Agent Kit](https://github.com/Andy00L/ton-agent-kit).
+
+## Install
+
+```bash
+npm install @ton-agent-kit/plugin-escrow @ton-agent-kit/core zod
+```
+
+## Usage
+
+```typescript
+import { TonAgentKit, KeypairWallet } from "@ton-agent-kit/core";
+import EscrowPlugin from "@ton-agent-kit/plugin-escrow";
+
+const agent = new TonAgentKit(wallet).use(EscrowPlugin);
+
+// Create an escrow deal
+const escrow = await agent.runAction("create_escrow", {
+  beneficiary: "EQBx...",
+  amount: "1.5",
+});
+
+// Release funds after delivery
+await agent.runAction("release_escrow", { escrowId: escrow.id });
+```
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `create_escrow` | Create a new escrow deal (arbiters self-select during disputes). |
+| `deposit_to_escrow` | Fund an escrow with TON. |
+| `release_escrow` | Release funds to beneficiary (depositor only, non-dispute). |
+| `refund_escrow` | Refund funds to depositor. |
+| `get_escrow_info` | Get escrow details or list all escrows. |
+| `confirm_delivery` | Confirm service delivery on-chain (buyer only). |
+| `auto_release_escrow` | Release after deadline (requires delivery confirmation). |
+| `open_dispute` | Open a dispute, freezing the escrow for arbiter voting. |
+| `join_dispute` | Stake TON to join as an arbiter in a dispute. |
+| `vote_release` | Arbiter votes to release funds during a dispute. |
+| `vote_refund` | Arbiter votes to refund funds during a dispute. |
+| `claim_reward` | Claim arbiter reward after settlement. |
+| `fallback_settle` | Settle after the 72h voting deadline expires. |
+| `seller_stake_escrow` | Seller stakes TON to signal commitment to the deal. |
+
+## Documentation
+
+See [docs/escrow-system.md](https://github.com/Andy00L/ton-agent-kit/blob/main/docs/escrow-system.md) for the full escrow system design.
+
+## Links
+
+- [GitHub](https://github.com/Andy00L/ton-agent-kit)
+- [npm](https://www.npmjs.com/package/@ton-agent-kit/plugin-escrow)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton-agent-kit/plugin-escrow",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "Escrow plugin for TON Agent Kit — create, fund, release, and refund escrow deals",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/actions/auto-release-escrow.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, saveEscrows, autoReleaseOnContract, getLatestTxHash } from "../utils";
+
+export const autoReleaseEscrowAction = defineAction({
+  name: "auto_release_escrow",
+  description:
+    "Auto-release escrow funds to the beneficiary after the deadline has passed. Requires delivery confirmation from the buyer (confirm_delivery). Fails if delivery was never confirmed or if escrow is disputed.",
+  schema: z.object({
+    escrowId: z
+      .string()
+      .describe("Escrow ID to auto-release after deadline"),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) throw new Error(`Escrow not found: ${params.escrowId}`);
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    await autoReleaseOnContract(agent, contractAddress);
+
+    escrow.status = "auto-released";
+    saveEscrows(escrows);
+
+    const txHash = await getLatestTxHash(
+      contractAddress.toRawString(),
+      agent.network,
+    );
+
+    // Save pending bidirectional ratings (non-critical)
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_buyer`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "buyer",
+          targetAddress: escrow.beneficiary,
+          suggestedSuccess: true,
+          escrowOutcome: "auto-released",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_seller`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "seller",
+          targetAddress: escrow.depositor,
+          suggestedSuccess: true,
+          escrowOutcome: "auto-released",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+
+    return {
+      released: true,
+      escrowId: params.escrowId,
+      contractAddress: escrow.contractAddress,
+      friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+      beneficiary: escrow.beneficiary,
+      autoReleaseTxHash: txHash,
+      message: `Escrow ${params.escrowId} auto-released to beneficiary after deadline.`,
+    };
+  },
+});

package/src/actions/claim-reward.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, claimRewardOnContract, getLatestTxHash } from "../utils";
+
+export const claimRewardAction = defineAction({
+  name: "claim_reward",
+  description:
+    "Claim arbiter reward after an escrow dispute is settled. Winners get back their stake + share of losers' stakes. Losers forfeit their stake.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to claim arbiter reward from"),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) {
+      return { claimed: false, message: `Escrow not found: ${params.escrowId}` };
+    }
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    try {
+      await claimRewardOnContract(agent, contractAddress);
+
+      const txHash = await getLatestTxHash(
+        agent.wallet.address.toRawString(),
+        agent.network,
+      );
+
+      return {
+        claimed: true,
+        escrowId: params.escrowId,
+        contractAddress: escrow.contractAddress,
+        friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+        arbiter: agent.wallet.address.toRawString(),
+        claimTxHash: txHash,
+        message: `Claim submitted for escrow ${params.escrowId}. If you voted with the majority, reward is sent to your wallet.`,
+      };
+    } catch (err: any) {
+      return {
+        claimed: false,
+        escrowId: params.escrowId,
+        error: err.message,
+        message: `Failed to claim reward: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/confirm-delivery.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, saveEscrows, confirmDeliveryOnContract, getLatestTxHash } from "../utils";
+
+export const confirmDeliveryAction = defineAction({
+  name: "confirm_delivery",
+  description:
+    "Confirm that a service was delivered for an escrow deal. Only the depositor (buyer) can call this. Once confirmed, auto-release becomes available after the deadline. The x402TxHash serves as an audit trail linking the payment to the delivery.",
+  schema: z.object({
+    escrowId: z
+      .string()
+      .describe("Escrow ID to confirm delivery for"),
+    x402TxHash: z
+      .string()
+      .optional()
+      .describe("Optional x402 payment TX hash as proof of service delivery"),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) {
+      return {
+        confirmed: false,
+        message: `Escrow not found: ${params.escrowId}`,
+      };
+    }
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    try {
+      await confirmDeliveryOnContract(agent, contractAddress, params.x402TxHash || "");
+
+      escrow.status = "delivery-confirmed";
+      saveEscrows(escrows);
+
+      const txHash = await getLatestTxHash(
+        contractAddress.toRawString(),
+        agent.network,
+      );
+
+      return {
+        confirmed: true,
+        escrowId: params.escrowId,
+        contractAddress: escrow.contractAddress,
+        friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+        x402TxHash: params.x402TxHash || null,
+        confirmTxHash: txHash,
+        message: `Delivery confirmed on-chain for escrow ${params.escrowId}. Auto-release will be available after deadline.`,
+      };
+    } catch (err: any) {
+      return {
+        confirmed: false,
+        escrowId: params.escrowId,
+        error: err.message,
+        message: `Failed to confirm delivery: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/create-escrow.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { Address } from "@ton/core";
+import { Address, toNano } from "@ton/core";
 import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
 import {
   loadEscrows,
@@ -7,11 +7,14 @@ import {
   deployEscrowContract,
   type EscrowRecord,
 } from "../utils";
+import { resolveContractAddress } from "../../../plugin-identity/src/reputation-config";
 
 export const createEscrowAction = defineAction<
   {
     beneficiary: string;
     amount: string;
+    minArbiters?: number;
+    minStake?: string;
     description?: string;
     deadlineTimestamp?: number;
     deadlineDays?: number;
@@ -23,31 +26,24 @@ export const createEscrowAction = defineAction<
   name: "create_escrow",
   description:
     "Create a new on-chain escrow deal. Deploys a Tact Escrow contract to TON. " +
-    "The beneficiary receives funds when released. " +
-    "Deadline can be set via deadlineTimestamp (exact Unix timestamp), deadlineDays, deadlineHours, or deadlineMinutes. " +
-    "Priority: timestamp > days > hours > minutes. Defaults to 60 minutes if none provided.",
+    "No arbiters needed upfront — they self-select by staking during disputes. " +
+    "minArbiters sets the minimum arbiters needed for voting (default 3). " +
+    "minStake sets the minimum stake per arbiter in TON (default 0.5).",
   schema: z.object({
     beneficiary: z
       .string()
       .describe("Address of the beneficiary (who receives funds)"),
     amount: z.string().describe("Amount of TON to escrow"),
+    minArbiters: z.coerce.number().optional().describe("Minimum arbiters for dispute voting. Default 3."),
+    minStake: z.string().optional().describe("Minimum stake per arbiter in TON. Default 0.5."),
+    requireRepCollateral: z.boolean().optional().describe("Require reputation-based collateral from seller. Default false."),
+    minRepScore: z.coerce.number().optional().describe("Minimum rep score for seller (0-100). Default 30. Only if requireRepCollateral=true."),
+    baseSellerStake: z.string().optional().describe("Base seller stake in TON before rep adjustment. Default 0.5. Only if requireRepCollateral=true."),
     description: z.string().optional().describe("Description of the deal"),
-    deadlineTimestamp: z.coerce
-      .number()
-      .optional()
-      .describe("Exact deadline as Unix timestamp (seconds). Takes highest priority."),
-    deadlineDays: z.coerce
-      .number()
-      .optional()
-      .describe("Deadline in days from now (e.g., 90 for ~3 months)"),
-    deadlineHours: z.coerce
-      .number()
-      .optional()
-      .describe("Deadline in hours from now (e.g., 24 for 1 day)"),
-    deadlineMinutes: z.coerce
-      .number()
-      .optional()
-      .describe("Deadline in minutes from now (e.g., 60 for 1 hour). Default if nothing else set."),
+    deadlineTimestamp: z.coerce.number().optional().describe("Exact deadline as Unix timestamp (seconds)."),
+    deadlineDays: z.coerce.number().optional().describe("Deadline in days from now"),
+    deadlineHours: z.coerce.number().optional().describe("Deadline in hours from now"),
+    deadlineMinutes: z.coerce.number().optional().describe("Deadline in minutes from now. Default 60."),
   }) as any,
   handler: async (agent, params) => {
     const escrowId = `escrow_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -66,27 +62,42 @@ export const createEscrowAction = defineAction<
 
     const depositor = agent.wallet.address;
     const beneficiary = Address.parse(params.beneficiary);
-    const arbiter = agent.wallet.address; // Agent is arbiter by default
+    const minArbiters = params.minArbiters || 3;
+    const minStakeNano = toNano(params.minStake || "0.5");
+
+    // Layer 3+4: Rep collateral
+    const requireRepCollateral = params.requireRepCollateral || false;
+    const minRepScore = params.minRepScore || 30;
+    const baseSellerStake = params.baseSellerStake || "0.5";
+    const baseSellerStakeNano = toNano(baseSellerStake);
+
+    // Resolve reputation contract for cross-contract notifications
+    const repAddr = resolveContractAddress(undefined, agent.network);
+    const reputationContract = repAddr ? Address.parse(repAddr) : depositor; // fallback
 
-    // Deploy a new Escrow contract on-chain
     const contractAddress = await deployEscrowContract(
       agent,
       depositor,
       beneficiary,
-      arbiter,
       BigInt(deadline),
+      BigInt(minArbiters),
+      minStakeNano,
+      reputationContract,
+      requireRepCollateral,
+      BigInt(minRepScore),
+      baseSellerStakeNano,
     );
 
-    // Save to JSON index (escrowId → contract address mapping)
     const escrow: EscrowRecord = {
       id: escrowId,
       contractAddress: contractAddress.toRawString(),
       depositor: depositor.toRawString(),
       beneficiary: params.beneficiary,
-      arbiter: arbiter.toRawString(),
       amount: params.amount,
       deadline,
       deadlineISO: new Date(deadline * 1000).toISOString(),
+      minArbiters,
+      minStake: params.minStake || "0.5",
       description: params.description || "",
       status: "created",
       createdAt: new Date().toISOString(),
@@ -103,10 +114,17 @@ export const createEscrowAction = defineAction<
       friendlyContract: toFriendlyAddress(contractAddress, agent.network),
       beneficiary: params.beneficiary,
       friendlyBeneficiary: toFriendlyAddress(beneficiary, agent.network),
+      minArbiters,
+      minStake: params.minStake || "0.5",
       amount: params.amount + " TON",
       deadline: escrow.deadlineISO,
+      requireRepCollateral,
+      minRepScore: requireRepCollateral ? minRepScore : "disabled",
+      baseSellerStake: requireRepCollateral ? baseSellerStake + " TON" : "not required",
       description: params.description || "",
-      nextStep: `Deposit ${params.amount} TON using deposit_to_escrow with escrowId: ${escrowId}`,
+      nextStep: requireRepCollateral
+        ? `Seller must stake first using seller_stake_escrow, then deposit ${params.amount} TON`
+        : `Deposit ${params.amount} TON using deposit_to_escrow with escrowId: ${escrowId}`,
     };
   },
 });

package/src/actions/fallback-settle.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, saveEscrows, fallbackSettleOnContract, getLatestTxHash } from "../utils";
+
+export const fallbackSettleAction = defineAction({
+  name: "fallback_settle",
+  description:
+    "Settle a disputed escrow after the 72h voting deadline. If not enough arbiters joined or votes are tied, " +
+    "settles based on delivery status. Anyone can call after votingDeadline.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to settle after voting timeout"),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) {
+      return { settled: false, message: `Escrow not found: ${params.escrowId}` };
+    }
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    try {
+      await fallbackSettleOnContract(agent, contractAddress);
+
+      escrow.status = "fallback-settled";
+      saveEscrows(escrows);
+
+      const txHash = await getLatestTxHash(
+        contractAddress.toRawString(),
+        agent.network,
+      );
+
+      return {
+        settled: true,
+        escrowId: params.escrowId,
+        contractAddress: escrow.contractAddress,
+        friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+        settleTxHash: txHash,
+        message: `Escrow ${params.escrowId} settled via fallback after voting deadline.`,
+      };
+    } catch (err: any) {
+      return {
+        settled: false,
+        escrowId: params.escrowId,
+        error: err.message,
+        message: `Fallback settle failed: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/get-escrow-info.ts

@@ -35,19 +35,37 @@ export const getEscrowInfoAction = defineAction<{ escrowId?: string }, any>({
           onChain: {
             depositor: toFriendlyAddress(onChain.depositor, agent.network),
             beneficiary: toFriendlyAddress(onChain.beneficiary, agent.network),
-            arbiter: toFriendlyAddress(onChain.arbiter, agent.network),
+            reputationContract: toFriendlyAddress(onChain.reputationContract, agent.network),
             amount: fromNano(onChain.amount) + " TON",
             balance: fromNano(onChain.balance) + " TON",
             deadline: new Date(Number(onChain.deadline) * 1000).toISOString(),
             released: onChain.released,
             refunded: onChain.refunded,
+            deliveryConfirmed: onChain.deliveryConfirmed,
+            disputed: onChain.disputed,
+            votingDeadline: onChain.votingDeadline ? new Date(Number(onChain.votingDeadline) * 1000).toISOString() : null,
+            arbiterCount: Number(onChain.arbiterCount),
+            votesRelease: Number(onChain.votesRelease),
+            votesRefund: Number(onChain.votesRefund),
+            minArbiters: Number(onChain.minArbiters),
+            minStake: fromNano(onChain.minStake) + " TON",
+            sellerStake: fromNano(onChain.sellerStake) + " TON",
+            sellerStaked: onChain.sellerStaked,
+            requireSellerStake: onChain.requireSellerStake,
+            baseSellerStake: fromNano(onChain.baseSellerStake) + " TON",
+            requireRepCollateral: onChain.requireRepCollateral,
+            minRepScore: Number(onChain.minRepScore),
+            autoReleaseAvailable: onChain.autoReleaseAvailable,
+            refundAvailable: onChain.refundAvailable,
             status: onChain.released
               ? "released"
               : onChain.refunded
                 ? "refunded"
-                : onChain.amount > BigInt(0)
-                  ? "funded"
-                  : "created",
+                : onChain.disputed
+                  ? "disputed"
+                  : onChain.amount > BigInt(0)
+                    ? "funded"
+                    : "created",
           },
         };
       } catch (e: any) {

package/src/actions/join-dispute.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, joinDisputeOnContract, getLatestTxHash } from "../utils";
+
+export const joinDisputeAction = defineAction({
+  name: "join_dispute",
+  description:
+    "Join an escrow dispute as an arbiter by staking TON. Self-selecting: any agent can join (except depositor/beneficiary). " +
+    "A 2% fee is deducted from the stake. Winners get back their stake + share of losers' stakes. Losers forfeit.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to join as arbiter"),
+    stake: z.string().optional().describe("Stake amount in TON (sent to contract, 2% fee deducted). Default 0.5."),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) {
+      return { joined: false, message: `Escrow not found: ${params.escrowId}` };
+    }
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+    const stakeAmount = params.stake || escrow.minStake || "0.5";
+
+    // Add 3% buffer to cover the 2% fee + gas
+    const stakeNum = parseFloat(stakeAmount);
+    const withBuffer = (stakeNum * 1.03).toFixed(9);
+
+    try {
+      await joinDisputeOnContract(agent, contractAddress, withBuffer);
+
+      const txHash = await getLatestTxHash(
+        agent.wallet.address.toRawString(),
+        agent.network,
+      );
+
+      return {
+        joined: true,
+        escrowId: params.escrowId,
+        contractAddress: escrow.contractAddress,
+        friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+        arbiter: agent.wallet.address.toRawString(),
+        stakeAmount: stakeAmount + " TON",
+        stakeTxHash: txHash,
+        message: `Joined dispute on escrow ${params.escrowId} with ${stakeAmount} TON stake. Vote with vote_release or vote_refund.`,
+      };
+    } catch (err: any) {
+      return {
+        joined: false,
+        escrowId: params.escrowId,
+        error: err.message,
+        message: `Failed to join dispute: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/open-dispute.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, saveEscrows, openDisputeOnContract, getLatestTxHash } from "../utils";
+
+export const openDisputeAction = defineAction({
+  name: "open_dispute",
+  description:
+    "Open a dispute on an escrow deal. Freezes the escrow so only arbiter voting (or single-arbiter decision) can settle it. Only the depositor or beneficiary can open a dispute.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to open a dispute on"),
+  }),
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) {
+      return { disputed: false, message: `Escrow not found: ${params.escrowId}` };
+    }
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    try {
+      await openDisputeOnContract(agent, contractAddress);
+
+      escrow.status = "disputed";
+      saveEscrows(escrows);
+
+      const txHash = await getLatestTxHash(
+        agent.wallet.address.toRawString(),
+        agent.network,
+      );
+
+      return {
+        disputed: true,
+        escrowId: params.escrowId,
+        contractAddress: escrow.contractAddress,
+        friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+        arbiterCount: escrow.arbiterCount || 1,
+        arbiters: escrow.arbiters || [escrow.arbiter],
+        disputeTxHash: txHash,
+        message: `Dispute opened on escrow ${params.escrowId}. ${
+          (escrow.arbiterCount || 1) > 1
+            ? `Waiting for ${Math.floor((escrow.arbiterCount || 1) / 2) + 1}/${escrow.arbiterCount} arbiter votes.`
+            : "Single arbiter can now release or refund."
+        }`,
+      };
+    } catch (err: any) {
+      return {
+        disputed: false,
+        escrowId: params.escrowId,
+        error: err.message,
+        message: `Failed to open dispute: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/refund-escrow.ts

@@ -44,6 +44,37 @@ export const refundEscrowAction = defineAction<{ escrowId: string }, any>({
     escrow.status = "refunded";
     saveEscrows(escrows);
 
+    // Save pending bidirectional ratings (non-critical)
+    // Refund = deal failed — negative ratings for both
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_buyer`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "buyer",
+          targetAddress: escrow.beneficiary,
+          suggestedSuccess: false,
+          escrowOutcome: "refunded",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_seller`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "seller",
+          targetAddress: escrow.depositor,
+          suggestedSuccess: false,
+          escrowOutcome: "refunded",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+
     return {
       escrowId: params.escrowId,
       status: "refunded (on-chain)",

package/src/actions/release-escrow.ts

@@ -39,6 +39,36 @@ export const releaseEscrowAction = defineAction<{ escrowId: string }, any>({
     escrow.status = "released";
     saveEscrows(escrows);
 
+    // Save pending bidirectional ratings (non-critical)
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_buyer`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "buyer",
+          targetAddress: escrow.beneficiary,
+          suggestedSuccess: true,
+          escrowOutcome: "released",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+    try {
+      await (agent as any).runAction("save_context", {
+        key: `pending_rating_${params.escrowId}_seller`,
+        namespace: "pending_ratings",
+        value: JSON.stringify({
+          escrowId: params.escrowId,
+          raterRole: "seller",
+          targetAddress: escrow.depositor,
+          suggestedSuccess: true,
+          escrowOutcome: "released",
+          timestamp: Date.now(),
+        }),
+      });
+    } catch {}
+
     return {
       escrowId: params.escrowId,
       status: "released (on-chain)",