The plugin protocol on one page¶
The minimum an AI (or a person) needs to write a provider and a consumer of the plugin protocol (apiVersion 20, Kino 0.9.81). Every line points to the long page, The plugin protocol, for the rest.
Start from the scaffolds¶
node sdk/init.mjs my-provider --kind provider --door recipes --call byId
node sdk/init.mjs my-consumer --kind consumer --door recipes --call byId --repo owner/kino-plugin-recipes # writes "hosts": []
Copy next to each plugin sdk/ without sdk/test/ and contract.json (both required; kino.d.ts is optional, only for
editor typings). The consumer's test/provider is a stand-in: replace it with a copy of the real provider
(Testing offline).
Provider¶
{ "id": "recipes", "name": "Recetas", "version": "0.1.0", "apiVersion": 20, "entry": "plugin.js",
"description": "Recetas para otros plugins", "hosts": [],
"provides": { "recipes": { "summary": "Recetas con sus ingredientes",
"calls": { "byId": { "in": { "id": "number" }, "out": "Recipe" } },
"streams": { "latest": { "out": "Recipe", "everySeconds": 300 } },
"types": { "Recipe": { "id": "number", "title": "string", "imageUrl": "string?" } } } } }
export async function proto_recipes_byId({ id }) { /* return a Recipe, or throw: the consumer gets provider_failed */ }
export async function proto_recipes_latest(cursor) { return { items: [/* new Recipes */], cursor: 0 /* small JSON */ }; }
No capabilities and no settings make it provides-only (hosts [], or the real hosts its kino.fetch reads). Names:
^[A-Za-z][A-Za-z0-9]{0,31}$. Types: string, number, boolean, T?, T[], a door type, an inline object
(types). Test: node sdk/run.mjs . proto recipes.byId '{"id":1}', node sdk/run.mjs . proto
recipes.latest (exit 0 answer, 1 ✗ <code>, 2 bad command).
Consumer¶
{ "id": "recipe-picker", "name": "Recetario", "version": "0.1.0", "apiVersion": 20, "entry": "plugin.js",
"description": "Elige una receta del plugin Recetas", "hosts": [],
"capabilities": ["screen"], "screen": { "label": "Recetario", "labelEn": "Recipes" },
"recommends": ["owner/kino-plugin-recipes"],
"consumes": { "recipes": { "repo": "owner/kino-plugin-recipes", "door": "recipes", "calls": ["byId"], "streams": ["latest"] } } }
"hosts": []: a screen-only consumer (a non-empty consumes, capabilities exactly ["screen"]) declares no host, and an
Image needs no declaration. Add a real host only if the screen's own kino.fetch reaches it (any other capability brings back
"at least one host"); never example.com or a made-up name (the consumer's hosts).
The minimal screen (install gate, one compact bar with a real exit, a call, an error sentence with a default):
const REPO = "owner/kino-plugin-recipes"; // exactly as in "recommends"
const t = (es, en, more = {}) => ({ type: "Text", text: es, textEn: en, ...more });
const page = (kids) => ({ type: "Scaffold",
appBar: { type: "AppBar", title: "Recetario", titleEn: "Recipes", mergeWithKinoBar: true, dense: true,
leading: { type: "IconButton", icon: "close", labelText: "Cerrar", labelTextEn: "Close", onPressed: { close: true } } },
body: { type: "SingleChildScrollView", children: [{ type: "Column", padding: 16, gap: 12, children: kids }] } });
const ERR = { provider_missing: ["Recetas está apagado: revísalo en Plugins.", "Recipes is off: check it in Plugins."] };
const OTHER = ["No se pudo traer la receta.", "Could not get the recipe."]; // the default for any other code
export async function screen({ state = {}, installed = {} }) {
if (installed[REPO] !== true) return page([t("Necesitas el plugin Recetas.", "You need the Recipes plugin."),
{ type: "ElevatedButton", key: "install", labelText: "Instalar", labelTextEn: "Install",
onPressed: { go: { installPlugin: { repo: REPO } } }, autofocus: true }]);
const kids = [];
if (state.title) kids.push(t(state.title, state.title, { style: "h3" }));
if (state.error) kids.push(t(...(ERR[state.error] || OTHER), { color: "error" }));
kids.push({ type: "ElevatedButton", key: "next", labelText: "Otra receta", labelTextEn: "Another recipe", onPressed: "next", autofocus: true });
return page(kids);
}
export async function screenEvent({ name, state = {}, installed = {} }) {
if (installed[REPO] !== true) return null; // the gate; `open` too
if (name !== "next") return null;
try {
const r = await kino.plugins.call("recipes", "byId", { id: (state.n || 0) + 1 });
return { state: { title: r.title, n: (state.n || 0) + 1, error: null } };
} catch (e) { return { state: { error: e.code || "provider_failed", n: 0 } }; }
}
Test it (I='{"installed":{"owner/kino-plugin-recipes":true}}'; a clean run prints no dropped line):
node sdk/validate.mjs . # no ✗; read every !
node sdk/run.mjs --context "$I" --provider ../my-provider . screen # also --lang en, --device tv, and without --context (the gate)
node sdk/run.mjs --context "$I" --provider ../my-provider . screenEvent next
node sdk/run.mjs --context "$I" --state '{"error":"timeout"}' . screen # every code is drawn from the state
More: a search box, a detail route, open, unknown codes and focus, streams,
errors, the kit.
The five traps¶
SingleChildScrollViewtakeschildren(a list): withchildthe scroll is empty and nodroppedline warns you.appBarmust be{ "type": "AppBar", … }: withouttypethe whole bar is dropped.- There is no
FilledButton: useElevatedButton/TextButtonwithlabelText+labelTextEnandonPressed; and aTextwithtext: ""is dropped. - Without
--context '{"installed":{…:true}}'the kit draws the install gate and a gatedscreenEventanswers nothing; without--providerevery call isprovider_missing. - A
run.mjs screenEventvalue is the third word and JSON:screenEvent search "" '"tomate"', nevertomate.