Provider adapters
What a command-line tool has to satisfy to be driven by Deskworth — documented against the three adapters that exist, not against a hypothetical fourth.
Shipped in the current build. You can do this on your own machine today.
LimitThree adapters exist. This page documents those three. Adding a fourth is core work, not site work, and this page will not describe one before it exists.
#The contract
An adapter answers five questions about a binary, and nothing more. It never interprets the model’s output; it turns a byte stream into events.
| Question | What the adapter provides |
|---|---|
| Which binary? | The executable name to look for on the path. |
| How is it started? | The exact argument list for a headless, non-interactive run in a given workspace. |
| How is its output read? | A normalisation from the vendor’s stream format into Deskworth phases and tool events. |
| How is it cancelled? | A stop path that terminates the process and releases the workspace. |
| What does it report about usage? | Whatever the CLI publishes — or nothing, which the header then states. |
#Normalising a stream, not summarising it
Each vendor emits a different stream. The adapter maps it onto a common vocabulary of phases so that a trace reads the same whichever CLI produced it. What it must never do is condense: every line of trace corresponds to an event that actually occurred, and the raw output stays available underneath, whole, with the exact command line.
The command line is emitted before the first line of output, deliberately: a card must be replayable by hand. If what you see in the trace cannot be reproduced by running that command yourself, the trace is wrong and the adapter is at fault.
#The mandate goes in through the input, not the arguments
A card sends its instruction on the process’s standard input and leaves that input open. This is what lets a card continue: a second message resumes the same session with its context intact. Verified on 2026-08-26 — asking a card to remember a number, then asking for it back, returns the number, with the structured stream and the usage report preserved.
#What an adapter must never do
- Store or read a vendor key. Credentials belong to the CLI and to the keychain.
- Rewrite the model’s output before it reaches the trace.
- Widen a role’s reach. Capabilities are checked by the tool server, not by the adapter.
- Keep a process alive after its card is done.
- Assemble its command through a shell. There is no interpreter in the path from registry to process.
#Detection is not a promise
Detection is a fact about the machine: the application can see that a binary exists and can be started. Whether the subscription behind it is active is something only the vendor knows, and it surfaces the first time a card runs — which is why the connection states distinguish “installed” from “signed in” rather than collapsing both into “usable”.
#Sources
- The provider manifest, generated by the coreDeskworthInternal document, not published
- Deskworth OS — product state at 0.0.23DeskworthInternal document, not published