Models reason.Code acts.Agents built it. Agents maintain it. Agents run the brain.
Code still holds every limit and sends every order. You still decide.
CalmTrader sits beside one trader like a chief of staff. It prepares, briefs, watches, drafts, challenges, remembers and follows up. Agents own the proposal plane, code owns the effect plane, and you decide. It is paper only, and code checks that every venue is a paper venue.
The design draws on these patterns from agent and safety engineering.
Agents run the brain
Proposal plane and effect plane separation
Agents think, draft and object. Deterministic code acts. There is no direct executable path between them.
Orchestrator and typed specialist workers
The Desk: Research, Market context, Journal and Challenger agents under a chief-of-staff coordinator.
Delegated authority as leases
Typed, scoped, expiring, revocable. Code caps and mints each one. The trader signs it.
Monotonic cancel-or-reduce authority
No agent can open or add to a position, raise a limit, mint a permit or write to a venue.
Structural red team
The Challenger: one agent whose only job is to argue against the plan and the ticket.
Automatic revocation, graceful degradation
The Circuit Breaker ends a lease on an observable failure. The app falls back to its deterministic baseline.
Derived memory with provenance; source-linked output
Memory is a view computed from the record. Every line of a brief links to its source.
Agents maintain it
Replay-driven maintenance
The Night Shift reproduces a failure on the recorded day. Code tests the fix on days the agent has not seen.
Evals as merge gates; shadow promotion
A new prompt, model or tool is a change like any other. It starts in shadow and is promoted by a script.
Evidence bound to a version manifest
Evidence belongs to one exact version of everything that can change behaviour.
The system watches itself
Data lineage and end-to-end tracing
The Flow Map follows each source hop by hop. Any ticket traces back to the bars and alerts behind it.
Scorecards with calibration
Every recipe and every agent is measured over time, version by version.
Automated improvement proposals, champion and challenger
The Recipe Coach proposes. A proposal starts as a new version in shadow.
Counterfactual replay; simulation and fault injection as a promotion gate
What-If Replay and the Gym.
Incident reports from the event log; cost budgets as a hard limit
The Flight Recorder and the Meter.
What never becomes an agent
A small deterministic kernel
Risk gate, sizing, permits, the paper lock, the ledger, replay and Stop, outside every agent's write scope.
Capability isolation, capability tokens
An order needs a single-use permit that only code can mint.
Event sourcing, deterministic replay
One append-only, hash-chained ledger. The effect plane replays to the same decisions and the same hash.
Fail closed
When the app can't see, it stands aside and says why.
Agents built it
Multi-agent build with a deterministic gate
Role agents planned, an advisor ruled, builders worked in isolated lanes, two independent reviews attacked each change, a gate script judged the evidence, a person approved.
§ 1
What we built first, and why the order mattered
The hardest place to put an agent is next to an order button. So we did not put one there. First we built the code around the button, and the first version was designed to work fully with models off.
PatternKernel firstContract-first build
First
Contracts and types
Frozen before any parallel work, so every later part met the same edges.
Then
The record and replay
Every decision became an event, so a day could be run again.
Then
The gate, permits and Stop
The limits, and the only door to a venue, were code before anything could propose.
Only then
A model, in shadow
It could read and be scored. By design its output counted toward nothing.
The order mattered because anything we later lent an agent had to be measured, bounded and taken back. Replay is how we measure an agent. The gate is what makes a grant safe to give.
What we learned
a.A setting is not a proof, so we added a refusal test. A promise is only as good as the test that tries to break it.
b.Agents earn authority in tiers, like recipes. Shadow first, measured, and demoted automatically.
c.Maintenance needs the same gate as building. A fix drafted at night by an agent is a change like any other.
d.Memory and measurement must live in the record. Anything kept elsewhere cannot be replayed or checked.
§ 2
How authority grew: read, then propose, then prepare
Since the first version the agents have been given more to think about. The design has no key to give them. Each step up is a typed grant, written to the ledger, revocable, and demoted automatically when the evidence stops supporting it.
PatternProgressive trustMonotonic authority
Step 1
Read
Agents read the sources and the record. Their output is shown and scored.
Limit: shown as "not counted". It changes no stance and no ticket.
Step 2
Propose
Agents draft the Morning Brief, object to a plan, and propose edits to your Standing Orders Book.
Limit: a proposal is a draft. Only you change your rules, and loosening takes effect next session, never this one.
Step 3
Prepare
Under a lease you signed, an agent may ask code to cancel or reduce.
Limit: no agent can open or add to a position, raise a limit, mint a permit or write to a venue.
A lease is authority as a typed object with an end time
You can lend an agent a job. You cannot lend it a limit. An agent asks for a lease in a typed form, and that request is only a draft. Code caps every requested field against a fixed policy that no agent can edit, then mints the lease for one agent version. It is not active until you sign it.
Any lease that can touch an order is cancel-or-reduce only. When an agent uses one, code checks the request against the lease and the policy, compares a reduction with the original, and rejects anything that is not smaller. Then code performs it. Permission to write a brief or a draft is called a work grant. Every lease and work grant ends on expiry, revocation or Stop, whichever comes first.
RequestedBy an agent, in a typed form. A draft only.
↓
Capped and mintedBy code. Every field is capped against a fixed policy no agent can edit.
↓
Signed by youNot active before this.
↓
ActiveCancel or reduce only. Code checks each request, then performs it.
↓
Ended, whichever comes firstExpiry. Revocation by the Circuit Breaker or by you.
■ StopEnds every lease at once.
Authority LedgerEvery state above is an event you can read.
an agent asks
code acts
the trader signs or grants
Fig. 1. The life of a lease. Nothing carries over after it ends. A new job needs a new lease.
Wireframe‹…› marks a placeholder
The Authority Ledger, as you see it
Agent
Kind
May
Cannot
Ends
Challenger
Lease
Block or shrink a ticket
Add or enlarge one
Expiry ‹hh:mm› ET, revocation or Stop
Market context
Lease
Ask code to cancel resting entries on ‹instrument›
Place or raise anything
Expiry ‹hh:mm› ET, revocation or Stop
Research
Work grant
Write lines for the Morning Brief
Print a line with no source
Expiry ‹the open›, revocation or Stop
Journal
Work grant
Draft the Day Book
Sign it
Expiry ‹hh:mm› ET, revocation or Stop
Every row ends on whichever comes first. Phone, voice and menu bar can read, skip, lower and stop. They cannot arm or raise.
§ 3
Agents run the brain, in a plane with no direct executable path
No agent can open or add to a position, raise a limit, mint a permit or write to a venue. Three things connect the planes, and each is a different kind.
One agent-originated request can reach the order path: cancel or reduce, under a lease you signed. Code checks it against the lease and a fixed policy, then performs it.
Briefs and drafts cross only to a read-only screen. This is a real path of influence: agents shape what you see. So every line is source-linked for you to check, and the deterministic checks do not depend on what any agent wrote.
Your tap is a separate human input. It does not come from an agent.
Proposal plane · agents work here
Chief-of-staff coordinatorOne voice. Every line source-linked.
Research
Market context
Journal
Challenger
No direct executable path
1 · Cancel-or-reduce requestGoes to the lease check. Code checks the lease and a fixed policy, then performs it.
2 · Briefs and draftsGo to a read-only screen. Read by you. Nothing there executes.
3 · Your tapA separate human input, between the risk gate and the order manager.
Effect plane · deterministic code · no agent can write here
Sources, then intakeValidated, checked for staleness.
↓
Decision logicPure code. Stance, then candidate. Cancel or reduce arrives here from the lease check.
↓
Risk gateOrdered rules and locks. Passes a typed value.
↓
YouOne tap.
↓
Order managerMints a single-use permit, then writes.
↓
Venue adaptersEach declares paper or not.
Event ledgerEvery step above is an event. Append-only, hash chained.
ReplayIts own ledger. Can never reach a venue.
■ StopA small separate path. Needs no main window and no agent.
agents
deterministic code
no direct executable path
the trader
replay, never live
Fig. 2. Two planes. The heavy line is the claim: nothing an agent emits is executed directly. Opening 1 leads to a check run by code. Opening 2 leads to a screen.
Orchestrator and workers · typed interfaces
The Desk
Why
Several agents talking at once is noise at the worst moment, and text passed between them can carry someone else's instructions.
How
Each agent does one job and the coordinator briefs you in one voice. Untrusted text is treated as hostile. Schemas limit shape, not meaning. The safety boundary is that no agent holds a capability worth hijacking.
Checked by
Provenance marks and adversarial test cases reduce the rest. A line whose source is missing from the record is dropped before the brief is shown.
Structural red team · monotonic authority
The Challenger
Why
Agents built to be helpful tend to agree.
How
It argues against the plan before the open and against the ticket while the countdown runs. It can block a ticket or shrink it. Code compares the reduction with the original and rejects anything that is not smaller.
When it is late or off
The ticket is shown with "Challenger unavailable" and the deterministic gate still applies. Its standing is changed only by offline evaluation and a human.
Automatic revocation · graceful degradation
The Circuit Breaker
Why
Waiting for a person to notice a failing agent is too slow.
How
It trips only on observable failures: an output that is late, malformed, out of scope or outside its lease. Code then ends the lease, and the app runs on its deterministic baseline with that agent off. Quality drift is a different problem. It is found by offline evaluation and ends in demotion.
Checked by
Seeded faults of each kind. The test expects the lease to end and this sentence to be shown.
The Research agent is off. Running on your rules alone.
Derived state · provenance
Memory
Why
A chief of staff has to remember. A model that "remembers" can invent.
How
The Mirror and the Follow-ups are views computed from events, and each remark cites them. It counts actions. It does not read feelings. The ledger keeps an immutable audit trail. Erasing a memory entry writes a tombstone, so a rebuild leaves it out.
Checked by
A rebuild from the ledger must give the same entries, and an entry with no event behind it fails.
§ 4
Agents maintain it, and a change has to earn human review
After the close, the Night Shift starts. Maintenance agents read the day's complaints and safety events and find the failure in the ledger. The loop does not let an agent say a fix works. It qualifies a change for human review.
The failing day
Reproduce it
An agent replays the recorded day until the failure appears again. No reproduction, no fix.
→
Proposed fix
Draft the change
In a copy, inside the agent's own write scope. The kernel and the gate are outside that scope.
→
Development regressions
Test on days it may see
The fix must change the failing decision and explain any other decision it changes.
↓ handed to code
Sealed regression
Holdout days it never sees
Code runs the change on recorded days kept away from every agent.
→
Gate script
Judge the evidence
Pass or fail. The gate and everything it depends on sit outside every agent's write scope.
→
Human review
A person approves
You, for anything that changes behaviour. Selva, for anything in the kernel.
done by an agent
done by code or a person
Fig. 3. The maintenance loop and its three sets of recorded days: the failing day, development regressions the agent may see, and sealed holdout days it never sees.
PatternDeterministic replayOffline evaluation
Two kinds of replay, with different promises
Mode
What runs
Where
Promise
Deterministic replay
The effect plane, fed the recorded agent outputs
A separate ledger, under a pinned build
Same decisions and same ledger hash
Candidate evaluation
A new agent version, on frozen inputs, sampled more than once
An isolated ledger that cannot reach a venue
A measured comparison. No same-hash promise
PatternEvals as merge gatesShadow promotionVersioned evidence
The Agent Regression Suite and the Evidence Library
Without versioned evaluations we could not tell whether an agent got worse. So a new prompt, model or tool for any agent is treated like a code change. It runs in shadow on recorded days and on days with seeded faults, against the current version and the deterministic baseline, and it is promoted only when a script says so. Agents do not grade their own work. We measure agent behaviour, never trading results.
Evidence is tied to a full manifest of what can change behaviour: logic, prompts, schemas, tools, and the model version where the provider allows. A change to any of them starts a new file in the Evidence Library, and old evidence does not carry over.
§ 5
The system watches itself
An agent system you cannot observe is one you have to take on trust. So every part of CalmTrader reports on itself from the same ledger: where its data came from, how each recipe and agent has done, what could be better, and what it cost. The app measures. It promises nothing.
Source ‹A› · price bars
ReceivedEvery ‹n› s.
↓
Validated‹n› rejected.
↓
Deduplicated‹n› dropped.
↓
StampedDelay ‹n› ms.
↓
Used in stanceFresh ‹n› s ago.
↓
Ticket ‹id›Traces back through every hop above. Each hop is a ledger event.
▨ Gap on source ‹B›Shown as a gap. Not used since ‹hh:mm›.
Fig. 4. The Flow Map. Schematic with placeholders. Pattern: data lineage, freshness and completeness checks, end-to-end tracing bound to ledger events. A gap is shown as a gap and is never filled in.
PatternScorecards over versionsCalibration
Scorecards for every recipe and every agent
Scorecard
Shows, version by version
Limit
A recipe
Sessions ‹n›, tier history, tickets offered, taken, skipped and blocked, R per trade ‹R›, slip from the trigger price, cost of delay.
It is a measurement on your own days. It is not a forecast, and money is never coloured.
An agent
How often its objections were upheld or overridden, how well its confidence matched what happened, how late it ran, what it cost per session.
It scores agent behaviour. An agent cannot read or edit its own scorecard's rules.
PatternAutomated improvement proposalsChampion and challengerSealed holdouts
The Recipe Coach proposes. It never edits the recipe you are running.
Each night agents read the scorecards and the record and write specific proposals for a recipe: a small readable change with the evidence beside it. A proposal becomes a new version that starts in shadow beside the current one.
ChampionThe recipe you are running. No proposal edits it.
↓ measured
Scorecards and the record
↓
ProposalWritten by an agent. A small readable change with its evidence.
↓
New version, in shadowThe challenger. Runs beside the champion.
↓
Sealed regressionHoldout days the agent never sees.
↓
The GymHostile days.
↓
Your sign-offOn measured sessions. Only then does it become the champion.
Fig. 5. The Recipe Coach loop. A recipe proposed by an agent earns authority the same way as one you wrote.
Four more instrumentsand a switchboard
Part
What it does
Limit
Pattern
What-If Replay
Ask a question of your own past days, such as "what if I had skipped the first half hour?" Replay answers it on the record.
It runs in an isolated ledger that cannot reach a venue. It describes recorded days. It does not predict.
Counterfactual replay
The Gym
Synthetic days and hostile scenarios: a feed that lies, a gap, a flood of alerts, an injected instruction.
Every recipe and agent version must pass before it is lent authority. Passing earns a place in shadow, nothing more.
Simulation and fault injection as a promotion gate
The Flight Recorder
After any safety event it writes the incident up from the ledger: what it saw, what it did, what it refused, and what the Night Shift proposes.
A line with no event behind it is not written.
Automated incident reports from an event log
The Meter
What the agents cost, per agent and per session, against a budget.
Code enforces the budget. An agent over budget is paused, and the app carries on with models off.
Cost budgets as a hard limit
The Model Switchboard
Chooses which model runs each agent.
A model that has not passed the Agent Regression Suite for that agent is not used.
Evals as a deployment gate
§ 6
Agents built it. A gate script judged the evidence.
PatternRole agents with an arbiterIsolated lanesIndependent reviewSeparation of duties
The first build used the same idea as the product. A planning team of role agents wrote one draft each. An advisor agent checked the drafts against each other and against outside documents, and ruled where they disagreed. Each ruling went into a decision log with the evidence that would reopen it.
We froze the contracts first. Then builder agents worked in isolated lanes, each limited to its own directory. A separate reviewer agent with read-only tools tried to break each change, and so did a second model from another vendor.
The gate required a recorded failing test, reviews bound to the exact change, and human approval before a protected change could merge. A gate script decided whether the evidence passed. A person approved the change. The risk and order code, the ledger and the review rules are protected paths, and they are the same paths the Night Shift cannot write to.
§ 7
What we would not change
Seven design rules were written before the first line of code. Each is held by a test, a type or a build check. We would write the same seven again.
Rule
Mechanism
Verified by
1No agent can write to a venue.
Capability isolation. Venue code sits behind a module boundary. Agent code cannot import across it, and no agent is given a tool on the other side.
A build check plants a forbidden import and must fail. A refusal test asks an agent to use a tool it should not have.
2An order needs a permit that only code can mint.
Capability tokens. A risk-gate pass is a typed value. Code mints a single-use permit paired with one stable order identity. An unknown outcome is never resent before reconciling with the venue.
Each gate rule is made to fail alone. The test expects that rule's reason and no order event.
3An agent's output can only cancel or reduce.
Monotonic authority. An opinion has its own type, which the stance logic and the gate do not accept as evidence. Types are one layer. Code also compares each reduction with the original.
Tests submit an opinion as evidence, and a "reduction" that is larger. Both must be rejected.
4Text from outside is data, never instructions.
Prompt-injection containment. Untrusted text is treated as hostile and kept in quoted data fields. A data connector can only emit data events.
Adversarial cases put instructions inside an alert. The test expects no change to a stance, a lease or an order.
5One append-only record. The effect plane replays.
Event sourcing. Hash chained, one writer. Decision code gets time, randomness and ids through ports. Replay uses recorded agent outputs.
Under a pinned build, a replayed day must give the same decisions and the same ledger hash on two machines.
6Authority is earned in tiers and lost automatically.
Progressive trust. Every recipe, source and agent version starts in shadow. The app ships with no recipe and recommends none. An edit starts again in shadow.
Each version is compared with doing nothing on the same days. Replayed days are never mixed with live days.
7It stands aside when it can't see, and says why.
Fail closed. The Blind Notice says what it can't see and what it stopped doing. Stop runs on a small separate path that needs neither the main window nor any agent. Protective orders rest at the venue, and the engine reconciles with the venue on restart before any watch can start.
Fault tests cut each source, hang the window, and restart the engine in the middle of a trade.
Can't see NQ prices. Not trading NQ. The venue last confirmed your stop.
Scope of this page
What is deliberately not published here
This page gives the kind of mechanism behind each part, why it exists, and how it is checked. It leaves out what would be needed to rebuild it, and it contains no trading rules.
CalmTrader is private software. There is no public download.