feat: add WIP x402 client SDK and stackflow agent scaffolds

Author: obycode

README.md

@@ -550,6 +550,9 @@ This repo includes a starter x402-style gateway at
 Detailed technical design and production guidance:
 
 - `server/X402_GATEWAY_DESIGN.md`
+- `server/X402_CLIENT_SDK_DESIGN.md`
+- `packages/x402-client/` (SDK scaffold with SQLite-backed client state store)
+- `server/STACKFLOW_AGENT_DESIGN.md` (simple agent runtime without local node)
 
 Run it with:
 
@@ -705,6 +708,26 @@ Current scaffold scope:
 2. one-time proof consumption per method/path within replay TTL
 3. single protected route configuration (expand to route policy map as next step)
 
+## Agent Scaffold
+
+This repo includes an agent-first Stackflow scaffold at
+`packages/stackflow-agent/` for deployments that do not run local
+`stacks-node`/`stackflow-node`.
+
+It provides:
+
+1. SQLite persistence for tracked pipes and latest signatures
+2. AIBTC MCP wallet adapter hooks for `sip018_sign`, `call_contract`, and
+   read-only `get-pipe`
+3. hourly closure watcher (default `60 * 60 * 1000`) that polls tracked pipes
+   via read-only `get-pipe` and can auto-submit
+   disputes when a newer beneficial local signature state exists
+
+See:
+
+1. `packages/stackflow-agent/README.md`
+2. `server/STACKFLOW_AGENT_DESIGN.md`
+
 Integration tests for the HTTP server are opt-in (they spawn a real process and
 bind a local port):
 

package.json

@@ -9,6 +9,7 @@
     "init:stackflow": "node scripts/init-stackflow.js",
     "build:ui": "node scripts/build-ui.js",
     "test": "vitest run",
+    "test:node-utils": "vitest run -c vitest.node.config.js tests/x402-client.test.ts tests/stackflow-agent.test.ts",
     "test:stackflow-node:http": "STACKFLOW_NODE_HTTP_INTEGRATION=1 vitest run tests/stackflow-node-http.integration.test.ts",
     "test:report": "vitest run -- --coverage --costs",
     "test:watch": "chokidar \"tests/**/*.ts\" \"contracts/**/*.clar\" -c \"npm run test:report\"",

packages/stackflow-agent/README.md

@@ -0,0 +1,85 @@
+# @stackflow/agent (scaffold)
+
+Simple Stackflow agent runtime for AI agents that do **not** run `stacks-node`
+or `stackflow-node`.
+
+Current model:
+
+1. SQLite local state for tracked pipes and latest signatures
+2. signer + contract call adapter backed by AIBTC MCP wallet tools
+3. hourly chain watcher to detect force-close/force-cancel and dispute
+
+## Runtime Components
+
+1. `AgentStateStore`: SQLite persistence
+2. `StackflowAgentService`: pipe tracking + signature state + dispute logic
+3. `AibtcWalletAdapter`: wrapper around AIBTC MCP tools
+4. `HourlyClosureWatcher`: periodic closure scan (default every hour)
+
+## Example Wiring
+
+```js
+import {
+  AgentStateStore,
+  AibtcPipeStateSource,
+  AibtcWalletAdapter,
+  HourlyClosureWatcher,
+  StackflowAgentService,
+} from "./src/index.js";
+
+const stateStore = new AgentStateStore({
+  dbFile: "./tmp/stackflow-agent.db",
+});
+
+// You provide invokeTool using your MCP client runtime.
+const wallet = new AibtcWalletAdapter({
+  invokeTool: async (toolName, args) => {
+    // Example:
+    // return mcpClient.callTool({ name: toolName, arguments: args });
+    throw new Error("implement invokeTool");
+  },
+});
+
+const agent = new StackflowAgentService({
+  stateStore,
+  signer: wallet,
+  network: "devnet",
+  disputeOnlyBeneficial: true,
+});
+
+const pipeSource = new AibtcPipeStateSource({
+  walletAdapter: wallet,
+  contractId: "ST...stackflow",
+  network: "devnet",
+});
+
+const watcher = new HourlyClosureWatcher({
+  agentService: agent,
+  // Simpler mode: poll each tracked pipe via read-only `get-pipe`.
+  getPipeState: (args) => pipeSource.getPipeState(args),
+  intervalMs: 60 * 60 * 1000, // 1 hour
+});
+
+watcher.start();
+```
+
+## Core Operations
+
+1. `trackPipe(...)`
+2. `recordSignedState(...)`
+3. `openPipe(...)` (via wallet `call_contract`)
+4. `buildOutgoingTransfer(...)`
+5. `validateIncomingTransfer(...)`
+6. `acceptIncomingTransfer(...)` (validate + sign + persist)
+7. `evaluateClosureForDispute(...)`
+8. `disputeClosure(...)`
+9. `watcher.runOnce()` or `watcher.start()` for hourly checks
+
+## Notes
+
+1. This scaffold intentionally avoids observer endpoints and local chain node.
+2. The watcher interval defaults to one hour; dispute window is still 144 BTC blocks.
+3. `HourlyClosureWatcher` supports two sources:
+   - `getPipeState` (recommended): per-pipe read-only polling (`get-pipe`)
+   - `listClosureEvents`: event scan mode
+4. For production hardening, add alerting, signer balance checks, and idempotency audit logs.

packages/stackflow-agent/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@stackflow/agent",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  }
+}