What will the intent firewall check?

1. A plain API call

This is the refund that every backend already has. It returns and the code moves on.

const refund = await stripe.refunds.create({
  charge: chargeId,
  amount: 14200,
});

// 200. The object exists. Carry on.
return { ok: true, id: refund.id };

refund = stripe.Refund.create(
    charge=charge_id,
    amount=14200,
)

# 200. The object exists. Carry on.
return {"ok": True, "id": refund.id}

curl -X POST https://api.stripe.com/v1/refunds \
  -u "$STRIPE_SECRET_KEY:" \
  -d charge="$CHARGE_ID" -d amount=14200

# 200 {"id":"re_1Qx...","status":"pending"}

The status is pending, and only succeeded moves the money. Nothing above reads the status.

2. An agent calls the same thing

Put the same call behind a tool. Now nobody reads the response at all.

server.tool("refund_customer", schema, async ({ chargeId }) => {
  const refund = await stripe.refunds.create({ charge: chargeId, amount: 14200 });
  return { content: [{ type: "text", text: `refund ${refund.id} created` }] };
});

// The agent reads that sentence and answers: "Done. Refunded $142."

@server.tool("refund_customer")
def refund_customer(charge_id: str):
    refund = stripe.Refund.create(charge=charge_id, amount=14200)
    return f"refund {refund.id} created"

# The agent reads that sentence and answers: "Done. Refunded $142."

# The tool result the agent sees:
{"content":[{"type":"text","text":"refund re_1Qx... created"}]}

# The answer the customer sees:
Done. Refunded $142.

That sentence is evidence level E0. It is the agent repeating its own tool call, and it is never sufficient.

3. The same task, compiled

Pass the prompt and the context. Provely compiles the contract, and you confirm it before it runs. Read intent compilation.

const proposal = await provely.compileIntent({
  statement: "Refund order 4471 for $142 and email the customer.",
  context: { order_id: "4471", customer: "cus_8k2Rv1LmQ9xT" },
  tools: [{ name: "stripe.refunds.create", system: "stripe" }],
});

// Show proposal.review to a person. Confirm names every part it cannot check.
const { contract, confirmationId } = await provely.confirmIntent(proposal.proposalId, {
  proposalHash: proposal.proposalHash,
  confirmedBy: "alex@example.com",
  acknowledge: proposal.unchecked.map((part) => part.id),
});

const op = await provely.begin({
  contractId: contract.id,
  contractVersion: contract.version,
  confirmationId,
});

await agent.run(task, { idempotencyKey: op.idempotencyKey });
const v = await provely.verify(op.operationId, { waitMs: 600_000 });

proposal = provely.compile_intent(
    statement="Refund order 4471 for $142 and email the customer.",
    context={"order_id": "4471", "customer": "cus_8k2Rv1LmQ9xT"},
    tools=[{"name": "stripe.refunds.create", "system": "stripe"}],
)

# Show proposal.review to a person. Confirm names every part it cannot check.
confirmed = provely.confirm_intent(
    proposal.proposal_id,
    proposal_hash=proposal.proposal_hash,
    confirmed_by="alex@example.com",
    acknowledge_unchecked=[part.id for part in proposal.unchecked],
)

op = provely.begin(
    confirmed.contract_id,
    version=confirmed.contract_version,
    confirmation_id=confirmed.confirmation_id,
)

agent.run(task, idempotency_key=op.idempotency_key)
verdict = provely.verify(op.id, wait=600.0)

curl -X POST https://api.provely.sh/v1/intents \
  -H "Authorization: Bearer $PROVELY_API_KEY" \
  -d '{"statement":"Refund order 4471 for $142 and email the customer.",
       "context":{"order_id":"4471","customer":"cus_8k2Rv1LmQ9xT"},
       "tools":[{"name":"stripe.refunds.create","system":"stripe"}]}'

# A person reads the proposal, then confirms every part it does not check.
curl -X POST https://api.provely.sh/v1/intents/$PROPOSAL/confirm \
  -H "Authorization: Bearer $PROVELY_API_KEY" \
  -d '{"proposal_hash":"'$HASH'","confirmed_by":"alex@example.com",
       "acknowledged_unchecked":["u1"]}'

curl -X POST https://api.provely.sh/v1/operations \
  -H "Authorization: Bearer $PROVELY_API_KEY" \
  -d '{"contract":{"id":"order.refund.completed","version":"'$VERSION'"},
       "intent":{"confirmation_id":"'$CONFIRMATION'"}}'

The samples read the key from PROVELY_API_KEY. Get your API key: sign in at app.provely.sh/account/api-keys, open API keys, and create a key. The dashboard shows the key once. Keep it in an environment variable, never in code.

contract: order.refund.completed
subject:  { order_id: "4471" }
steps:
  - stripe.refund.succeeded
    evidence:  readback + refund.updated event
    correlate: [refund_id, payment_intent]
    amount:    14200 usd
negative:
  - no second settled refund for this payment intent
review:
  - "the customer" resolves to one address

Multi Action workflow

A person writes one sentence: "Refund order 4471 for $142, restock the item, tell the customer, and close the ticket." That sentence is four side effects in four systems. The agent reports one word at the end. This section follows it the whole way.

Step 1 of 5. Read the instruction as separate promises

A workflow is not one promise. It is one promise for each system that changes, and each system draws the line between an acknowledgement and an outcome somewhere else. The table below is the whole difficulty of the task in one place.

Every acknowledgement in this table is true the moment the agent finishes. Not one of them proves the outcome beside it.

Step 2 of 5. Name what must never happen

A missing step is the smaller danger. The larger one is a step that happens twice. A retry with no idempotency key refunds the customer again, and every positive check still passes. A workflow contract therefore carries negative postconditions, and they are checked with the same evidence as the positive ones.

• no second settled refund exists for this payment intent
• the inventory of this line item is adjusted once, not twice

Each step correlates on the resource that this run created. That is what stops a pre-existing match from verifying. Take an inventory count that already read the right number, a ticket that somebody closed yesterday, or a refund from last week. None of them satisfies a step, because none of them carries the id of this run.

Step 3 of 5. The contract that comes out

contract: support.refund_and_close
subject:  { order: "4471", customer: "cus_8k2Rv1LmQ9xT" }
steps:
  - id: stripe.refund.succeeded
    correlate_by: refund id
    evidence: readback by refund id, then the refund.updated event   # E2 + E3
  - id: shopify.inventory.adjusted
    correlate_by: line item id
    evidence: readback of the inventory level for the line item   # E2
  - id: resend.email.delivered
    correlate_by: message id
    evidence: the email.delivered event for the message id   # E3
  - id: helpdesk.ticket.closed
    correlate_by: ticket id
    evidence: readback of the ticket status   # E2
negative:
  - no second settled refund exists for this payment intent
  - the inventory of this line item is adjusted once, not twice

Step 4 of 5. Open one operation for the workflow

You open one operation for the workflow, let the agent do its work, and ask once. The agent needs no knowledge of the contract, and it holds no verifier credential.

const op = await provely.begin({
  contractId: 'support.refund_and_close',
  contractVersion: '1.0.0',
  input: { order: '4471', customer: 'cus_8k2Rv1LmQ9xT', amount_cents: 14200 },
  intent: task.prompt,
});

// Your agent runs. It uses op.idempotencyKey for every side effect.
await agent.run(task, { idempotencyKey: op.idempotencyKey });

const v = await provely.verify(op.operationId, { waitMs: 600_000 });
// v.verdict covers all four steps. v.steps holds one row for each of them, and
// v.verdictDocument.decided_by_step names the step that stopped the workflow.

op = provely.begin(
    "support.refund_and_close",
    version="1.0.0",
    input={"order": "4471", "customer": "cus_8k2Rv1LmQ9xT", "amount_cents": 14200},
    intent=task.prompt,
)

# Your agent runs. It uses op.idempotency_key for every side effect.
agent.run(task, idempotency_key=op.idempotency_key)

verdict = provely.verify(op.id, wait=600.0)
# verdict.verdict covers all four steps.
# verdict.decided_by_step names the step that stopped the workflow.

provely begin --contract support.refund_and_close --contract-version 1.0.0 \
  --input '{"order":"4471","customer":"cus_8k2Rv1LmQ9xT","amount_cents":14200}'

# the agent works with the key that begin printed, then:
provely verify "$OPERATION_ID" --wait 10m --json

Step 5 of 5. Read the audit

The agent reported "Refunded and closed." Three steps passed. The audit below is what the runtime observed, step by step, and it is the same list that the signed receipt carries.

The workflow is not done. Three of four steps carry evidence, and the fourth carries only the word of the agent. An agent assertion is E0, and E0 is never sufficient, so the verdict is UNVERIFIABLE and it names the step.

Each row states what was promised, what was observed, at which evidence level, and against which resource. An auditor settles the run without the agent transcript, and a machine reads the same list out of the signed receipt.

What a longer workflow changes

Nothing in the shape. A workflow of twenty steps is twenty promises, twenty correlation keys and one verdict. Three properties keep it readable at that size.

1. A step that no evidence covers is a defect of the contract, not of the run. The compiler marks it REQUIRES_REVIEW and you see it before the workflow runs, never after.
2. A step that is still moving holds the whole workflow at PENDING. The verdict never guesses forward, and PENDING is a normal answer.
3. One failing step names itself. The verdict carries the step id and the reason code, so the correction is one step, not the whole task again.

Every step above is one operation against one contract. A workflow contract composes them and returns one verdict. Read what a completion contract contains.