36 lines
3.3 KiB
Markdown
36 lines
3.3 KiB
Markdown
# 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: durable batches from supervised stdout/stderr and plugin-declared file tails through `/api/v1/run/logs/batches`, with local spool and sequence acknowledgement.
|
|
- 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 log ingest/upload.
|
|
|
|
## 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. Do not apply game-specific redaction to plugin-declared game records or SQL query rows: return those bounded typed fields faithfully through Platform channels. Supervised stdout/stderr and plugin-declared file tails are opaque verbatim channels: do not inspect, parse, filter, redact, truncate by content, normalize, correlate, transform, or special-case their payloads. Run only assigns transport metadata, spools, and forwards the exact body bytes. A plugin-owned component may consume its declared raw stream, parse it, and derive its own typed users or business records after receipt; Run neither performs nor repeats that plugin work. This pass-through rule does not grant plugins or the browser a direct host-path, credential, key, or socket API outside that log channel.
|
|
|
|
## 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 upload them through the durable log channel. Do not inspect or transform supervised output, 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.
|