cletus-plugins/docs/patterns.md

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 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.