Cletus plugin kit: rules for coding agents, specification, host API, style guide, worker SDK and cletus-plugin tool

docs/host-api.md

@@ -0,0 +1,82 @@
+# 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).