aba-payway-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# ABA PayWay Agent (Agentic CLI)

The agentic CLI lets a supported provider propose and run PayWay actions through a
risk-gated pipeline. It is the safest way to let an LLM drive PayWay: **no
side-effecting call runs unless the plan validates, is authorized, and is
materialized through the execution ledger.**

## Quick Start

```sh
# 1. Configure the provider (API key stays in the environment, never stored).
#    Presets: opencode (free) | openai | openrouter | nvidia | custom
export PAYWAY_AGENT_API_KEY=sk-...
payway-sdk agent setup --provider opencode --model deepseek-v4-flash-free --capability-mode strict-json-plan \
  --max-tokens 8192 --temperature 0.2
# For NVIDIA thinking models add: --extra-body '{"chat_template_kwargs":{"enable_thinking":false}}'

# 2. First run must acknowledge the privacy notice, then ask.
payway-sdk ask "Generate a $3 online QR for sandbox" --yolo
```

The provider config shape (stored as plaintext, no secrets; managed by
`payway-sdk agent setup` — you normally never write it by hand) is:

```ts
// ProviderConfigV1 lives in the SDK source (src/agent/contracts.ts).
// The package exports only the root entrypoint ("."), so import the
// PayWay client from 'aba-payway-ts' and manage agent config via the CLI:
//   payway-sdk agent setup --provider opencode --model deepseek-v4-flash-free \
//     --capability-mode strict-json-plan
const config = {
  version: 'agent-config/v1',
   provider: 'opencode',               // 'opencode' | 'openai' | 'openrouter' | 'nvidia' | 'custom'
   model: 'deepseek-v4-flash-free',    // rotate as the provider's catalog changes — a dead model fails with 401 "not supported"
  capabilityMode: 'strict-json-plan', // 'native-tools' | 'strict-json-plan'
  privacyAcknowledgedAt: new Date().toISOString(),
};
```

## Provider capability modes

- **`native-tools`** — the provider emits tool calls directly (function calling).
  Every call is validated against the tool schemas before execution.
- **`strict-json-plan`** — the provider returns a single JSON plan of `actions`;
  the orchestrator normalizes, authorizes, and executes them one by one. This is
  the default and the most auditable mode.

Both modes funnel through the same safety pipeline; only the plan source differs.

## The 14 tools

| # | Tool | Create? | Purpose / key inputs |
|---|---|---|---|
| 1 | `generate_online_qr` | yes | Online QR via PayWay API. `amount`, `currency`, `callbackUrl`, `transactionId?` |
| 2 | `generate_offline_khqr` | yes | Local-only ABA KHQR. `amount?`, `currency`, `merchantRef` |
| 3 | `create_checkout_payload` | yes | LOCAL signed checkout payload (no network). `amount`, `currency`, `transactionId?` |
| 4 | `create_checkout_purchase` | yes | NETWORK checkout request to PayWay. `amount`, `currency`, `transactionId?` |
| 5 | `create_payment_link` | yes | Shareable link (needs RSA). `title`, `amount`, `currency`, `merchantRefNo`, `returnUrl`, `payout?` |
| 6 | `get_payment_link_details` | no | Read-only payment-link lookup by `paymentLinkId` (the opaque Link ID from create) |
| 7 | `check_transaction` | no | Read-only status lookup by `transactionId` |
| 8 | `check_transaction_by_merchant_ref` | no | Read-only lookup by `merchantRef` |
| 9 | `poll_transaction` | no | Read-only repeated lookup (sandbox verification) by `transactionId` |
| 10 | `query_journal` | no | Read-only local journal query: `timeline`, `stats`, `reconcile`, or `anomalies` |
| 11 | `save_artifact` | no | Persist a produced artifact to `./payway-output` |
| 12 | `open_artifact` | no | Open a saved artifact |
| 13 | `copy_to_clipboard` | no | Copy an artifact value to the clipboard |
| 14 | `query_knowledge` | no | Read-only offline knowledge base: `query: search|read` over the curated PayWay corpus (`payway-sdk docs`) — pull integration guidance, error hints, and sandbox-verified lessons into a plan |

> `create_checkout_payload` builds a **local** signed payload; `create_checkout_purchase`
> performs the actual **network** request. Treat them as distinct tools.

## Resolved context (no ambient override)

The effective PayWay context is resolved **once** from the selected CLI profile
(`--profile` / `PAYWAY_PROFILE` / saved default / active profile). A selected
profile's credentials are authoritative; **stale ambient `PAYWAY_MERCHANT_ID` /
`PAYWAY_API_KEY` values MUST NOT override it**, and a provider plan can never
change the selected profile or environment. The context is what the executor
uses — the provider only receives a scrubbed, secret-free summary.

## Risk gates

| Invocation | Sandbox create | Production create |
|---|---|---|
| `ask ... --approve` | allowed | allowed (authorizes both) |
| `ask ... --yolo` | allowed (sandbox only) | **refused** — `--approve` required |
| `ask ...` in a TTY | interactive confirmation | interactive confirmation |
| `ask ...` in non-TTY, no flag | `needs_confirmation` — **no create** | `needs_confirmation` — **no create** |

Read-only tools (`get_payment_link_details`, `check_transaction`,
`check_transaction_by_merchant_ref`, `poll_transaction`, and `query_journal`)
never require approval. Plans containing only read-only
actions run without a flag. A resumed session restores **no** stored approval —
it returns `needs_confirmation` and must be re-confirmed.

## Execution ledger

Every create action passes through versioned ledger records with a strict,
non-replayable lifecycle:

```
planned -> confirmed -> submitted -> succeeded | failed | outcome_unknown
```

- `planned`: created when the plan is accepted (no PayWay call yet).
- `confirmed`: a `transactionId` is generated and bound to the materialized plan.
- `submitted`: the single SDK call runs.
- terminal: `succeeded`, `failed`, or `outcome_unknown` (network/timeout — verify before retrying).

Ledger records are **never replayed**. A crash between `confirmed` and `submitted`
executes zero PayWay creates.

## Local utilities

- `payway-sdk agent doctor` — prints the capability matrix (provider connectivity,
  context, online QR, offline KHQR, checkout, payment-link RSA, artifact/session storage).
  Every non-ready row includes a `→` fix hint pointing at the command that resolves it.
- `payway-sdk onboard` — **guided interactive setup**. Scans state, shows a
  configured/missing checklist, then runs the needed stages in order: inference provider

From Ruzaid-aman/ABA-Payway-SDK-unofficial, MIT.

More from Ruzaid-aman/ABA-Payway-SDK-unofficial