plugin-record

Placement	runtime (out-of-process over gRPC)
Source	github.com/opencharly/charly/candy/plugin-record
Version	2026.182.1805
Candy	plugin-record

This plugin is not listed in charly/charly.yml’s compiled_plugins:. It is not part of the shipped binary: charly builds and loads it out-of-process over gRPC when a plan references one of its words (the coexist path).

Providers

The reserved words this plugin serves:

• record — verb class

What it does

OUT-OF-TREE charly plugin serving the record live-container check verb — a standalone Go module (go.mod + main.go) that manages recording sessions inside a running deployment (list, start, stop, cmd) over go-plugin gRPC via the charly plugin SDK (github.com/opencharly/sdk). charly’s loader fetches this candy’s repo, go-builds the provider binary on the HOST, and serves it OUT-OF-PROCESS via LocalTransport — so the asciinema/wf-recorder/pixelflux recording driver lives HERE, out of charly’s core check surface (the first live-verb dep-shed of the EXEC-based kind, after the PORT-based candy/plugin-mcp/spice/kube). Since the schema-compaction cutover an authored record: step desugars to the internal plugin/plugin_input envelope, and every record-exclusive modifier (method/record_name/record_mode/record_fps/record_audio/text/artifact) lives in the plugin’s OWN #RecordInput (schema/record.cue); the verb dispatches through the provider registry exactly like a built-in (ResolveVerb → grpcProvider → invokeVerbProvider hands it the full #Op). FIRST consumer of the executor reverse channel: record is EXEC-based, so the host attaches its live DeployExecutor over the E3b reverse channel and this plugin dials back through the SDK (sdk.ExecutorFromInvoke) to RunCapture the asciinema/wf-recorder commands in-container via tmux and GetFile the produced .cast/.mp4 artifact back to the host — it owns no podman / SSH machinery. The R10 consumer is a desktop pod bed whose check composes this plugin (the sway-browser-vnc bed’s record: start).

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/record.cue

// The `record` plugin's OWN CUE schema — the typed plugin_input for the
// `record` session-recording check verb. It is the SINGLE SOURCE for this
// plugin's params, used two ways (the same contract core `spec` and the http
// plugin use):
//
//  1. GENERATE the Go param struct — `cue exp gengotypes` (driven by the cue:gen
//     pipeline, which wraps this with `package params` + `@go(params)`) emits
//     ../params/cue_types_gen.go, so the provider decodes plugin_input into a
//     TYPED struct, never a hand-parsed map.
//  2. VALIDATE authored input AT RUNTIME — the plugin serves this source over the
//     Describe channel; the host splices it onto the base (base ++ plugin) and
//     validates every authored `record:` step's plugin_input against
//     #RecordInput.
//
// Since the schema-compaction cutover the per-verb fields LEFT core #Op: an
// authored `record: <method>` step (scalar sugar) or `record: {method: …,
// record_name: …}` (map form) desugars to the INTERNAL plugin/plugin_input
// envelope, and every record-exclusive modifier lives HERE — the former core
// #RecordMethod enum is this def's `method` field. The shared assertion
// matchers (exit_status/stdout/stderr) and the general `timeout` stay on core
// #Op, read off the step Op by the provider.
//
// SELF-CONTAINED: it references NO base def, so it compiles standalone
// (gengotypes + the load-gate compile) AND splices onto the base (base ++ plugin
// is a def-name collision check, not a base-reference resolver).
#RecordInput: {
  // method — the record method to dispatch (the former core #RecordMethod
  // enum; also the scalar-sugar primary: `record: <method>`).
  method: "list" | "start" | "stop" | "cmd"
  // record_name — the recording session name (default "default").
  record_name?: string @go(RecordName)
  // record_mode — terminal (asciinema) / desktop (pixelflux-record or
  // wf-recorder); empty means auto-detect from the venue's tools.
  record_mode?: string @go(RecordMode)
  // record_fps — the desktop-recorder frame rate (default 30).
  record_fps?: int & >=0 @go(RecordFps,type=int)
  // record_audio — capture audio with the desktop recording.
  record_audio?: bool @go(RecordAudio)
  // text — the command line `cmd` sends into the recording's tmux session.
  text?: string
  // artifact — the host path `stop` copies the recording to.
  artifact?: string
  // artifact_min_bytes / artifact_min_cast_events — the post-run
  // artifact-reality assertions (sdk.RunArtifactValidators).
  artifact_min_bytes?:       int & >=0 @go(ArtifactMinBytes,type=int)
  artifact_min_cast_events?: int & >=0 @go(ArtifactMinCastEvents,type=int)
}

---

See also the candy reference for this candy’s install surface.