run/AGENTS.md

AGENTS.md for run

This file applies to run/.

Channel Rules

Do not rebuild the old all-in-one WebSocket model. Keep these workloads separate:

• Control: hello, heartbeat, version, capabilities, capacity.
• Job: claim, ack, progress, result, cancel, reconcile.
• Logs: current supervised stdout/stderr live relay through /api/v1/run/logs/relay; no local durable log spool, cache, resend backlog, or sequence-ack dependency.
• Artifacts: chunks, checksums, resume, throttling.
• Game client bridge: optional in-game command/snapshot channel.

Artifact transfer must not block control heartbeats, job result reporting, or current live log relay.

Structure Rules

Protocol structs live in protocol/. Local runtime types live in runtime/ or domain/. Shared helpers live in shared/ only when needed by multiple packages.

Safety Rules

Run must enforce scoped paths and never expose raw host paths, local secrets, or unrestricted command execution to platform_web or plugins.

Generic Executor Boundary

Run is a generic machine-side executor. It may provide bounded primitives such as process start/stop/restart, scoped file existence/list/read/write/patch operations, downloads, extraction, log capture, artifact transfer, and capability enforcement.

Run must not contain game-specific lifecycle logic. Do not add hardcoded game names, executable paths, Steam app IDs, SteamCMD app-update commands, launch flags, install directories, or update policies to run. In particular, SCUM-specific values such as SCUMServer.exe, app 3792580, +app_update 3792580 validate, -port, -MaxPlayers, and -log belong to the SCUM plugin, not this repository.

If a lifecycle flow needs "install if missing", "stop before update", "validate via SteamCMD", or "start with game-specific arguments", run should execute the plugin-declared action through generic capabilities. Fix missing generic capabilities in run when necessary, but keep the game policy and concrete commands in the plugin action assets.

Run should supervise plugin-declared start commands generically: hide started process windows when the operating system supports it, capture the supervised stdout/stderr streams, and push only current observed output through live log relay. Do not persist supervised process output in a local log database/cache, do not wait for platform delivery acknowledgement, and do not replace plugin-declared process output with game-specific file inspection.

Do not introduce per-game runtime files such as scum_deployment.go. Prefer generic action execution, dependency helpers, process supervision, and manifest-declared capability checks that any plugin can use.