SDK
@kalam/plugin-sdk version 0.1.0 provides typed Node worker and sandboxed WebView helpers for Kalam's JSON-RPC 2.0 wire protocol. Link the package from packages/plugin-sdk in the Kalam desktop repository, or emit the JSON-RPC messages directly from any runtime.
import { definePlugin, pass, transform, divert } from '@kalam/plugin-sdk'
import { createKalamWebviewClient } from '@kalam/plugin-sdk/webview'
The newline-delimited JSON-RPC 2.0 wire protocol is the canonical host contract; new host events or fields documented in Hooks and Host methods can always be read directly even before TypeScript definitions expand in a future SDK release.
Worker: definePlugin
definePlugin reads stdin and writes stdout. One JSON object per line. It returns the same host object your handlers receive.
| Handler | Host message | Reply |
|---|---|---|
setup(host) | none — runs once at boot | none |
onHook(event, host) | kalam.hook notification | none |
onConfigChanged(config, host) | kalam.config_changed notification | none |
onIntercept(ctx, host) | kalam.intercept request | pass, transform, or divert |
onPillSlotClick(slotId, host) | kalam.pill.slot_click request | any JSON result |
onViewOpen(viewKind, host) | kalam.view.open request | none |
methods[name](params, host) | request whose method name is name | any JSON result |
Unknown request methods return error -32601. A thrown error returns -32000 with the error message.
Interceptor context
| Field | Meaning |
|---|---|
interceptor_id | Manifest interceptor id. |
stage | before_polish or before_inject. |
text | Text at this stage. An earlier interceptor may already have changed it. |
raw_stt | Transcript before polish. |
mode_id | Active mode. |
focus | FocusSnapshot. |
Decisions
| Helper | JSON |
|---|---|
pass() | { "action": "pass" } |
transform(text) | { "action": "transform", "text": "…" } |
divert() | { "action": "divert" } |
divert(message) | { "action": "divert", "status_message": "…" } |
transform replaces the text for later stages. divert stops insert. Return one of these. A missing action is not a pass.
Host client
host.call(method, params) sends { jsonrpc: "2.0", id, method, params } and waits for result. A host error rejects the promise with error.message.
Typed wrappers map to these methods:
| Wrapper | Method |
|---|---|
getConfig() | config.get |
currentFocus() | focus.current |
systemIdle(thresholdSecs?) | system.idle |
insertText(text) | insert.text |
llmComplete(prompt, { system, slot }) | llm.complete |
llmStructured(prompt, { system, schema }) | llm.structured — resolves to { data } |
renderOpenUI(code, state?) | ui.renderOpenUI |
setPillSlot({ slot_id, text, icon, tooltip, accent }) | pill.setSlot |
clearPillSlot(slotId?) | pill.clearSlot |
notifyPill(message) | pill.notify |
emitUI(event, payload?) | ui.emit |
entries.query / create / update | unwraps entries or entry |
entries.delete(id) | entries.delete |
kv.get / set / delete / list | storage.kv.* — get returns the value or null |
sql.query(sql, params?) | returns rows |
sql.execute(sql, params?) | returns { rows_affected, last_insert_rowid } |
Parameter tables and error codes are on Host methods.
Custom methods
definePlugin({
methods: {
'stamp.preview': async (params, host) => {
const text = String(params.speech ?? '')
return { text, status_message: 'Stamped' }
},
},
})
A voice command of kind plugin_action calls this name directly (stamp.preview). A WebView calls it as callWorker('stamp.preview', params), which the bridge sends to the host as worker.stamp.preview. The worker still sees the name without the worker. prefix when the host forwards it. Voice-command params are the object in Command actions.
WebView
Plugin pages run in <iframe sandbox="allow-scripts"> on kalam-plugin://. They have no Tauri IPC. createKalamWebviewClient posts to window.parent and listens for replies.
Call it once, at load. The helper immediately posts { type: 'kalam:webview:ready' }. A custom Pill skin must do this within the host's readiness wait (3 seconds).
| You send | Host sends back |
|---|---|
{ type: 'kalam:webview:ready' } | { type: 'kalam:host:init', theme, tokens } |
{ type: 'kalam:webview:rpc', id, method, params } | { type: 'kalam:host:rpc-reply', id, ok, result or error } |
{ type: 'kalam:host:hook', event } | |
{ type: 'kalam:host:plugin-event', event, payload } | |
{ type: 'kalam:host:overlay-state', state } on a Pill skin | |
{ type: 'kalam:host:audio-level', level } while recording, about 30 times a second |
callHost(method, params) uses a host method name such as storage.sql.query. callWorker(method, params) prefixes worker.. setPillHitRectFromElement(element) sends pill.setHitRect with the element's box. That call requires pill:replace, and the plugin must be the active Pill skin.
By default the helper writes the theme tokens onto document.documentElement as CSS variables and sets data-theme. Pass { applyRisoTokens: false } to skip that. onTheme, onHook, onPluginEvent, onOverlayState, and onAudioLevel are optional.
destroy() removes the listener. Call it if the page tears the client down without unloading.
End-to-end WebView + Worker example
In a sidebar WebView (index.html):
const kalam = createKalamWebviewClient({
onHook(event) {
if (event.event === 'dictation.delivered') renderRecent()
},
})
const entries = await kalam.callWorker('tasks.list', { limit: 10 })
await kalam.callHost('pill.setSlot', { slot_id: 'tasks-badge', text: `${entries.length} open` })
In the matching Node worker (bin/worker.mjs):
definePlugin({
methods: {
'tasks.list': async ({ limit = 10 }, host) => {
const { entries } = await host.call('entries.query', { entry_type: 'task', limit })
return entries
},
},
})