Build a Budgeted Envelope Before Giving the Agent Filing Authority

The request looked harmless from the UI when a finance ops person clicked summarize and file. They waited through a spinner, watched a clean paragraph appear, and assumed the cabinet was done. Then the record landed in another tenant's workspace because the model call was wired like a chat box. Have you ever shipped a demo that survived the prompt and died on the first authenticated mutation?

I keep hearing this week that models already write code better than most working developers. That argument is a sideshow once your product has to file a record, charge a card, or notify a human. The first layer that fails is rarely syntax; it is tenant scope, idempotency, or a missing spend cap. Why would a stronger completion fix a handler that never even forwarded the workspace header downstream?

I am taking a blunt position, and I do not intend to sand it down for comfort. If your agent can mutate storage before you can name the envelope fields, you are decorating a prototype. You are not productionizing an AI feature, no matter how confident the summary sounds in staging. The rehearsal I want is boring: freeze the request shape, cap the spend, and prove the handoff on a throwaway host.

The click, and the layer that actually breaks

Picture the same click again as an HTTP POST with a cookie, a workspace id, and an invoice id. Your handler should refuse that call unless those three facts survive every hop into the model client. What happens in vibe-coded slices is a route that concatenates PDF text, fires a vendor SDK, and inserts the JSON. The summary can be gorgeous while the insert is still a cross-tenant write into the wrong cabinet.

I treat that POST as one vertical slice rather than an AI feature glued onto a database. The envelope is the contract for who is asking, which tenant, which artifact, and how many tokens remain. If any field is missing, the model never sees the bytes, and that refusal is the product. Does that feel slower than dropping an SDK into the route and hoping the prompt behaves?

Carry money through the port, not a model nickname

I do not want model names sprinkled through handlers like confetti after a too-happy demo day. I want one port that accepts an envelope and returns a draft the rest of the application can persist. The sketch below is a proposed template, not a measured service, so treat the token fields as local fixtures. You should copy the shape, not any claim about latency, quality, or capacity that I have not measured here.

# envelope.py — proposed template, not production metrics
from dataclasses import dataclass
from typing import Protocol

@dataclass(frozen=True)
class FilingEnvelope:
    workspace_id: str
    actor_id: str
    invoice_id: str
    idempotency_key: str
    max_output_tokens: int
    attempt: int

@dataclass(frozen=True)
class FilingDraft:
    summary: str
    provider: str
    usage_tokens: int

class ModelPort(Protocol):
    def draft_summary(self, envelope: FilingEnvelope, text: str) -> FilingDraft:
        ...

class BudgetExceeded(Exception):
    pass

class TenantMismatch(Exception):
    pass

The handler then becomes a gate instead of a prompt playground with a database side effect. Notice how the model sits downstream of auth, budget, and the idempotency key on every attempt. If the ledger says this key already committed, we return the stored draft and skip another paid call. That is the opinion in code: the agent proposes, and the envelope decides whether anyone may ask.

# handler.py — proposed FastAPI slice
from fastapi import APIRouter, Header, HTTPException
from .envelope import FilingEnvelope, BudgetExceeded, TenantMismatch

router = APIRouter()

@router.post("/workspaces/{workspace_id}/invoices/{invoice_id}/file")
def file_invoice(
    workspace_id: str,
    invoice_id: str,
    payload: dict,
    x_actor_id: str = Header(...),
    idempotency_key: str = Header(...),
):
    env = FilingEnvelope(
        workspace_id=workspace_id,
        actor_id=x_actor_id,
        invoice_id=invoice_id,
        idempotency_key=idempotency_key,
        max_output_tokens=800,
        attempt=payload.get("attempt", 1),
    )
    try:
        return filing_service.apply(env)
    except TenantMismatch:
        raise HTTPException(status_code=403, detail="workspace mismatch")
    except BudgetExceeded:
        raise HTTPException(status_code=402, detail="filing budget exhausted")

Would I let this route import a vendor SDK and talk to storage in the same function? Not anymore, because that is how tenant identifiers vanish and how retries double-file the same invoice. The service loads the invoice under the workspace, checks the ledger, and only then asks the port. If you cannot narrate those three steps without mentioning a model nickname, the slice is still a toy.

# service.py — proposed apply path
class FilingService:
    def __init__(self, invoices, ledger, filings, port: ModelPort):
        self.invoices = invoices
        self.ledger = ledger
        self.filings = filings
        self.port = port

    def apply(self, env: FilingEnvelope):
        invoice = self.invoices.get(env.workspace_id, env.invoice_id)
        if invoice is None:
            raise TenantMismatch()
        existing = self.filings.get_by_key(env.idempotency_key)
        if existing:
            return existing
        if self.ledger.remaining(env.workspace_id) < env.max_output_tokens:
            raise BudgetExceeded()
        draft = self.port.draft_summary(env, invoice.redacted_text())
        self.ledger.consume(env.workspace_id, draft.usage_tokens)
        return self.filings.commit(env, draft)

Rehearse the status codes on a host you can throw away

Here is the workflow I want teams to run before anyone debates which completion sounds smarter. Stand up a throwaway server that speaks the same envelope your production handler will speak next month. Point a cheap client at it, then replay one recorded invoice until you can predict the status codes. You are not hunting for a prettier paragraph; you are hunting for 403, 402, 409, and 201.

A free rehearsal lane matters here because production credentials do not belong in that first loop at all. MonkeyCode fits that lane with free model access and a free server option, which keeps the experiment off billing. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I will not invent quotas, hardware, model names, or promises of permanence, because the envelope is the artifact.

A local replay looks like the curl below, aimed at a throwaway origin rather than a shared staging box. Freeze a redacted invoice as a fixture, then send the same headers your production browser will send. If the so-called AI feature cannot survive that request without a live customer database, it is not a feature. Can you honestly say your current filing button would pass that bar on a host you are willing to delete?

# replay.sh — local fixture against a throwaway origin
export REHEARSAL_ORIGIN="http://127.0.0.1:8088"
curl -i -X POST "$REHEARSAL_ORIGIN/workspaces/ws_9/invoices/inv_17/file" \
  -H "content-type: application/json" \
  -H "x-actor-id: user_22" \
  -H "idempotency-key: file:ws_9:inv_17:v1" \
  --data '{"attempt":1}'

The test I care about is not a similarity score and it is not whether the summary feels on-brand. It is a cross-layer failure test that pins tenancy, money, and retries to real HTTP statuses. Wrong workspace must be 403, a dead budget must be 402 before the provider is touched, and the same key must not insert twice. If those three cases are flaky, arguing about model quality is like polishing the hood of a car with no brakes.

# test_filing_envelope.py — proposed pytest, fixtures only
def test_wrong_workspace_is_forbidden(client, invoice_in_ws9):
    response = client.post(
        "/workspaces/ws_other/invoices/inv_17/file",
        headers={"x-actor-id": "user_22", "idempotency-key": "k1"},
        json={"attempt": 1},
    )
    assert response.status_code == 403
    assert invoice_in_ws9.filed is False

def test_zero_budget_never_calls_provider(client, ledger, fake_port):
    ledger.set_remaining(workspace_id="ws_9", tokens=0)
    response = client.post(
        "/workspaces/ws_9/invoices/inv_17/file",
        headers={"x-actor-id": "user_22", "idempotency-key": "k2"},
        json={"attempt": 1},
    )
    assert response.status_code == 402
    assert fake_port.calls == []

def test_retry_same_key_does_not_double_file(client, filing_repo):
    headers = {
        "x-actor-id": "user_22",
        "idempotency-key": "file:ws_9:inv_17:v1",
    }
    first = client.post(
        "/workspaces/ws_9/invoices/inv_17/file",
        headers=headers,
        json={},
    )
    second = client.post(
        "/workspaces/ws_9/invoices/inv_17/file",
        headers=headers,
        json={},
    )
    assert first.status_code in {200, 201}
    assert second.status_code in {200, 201}
    assert filing_repo.count("inv_17") == 1

Think of the envelope like a night-deposit slot at a bank after the lobby has closed. The essay a teller might write about your cash does not matter if the slot opens on the wrong account. Why are so many teams still grading the essay while the slot is unlatched for every workspace? File the invoice through the slot, then argue about prose, not the other way around.

What failed when the envelope was missing

I used to let the prototype chat with a live PDF and then persist whatever looked good enough. The first gateway timeout retried the handler and filed the same invoice twice into the cabinet. The first borrowed staging cookie wrote a summary into a workspace that did not belong to that actor. The first cost spike was not intelligence either; it was an unbounded attempt counter dressed up as helpfulness.

None of those failures required a famous model, a huge context window, or a new agent framework. They required a route that had no envelope, and they showed up as ordinary status codes if you looked. Production caveats follow from that mess, and they are not optional once money or tenancy is in the path. Redact fixtures, isolate rehearsal secrets from billing, and treat the free host as a fuse you will pull.

Do not promote the slice until 403, 402, and 409 are as boring as the happy 201 path. Do not keep customer PDFs overnight on a box you advertised as disposable, because cheap then becomes an incident. Keep the ledger schema in your real migration path, since budget rows are application data rather than prompt fluff. Are you still tempted to skip the ledger because the demo only files one invoice on a good day?

Who should not bother with this

If you are training weights, this envelope will not help you, and you should stop reading for a lab setup. If your app has no tenants and no persistence, stay in a notebook and enjoy the chat window while it lasts. If legal needs a vendor review before any third-party host sees text, run the same tests against a local fake port. The contract is the artifact you keep; the rehearsal host is optional and should remain easy to burn.

You set up a port, an envelope, a ledger, and three tests that fail closed on purpose. You run the curl against a throwaway origin until those status codes stay deterministic across ordinary retries. Only then do you point the same handler at a paid provider hiding behind the identical port. That path from setup to result stays useful even if you remove every product name from this article.

So here is my ask, and I want a concrete failure rather than a feeling about the model. Which layer handoff is least stable in your filing slice, and which status code or body do you actually get? If you rehearse the envelope on a throwaway host, does 402 appear before 403 when both gates should trip? That order tells you whether money or tenancy is the weaker lock on the cabinet you thought you had sealed.