Host methods
A worker calls the host with JSON-RPC 2.0 on stdout. One object per line.
{ "jsonrpc": "2.0", "id": "sdk-1", "method": "entries.create", "params": { "entry_type": "note", "content": "Buy milk" } }
Success:
{ "jsonrpc": "2.0", "id": "sdk-1", "result": { "entry": {} } }
Failure:
{ "jsonrpc": "2.0", "id": "sdk-1", "error": { "code": -32001, "message": "Permission denied: plugin 'com.example.note' lacks capability 'entries:write'" } }
jsonrpc must be "2.0". Method names are case-sensitive. The SDK wrappers in SDK send these names for you.
Error codes
| Code | Name | When |
|---|---|---|
-32600 | Invalid request | jsonrpc is not 2.0. |
-32601 | Method not found | The host does not implement that name. |
-32602 | Invalid params | A required field is missing or the wrong type. |
-32001 | Permission denied | The manifest does not list the capability. |
-32002 | Sensitive foreground | The focused app is marked sensitive. |
-32003 | Host failure | The call ran and failed. Read message. |
The platform must be on, and the plugin must be enabled, before the supervisor will deliver the call.
Methods that need no permission
config.get
Params: none. Result: the JSON object from config_schema defaults merged with the values saved in Labs.
engine.current
| Param | Default | Values |
|---|---|---|
slot | commands | stt, polish, commands |
Result: an EngineSnapshot. Any other slot is -32602.
Focus and idle
focus.current
Permission: focus:read. Result: a FocusSnapshot.
system.idle
Permission: idle:read.
| Param | Default |
|---|---|
threshold_secs | 300, and never below 5 |
Result when the OS reports idle time:
{ "supported": true, "state": "active", "idle_secs": 12 }
state is idle when idle_secs is at least the threshold. When the OS cannot report idle time, the result is { "supported": false, "state": "active", "idle_secs": null }.
Context
Each of these needs its own permission and returns -32002 when the foreground app is sensitive.
| Method | Permission | Result |
|---|---|---|
context.selection | context:selection | { "text": string } |
context.clipboard | context:clipboard | { "text": string } |
context.url | context:url | { "url": string } |
context.url reads the URL from the focused browser window. It is not a general HTTP client.
insert.text
Permission: insert:text. Param: text (string, required). The host types that string into the focused field, using the same insert path as dictation. The result is the host's insert report. Treat a response with no error as success.
Language model
Permission: llm:invoke. Both methods return -32002 on a sensitive foreground. The key stays in Kalam. You send a prompt, not a credential.
llm.complete
| Param | Required | Meaning |
|---|---|---|
prompt | yes | User text. |
system | no | Defaults to a short instruction to be concise. |
slot | no | polish uses the polish engine. Any other value, including omission, uses the commands engine. |
Result: { "text": string }.
llm.structured
| Param | Required | Meaning |
|---|---|---|
prompt | yes | What to extract. |
system | no | Defaults to an instruction to return JSON. |
schema | no | Appended to the system text as a JSON schema hint. |
The host always uses the commands engine for this method. It strips a markdown ```json fence if the model added one, then parses the body. Result: { "data": <parsed JSON> }. Invalid JSON is -32003.
Entries
entries.query needs entries:read. Create, update, and delete need entries:write.
entries.query
| Param | Default | Meaning |
|---|---|---|
entry_type | note | note, task, reminder, or history |
scope | omitted | Passed through to the library query |
limit | 50 | Page size |
offset | 0 | Page start |
Result: { "entries": [ ... ] }. Any other entry_type is -32003.
entries.create
| Param | Required | Meaning |
|---|---|---|
content | yes | Body text. |
entry_type | no | note (default), task, or reminder. history cannot be created here. |
title | no | String. |
tags | no | Array of strings. |
color | no | String. |
is_pinned | no | Boolean, default false. |
priority | no | Integer that fits in a byte. This is not the words low / medium / high. |
due_date | no | RFC 3339, or YYYY-MM-DD (stored as 12:00 UTC that day). |
reminder_at | no | Same timestamp forms as due_date. |
is_completed | no | Boolean. |
rrule | no | Recurrence string. |
subtasks | no | Array the host can decode as subtasks. |
target_app, target_app_name, raw_stt | no | Strings stored on the entry. |
Result: { "entry": { ... } } including the new id.
entries.update
id is required. You may send any of title, content, is_completed, priority (null clears it), due_date, reminder_at, tags, color, is_pinned, rrule, and subtasks. The host only updates fields you include. Notes, tasks, and reminders can be updated. Other types return an error.
Result: { "entry": { ... } }.
entries.delete
Param: id (string, required). Result: { "deleted": boolean, "id": string }.
Interface
ui.renderOpenUI
Permission: ui:view. Params: code (string, required), state (object, optional). Result: { "ok": true }. code is OpenUI source. The host renders it in the plugin view.
ui.emit
Permission: ui:view, pill:slot, or pill:replace. Params: event (string, required), payload (object, default {}). Result: { "ok": true }. Mounted WebViews for this plugin receive kalam:host:plugin-event.
pill.setSlot
Permission: pill:slot.
| Param | Limit | Meaning |
|---|---|---|
text | 24 characters after trim | Required. Empty text clears the slot. |
slot_id | must be declared when pill_slots is non-empty | Defaults to the first declared slot, or default. |
icon | 48 characters | Optional. |
tooltip | 120 characters | Optional. Falls back to the manifest tooltip. |
accent | 32 characters | Optional. |
Result: { "ok": true }, or { "ok": true, "cleared": true } when text is empty.
pill.clearSlot
Permission: pill:slot. Param: slot_id (optional). Omit it to clear every slot this plugin set. Result: { "ok": true, "removed": number }.
pill.notify
Permission: pill:slot or pill:replace. Param: message (string, required, trimmed, max 80 characters, not empty). Result: { "ok": true }. This is a short status line. It does not take focus.
pill.setHitRect
Permission: pill:replace. The plugin must be the active Pill skin.
Either { "clear": true }, or numeric x, y, width, and height. Width and height must be finite and greater than zero. Result: { "ok": true }. The SDK helper setPillHitRectFromElement fills these from the element box.
pill.control
Permission: pill:replace. The plugin must be the active Pill skin. Param: action (string, required). mode_id is required for set_mode.
action | Effect |
|---|---|
get_state | Returns the current Pill state. Does not change it. |
list_modes | Returns the mode list. Does not change it. |
toggle_recording, toggle_dictation | Starts or stops dictation. |
stop_recording | Stops dictation. |
cancel, cancel_transcription | Cancels the current transcription. |
set_mode | Sets the active mode to mode_id. |
restore_default_pill, restore_default | Restores the Kalam Pill. |
Any other action is -32003 with Unknown pill control action.
get_state and list_modes return the state object directly. The other actions return { "ok": true }.
Local storage
Permission: storage:local. Data lives in <plugin folder>/data/plugin.db. The connection denies ATTACH, DETACH, load_extension, and pragmas other than table_info, index_list, index_info, foreign_key_list, foreign_keys, user_version, journal_mode, synchronous, and busy_timeout. sqlite-vec virtual tables (vec0) are available in this database. A query returns at most 1000 rows.
| Method | Params | Result |
|---|---|---|
storage.kv.get | key (1–512 characters) | { "value": any or null } |
storage.kv.set | key, value | { "ok": true } |
storage.kv.delete | key | { "deleted": boolean } |
storage.kv.list | prefix optional | { "keys": string[] } |
storage.sql.query | sql, params (array, default []) | { "rows": object[] } |
storage.sql.execute | sql, params (array, default []) | { "rows_affected": number, "last_insert_rowid": number } |
Bind values with params. Do not interpolate untrusted text into sql.
What is not a host method
There is no net.fetch. net:http only widens the WebView allow list to the origins in net_allowlist. A Node worker can use its own HTTP stack. That traffic is the worker's, and it is not mediated by these methods.
process:spawn does not execute a command you pass at runtime. It only allows the manifest to declare entrypoints.backend.
Voice-command delivery (plugin_action) is a call from Kalam into your worker, not a host method you invoke. See Command actions.