Addi Agent Surface: Addi Architecture Disclosure

Overview · Modules · Addi Agent Surface

What it is

Where Addi becomes a principal

The agent surface is where Addi stops being a feature and becomes a principal. There is no in-app chat. Instead, the operator's own Claude connects to the platform over MCP through an OAuth 2.1 + PKCE authorization surface built into the backend: dynamic client registration, RS256 tokens, scoped access, and consent and audit recorded as schema, not as log lines. Once connected, the agent reads and writes through the same module boundaries a human user does.

We built it this way because the alternative, an embedded chatbot, makes the agent a guest in the product. A guest gets a curated window and a support burden. A principal gets an identity, a scope, a consent record, and accountability. Vetting question for the skeptical reader: an agent with write access? Yes, and the reason it is safe is the write law, not a gate. Machine writes land freely into empty or machine-sourced fields and never over a human-confirmed value; anything that would collide becomes a proposal a human accepts or declines. Agents get the door, never the tables.

Autonomous work flows through one queue: one connection, one token, work bounded by budget caps, and failed jobs retried rather than silently lost. The job kinds are a small set of autonomous analysis and recommendation tasks; the roster is held at Tier 2. The agent's operating doctrine is served from the platform itself at session start, so the doctrine it runs on is always the one we currently serve, and agent output passes a mechanical house-style gate at the write door before it lands anywhere a person will read it.

The questions it answers

For the operator, and for the investor evaluating us

For the operator: can my own AI work my pipeline without me babysitting it, and can I see everything it did and undo anything it got wrong? What has it been asked to do, what did it claim, what did it propose, and what did I confirm?

For the investor evaluating us: how does an autonomous agent touch production data without becoming the largest risk surface in the product? Our answer is identity, provenance, budgets, and traceability, and this unit is where each is enforced.

Scope and boundaries

What it owns, and what it does not

The unit owns the authorization surface, the consent and audit record, the work queue, the wake-up budget and record, and the served doctrine. It does not own any business data. Every read goes through another module's public API; every write goes through that module's one write door, under the write law, with tenant identity independently re-verified on every tool call. When a module is disabled for a tenant, the agent's writes into it refuse like anyone else's, because feature off means dead server-side.

What it is NOT

Not a chatbot, and not a chat feature of any kind. Not a bypass lane: there are no agent-only tables, no privileged queries, no side doors. Not an autopilot for the pipeline: the agent recommends and a human decides; the only automatic mover anywhere in the product is the buy-box rejection, and that belongs to another unit. Not a tool catalog document.

Withheld by design Tier 2 Tier 3

The catalog internals, scopes topology, and prompt and skill contents are held at Tier 2 and Tier 3.

The contract

The unit's public shape

Responsibilities, the write door, events, guarantees, and refusals. No fields, no schemas, no payloads; those are held at Tier 2.

Responsibilities

Own the authorization surface for external agents: OAuth 2.1 + PKCE with dynamic client registration, RS256 tokens, and scoped access, exposed over MCP.
Record consent and audit as schema: who connected, what they were granted, what was done under that grant, and when the grant ended.
Own the work queue: accept jobs, hand them to the connected agent, track completion, and never lose a failed job silently.
Bound autonomous work with budget caps: no work proceeds past a cap.
Serve the agent's current operating doctrine at session start, so the doctrine in the field is always the one we currently serve.
Enforce the mechanical house-style gate on agent-authored output at the write door.
Broker, never own: every business read and write is delegated to the owning module's public API and write door, with tenant identity re-verified on each call.

The write door

The door admits a small set of business-named commands covering the grant and revocation of agent access, the working of the queue, and the proposal path.

The proposal path is the part the write law forces into existence: when an agent write would land on a human-confirmed value, it arrives here as a proposal instead of a write, and a human's acceptance elsewhere stamps the result human-confirmed. Business writes themselves (an outlook onto a deal, an assist into underwriting) are not this unit's business; they pass through the owning module's own door under the same law.

Withheld by design Tier 2

The roster and the shapes are held at Tier 2.

Events announced

Events carry identity plus the business fact, never a data dump. The unit announces the facts of its own domain: that access changed hands, that queued work ran or failed, and that a proposal was made and later decided.

Withheld by design Tier 2

The event roster is held at Tier 2.

Guarantees

Every tool call independently re-verifies tenant identity before it does anything.
Agent writes flow through the same module write doors as human writes; there is no agent-privileged path to storage.
The write law is enforced at the door and exercised by tests: a machine write never lands over a human-confirmed value; a collision becomes a proposal.
Every action taken under a grant is attributable to that grant in the audit record, and provenance marks agent-produced values as agent-produced.
Autonomous work is bounded: budget caps on wakes, and failed jobs retried rather than silently lost.
The doctrine the agent runs on is the one the platform serves, not a stale copy.

Refusals

No in-app chat, and no impersonation of a human user: the agent is its own principal with its own provenance mark.
No writes into a module the tenant has disabled; feature off means dead, and the refusal is server-side.
No direct table access, no cross-module reads, no query surface outside the owning modules' public APIs.
No moving a deal through the pipeline: the agent recommends, a human decides, and the only automatic mover in the product is the buy-box rejection, which is not this unit.
No work past a budget cap; when the budget is spent, the queue waits.
No shipping of a capability we judge genuinely risky with write access; it ships read-only.

What done means

The gates a change passes

Done is an operator connecting their own Claude over MCP, granting scoped access with a recorded consent, and watching the agent claim work, do it, and land its results under the write law, with every step attributable and every write reversible. Done includes the failure paths: a job that dies is retried, a colliding write becomes a proposal, and a revoked grant ends access cleanly. A demo that only shows the happy path is not done here, because this unit's whole argument is what happens when things go wrong.

The authorization gate: the OAuth 2.1 + PKCE handshake, token verification, and scope enforcement are exercised end to end against the real backend, including expiry and revocation, not mocked.
The tenancy gate: every tool call is proven to re-verify tenant identity independently; a call carrying the wrong tenant is proven to refuse.
The write-law gate: the machine-over-human collision case is expressed as code, a failing test before the rule and a passing one after; the proposal path and the human-confirmed stamp are exercised, not asserted.
The door gate: reviewers verify no agent code path reaches another module's tables; every business effect traces to a named command on an owning module's write door.
The queue gate: the queue's full lifecycle is exercised, including failure and retry, along with the budget cap stopping work when spent.
The style gate: agent-authored output is run through the mechanical house-style check at the write door, and a violating output is proven to be held back.
The doctrine gate: a session start is proven to fetch the currently served doctrine, so a deploy changes behavior without touching any agent's configuration.

Per our method, every one of these load-bearing rules exists as code, a validator, a typed contract, a server-side check, or a failing test, never as prose discipline. The writer of the unit is never its auditor; verification is independent and adversarial.

The failing cases

It is a failure if any agent write reaches storage without passing a module write door.
It is a failure if a machine write lands over a human-confirmed value, even once, even harmlessly.
It is a failure if a tool call acts on a tenant it did not independently re-verify on that call.
It is a failure if an action under a grant cannot be traced back to that grant in the audit record.
It is a failure if a disabled module accepts an agent write; feature off means dead, for agents most of all.
It is a failure if a wake does work past its budget cap.
It is a failure if a failed job vanishes instead of being retried.
It is a failure if agent-authored text reaches a human surface without passing the house-style gate.
It is a failure if the agent moves a deal through the pipeline; recommending is its ceiling.

Honest-state behaviors

When the budget cap is spent, the unit stops and says so; it does not degrade into slower work or quieter work. Autonomy is deliberately budget-capped while trust accrues; that is sequencing, not apology.
When we judge a capability genuinely risky, it ships read-only. A read-only capability that tells the truth beats a write capability we cannot yet defend.
A declined proposal is recorded under its grant in the audit like any other action; the human's decision is part of the record.
Agent-produced values are always marked as agent-produced. Provenance is never laundered by acceptance flows; only a human's explicit acceptance stamps a value human-confirmed.

Withheld by design Tier 2 Tier 3

The tool catalog internals, scopes topology, wake cadence, and prompt and skill contents are withheld here by design; the catalog and scopes are held at Tier 2, and the doctrine and prompt contents at Tier 3.

Where it connects

The spine sections this unit realizes

Section 10, the agent as a first-class principal: the full argument for this unit's existence.
Section 8, provenance and the write law: the authorization mechanism the unit rides on.
Section 7, modules and boundaries: the doors the agent is required to use.
Section 6, the configuration kernel: why a disabled module refuses the agent server-side.
Section 13, tenancy and isolation: the per-call tenant re-check and the isolation ladder where agent blast-radius demands more.