Autonomous Agents Knowledge Modules

Plugins are small packages the SideButton MCP server loads from ~/.sidebutton/plugins/ and exposes as extra MCP tools. The catalogue lives in agent-runners/plugins.json (validated against plugins.schema.json) and is vendored by the portal to label the plugin chips it shows per agent. Each plugins.json entry maps a slug → public git repo (+ ref, submodules, system_deps).At provision time the portal forwards SIDEBUTTON_PLUGINS = a profile's default_plugins ∪ any provision-request override (see [[runners]] for profiles).base/19b-plugins.sh runs after 19-secrets.sh, clones the requested slugs into ~/.sidebutton/plugins/, then systemctl restart sidebutton so the server loads the new plugins together with the now-populated ~/.agent-env.Plugins only apply to variants that ship a server (ext, noext) — never the bare variant.The agent reports loaded plugins on GET /health (plugins[]); the portal fleet list + agent detail render those chips. A plugin folder contains a plugin.json manifest plus handler scripts the server shells out to (e.g. screen-record/handlers/{start,stop,list}_recording.sh). Tools surface in MCP tools/list once the server restarts. A plugin that needs a secret (e.g. writing-quality → ANTHROPIC_API_KEY) is useless until 19b restarts the server after secrets land — order matters.system_deps in a plugin entry are apt packages installed before the clone; a missing dep makes the tool load but fail at call time.The bare (ubuntu-claude-code) variant has no server, so SIDEBUTTON_PLUGINS is ignored there.Code-first module — verify the live catalogue against plugins.json at the pinned RUNNERS_REF before relying on a specific slug. See [[runners]] for how SIDEBUTTON_PLUGINS is wired through profiles and the provisioning pipeline.

How a SideButton agent VM is built. The agent-runners repo is a thin bootstrapper + a shared base/ set of ordered step scripts + per-variant overlays. It is also the single source of truth for what the Fleet Control portal displays for each variant + profile + plugin (the portal vendors these manifests rather than hardcoding). Production agents are provisioned by piping https://sidebutton.com/install.sh to bash. That thin bootstrapper resolves AGENT_RUNNER (variant) + RUNNERS_REF (git ref), downloads this repo at the requested ref, and hands off to base/run.sh, which sources the base/NN-*.sh steps in order. install.sh at the repo root is the direct entry point that dispatches to base/run.sh. A variant = a VM image recipe. kind drives portal status dots; display is the fleet-list fallback when a row has no profile. New variant = drop a folder under variants/<name>/ (≥ a manifest.json, optional pre-services / post-services / early-setup hooks) + an entry in variants.json. The product-level catalogue the Create-Agent wizard offers. Each profile picks a runner variant + default_roles + default_plugins. aliases maps renamed slugs so already-provisioned agents keep resolving (e.g. claude-code-headless → swe-native).

The contract for an agent that holds a live editing session on a workspace project: the project's own dev server runs on the agent VM and the user watches it through the portal while chatting with the agent. This module is what app_edit_session (see ops/) runs on — read it before booting a session and whenever a session misbehaves. Two lanes carry the work, and confusing them is the usual source of bugs. The live lane is the dev server: sub-second feedback, VM-local, gone when the VM is gone. The durable lane is git — a real commit pushed to the project's branch at every turn end. It survives spot reclaim, it is what the user can share, and for a repo project it is the only durable lane: the landing floor's auto-republish is switched off for projects that have an origin remote (SCRUM-1965), precisely so there is one answer to "where did my work go". The platform's per-turn autosave (SP-D, SCRUM-1937) mirrors uncommitted work to a scratch ref as a spot-reclaim safety net; it is not a substitute for the push. Every hop above the daemon is authenticated, and the daemon hard-pins the upstream to 127.0.0.1. The /api/preview/ passthrough itself ships with SP-B/SP-C (SCRUM-1935/1936) — until those land the dev server is simply unreachable from outside the VM, which changes nothing about how the agent must start it. So:

Operational workflows for autonomous agent fleets: repo management, environment updates, QA validation, SE implementation, PM epic analysis and breakdown, SD coverage improvement, experiment scoring, public data collection. Workflows that produce evidence — screenshots, logs, mocks, diagrams, datasets, reports — save each file and publish it during the session via the publish_artifact tool (an agent-local sidebutton-server tool; SCRUM-1606). The tool uploads the file, attaches it to the job's ticket, and returns a download_url: a tokenized, no-login, revocable link. The agent cites that link inline in its single resolution comment, so one comment carries both the outcome and its evidence — no separate "📎" attachment comment is posted for agent-initiated publishes.