Skip to main content
Kalam Documentation

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.

HandlerHost messageReply
setup(host)none — runs once at bootnone
onHook(event, host)kalam.hook notificationnone
onConfigChanged(config, host)kalam.config_changed notificationnone
onIntercept(ctx, host)kalam.intercept requestpass, transform, or divert
onPillSlotClick(slotId, host)kalam.pill.slot_click requestany JSON result
onViewOpen(viewKind, host)kalam.view.open requestnone
methods[name](params, host)request whose method name is nameany JSON result

Unknown request methods return error -32601. A thrown error returns -32000 with the error message.

Interceptor context​

FieldMeaning
interceptor_idManifest interceptor id.
stagebefore_polish or before_inject.
textText at this stage. An earlier interceptor may already have changed it.
raw_sttTranscript before polish.
mode_idActive mode.
focusFocusSnapshot.

Decisions​

HelperJSON
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:

WrapperMethod
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 / updateunwraps entries or entry
entries.delete(id)entries.delete
kv.get / set / delete / liststorage.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 sendHost 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
},
},
})