Build a provider

If you build software — or you want Kyra to drive something it does not yet reach — this is the door. A provider is the part of an application that lets an agent operate the meaning inside it rather than its pixels.

It is an open protocol, not a Kyra plugin format. Implement it once and any conforming agent can drive your application.

Specification and conformance suite: github.com/Kyra-H-I/uap-spec
Licensed permissively, versioned, and published with the gaps it has not closed written down.

The idea in one paragraph

An agent asked to “append ‘buy milk’ to the shopping note” has two bad options. It can look at pixels and click where the note probably is — precise about nothing, unable to tell whether it worked. Or it needs a bespoke integration per application per agent, which is a matrix nobody finishes.

UAP is the third option: applications say what they mean. One small contract, like a language server but for agents and applications. The application stays in charge of how; the agent only has to be right about what.

What a provider offers

Four things, in a cycle:

  discover  →  what can this application do?          (cheap, up front)
  observe   →  what is open, and what is in it?       (bounded snapshot + references)
  invoke    →  do this typed action to that thing     (declared effects)
  verify    →  did it actually happen?                (evidence, not optimism)

The parts that make it worth implementing properly:

Declared effects. Every action states its blast radius — does it only read, change the view, touch a draft, persist data, act on the device, or reach outside the machine entirely — and whether this particular operation can be taken back. The host derives from that when to ask the user first. Applications do not get to approve their own actions, and neither does a document or a web page that would like to.

References that admit staleness. “This note” is a handle scoped to a moment. When the world moves, it fails with a typed error and the agent re-resolves — rather than quietly acting on whatever happens to be focused now.

Verified endings. A result counts as completed only once the declared postcondition checks out. And when an outcome genuinely cannot be observed — you launched a dialler, you cannot hear whether the call connected — the action declares that, so the agent says “started the call, can’t confirm it connected” instead of inventing an ending in either direction.

Deterministic over generative. If your editor can rename a symbol exactly, expose that. An agent should invoke it, not improvise forty edits and call it a rename.

Four ways to build one

They differ in how they get into the application. Quality is earned per implementation — a careful adapter can outrank a sloppy native one.

Route	What it is	Good when
Native	The application speaks UAP itself	You own the application
Extension	A provider living inside the app’s plugin system	The app has one — this is how Kyra drives VS Code
Adapter	A wrapper beside the app, over the API it already exposes	The app has a documented API but will not change
Fallback	Browser structure, accessibility, or finally pixels and keystrokes	Nothing else exists

The fallback route is real and supported, and it is the lowest fidelity — an application that cannot verify what it did gets no relief from confirmation prompts, by design.

Roles never blur

The provider is the application’s hands. It answers what is open and what it can do, and it executes.
The host is the conscience. It holds the user’s authority: which provider gets an action, whether to ask first, whether it verifiably happened, what lands in the audit log, and what the agent says out loud.

Everything a provider says is treated as a claim to check, never as authorisation and never as proof that something happened.

Getting started

Read the specification, and read its Known gaps section before implementing. It is a draft that names what it has not finished, which is the useful kind.
Run the conformance suite. It ships with the specification, along with test vectors and a runner. It grades an implementation rather than taking its word.
Develop against the local door. Run it in the foreground and watch every frame:
Terminal window
```
kyra bridge -v
```
With no kyra connect running, it routes locally between whatever is attached and nothing reaches Kyra — which is exactly what you want while building.
Connect. A provider opens the socket and sends one line of JSON:
```
{ "type": "uap.hello", "provider": "your-app", "token": "<contents of uap.token>" }
```
The door answers {"type":"uap.welcome","ok":true} and the connection is line-delimited JSON in both directions. A refusal says only "ok": false — a caller that did not get in learns nothing else.

The socket and token live in ~/.kyra/bridge/. The token is regenerated on every start, so a provider must read the current one.

Reference implementation

The VS Code extension is a working extension-route provider: real actions, real effect declarations, real references, driven by a real agent every day. What it does →

Getting it in front of users

There is no provider marketplace. A provider you write and a user installs works immediately — the door is local and does not gate on a directory of approved applications.

If you have built one you would like Kyra to know about, get in touch through kyra-hi.com.