# Patterns

How to build common kinds of plugin on this contract. Each pattern says what
works today and what waits for a later release.

## Chat tools over your own files and formats

Works today. The smallest useful plugin and the fastest to review.

- Tools that read a format Cletus doesn't understand (an instrument export, a
  machine log, a proprietary report) and return a short, typed summary.
- `files` permission; every path through `host.files.resolve`.
- Large results are written to a file next to the input (after
  `host.files.can_write`) and the tool returns its path and a summary.

## Long computations and batch jobs

Works today.

- A tool or service that starts a job returns a job id at once. Separate
  tools report `status`, return `results` and `cancel`.
- Job state lives in the data folder, so a restarted worker can report it.
- `plugin.busy` answers `true` while a job runs, so Cletus doesn't stop the
  worker for an update.
- Results are written in the folder the user chose, never elsewhere.

## Shared reference data

Works today.

- Reference data a team shares (standards, tables, templates) lives in a
  shared folder the user picks (`workspace.read`), never inside the plugin.
- The worker fetches it with `host.workspace.fetch`, which caches unchanged
  files.
- Writing results back for the team needs `workspace.write`.

## Reading documents in the background

Works today.

- `agents`: `host.agent.start` runs Cletus over the files the user chose,
  with a playbook or a prompt. The run can call your plugin's own tools.
- Poll `host.agent.status`, or wait for `<id>:agent-done`.

## Connecting machines, databases and services

Works today, with direct network access.

- `net.configured` for addresses the user enters (controllers, databases,
  instruments), or `net:<domain>` for a fixed service.
- Pure-Go drivers only.
- Read-only by default. Every write is a separate tool marked `mutating` and
  `requires_approval`, and `docs/plan.md` says what it changes.
- Until the secret store ships, ask for passwords when needed and keep them
  in memory only.

## Libraries written in C or C++

Works today.

- Compile them to WebAssembly from source in your repository and run them
  with [wazero](https://wazero.io) inside the worker.
- The build stays pure Go, and review sees the library source.

## With a later release

- **Screens:** 2D and 3D screens in a sandboxed frame. The worker computes
  and publishes data (`host.data.publish`); the screen draws it.
- **The organization's AI, vision and speech:** summaries, image reading,
  transcription.
- **Camera and microphone** through the host.
- **Saved connections and a secret store.**
- **Services of Eidonix plugins**, such as opening a file in CAD Viewer.