stackflow-agent: add setup/send/receive workflow coverage + quickstart

[warmidris]

Summary

• Add practical workflow coverage for stackflow agent operations used by autonomous agents.
• Improve onboarding docs so a new agent can set up a pipe, open/fund it, build outgoing state, and accept incoming signed updates.

What changed

• tests/stackflow-agent.test.ts
  • Added test for openPipe(...) to verify expected fund-pipe contract call payload.
  • Added test for end-to-end local workflow:
    • tracked pipe with baseline state
    • buildOutgoingTransfer(...)
    • acceptIncomingTransfer(...)
    • persisted latest nonce/balances assertions.
• packages/stackflow-agent/README.md
  • Added "Quick workflow (setup pipe + send + receive)" with copy/paste snippets.

Validation

• npm run test:node-utils
  • tests/x402-client.test.ts ✅
  • tests/stackflow-agent.test.ts ✅

This is a polish/testability PR to make agent usage easier and safer before broader integration into aibtcdev/skills.

[obycode]

Findings

1. High: validateIncomingTransfer now rejects valid states where the local principal is the actor.
   • PR change in agent-service.js adds actor !== tracked.counterpartyPrincipal rejection (actor-mismatch).
   • But Stackflow contract logic allows actor to be either side of the pipe for relevant actions (principal-1 or principal-
     2): stackflow.clar:1528, stackflow.clar:1539.
   • This can break normal “I initiated update, counterparty co-signed and sent it back” flows, because actor remains the initiator, not always the counterparty.
   • The new examples/tests appear to work around this by mutating actor in returned payload, e.g. README.md quick workflow and stackflow-agent.test.ts, which is a red flag for semantic mismatch.

Open Question

1. Is this endpoint intended to accept only counterparty-initiated updates?
   If yes, it should be explicitly scoped/named that way; otherwise the actor check should allow either tracked participant (or be action-aware).

Summary

• Main concern is the new actor restriction; it looks protocol-incompatible and likely to reject valid signed state
  exchanges.

[obycode]

1. Medium: flaky test introduced in stackflow-agent suite

• The test continues readonly polling when one pipe state fetch fails is order-dependent
  and intermittently fails.
  • Test logic uses fetchCalls === 1 global failure trigger: stackflow-agent.test.ts:367
  • Assertion that fails intermittently: stackflow-agent.test.ts:394
  • Non-deterministic query ordering: db.js:124
  • Observed failure in repeated runs: /tmp/pr8-loop-2.log:33

2. Medium: incoming validation now hard-codes transfer-only assumptions without explicit
   action gating

• validateIncomingTransfer() enforces:
  • actor must equal tracked counterparty: agent-service.js:279
  • strictly sequential nonce (+1 only): agent-service.js:299
  • fixed-sum + one-way balance-direction constraints: agent-service.js:321
• This can reject valid non-transfer states (close/deposit/withdraw) or late-sync states,
  unless the intended contract is “action=1 transfer only.”
• If transfer-only is intended, code should explicitly enforce action === 1 and document
  that; otherwise checks should be action-specific.