4.6 KiB
Host API reference (version 1)
Every method a worker may call, with the permission it needs. A worker calls
them only while handling a request (parent_id). Errors return
{"error": {"message"}} as a plain sentence; show it or pass it on, don't
parse it.
Only the methods listed here exist. More host services (the organization's AI models, vision, speech, camera and microphone, saved connections and a secret store) are planned and will be added to this reference when they are released. Don't call a method that isn't listed.
Always available
| Method | Params | Result |
|---|---|---|
host.auth.has_capability |
{capability} |
{granted}: whether the signed-in user has a Cletus feature |
host.data.publish |
{path, contentType, ttl} |
{token, url, expiresAt}: a link your screen can fetch for an immutable file in your data folder; ttl is 1 to 3600 seconds, default 300 |
host.data.revoke |
{token} |
releases a link |
host.data.leases |
{path} |
the number of live links to a file |
host.data.remove |
{path} |
deletes a file in your data folder unless a link holds it (never check, then delete) |
host.event |
{name, args} |
sends an event to your screen; name starts with <your id>: |
host.screen.open |
{id, payload} |
opens your screen, or another plugin's screen that it offers as screen.open and that you use |
host.dialog.open |
{Title, DefaultDirectory, Filters: [{DisplayName, Pattern}]} |
the chosen path, or "" |
host.dialog.folder |
as open |
the chosen folder, or "" |
host.dialog.save |
{Title, DefaultDirectory, DefaultFilename, Filters} |
the chosen path, or "" |
host.dialog.message |
{Type, Title, Message, Buttons} |
the button pressed |
host.plugin.call |
{target, service, method, args} |
the provider's result; see "Services" in the specification |
Dialogs and screens are refused in background runs, where nobody is watching.
files
| Method | Params | Result |
|---|---|---|
host.files.resolve |
{path} |
the real path (a string) of a file the user opened, dropped or picked, or one in the working folder; an error otherwise. Resolve every path before reading it. |
host.files.can_write |
{path} |
true or false under the user's current write rules (read-only mode, background-run limits) |
workspace.read, workspace.write
Shared folders. Keys are full: ws:<uuid>/files/<path>. Vault (end-to-end
encrypted) folders and anything outside files/ are never visible.
| Method | Permission | Params | Result |
|---|---|---|---|
host.workspace.folders |
read | {} |
[{id, name, role, personal?}]; role is owner, member or viewer |
host.workspace.list |
read | {workspace, prefix} |
[{key, size, etag, modified}], at most 1000; workspace is an id or an exact folder name |
host.workspace.fetch |
read | {key} |
{path, etag}: a local cached copy (unchanged files aren't downloaded again) |
host.workspace.read |
read | {key} |
{data, etag, size}: the bytes as base64, in memory, at most 2 MiB |
host.workspace.put |
write | {workspace, key, path} or {workspace, key, data} |
{key, size, etag}; key is relative to files/; owner or member only |
host.workspace.delete |
write | {key} |
{key}; deleting a missing key succeeds |
host.workspace.create |
write | {name} |
{id, name, role}: a new folder the user owns |
agents
| Method | Params | Result |
|---|---|---|
host.agent.start |
{playbook_slug?, prompt, paths, label} |
{run_id} |
host.agent.status |
{run_id} |
{run_id, state, steps, last_message, error, label, report} |
host.agent.cancel |
{run_id} |
the status after the cancel |
A run is a separate Cletus conversation over files the user chose (paths,
at most 64, each passing host.files.resolve). Give a playbook, a prompt,
or both. It can use your plugin's tools and writes only inside the folders
in paths. state is queued, running, done, failed or cancelled.
Events <id>:agent-progress and <id>:agent-done carry the status; key
your screen's state by run_id. At most 4 runs per plugin are queued or
running.
identity
| Method | Params | Result |
|---|---|---|
host.auth.whoami |
{} |
{key_id, name, org, org_id}. key_id is the person's identity; names are unique only within an organization. |
Screen SDK
Arrives with the screen toolchain in a later SDK release. It will offer calls to your own worker, your events, navigation, confirm dialogs, storage, clipboard writes, the theme, and the host's components (icons, side panel, status bar, context menu, the standard 3D viewport look).