83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# 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).
|