Athena, the assistant

The problem

Operating a platform means knowing which of several hundred addresses to call, in what order, with what body. Most of that knowledge is not interesting: it is the cost of asking a simple question like “why is this deployment restarting”. Athena is the surface where the question is the input.

What it is

Athena is two services, and the split is the whole design.

The assistant holds the conversation. It talks to a model provider, keeps the session, and decides which operations to attempt. It never calls the control plane itself.

The tool server is the only thing that does. It publishes a fixed set of named operations — deployment_list, container_logs, sre_incidents and eighty-one more — each with a declared input shape and a required permission, and it turns a call into a request against the control plane’s own API. Everything the assistant can do to the platform, it does through one of those named operations, inside one tenant, with a permission check in front of it.

The consequence is that the assistant’s judgement decides what to try, and nothing else. It cannot reach an address no tool names, and it cannot exceed a permission the tenant’s principal does not hold.

How a request travels

A person types into the console. The console calls the control plane’s Athena routes. The control plane strips any tenant identity the caller supplied and injects the one it verified itself — a request it cannot attribute to exactly one tenant is refused rather than served broadly, and the refusal is recorded. The assistant then mints a short-lived credential carrying that same tenant, and the tool server mints its own to call the control plane, with a value in the credential matched against a header on every write.

None of those hops widens scope. Being a platform operator is a privilege signal, not a wider view: an operator still acts inside one named tenant, and the code says so in three separate places because it is the assumption most likely to be re-broken.

Permissions come from one side only

Every tool declares the permission it needs. Which roles hold that permission is not written down in the assistant — it is generated from the control plane’s own grant.

That is a repair, not a preference. The two used to be hand-maintained copies, and they disagreed: a developer was offered the tool that raises an incident and then refused by the server halfway through the conversation. Three more disagreements of the same shape were found at the same time, including two permission names the control plane has never had. Generating one half from the other makes that class of defect impossible to reintroduce quietly, and it is why the tool reference reads the permission from the tool server and the role list from the control plane.

Most tools are not advertised

Eighty-four operations are registered and eight are advertised in the model’s default list: five common reads and the three helpers that find everything else. An agent searches for an operation by intent, reads its input shape, and asks for it by name. A tool reached that way is checked against the same permission as a direct call — the asking is not the doing.

This keeps the advertised surface small without hiding anything. The full list, with every argument, is the tool reference.

What it will not accept

Secret material never enters a conversation. The control plane’s own API accepts inline secret values; the tools deliberately do not, and a call that supplies one is refused rather than quietly stripped. Anything typed into a chat is in the transcript, the session store and the tool-call audit record, none of which are the secret store and none of which can be un-written afterwards. What the tools accept instead is a declaration that the platform should mint the material, a path to material that already exists, or a template resolved inside the control plane — see secrets.

Nothing crosses a tenant boundary, and running is not building: an assistant can start, change and stop deployments, and cannot produce the container images they run.

Which model, and whose key

Three providers are supported, and the key can belong to the platform or to the tenant: a per-tenant key is read from the secret store under that tenant’s own path, and the platform’s key is the fallback. A deployment with no secret store at all can supply keys through the environment instead, at platform scope only.

Not this

This page does not list the tools or their arguments — that is the tool reference — and it does not describe the assistant’s own configuration surface, which is a platform-operator matter rather than part of a tenant’s API.

It also does not describe how a conversation is stored or how long for. That is a data-retention question this page cannot answer honestly from the code alone.

Where to see it

• Every tool, its permission and the roles that hold it: tool reference.
• The addresses the console calls: Athena routes.
• What an agent principal cannot do, before planning: agent principal limits.