Use built-in and third-party plugins

Plugins connect the Scientific Agent research loop to domains, solvers, evaluators, and reporting tools. A run authorizes named capabilities such as toy.evaluate; it does not give the Reasoner unrestricted access to local programs.

Plugin states

The Plugins page exposes these states:

An existing research contract retains its plugin and capability records. Installing, disabling, or updating a plugin primarily affects new runs.

Preinstalled and on-demand plugins

Desktop preinstalls seven reviewed project-plugin packages. Universal packages and the dependency-free symbolic baseline can share Runtime Core's process; Beam remains app-owned but uses an isolated environment for Xsuite:

toy and executor.local remain Runtime reference aliases rather than managed plugin packages. Settings → Plugins or /api/v1/capabilities is authoritative for all capabilities currently available on the machine.

The general ml.symbolic_regression PySR provider is shipped in the local Available catalog and is installed into an isolated environment when a symbolic-search task leases it. The enabled builtin provider is only a bounded polynomial fallback and is not silently substituted for PySR. Other specialized packages such as three-body are not bundled into the application. A source checkout may expose them through approved local roots, and a user can install a separately supplied custom ZIP. The current release has no remote plugin marketplace. The repository also contains runnable teaching domain plugins:

• physics.three_body for three-body integration and surrogate dataset generation;
• tutorial.oscillator, the zero-dependency example built in this guide.

Use a plugin in Desktop

1. Open Settings → Plugins.
2. Browse Core or Domain categories.
3. Expand a plugin and inspect capabilities, inputs, metric outputs, dependencies, and Runtime requirements.
4. Choose Install for an Available plugin.
5. Wait while Desktop automatically prepares the plugin's private dependency environment.
6. Review the manifest and choose Enable; only this step probes/imports plugin code in its worker.
7. When the local catalog contains a newer version, the list and detail views show the installed → available version. Choose Update to keep the plugin's existing Enabled or Disabled state.
8. The default new-task page leases capabilities from the request and attachments. In Advanced setup, select only the capabilities needed for that study.

The detail view lets you review the candidate dependencies, capabilities, runtime requirements, and full manifest before updating. An update is copied to a staging directory and its manifest, dependencies, and worker are validated before the installed directory is replaced. A replacement or state-persistence failure restores the old version. A plugin cannot be updated while a nonterminal run uses it. Built-in plugins do not have an individual Update action; they are upgraded with Runtime.

Desktop uses its bundled uv executable to install declared Python dependencies into an immutable environment owned by that plugin. It does not modify Runtime Core, another plugin, or a system Python installation. Custom ZIP dependencies are binary-wheel-only. A separately allowlisted, reviewed catalog plugin may automatically build a source distribution in the managed installer environment when no wheel exists. If preparation fails, inspect the error for an unsupported requirement, unavailable distribution, network problem, or incompatible platform; do not repair the app's own Python environment manually.

Use a plugin from the CLI

The plugins list accepts repository-relative directories, absolute directories, and built-in aliases:

plugins:
  - examples/plugins/three_body_solver
  - executor.local

capabilities:
  - physics.three_body.solve
  - execution.local.run

Run it normally:

scientific-agent run my-study.yaml

When starting the Control API, repeat --plugin-dir to add discovery locations:

scientific-agent serve \
  --plugin-dir ./my-plugins/one \
  --plugin-dir ./my-plugins/two

List discovered capabilities:

curl -sS http://127.0.0.1:8000/api/v1/capabilities | jq

Install or update a custom ZIP

In Desktop, choose Install or update from ZIP and select a .zip. A valid package must:

• contain exactly one unambiguous manifest named plugin.yaml, plugin.yml, or plugin.json;
• provide an importable in-package entrypoint;
• contain no absolute paths, path traversal, symlinks, encrypted entries, or duplicates;
• be at most 10 MiB compressed, 50 MiB expanded, and 512 files.

Repository developers can produce a deterministic, versioned archive and checksum with:

python scripts/release_domain_plugin.py path/to/domain_plugin

Installation validates the ZIP and manifest, copies the package, and prepares its dependencies without importing Python code. Code is probed/imported in an isolated worker only when you choose Enable.

When the ZIP has the same plugin ID as an installed custom plugin and a strictly newer three-part manifest version (for example, 1.4.0 → 1.5.0), the same control updates it. Equal versions, downgrades, prerelease labels, and non-three-part versions are rejected; a custom ZIP also cannot replace a catalog or built-in plugin. Updating preserves the existing Enabled, Disabled, or Installed state and uses the same staging and rollback path as a catalog update.

Task-generated project plugins

When a one-request task explicitly requires a reusable tool and has produced an accepted file-predictor-v1 model, inference source, exact evaluation artifact, accepted predictor output, and model card, Runtime can build a plugin candidate from fixed templates. It does not accept arbitrary plugin source or let the Reasoner edit the registry. The publisher wraps those recorded artifacts, plus an optional solver helper and report, and records SHA-256 identities for source artifacts and package files. Control rejects the package unless its attestation exactly matches the frozen successful predictor and every recorded non-Runtime acceptance metric.

After the task succeeds, the candidate still passes the normal managed archive, reserved-ID, dependency, install, and worker checks. A published entry has origin=generated; later tasks can lease its inference capability and Settings can manage it. Its model card supplies input/output schemas, validity domain, informational evaluation metrics, and task tags for conservative reuse; ambiguous compatible tools are not selected silently. Applicable result exports include exactly the published plugin ZIP, frozen model, minimal example, and instructions. Digest attestation is not a code signature or independent scientific evidence.

Generate an adapter plugin from a solver folder

The Create page can also select a folder containing README/usage documentation and a native executable. Web and Desktop deterministically package it as one ZIP attachment, limited to 512 regular files, 50 MiB before compression, and 10 MiB compressed. Unsafe paths, duplicates, and limit overruns are rejected during packaging or backend validation; native Desktop selection also rejects symlinks and special entries. Backend profiling reads at most 64 KiB of README text and statically inspects ELF, PE, or Mach-O headers. It neither starts the binary nor extracts the whole archive. A qualifying attachment is solver_bundle; its README excerpt is untrusted user documentation, not execution authority.

After the operator checks the existing Allow reusable plugin publishing permission, the Agent may implement a Python compatibility layer under file-solver-adapter-v1. It accepts --solver-root, --solver-executable, --input, and --output; the contract requires Local Executor to run a bounded help/version or documented-example smoke test as a child process. The fixed runtime.solver_adapter.publish publisher accepts exactly three immutable Artifact inputs: the original solver_bundle, generated adapter_source, and validation. It checks the validation record's declared pass state, interface, exact bundle/source SHA-256 values, and Artifact provenance; embedded and external attestations then bind all three Artifact IDs/SHA-256 values and every package file. Control rechecks that three-source lineage and package digest before the managed install/enable flow publishes an origin=generated project plugin. The validation record and attestation are not independent proof that the smoke test actually ran. This does not relabel binary wrapping as model training or a final predictor.

ExternalBinarySecurityReviewer is a replaceable publisher-policy interface. Its current default explicitly returns permissive_deferred: it permits publication and records independent_binary_review_performed=false, but performs no malware scan, signature validation, provenance authentication, or independent binary safety review. Digest attestation proves identity and lineage; it must not be described as a passed security review. Both smoke validation and later adapter calls run with the current user's operating-system authority.

Choose the right capability

Open capability details and focus on:

• required_inputs: ordinary fields required on every call;
• artifact_inputs: existing artifacts and expected types;
• metric_outputs: acceptance metrics the capability can support;
• example and cost_hints: valid input shape and approximate resource cost.

If several plugins implement the same abstract capability, the detail view lists each provider. The research contract records the concrete provider so an environment change cannot silently swap implementations later.

Core and Domain

• Domain plugins express operations in a scientific or problem domain, such as three-body integration and beam tracking.
• Core plugins provide cross-domain infrastructure such as execution, evaluation, analysis, knowledge management, and reporting.

The category aids discovery; it does not grant higher privilege. Special authority comes from the trusted_evaluator access role, which should be reserved for independent evaluators.

Security boundary

Managed plugins run in separate worker processes with separate Python dependency directories and without provider credentials in their process environment. This avoids dependency conflicts; it is not an operating-system security sandbox. An enabled plugin still has the current user's local authority. Install only packages from sources you trust, and inspect the manifest, dependencies, and source before enabling one.

Local Executor, generated-predictor inference, and generated external-solver adapters run as ordinary child processes on Linux, macOS, and Windows. Runtime enforces workspace, credential filtering, digest, timeout, and output checks, but these are not an OS sandbox; the process retains the current user's filesystem and network authority. A permissive_deferred external-binary reviewer status does not mean that the solver passed a security review.

When a plugin fails

Check in this order:

1. It is Enabled, not merely Installed.
2. Dependency preparation produced an environment_id and worker probing succeeded.
3. The research contract selected the correct capability.
4. Input field names and artifact types match capability details.
5. Failure, Jobs, and logs show no load_error or execution error.

If an upgrade changes capability names or input formats, copy the old run configuration and migrate it explicitly. Never edit a research contract after its run has started.

Managed worker protocol v1 supports ordinary ScientificPlugin packages. Custom isolated executors are currently unsupported, and plugin-local reasoners are not transported into Desktop; Desktop uses its configured Runtime reasoner. Direct CLI directory loads remain an in-process developer path using the current Python environment.