YOUR AI PLATE HANDBOOK
Runtime context & artifacts
Use storage, files, Python, and document search from a tool.
Desktop source reviewed October 5, 2026
PluginContext reference
| API | Behavior |
|---|---|
| pluginId / params | Executing plugin identity and input object. |
| fs.readFile(path, encoding?) / readBuffer(path) | Search sandbox, artifacts, then working directory. |
| fs.writeFile(path, content) | Write relative to the sandbox directory; returns the full path. |
| fs.saveArtifact(filename, content) | Save under artifacts using the basename; returns the full path. |
| fs.listSandboxFiles() / listArtifactFiles() | List immediate, non-dot entries. |
| fs.exists(path) / deleteFile(path) | Check lookup locations / delete a sandbox-relative file. |
| fs.getSandboxDir() / getArtifactsDir() | Resolve working directories. |
| storage.get(key, fallback?) / set(key, value) | Persistent SQLite values scoped to this plugin. |
| storage.delete(key) / list() / clear() | Remove, enumerate, or reset plugin data. |
| shell.exec(command, timeoutMs?) | Execute in the sandbox working directory; default 30 seconds. |
| shell.runPython(codeOrPath, args?, timeoutMs?) | Run Python source or a .py file; Python must be available to this helper. |
| rag.search(query, topK?) | Return document, text, and similarity; default topK is 3. |
| rag.ingest(name, text) / listDocuments() | Ingest text / inspect knowledge-base documents. |
| crypto / Buffer / env / log() | Runtime utilities, environment snapshot, and structured plugin log. |
Create an artifact
const content = 'month,revenue\nJan,20000\nFeb,25000\n';
const path = fs.saveArtifact('monthly-revenue.csv', content);
return { success: true, path, message: 'Saved the revenue CSV.' };The returned path identifies the saved file. UI rendering depends on the app’s artifact flow; returning a path is not a guarantee that every custom object will become a rich card.
Runtime considerations
- Validate path inputs yourself. Current helpers resolve paths but do not universally enforce directory containment.
- Do not interpolate untrusted input into shell command strings. Prefer fixed commands and validated values.
- env is a snapshot of process.env and may contain secrets. Never dump it to logs or tool results.
- rag.search returns [] on internal failure in the current implementation; an empty result may also mean an embedding/configuration problem.
- Uninstall clears the plugin’s persistent storage. Export user data before uninstalling if you need to keep it.
Implementation sources
Paths in your AI Plate source checkout:
core/types.tscore/plugin-manager.ts