@t2000/engine 0.7.6 → 0.7.8

package/README.md

@@ -87,7 +87,7 @@ QueryEngine.submitMessage()
 
 ## Built-in Tools
 
-### Read Tools (19 — parallel, auto-approved)
+### Read Tools (20 — parallel, auto-approved)
 
 | Tool | Description |
 |------|-------------|
@@ -96,6 +96,7 @@ QueryEngine.submitMessage()
 | `health_check` | Health factor with risk assessment |
 | `rates_info` | Current supply/borrow APYs |
 | `transaction_history` | Recent transaction log |
+| `allowance_status` | Agent budget allowance and permissions |
 | `explain_tx` | Human-readable transaction explanation from digest |
 | `web_search` | Web search via Brave Search API |
 | `swap_quote` | Preview swap route, output amount, and price impact (no execution) |

package/dist/index.d.ts

@@ -850,6 +850,7 @@ declare const withdrawTool: Tool<{
 declare const sendTransferTool: Tool<{
     amount: number;
     to: string;
+    memo?: string | undefined;
 }, {
     success: boolean;
     tx: string;
@@ -859,6 +860,7 @@ declare const sendTransferTool: Tool<{
     gasCost: number;
     gasMethod: _t2000_sdk.GasMethod;
     balance: _t2000_sdk.BalanceResponse;
+    memo: string | null;
 }>;
 
 declare const borrowTool: Tool<{

package/dist/index.js

@@ -1135,7 +1135,8 @@ var sendTransferTool = buildTool({
   description: "Send USDC to another Sui address or contact name. Validates the address, checks balance, and executes the on-chain transfer. Returns tx hash, gas cost, and updated balance.",
   inputSchema: z.object({
     to: z.string().min(1),
-    amount: z.number().positive()
+    amount: z.number().positive(),
+    memo: z.string().optional()
   }),
   jsonSchema: {
     type: "object",
@@ -1147,6 +1148,10 @@ var sendTransferTool = buildTool({
       amount: {
         type: "number",
         description: "Amount in USD to send"
+      },
+      memo: {
+        type: "string",
+        description: "Optional note attached to the transfer (shown in transaction receipt)"
       }
     },
     required: ["to", "amount"]
@@ -1165,7 +1170,8 @@ var sendTransferTool = buildTool({
         contactName: result.contactName,
         gasCost: result.gasCost,
         gasMethod: result.gasMethod,
-        balance: result.balance
+        balance: result.balance,
+        memo: input.memo ?? null
       },
       displayText: `Sent $${result.amount.toFixed(2)} to ${result.contactName ?? result.to.slice(0, 10)}\u2026 (tx: ${result.tx.slice(0, 8)}\u2026)`
     };
@@ -1295,7 +1301,15 @@ var payApiTool = buildTool({
 
 Use mpp_services tool first to discover available services and get the correct endpoint URL, required body parameters, and pricing. Then call this tool with the full URL and JSON body.
 
-Always use POST. Construct the URL from the gateway base + service path. Pass parameters as a JSON string in body.`,
+Always use POST. Construct the URL from the gateway base + service path. Pass parameters as a JSON string in body.
+
+CRITICAL \u2014 non-retryable errors: If the result contains "doNotRetry": true or "paymentConfirmed": true, the user has ALREADY been charged. NEVER call pay_api again for the same request. Report the error to the user.
+
+Lob (postcards/letters) \u2014 MULTI-STEP, NEVER skip:
+1. Generate design image FIRST via fal/fal-ai/flux/dev ($0.03). Show the image to the user as markdown ![design](url).
+2. Ask the user to confirm before mailing ("Here's the design. Print and mail for $1.00?").
+3. ONLY after user confirms: call lob/v1/postcards with the image URL in the front HTML (<img src="URL" style="width:100%;height:100%;object-fit:cover"/>).
+Always use ISO-3166 country codes (GB not UK, US not USA). A return address ("from") is added automatically \u2014 do not include one.`,
   inputSchema: z.object({
     url: z.string().url(),
     method: z.enum(["GET", "POST", "PUT", "DELETE"]).optional(),
@@ -1971,6 +1985,246 @@ Risks: ${riskFactors.join("; ")}`
     };
   }
 });
+var allowanceStatusTool = buildTool({
+  name: "allowance_status",
+  description: "Check the agent spending allowance status: whether it is enabled, the daily USDC limit, amount spent today, remaining budget, which service categories are permitted, and when the budget resets. Use this when the user asks about their agent budget, spending limits, or autonomous transaction permissions.",
+  inputSchema: z.object({}),
+  jsonSchema: { type: "object", properties: {}, required: [] },
+  isReadOnly: true,
+  async call(_input, context) {
+    if (!context.env?.ALLOWANCE_API_URL || !context.walletAddress) {
+      return {
+        data: {
+          enabled: false,
+          dailyLimit: 0,
+          spent: 0,
+          remaining: 0,
+          permissions: [],
+          resetsAt: null
+        },
+        displayText: "Agent allowance is not configured."
+      };
+    }
+    const disabledResult = {
+      data: {
+        enabled: false,
+        dailyLimit: 0,
+        spent: 0,
+        remaining: 0,
+        permissions: [],
+        resetsAt: null
+      },
+      displayText: "Unable to fetch allowance status."
+    };
+    let allowance;
+    try {
+      const url = `${context.env.ALLOWANCE_API_URL}/api/allowance/${context.walletAddress}`;
+      const res = await fetch(url, {
+        signal: context.signal,
+        headers: context.env.AUDRIC_INTERNAL_KEY ? { "x-internal-key": context.env.AUDRIC_INTERNAL_KEY } : void 0
+      });
+      if (!res.ok) return disabledResult;
+      allowance = await res.json();
+    } catch {
+      return disabledResult;
+    }
+    const statusText = allowance.enabled ? `Allowance active: $${allowance.spent.toFixed(2)} / $${allowance.dailyLimit.toFixed(2)} used today. ${allowance.permissions.length} service categories enabled.` : "Agent allowance is disabled.";
+    return {
+      data: allowance,
+      displayText: statusText
+    };
+  }
+});
+var PaymentLinkSchema = z.object({
+  amount: z.number().positive().optional().describe("Amount in USDC. Omit for open-amount links."),
+  label: z.string().optional().describe('Human-readable label e.g. "Consulting fee March"'),
+  memo: z.string().optional().describe("Optional note shown to the payer"),
+  expiresInHours: z.number().positive().optional().describe("Hours until the link expires. Omit for permanent links.")
+});
+var InvoiceSchema = z.object({
+  amount: z.number().positive().describe("Total invoice amount in USDC"),
+  label: z.string().describe('Invoice title e.g. "Web design \u2014 March 2026"'),
+  memo: z.string().optional().describe("Optional note or payment terms"),
+  recipientName: z.string().optional().describe("Name of the person or company being invoiced"),
+  recipientEmail: z.string().optional().describe("Email address of the recipient"),
+  dueDays: z.number().int().positive().optional().describe("Days until payment is due. Omit for no due date."),
+  items: z.array(z.object({
+    description: z.string(),
+    amount: z.number().positive()
+  })).optional().describe("Line items. If omitted, a single line item matching the total is implied.")
+});
+var createPaymentLinkTool = buildTool({
+  name: "create_payment_link",
+  description: 'Create a shareable payment link so someone can send USDC to the user. Returns a URL the user can share. Use when the user says "create a payment link", "generate a payment link", "I want to get paid", or similar.',
+  inputSchema: PaymentLinkSchema,
+  jsonSchema: {
+    type: "object",
+    properties: {
+      amount: { type: "number", description: "Amount in USDC. Omit for open-amount links." },
+      label: { type: "string", description: 'Human-readable label e.g. "Consulting fee March"' },
+      memo: { type: "string", description: "Optional note shown to the payer" },
+      expiresInHours: { type: "number", description: "Hours until the link expires. Omit for permanent links." }
+    },
+    required: []
+  },
+  isReadOnly: false,
+  async call(input, context) {
+    const apiUrl = context.env?.ALLOWANCE_API_URL;
+    const internalKey = context.env?.AUDRIC_INTERNAL_KEY;
+    if (!apiUrl || !context.walletAddress) {
+      return { data: null, displayText: "Payment link creation is not available." };
+    }
+    try {
+      const res = await fetch(`${apiUrl}/api/internal/payment-links`, {
+        method: "POST",
+        signal: context.signal,
+        headers: {
+          "Content-Type": "application/json",
+          "x-sui-address": context.walletAddress,
+          ...internalKey ? { "x-internal-key": internalKey } : {}
+        },
+        body: JSON.stringify(input)
+      });
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        return { data: null, displayText: err.error ?? "Failed to create payment link." };
+      }
+      const link = await res.json();
+      const amountStr = link.amount != null ? `$${link.amount.toFixed(2)} ${link.currency}` : `any amount ${link.currency}`;
+      return {
+        data: link,
+        displayText: `Payment link created for ${amountStr}${link.label ? ` \u2014 ${link.label}` : ""}. Share: ${link.url}`
+      };
+    } catch {
+      return { data: null, displayText: "Failed to create payment link." };
+    }
+  }
+});
+var listPaymentLinksTool = buildTool({
+  name: "list_payment_links",
+  description: `List the user's payment links \u2014 active, paid, expired, and cancelled. Use when the user asks "show my payment links", "what payment links do I have", or wants to check payment status.`,
+  inputSchema: z.object({}),
+  jsonSchema: { type: "object", properties: {}, required: [] },
+  isReadOnly: true,
+  async call(_input, context) {
+    const apiUrl = context.env?.ALLOWANCE_API_URL;
+    const internalKey = context.env?.AUDRIC_INTERNAL_KEY;
+    if (!apiUrl || !context.walletAddress) {
+      return { data: { links: [] }, displayText: "No payment links found." };
+    }
+    try {
+      const res = await fetch(`${apiUrl}/api/internal/payment-links`, {
+        signal: context.signal,
+        headers: {
+          "x-sui-address": context.walletAddress,
+          ...internalKey ? { "x-internal-key": internalKey } : {}
+        }
+      });
+      if (!res.ok) return { data: { links: [] }, displayText: "Could not fetch payment links." };
+      const data = await res.json();
+      const count = data.links.length;
+      return {
+        data,
+        displayText: count === 0 ? "No payment links yet." : `${count} payment link${count !== 1 ? "s" : ""} found.`
+      };
+    } catch {
+      return { data: { links: [] }, displayText: "Could not fetch payment links." };
+    }
+  }
+});
+var createInvoiceTool = buildTool({
+  name: "create_invoice",
+  description: 'Create a formal invoice that the user can share with a client or customer. Returns a URL for the invoice page. Use when the user says "create an invoice", "generate an invoice", "bill a client", or similar.',
+  inputSchema: InvoiceSchema,
+  jsonSchema: {
+    type: "object",
+    properties: {
+      amount: { type: "number", description: "Total invoice amount in USDC" },
+      label: { type: "string", description: 'Invoice title e.g. "Web design \u2014 March 2026"' },
+      memo: { type: "string", description: "Optional note or payment terms" },
+      recipientName: { type: "string", description: "Name of the person or company being invoiced" },
+      recipientEmail: { type: "string", description: "Email address of the recipient" },
+      dueDays: { type: "number", description: "Days until payment is due. Omit for no due date." },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            description: { type: "string" },
+            amount: { type: "number" }
+          },
+          required: ["description", "amount"]
+        },
+        description: "Line items. If omitted, a single line item matching the total is implied."
+      }
+    },
+    required: ["amount", "label"]
+  },
+  isReadOnly: false,
+  async call(input, context) {
+    const apiUrl = context.env?.ALLOWANCE_API_URL;
+    const internalKey = context.env?.AUDRIC_INTERNAL_KEY;
+    if (!apiUrl || !context.walletAddress) {
+      return { data: null, displayText: "Invoice creation is not available." };
+    }
+    try {
+      const res = await fetch(`${apiUrl}/api/internal/invoices`, {
+        method: "POST",
+        signal: context.signal,
+        headers: {
+          "Content-Type": "application/json",
+          "x-sui-address": context.walletAddress,
+          ...internalKey ? { "x-internal-key": internalKey } : {}
+        },
+        body: JSON.stringify(input)
+      });
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        return { data: null, displayText: err.error ?? "Failed to create invoice." };
+      }
+      const invoice = await res.json();
+      const dueStr = invoice.dueDate ? ` due ${new Date(invoice.dueDate).toLocaleDateString()}` : "";
+      return {
+        data: invoice,
+        displayText: `Invoice created for $${invoice.amount.toFixed(2)} ${invoice.currency}${dueStr} \u2014 ${invoice.label}. Share: ${invoice.url}`
+      };
+    } catch {
+      return { data: null, displayText: "Failed to create invoice." };
+    }
+  }
+});
+var listInvoicesTool = buildTool({
+  name: "list_invoices",
+  description: `List the user's invoices \u2014 pending, overdue, paid, and cancelled. Use when the user asks "show my invoices", "what invoices do I have", or wants to check invoice status.`,
+  inputSchema: z.object({}),
+  jsonSchema: { type: "object", properties: {}, required: [] },
+  isReadOnly: true,
+  async call(_input, context) {
+    const apiUrl = context.env?.ALLOWANCE_API_URL;
+    const internalKey = context.env?.AUDRIC_INTERNAL_KEY;
+    if (!apiUrl || !context.walletAddress) {
+      return { data: { invoices: [] }, displayText: "No invoices found." };
+    }
+    try {
+      const res = await fetch(`${apiUrl}/api/internal/invoices`, {
+        signal: context.signal,
+        headers: {
+          "x-sui-address": context.walletAddress,
+          ...internalKey ? { "x-internal-key": internalKey } : {}
+        }
+      });
+      if (!res.ok) return { data: { invoices: [] }, displayText: "Could not fetch invoices." };
+      const data = await res.json();
+      const count = data.invoices.length;
+      return {
+        data,
+        displayText: count === 0 ? "No invoices yet." : `${count} invoice${count !== 1 ? "s" : ""} found.`
+      };
+    } catch {
+      return { data: { invoices: [] }, displayText: "Could not fetch invoices." };
+    }
+  }
+});
 var LLAMA_API2 = "https://api.llama.fi";
 var YIELDS_API2 = "https://yields.llama.fi";
 var COINS_API = "https://coins.llama.fi";
@@ -2273,7 +2527,10 @@ var READ_TOOLS = [
   defillamaPriceChangeTool,
   defillamaChainTvlTool,
   defillamaProtocolFeesTool,
-  defillamaSuiProtocolsTool
+  defillamaSuiProtocolsTool,
+  allowanceStatusTool,
+  listPaymentLinksTool,
+  listInvoicesTool
 ];
 var WRITE_TOOLS = [
   saveDepositTool,
@@ -2286,7 +2543,9 @@ var WRITE_TOOLS = [
   swapExecuteTool,
   voloStakeTool,
   voloUnstakeTool,
-  saveContactTool
+  saveContactTool,
+  createPaymentLinkTool,
+  createInvoiceTool
 ];
 function getDefaultTools() {
   return [...READ_TOOLS, ...WRITE_TOOLS];