Audit Trail (Memo + Decision Context)

Every paid tool call accepts two optional audit fields:

Field	Type	Purpose
`memo`	string (≤ 1000 chars)	Human-readable reason this tool was called. Shows up on the receipt — useful when you’re triaging spend or debugging an agent that went off the rails.
`decisionContext`	object	Machine-readable companion. Open schema with known fields (`goal`, `goalId`, `alternatives`, `confidence`) plus any extras. Consumed by supervisor / auditor agents.

The SDK warns (does not error) when a paid tool is called without memo. Both fields are stored on the receipt — see GET /v1/analytics/receipts.

TypeScript SDK

import { OneShot } from "@oneshot-agent/sdk";

const agent = await OneShot.create({ cdp: true });

await agent.email(
  { to: "[email protected]", subject: "Follow-up", body: "..." },
  {
    memo: "Following up on demo request from yesterday's webinar",
    decisionContext: {
      goal: "Convert webinar leads to discovery calls",
      goalId: "goal_01HX...",
      alternatives: ["sms_send", "voice_call"],
      confidence: 0.78,
      // Open schema — any extra keys are stored verbatim
      campaign: "webinar-q2",
    },
  },
);

memo is plain text. decisionContext is any JSON-serialisable object — known fields are typed (see DecisionContext in the SDK types), extras are kept as-is.

Python SDK

from oneshot import OneShot

agent = OneShot.create(cdp=True)

await agent.email(
    {"to": "[email protected]", "subject": "Follow-up", "body": "..."},
    memo="Following up on demo request from yesterday's webinar",
    decision_context={
        "goal": "Convert webinar leads to discovery calls",
        "goalId": "goal_01HX...",
        "alternatives": ["sms_send", "voice_call"],
        "confidence": 0.78,
        "campaign": "webinar-q2",
    },
)

Python accepts both decisionContext and decision_context — the SDK normalises to camelCase before sending.

Raw HTTP

If you’re not using an SDK, just include memo and decisionContext in the JSON body of any paid tool call:

curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: ..." \
  -d '{
    "quote_id": "qte_01HX...",
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Follow-up",
    "body": "...",
    "memo": "Following up on demo request from yesterday'\''s webinar",
    "decisionContext": {
      "goal": "Convert webinar leads to discovery calls",
      "confidence": 0.78
    }
  }'

Validation

The SDK does light client-side validation before sending:

memo over 1000 chars → truncated with a warning log
memo empty / non-string → dropped silently
decisionContext.confidence outside [0, 1] → dropped silently
decisionContext non-object → dropped silently

These guardrails keep malformed values from blocking the underlying tool call.

Where it shows up

Both fields are written onto the receipt at creation time:

{
  "receipt_id": "rcpt_01HGW2HB4V4T0PZGJ8PFDRCHQM",
  "category": "communication",
  "subcategory": "email",
  "amount_usdc": "0.150000",
  "memo": "Following up on demo request from yesterday's webinar",
  "decisionContext": {
    "goal": "Convert webinar leads to discovery calls",
    "confidence": 0.78,
    "campaign": "webinar-q2"
  },
  "status": "settled",
  "created_at": "2026-05-11T14:30:00Z"
}

Query via GET /v1/analytics/receipts. The fields are returned alongside every other receipt attribute — no extra request needed.

When to use which

Memo only — quick debugging. Set it on every paid call as a one-liner (“why am I calling this?”). The SDK nudges you with a warn log if you forget.
Memo + decisionContext — agents under programmatic oversight (supervisor agents, audit pipelines, eval rigs). The structured context lets a downstream system reason about the decision without parsing prose.
Neither — fine for fire-and-forget scripts where the receipts are noise. The SDK won’t block you; you just lose the audit trail.

Tag vs memo vs decisionContext

These three fields tell different stories about the same receipt:

Field	Set when	Answers
`memo`	At call time	Why did I make this call?
`decisionContext`	At call time	What was the structured reasoning?
`value_tag`	After the outcome is known — via PATCH `/v1/analytics/receipts/{receiptId}/value`	Did this call generate value?

Together they form the input → outcome chain that powers RoCS.

​TypeScript SDK

​Python SDK

​Raw HTTP

​Validation

​Where it shows up

​When to use which

​Tag vs memo vs decisionContext