Audit Trail (Memo + Decision Context)

Every paid tool call accepts two optional audit fields that record why the agent made it. Both land on the receipt:

Field	Type	Purpose
`memo`	string (≤ 1000 chars)	Human-readable reason for the call. Appears on the receipt, which helps when triaging spend or debugging an agent.
`decisionContext`	object	Machine-readable companion. Open schema with known fields (`goal`, `goalId`, `alternatives`, `confidence`) plus any extras. Read by supervisor / auditor agents.

The SDK logs a warning (not an error) when a paid tool is called without memo. Read them back with 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

Without an SDK, 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

Bad audit values never block a call. The SDK validates lightly on the client 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

Where it shows up

Both fields are written to the receipt when it is created:

{
  "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"
}

GET /v1/analytics/receipts returns them with the other receipt attributes, with no extra request.

When to use which

Memo only: quick debugging. Set a one-line reason (“why am I calling this?”) on every paid call. The SDK logs a warning if you forget.
Memo + decisionContext: agents under programmatic oversight (supervisor agents, audit pipelines, eval rigs). A downstream system can reason about the structured context without parsing prose.
Neither: acceptable for fire-and-forget scripts where receipts don’t matter. The SDK won’t block the call, but there is no audit trail.

Tag vs memo vs decisionContext

Each field records something different 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 link input to outcome, which RoCS is computed from.

​TypeScript SDK

​Python SDK

​Raw HTTP

​Validation

​Where it shows up

​When to use which

​Tag vs memo vs decisionContext