saltapp-agentkit

Staging repo for a Salt (saltapp.ai) action provider for Coinbase AgentKit, in both Python and TypeScript. This is not a runnable AgentKit checkout -- it holds only the new provider files, laid out at the same relative paths they will occupy in a fork of coinbase/agentkit, plus a local test harness for the TypeScript side so those files can be built and tested without vendoring the whole monorepo.

See HANDOFF.md for the full design rationale (why the two languages don't share a dependency shape, why the TypeScript side has a local test harness, what was verified and how, and known gaps). This file is the short version: what's here, where it goes, how to run the tests.

What the provider does

Seven actions on Salt, the end-to-end encrypted chat app where humans and AI agents message each other and move money in the conversation: send an encrypted message, ask a specific human a question and wait for their answer (with resume support), request a payment, send an itemized invoice, check a payment's status, and pay an incoming request from the agent's own AgentKit wallet. Same actions, same names, same behavior in both languages -- see each provider's own README.md for the full list and their current limits.

Layout, and where each part goes in a coinbase/agentkit fork

saltapp-agentkit/
├── HANDOFF.md                     # Design rationale + verification record -- read this first
├── README.md                       # This file
├── python/
│   └── coinbase-agentkit/
│       ├── coinbase_agentkit/action_providers/salt/    -> same path in the fork
│       │   ├── __init__.py
│       │   ├── salt_action_provider.py
│       │   ├── schemas.py
│       │   ├── constants.py
│       │   └── ask_poll.py
│       └── tests/action_providers/salt/                -> same path in the fork
│           └── test_salt_action_provider.py
└── typescript/
    ├── .changeset/                 # Empty scaffold; not meaningfully used yet
    └── agentkit/
        ├── src/
        │   ├── action-providers/
        │   │   ├── salt/                                -> same path in the fork, verbatim
        │   │   │   ├── saltActionProvider.ts / .test.ts
        │   │   │   ├── schemas.ts
        │   │   │   ├── constants.ts
        │   │   │   ├── types.ts
        │   │   │   ├── saltRestClient.ts
        │   │   │   ├── saltCrypto.ts / .test.ts
        │   │   │   ├── verifyEnvelope.ts / .test.ts
        │   │   │   ├── askPoll.ts
        │   │   │   ├── index.ts
        │   │   │   └── README.md
        │   │   ├── index.ts         # -> overwrites the fork's real file (one line added, see HANDOFF.md)
        │   │   ├── actionProvider.ts # LOCAL TEST SHIM ONLY -- do not copy, see HANDOFF.md
        │   │   └── actionDecorator.ts # LOCAL TEST SHIM ONLY -- do not copy, see HANDOFF.md
        │   ├── network/index.ts      # LOCAL TEST SHIM ONLY -- do not copy
        │   └── wallet-providers/index.ts # LOCAL TEST SHIM ONLY -- do not copy
        ├── package.json               # LOCAL HARNESS ONLY -- but see HANDOFF.md for the one
        │                               #   real dependency (openpgp) the fork's package.json needs added
        ├── tsconfig.json               # LOCAL HARNESS ONLY
        ├── jest.config.cjs             # LOCAL HARNESS ONLY
        └── jest.setup.cjs              # LOCAL HARNESS ONLY

Every file under action-providers/salt/ (both languages) is the actual PR payload, meant to be copied verbatim. Everything marked "LOCAL … ONLY" exists solely so this repo's own test suite can run in isolation and is not meant to be copied into the fork -- the fork already has its own real versions of those files. HANDOFF.md has the full explanation and a table of exactly what changes where, including the one dependency (openpgp) that needs adding to the fork's real typescript/agentkit/package.json and the current, verified gap on the Python side (saltapp, the SDK this provider depends on, is not yet published to PyPI -- see HANDOFF.md's "Known gap" section).

Running the tests

TypeScript -- fully working, self-contained:

cd typescript/agentkit
npm install
npm test          # jest: 2 suites / 37 tests
npm run build      # tsc --noEmit

This has also been verified against the real @coinbase/agentkit framework code (not just this repo's local shims) by briefly copying action-providers/salt/* into a separate checkout of the actual monorepo and running its real compiler and test runner. See HANDOFF.md for what that caught and fixed.

Python -- not runnable standalone in this staging repo (no pyproject.toml here), but verified good: copied into a real coinbase/agentkit checkout, uv sync + the local saltapp wheel installed into that venv, uv run pytest tests/action_providers/salt/ -v -> 27 passed, 0 failed. saltapp (Salt's own Python SDK, which the provider imports) is not published to PyPI yet, which is what blocks running it here and blocks the eventual PR from being installable -- the code itself works. See HANDOFF.md.

Opening the PR

Not done here -- forking coinbase/agentkit, copying files per the layout above, and submitting is left as an owner-gated next step.