feat(M4): acp-sdk-ts: LLM helpers (availableTools, toMessages, executeTool)

packages/acp-sdk-ts/package.json

@@ -15,6 +15,10 @@
     "./providers/alchemy": {
       "types": "./dist/providers/alchemy.d.ts",
       "import": "./dist/providers/alchemy.js"
+    },
+    "./llm": {
+      "types": "./dist/llm/index.d.ts",
+      "import": "./dist/llm/index.js"
     }
   },
   "files": ["dist", "README.md"],

packages/acp-sdk-ts/src/__tests__/__snapshots__/llm-tools.test.ts.snap

@@ -0,0 +1,133 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`availableTools > schema is stable 1`] = `
+[
+  {
+    "function": {
+      "description": "Register a new ACP agent on chain via AgentRegistry.register. Returns the new agentId, tx hash, and the controller address that owns the agent. The connected signer pays gas.",
+      "name": "acp_register",
+      "parameters": {
+        "additionalProperties": false,
+        "properties": {
+          "capabilities": {
+            "description": "Packed capability bitmap as a decimal-encoded uint256 (e.g. \`"5"\` for caps 1+4).",
+            "pattern": "^(0|[1-9][0-9]*)$",
+            "type": "string",
+          },
+          "controller": {
+            "description": "Optional. Address that will control the agent on chain. Defaults to the connected signer's address.",
+            "pattern": "^0x[0-9a-fA-F]{40}$",
+            "type": "string",
+          },
+          "metadataUri": {
+            "description": "Non-empty URI pointing to off-chain agent metadata. Typically \`ipfs://<cid>\` or \`https://...\`.",
+            "type": "string",
+          },
+        },
+        "required": [
+          "metadataUri",
+          "capabilities",
+        ],
+        "type": "object",
+      },
+    },
+    "type": "function",
+  },
+  {
+    "function": {
+      "description": "Browse the on-chain agent registry through the gateway. Read-only; does not require a signer. Returns a paginated AgentsPage with \`data\` and \`next_cursor\`.",
+      "name": "acp_browse",
+      "parameters": {
+        "additionalProperties": false,
+        "properties": {
+          "cursor": {
+            "description": "Opaque pagination cursor returned in the previous page's \`next_cursor\`. Omit for the first page.",
+            "type": "string",
+          },
+          "kind": {
+            "description": "Filter by agent kind. Omit to return both.",
+            "enum": [
+              "launchpad",
+              "acp",
+            ],
+            "type": "string",
+          },
+          "limit": {
+            "description": "Page size in [1, 200]. Defaults to 50 server-side.",
+            "maximum": 200,
+            "minimum": 1,
+            "type": "integer",
+          },
+        },
+        "type": "object",
+      },
+    },
+    "type": "function",
+  },
+  {
+    "function": {
+      "description": "Create a new ACP job on chain via JobFactory.createJob. The connected signer must have already approved the JobFactory for \`budget\` of \`token\` (the SDK does not move ERC-20 allowance on its own). Returns the new jobId, the deployed clone address, and the tx hash.",
+      "name": "acp_create_job",
+      "parameters": {
+        "additionalProperties": false,
+        "properties": {
+          "arbiter": {
+            "description": "Optional arbiter override; falls back to the factory's default arbiter.",
+            "pattern": "^0x[0-9a-fA-F]{40}$",
+            "type": "string",
+          },
+          "budget": {
+            "description": "Amount to lock into Escrow (in token base units). Must be > 0.",
+            "pattern": "^(0|[1-9][0-9]*)$",
+            "type": "string",
+          },
+          "deadline": {
+            "description": "UNIX seconds after which the job may be expired. Must be in the future.",
+            "pattern": "^(0|[1-9][0-9]*)$",
+            "type": "string",
+          },
+          "evaluator": {
+            "description": "Required iff \`jobType\` is \`evaluated\`; ignored otherwise. Must be a non-zero address.",
+            "pattern": "^0x[0-9a-fA-F]{40}$",
+            "type": "string",
+          },
+          "hooks": {
+            "description": "Optional list of pre-approved hook addresses.",
+            "items": {
+              "description": "EVM address as a \`0x\`-prefixed 20-byte hex string.",
+              "pattern": "^0x[0-9a-fA-F]{40}$",
+              "type": "string",
+            },
+            "type": "array",
+          },
+          "jobType": {
+            "description": "Job type. \`evaluated\` requires \`evaluator\`. Defaults to \`direct\` when omitted.",
+            "enum": [
+              "direct",
+              "evaluated",
+            ],
+            "type": "string",
+          },
+          "targetAgentId": {
+            "description": "Optional agent registry id to target. Pass \`"0"\` (or omit) to leave the job open to any active agent.",
+            "pattern": "^(0|[1-9][0-9]*)$",
+            "type": "string",
+          },
+          "token": {
+            "description": "ERC-20 payment token address. Must not be the zero address.",
+            "pattern": "^0x[0-9a-fA-F]{40}$",
+            "type": "string",
+          },
+        },
+        "required": [
+          "token",
+          "budget",
+          "deadline",
+        ],
+        "type": "object",
+      },
+    },
+    "type": "function",
+  },
+]
+`;