Skip to main content
Kalam Documentation

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​

CodeNameWhen
-32600Invalid requestjsonrpc is not 2.0.
-32601Method not foundThe host does not implement that name.
-32602Invalid paramsA required field is missing or the wrong type.
-32001Permission deniedThe manifest does not list the capability.
-32002Sensitive foregroundThe focused app is marked sensitive.
-32003Host failureThe 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​

ParamDefaultValues
slotcommandsstt, 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.

ParamDefault
threshold_secs300, 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.

MethodPermissionResult
context.selectioncontext:selection{ "text": string }
context.clipboardcontext:clipboard{ "text": string }
context.urlcontext: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​

ParamRequiredMeaning
promptyesUser text.
systemnoDefaults to a short instruction to be concise.
slotnopolish uses the polish engine. Any other value, including omission, uses the commands engine.

Result: { "text": string }.

llm.structured​

ParamRequiredMeaning
promptyesWhat to extract.
systemnoDefaults to an instruction to return JSON.
schemanoAppended 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​

ParamDefaultMeaning
entry_typenotenote, task, reminder, or history
scopeomittedPassed through to the library query
limit50Page size
offset0Page start

Result: { "entries": [ ... ] }. Any other entry_type is -32003.

entries.create​

ParamRequiredMeaning
contentyesBody text.
entry_typenonote (default), task, or reminder. history cannot be created here.
titlenoString.
tagsnoArray of strings.
colornoString.
is_pinnednoBoolean, default false.
prioritynoInteger that fits in a byte. This is not the words low / medium / high.
due_datenoRFC 3339, or YYYY-MM-DD (stored as 12:00 UTC that day).
reminder_atnoSame timestamp forms as due_date.
is_completednoBoolean.
rrulenoRecurrence string.
subtasksnoArray the host can decode as subtasks.
target_app, target_app_name, raw_sttnoStrings 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.

ParamLimitMeaning
text24 characters after trimRequired. Empty text clears the slot.
slot_idmust be declared when pill_slots is non-emptyDefaults to the first declared slot, or default.
icon48 charactersOptional.
tooltip120 charactersOptional. Falls back to the manifest tooltip.
accent32 charactersOptional.

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.

actionEffect
get_stateReturns the current Pill state. Does not change it.
list_modesReturns the mode list. Does not change it.
toggle_recording, toggle_dictationStarts or stops dictation.
stop_recordingStops dictation.
cancel, cancel_transcriptionCancels the current transcription.
set_modeSets the active mode to mode_id.
restore_default_pill, restore_defaultRestores 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.

MethodParamsResult
storage.kv.getkey (1–512 characters){ "value": any or null }
storage.kv.setkey, value{ "ok": true }
storage.kv.deletekey{ "deleted": boolean }
storage.kv.listprefix optional{ "keys": string[] }
storage.sql.querysql, params (array, default []){ "rows": object[] }
storage.sql.executesql, 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.