# Stripe pack: recorder and OpenTelemetry setup

How an agent's tool calls become recorded actions of the [Stripe Customer Operations
pack](/docs/packs/stripe-customer-operations) without code of your own, and what OpenTelemetry adds. Both sections are the
pack's own templates, included from its files. The recorder's full reference is on the
[Python](/docs/recorder/python) and [TypeScript](/docs/recorder/js) recorder pages; the span
convention is on the [OpenTelemetry convention](/docs/otel-convention) page.

## MCP: record from the tool call itself

The MCP recorder is a stdio proxy between the agent and one MCP server. It forwards every message unchanged and
records each mapped `tools/call` as an action before forwarding it. It reads the request's `arguments`, never the
tool server's credentials or its answer.

```bash
pip install commitlayer-mcp-recorder
export COMMITLAYER_API_KEY="paste-your-recorder-key"

curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
  -H "X-API-Key: $COMMITLAYER_API_KEY" > recorder.json

commitlayer-mcp-recorder --map recorder.json --warn-unmapped -- your-mcp-server --its-arguments
```

Replace `your-mcp-server --its-arguments` with the command that starts your MCP server over stdio. The same
command line works for the TypeScript build (`npm install -g @commitlayer/mcp-recorder`). The key is a `recorder`
key (Settings, API keys); it can read the mapping and cannot push facts. The mapping is your workspace's own copy
with `contract_version` pinned to the drafts the install created, so fetch it after installing the pack and
activating its contracts: an action recorded against a draft nobody selected is refused (`409 contract_not_active`). The file
holds only the keys a recorder reads.

### What the mapping records

| Tool key | Contract | Subject | Action id |
|---|---|---|---|
| `stripe.refund` | `scop_refund_order` | `arguments.order_id` | `refund:{order_id}` |
| `stripe.refunds_create` | `scop_refund_order` | `arguments.metadata.order_id` | `refund:{order_id}` |
| `shopify.refund_order`, `shopify.cancel_order` | `scop_refund_order` | `arguments.order_id` | `refund:{order_id}` (the cancel and the refund are one action) |
| `stripe.subscriptions_cancel` | `scop_cancel_subscription` | `arguments.subscription` | `cancel:{subscription}` |
| `stripe.credit_notes_create` | `scop_issue_credit_note` | `arguments.invoice` | `credit:{invoice}` |
| `stripe.invoices_adjust`, `stripe.invoices_void` | `scop_adjust_invoice` | `arguments.invoice` | `adjust:{invoice}` |
| `zendesk.update_ticket`, or `intercom.close_conversation`, `salesforce.update_case`, `hubspot.update_ticket` | `scop_resolve_customer_case` | `zendesk_ticket_{ticket_id}`, `intercom_conv_{conversation_id}`, `sf_case_{case_id}`, `hubspot_ticket_{ticket_id}` | `resolve:{subject}` |

The tool keys and argument names are this pack's convention. They are not a verified list of any vendor's MCP
tool names: compare them with the `tools/list` answer of the server you run, and change the mapping where they
differ (below). The recorder matches the exact key first, then the first key whose part after the last dot is the
tool's name, so `subscriptions_cancel` on your server is matched by `stripe.subscriptions_cancel`.

Things to know before the first call:

- **Amounts.** `stripe.refunds_create` and `stripe.credit_notes_create` are declared `units: {amount: minor}`:
  the tool sends `4000` for forty dollars, as the Stripe API does, and the intake records `40.0` and keeps what
  was sent under `action.units`. Every other tool key is read as sent, in major units. If your tool sends cents
  under another key, add `"units": {"amount": "minor"}` to its rule in the annotated document (below). The
  conversion goes by the call's `currency`: divided by 100, and taken as sent for the currencies Stripe's
  currency page lists as zero-decimal (JPY and KRW among them). A call that states no currency is read as
  hundredths, and `action.units` says so (`currency: null, decimals: 2`); this pack's keys for Stripe's own
  refund and credit-note calls read `arguments.currency`, and whether your server's tool carries one is yours to
  check. Three-decimal currencies are read as hundredths.
- **One action, said twice.** A retry, or the second mapped tool for the same order, renders the same action id
  and is the same action when it agrees with the first record on every parameter both carry; the first record
  stands. The reason is left out of that comparison (`describes` on the rule). Another amount, customer, payment
  or support case under the same id is refused with `409 conflict`, and so is a later call that states a
  parameter a check reads when the first did not: a cancellation recorded without `refund_amount`, then a refund
  with an amount, is two statements the first record cannot hold, and the action stays UNKNOWN on policy.
- **Arguments the checks read.** A refund must carry `amount`; a cancellation must carry `cancel_at_period_end`
  (`true` or `false`); a case resolution must carry `resolution_kind`. A call without one is recorded, and its
  action is UNKNOWN on the policy lens (`param_missing:<name>`) where it would have passed. If your tool has no
  such argument, record the action from your own code instead (the REST or SDK example), where you can state it.
- **Order id.** The refund tools need the order id in the call (`order_id`, or `metadata.order_id` for
  `stripe.refunds_create`). A call without it is forwarded and not recorded; the recorder logs the missing path.
- **One action per order, subscription, invoice or case.** A retried call, or a second mapped tool for the same
  order (a cancel after a refund), renders the same action id and is the same action: the first record stands. A
  call that gives another amount for the same id is refused with `409 conflict` and logged; the call itself is
  still forwarded unless you run with `--no-fail-open`.
- **Your help desk only.** The served mapping holds the rule of the help desk your `resolve_customer_case`
  contract reads (Zendesk by default), not the other three.
- **Help-desk subjects need a newer recorder.** The help-desk rules build the subject from a template
  (`zendesk_ticket_{arguments.ticket_id}`). The published recorders (`commitlayer-mcp-recorder` 0.1.1 on PyPI,
  `@commitlayer/mcp-recorder` 0.1.2 on npm) read a subject as a plain path, forward those calls unrecorded and log
  the unresolved path; subject templates are in the client repository from recorder 0.1.3 (Python) and 0.1.4
  (TypeScript), which are not published yet. The Stripe and Shopify rules record with the published versions.
- **A general update tool.** A rule fires on every call of its tool. `zendesk.update_ticket`,
  `salesforce.update_case` and `hubspot.update_ticket` are recorded as a resolution whenever they are called,
  whatever the update was. If your agent uses the tool for other updates, remove the rule and record the
  resolution from your own code.

### Change or extend the mapping

The mapping is yours to edit. The file a recorder reads holds the recorder's own keys only, so edit the annotated
document instead: it is the same mapping with the keys only the API reads (`units`, `when_source` and `describes` in a rule,
`consequential_tools`, `read_only_tools` and `customised_at` at the top).

```bash
export COMMITLAYER_FULL_KEY="paste-your-full-key"   # a key with the full preset (Settings, API keys)

curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping?annotated=true" \
  -H "X-API-Key: $COMMITLAYER_FULL_KEY" > mapping.json
```

In `mapping.json`, rename a key to the name your server gives the tool, change a path to your tool's argument, add
a rule for another tool, list your own `consequential_tools`. Then store it and fetch the recorder's file again:

```bash
curl -sS -X PUT "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
  -H "X-API-Key: $COMMITLAYER_FULL_KEY" -H "Content-Type: application/json" \
  -d "{\"mapping\": $(cat mapping.json)}"

curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
  -H "X-API-Key: $COMMITLAYER_API_KEY" > recorder.json
```

Storing needs a key with every scope (the `full` preset): a recorder key is refused with `403`, because the
mapping decides which calls are recorded at all. A rule that leaves out `units`, `when_source` or `describes`
keeps what the stored rule of the same tool name has, so `recorder.json` sent back does not take the unit off an
amount; send a key empty (`"units": {}`) to remove it. A tool you rename has no stored rule: state its `units`
again, or its amount is read in major units from then on. A rule must name a `contract_id` that is an action contract of your workspace and a `subject`; a rule for one
of the pack's contracts without `contract_version` is pinned to the installed draft. The stored copy is kept
through an upgrade and a rollback; only the help desk's rule changes with `helpdesk_source`. Do not give `mapping.json` to a recorder: the TypeScript recorder refuses a
file with a key it does not know. There is no editor for the mapping in the app yet; the pack's Recorder mapping
tab shows it read-only.

### The warning for tools without a rule

`--warn-unmapped` logs, once per tool name, every call the recorder forwarded without a rule. It is off unless
you pass it, and it cannot tell a refund from a read. To make the warning visible to the workspace, report the
tool names your server exposes, with the server's own read-only flag where it has one:

```bash
curl -sS -X POST "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/observed-tools" \
  -H "X-API-Key: $COMMITLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"tools": [{"name": "stripe.payouts_create"}, {"name": "stripe.invoices_list", "read_only": true}]}'
```

`GET /v1/packs/stripe_customer_operations/coverage` then lists under `unmapped_consequential_tools` every
reported tool that has no rule and was not read-only when first reported, together with every tool in the mapping's
`consequential_tools` that has no rule; the pack's Coverage page in the app shows the same list. The recorder does
not send this report itself yet, so a tool nobody listed and nobody reported is not known to CommitLayer.

The read-only flag counts the first time a name is reported. A tool once reported as changing something stays
so through this route, because it accepts the recorder's key and that key must not be able to quieten the
warning. If a read was reported without the flag, list it under `read_only_tools` at the top of `mapping.json`
and store the mapping (above); coverage then stops warning for it.

### The CommitLayer MCP server

Separate from the recorder: the CommitLayer MCP server gives an assistant read access to packs. Its pack tools
are `list_workflow_packs`, `get_workflow_pack`, `get_pack_requirements`, `validate_pack_configuration`,
`dry_run_workflow_pack`, `draft_pack_contract`, `compare_pack_versions`, `get_pack_coverage` and
`get_pack_scenarios`. None of them installs, activates, weakens a contract or pushes a fact; a person activates
in the app or with `POST /v1/contracts/{id}/select`.

## OpenTelemetry: runtime context beside the verdict, not a way to record a pack action

OpenTelemetry ingestion does not record an action under a pack contract today. Record the action with the REST
API, an SDK or the MCP recorder. What the ingestion does with an agent's spans is narrower:

- A span that carries `agent.action.type` and `agent.action.subject_id` becomes a **fact** with source `otel`,
  classed `runtime_context`. It ranks as `self_reported` whatever trust is declared, and no check of this pack
  reads the `otel` source, so it never satisfies an expected effect. It does count as a fact on the subject: an
  action that would have read UNKNOWN `identity_unmatched`, because nothing was known about its subject, is
  judged on its expected effects instead and reads FAIL while they are missing. It appears in the fact list of
  an action on the same subject, as context for the person reading the verdict.
- A span that carries `agent.outcome.type` and `agent.outcome.subject_id` becomes a **claim** under the
  `internal_agent_otel` contract (an outcome claim for statements), not a pack action.
- Every other attribute is dropped at ingestion. The convention is in `docs/otel-convention.md`.

### Setup

A signed-in admin creates the source in the app (Internal agents); the route behind it, `POST /v1/otel/sources`,
does not accept an API key. The answer shows the endpoint once, with its key in the URL. The endpoint accepts OTLP/HTTP **JSON** only: a protobuf body is answered
`415`, so set your exporter or collector to `http/json`.

```bash
export COMMITLAYER_API="https://api.commitlayer.ai"
export OTEL_ENDPOINT_KEY="paste-the-endpoint-key"

curl -sS -X POST "$COMMITLAYER_API/v1/otel/$OTEL_ENDPOINT_KEY/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [{
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8aa5a2d2c872e8321cf37308d69df2",
          "spanId": "051581bf3cb55c13",
          "name": "stripe.credit_notes_create",
          "startTimeUnixNano": "1794474120000000000",
          "endTimeUnixNano": "1794474121000000000",
          "attributes": [
            {"key": "agent.action.type", "value": {"stringValue": "credit_note_requested"}},
            {"key": "agent.action.subject_id", "value": {"stringValue": "in_1PxYz"}},
            {"key": "agent.name", "value": {"stringValue": "billing-agent"}}
          ]
        }]
      }]
    }]
  }'
```

The answer is `{"accepted": 1, "claims": 0, "facts": 1}`: one span read, one `agent_action` fact on `in_1PxYz`.
Use the Stripe id of the subscription or invoice (or your order id) as `agent.action.subject_id`, so the fact
lands on the subject the action names.

What stays out of the span: the Stripe secret key, the customer's email or card, the response body. Only the
attributes above are kept.
