ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Add remote packages, services, sudo, job streaming and capability re-probe
Juan Denise71099a4e9c5
diff --git a/agent/internal/agent/agent.go b/agent/internal/agent/agent.goindex 4446b30c..fad17188 100644--- a/agent/internal/agent/agent.go+++ b/agent/internal/agent/agent.go@@ -26,6 +26,7 @@ import ("github.com/serverkit/agent/internal/events""github.com/serverkit/agent/internal/gui""github.com/serverkit/agent/internal/ipc"+ "github.com/serverkit/agent/internal/jobs""github.com/serverkit/agent/internal/logger""github.com/serverkit/agent/internal/metrics""github.com/serverkit/agent/internal/terminal"@@ -54,6 +55,13 @@ type Agent struct {sampler *metricSamplerevents *events.Storegui *gui.SDK+ jobs *jobs.Registry++ // pkgLock serializes package-manager mutations (install / remove /+ // upgrade / update_cache) inside a single agent so two concurrent+ // requests don't race on dpkg/rpm locks. Reads (list_installed,+ // search, info) don't take the lock.+ pkgLock sync.Mutex// Active subscriptionssubscriptions map[string]context.CancelFunc@@ -62,10 +70,24 @@ type Agent struct {// Command handlershandlers map[string]CommandHandler- // Capabilities probed once at startup. Sent to the panel each time- // the transport reconnects (so a panel restart picks them up- // without waiting for the agent to also restart).+ // Capabilities probed at startup, refreshable via+ // agent:recapabilities. Sent to the panel each time the transport+ // reconnects (so a panel restart picks them up without waiting for+ // the agent to also restart). capMu guards reads/writes during a+ // re-probe so we don't ship a half-mutated payload.capabilities protocol.CapabilitiesMessage+ capMu sync.Mutex+ reprobing bool++ // sudoMode is the agent's privilege-escalation mode (root /+ // passwordless / unavailable). Probed once at startup; if the user+ // adds sudoers config later, agent:recapabilities re-probes.+ sudoMode SudoMode++ // systemdJSON tracks whether `systemctl --output=json` is supported+ // on this host (systemd >= 244). Probed lazily on first use.+ systemdJSON bool+ systemdJSONOnce sync.Once// Lifecycle trackingstartTime time.Time@@ -136,6 +158,7 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {sampler: newMetricSampler(300), // 5 min @ 1 Hzevents: eventStore,gui: gui.New(log),+ jobs: jobs.NewRegistry(64),subscriptions: make(map[string]context.CancelFunc),handlers: make(map[string]CommandHandler),startTime: time.Now(),@@ -146,7 +169,7 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {// every reconnect without re-probing. Docker availability is taken// from whether NewClient succeeded above; the capability layer// doesn't redo that work.- probeCtx, probeCancel := context.WithTimeout(context.Background(), 5*time.Second)+ probeCtx, probeCancel := context.WithTimeout(context.Background(), 10*time.Second)agent.capabilities = capabilities.Probe(probeCtx,log,@@ -154,7 +177,11 @@ func New(cfg *config.Config, log *logger.Logger) (*Agent, error) {cfg.Features.FileAccess,cfg.Security.AllowedPaths,)+ agent.sudoMode = probeSudoMode(probeCtx)+ agent.capabilities.Sudo = string(agent.sudoMode)+ agent.capabilities.ProbedAt = time.Now().UnixMilli()probeCancel()+ log.Info("Sudo probe complete", "mode", agent.sudoMode)// Register command handlersagent.registerHandlers()@@ -178,24 +205,29 @@ func (a *Agent) registerHandlers() {if a.docker != nil {a.handlers[protocol.ActionDockerContainerList] = a.handleDockerContainerLista.handlers[protocol.ActionDockerContainerInspect] = a.handleDockerContainerInspect+ a.handlers[protocol.ActionDockerContainerCreate] = a.handleDockerContainerCreatea.handlers[protocol.ActionDockerContainerStart] = a.handleDockerContainerStarta.handlers[protocol.ActionDockerContainerStop] = a.handleDockerContainerStopa.handlers[protocol.ActionDockerContainerRestart] = a.handleDockerContainerRestarta.handlers[protocol.ActionDockerContainerRemove] = a.handleDockerContainerRemovea.handlers[protocol.ActionDockerContainerStats] = a.handleDockerContainerStatsa.handlers[protocol.ActionDockerContainerLogs] = a.handleDockerContainerLogs+ a.handlers[protocol.ActionDockerContainerExec] = a.handleDockerContainerExec// Docker image commandsa.handlers[protocol.ActionDockerImageList] = a.handleDockerImageLista.handlers[protocol.ActionDockerImagePull] = a.handleDockerImagePulla.handlers[protocol.ActionDockerImageRemove] = a.handleDockerImageRemove+ a.handlers[protocol.ActionDockerImageBuild] = a.handleDockerImageBuild// Docker volume commandsa.handlers[protocol.ActionDockerVolumeList] = a.handleDockerVolumeList+ a.handlers[protocol.ActionDockerVolumeCreate] = a.handleDockerVolumeCreatea.handlers[protocol.ActionDockerVolumeRemove] = a.handleDockerVolumeRemove// Docker network commandsa.handlers[protocol.ActionDockerNetworkList] = a.handleDockerNetworkList+ a.handlers[protocol.ActionDockerNetworkCreate] = a.handleDockerNetworkCreatea.handlers[protocol.ActionDockerNetworkRemove] = a.handleDockerNetworkRemove// Docker compose commands@@ -256,16 +288,26 @@ func (a *Agent) registerHandlers() {a.handlers[protocol.ActionPackagesInstall] = a.handlePackagesInstalla.handlers[protocol.ActionPackagesRemove] = a.handlePackagesRemovea.handlers[protocol.ActionPackagesListInstalled] = a.handlePackagesListInstalled+ a.handlers[protocol.ActionPackagesUpdateCache] = a.handlePackagesUpdateCache+ a.handlers[protocol.ActionPackagesInstallAsync] = a.handlePackagesInstallAsync+ a.handlers[protocol.ActionPackagesUpgrade] = a.handlePackagesUpgrade+ a.handlers[protocol.ActionPackagesSearch] = a.handlePackagesSearch+ a.handlers[protocol.ActionPackagesInfo] = a.handlePackagesInfoa.handlers[protocol.ActionSystemdStatus] = a.handleSystemdStatusa.handlers[protocol.ActionSystemdStart] = a.handleSystemdStarta.handlers[protocol.ActionSystemdStop] = a.handleSystemdStopa.handlers[protocol.ActionSystemdRestart] = a.handleSystemdRestarta.handlers[protocol.ActionSystemdEnable] = a.handleSystemdEnablea.handlers[protocol.ActionSystemdDisable] = a.handleSystemdDisable+ a.handlers[protocol.ActionSystemdDaemonReload] = a.handleSystemdDaemonReload+ a.handlers[protocol.ActionSystemdListUnits] = a.handleSystemdListUnits+ a.handlers[protocol.ActionSystemdLogs] = a.handleSystemdLogs+ a.handlers[protocol.ActionSystemdLogsFollow] = a.handleSystemdLogsFollowa.handlers[protocol.ActionSystemExec] = a.handleSystemExec// Agent commandsa.handlers[protocol.ActionAgentUpdate] = a.handleAgentUpdate+ a.handlers[protocol.ActionAgentRecapabilities] = a.handleAgentRecapabilities// GUI SDK — primitives that panel extensions (serverkit-gui, etc.)// compose into desktop-streaming or synthetic-UI features. Always@@ -490,22 +532,30 @@ func (a *Agent) connectionWatcher(ctx context.Context) {// metadata; missing ones just mean an agent doesn't show up in feature// pickers until the next reconnect.func (a *Agent) sendCapabilities() {+ a.capMu.Lock()+ caps := a.capabilities+ a.capMu.Unlock()msg := protocol.CapabilitiesMessage{- Message: protocol.NewMessage(protocol.TypeCapabilities, auth.GenerateNonce()),- Capabilities: a.capabilities.Capabilities,- Platform: a.capabilities.Platform,- Distro: a.capabilities.Distro,- DistroVersion: a.capabilities.DistroVersion,- Runtimes: a.capabilities.Runtimes,- AllowedPaths: a.capabilities.AllowedPaths,+ Message: protocol.NewMessage(protocol.TypeCapabilities, auth.GenerateNonce()),+ Capabilities: caps.Capabilities,+ Platform: caps.Platform,+ Distro: caps.Distro,+ DistroVersion: caps.DistroVersion,+ Runtimes: caps.Runtimes,+ AllowedPaths: caps.AllowedPaths,+ Sudo: caps.Sudo,+ RuntimeManagers: caps.RuntimeManagers,+ SystemdJSON: caps.SystemdJSON,+ ProbedAt: caps.ProbedAt,}if err := a.ws.Send(msg); err != nil {a.log.Warn("Failed to send capabilities", "error", err)return}a.log.Debug("Sent capabilities to panel",- "platform", a.capabilities.Platform,- "distro", a.capabilities.Distro,+ "platform", caps.Platform,+ "distro", caps.Distro,+ "sudo", caps.Sudo,)}@@ -639,6 +689,20 @@ func (a *Agent) handleSubscribe(data []byte) {a.log.Info("Subscribing to channel", "channel", sub.Channel)+ // Replay any buffered events for job channels so a panel that+ // subscribed mid-flight (or just after the job finished) still sees+ // the full progress history. Replay before installing the+ // subscription record so a brand-new "live" event can't get+ // interleaved before the replay.+ if job := a.jobs.LookupByChannel(sub.Channel); job != nil {+ for _, ev := range job.Replay() {+ if err := a.ws.SendStream(sub.Channel, ev); err != nil {+ a.log.Warn("Failed to replay job event", "channel", sub.Channel, "error", err)+ break+ }+ }+ }+// Create cancellable context for this subscriptionctx, cancel := context.WithCancel(context.Background())diff --git a/agent/internal/agent/docker_extra_handlers.go b/agent/internal/agent/docker_extra_handlers.gonew file mode 100644index 00000000..002193d3--- /dev/null+++ b/agent/internal/agent/docker_extra_handlers.go@@ -0,0 +1,270 @@+package agent++// Phase 1e — fill in the docker actions that were declared in the+// protocol but never wired to handlers: container:create,+// container:exec, image:build, volume:create, network:create. The+// existing handlers (start/stop/list/inspect/logs/stats, image+// list/pull/remove, compose) live in agent.go alongside their+// containers; we put the new ones in their own file to keep the diff+// reviewable.++import (+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "os/exec"+ "path/filepath"+ "strings"+ "time"++ "github.com/serverkit/agent/internal/docker"+ "github.com/serverkit/agent/internal/jobs"+)++// validateImageName rejects shell metacharacters in user-supplied image+// references. Docker is generally tolerant about what it accepts as a+// tag, but we don't want a "registry.example.com/img;rm -rf /" landing+// in argv even if exec.Command is safe — it's a clearer error to+// reject up front.+func validateImageName(s string) error {+ s = strings.TrimSpace(s)+ if s == "" {+ return errors.New("image is required")+ }+ if strings.ContainsAny(s, ";&|`$<>\n\r\"'\\") {+ return fmt.Errorf("invalid image: %q", s)+ }+ return nil+}++func validateContainerID(s string) error {+ s = strings.TrimSpace(s)+ if s == "" {+ return errors.New("container is required")+ }+ if strings.ContainsAny(s, ";&|`$<>\n\r\"'\\ /") {+ return fmt.Errorf("invalid container id/name: %q", s)+ }+ return nil+}++// ───── docker:container:create ────────────────────────────────────++func (a *Agent) handleDockerContainerCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if a.docker == nil {+ return nil, errors.New("docker not available")+ }+ var spec docker.ContainerCreateSpec+ if err := json.Unmarshal(params, &spec); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validateImageName(spec.Image); err != nil {+ return nil, err+ }+ // v1 reject privileged-ish fields. They round-trip in the JSON but+ // are not part of ContainerCreateSpec — defensively check raw params+ // to fail loudly when a caller tries to set them. The struct-shaped+ // check is at the field level above.+ var raw map[string]interface{}+ _ = json.Unmarshal(params, &raw)+ for _, banned := range []string{"privileged", "cap_add", "devices"} {+ if _, ok := raw[banned]; ok {+ return nil, fmt.Errorf("%s is not supported in v1 container:create", banned)+ }+ }+ id, err := a.docker.CreateContainer(ctx, spec)+ if err != nil {+ return nil, fmt.Errorf("create container: %w", err)+ }+ return map[string]interface{}{+ "id": id,+ "name": spec.Name,+ "image": spec.Image,+ "status": "created",+ }, nil+}++// ───── docker:container:exec ──────────────────────────────────────++func (a *Agent) handleDockerContainerExec(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if a.docker == nil {+ return nil, errors.New("docker not available")+ }+ var p struct {+ Container string `json:"container"`+ Cmd []string `json:"cmd"`+ User string `json:"user"`+ WorkingDir string `json:"working_dir"`+ TimeoutSeconds int `json:"timeout_seconds"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validateContainerID(p.Container); err != nil {+ return nil, err+ }+ if len(p.Cmd) == 0 {+ return nil, errors.New("cmd is required")+ }+ timeout := time.Duration(p.TimeoutSeconds) * time.Second+ if timeout <= 0 || timeout > 5*time.Minute {+ timeout = 60 * time.Second+ }+ cctx, cancel := context.WithTimeout(ctx, timeout)+ defer cancel()+ res, err := a.docker.ExecContainer(cctx, p.Container, p.Cmd, p.User, p.WorkingDir, 1024*1024)+ if err != nil {+ return nil, fmt.Errorf("exec: %w", err)+ }+ return res, nil+}++// ───── docker:image:build ─────────────────────────────────────────++func (a *Agent) handleDockerImageBuild(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if a.docker == nil {+ return nil, errors.New("docker not available")+ }+ var spec docker.ImageBuildSpec+ if err := json.Unmarshal(params, &spec); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validateImageName(spec.Tag); err != nil {+ return nil, fmt.Errorf("tag: %w", err)+ }+ abs, err := filepath.Abs(spec.ContextPath)+ if err != nil {+ return nil, fmt.Errorf("context_path: %w", err)+ }+ if !a.contextPathAllowed(abs) {+ return nil, fmt.Errorf("context_path %q is not under any allowed root", abs)+ }+ spec.ContextPath = abs++ job := a.jobs.New(500)+ go a.runDockerBuildJob(job, spec)+ return map[string]interface{}{+ "job_id": job.ID,+ "channel": job.Channel,+ "tag": spec.Tag,+ }, nil+}++func (a *Agent) contextPathAllowed(path string) bool {+ for _, root := range a.cfg.Security.AllowedPaths {+ ar, err := filepath.Abs(root)+ if err != nil {+ continue+ }+ // path must be under ar (or equal). Use Rel to detect ".." escapes.+ rel, err := filepath.Rel(ar, path)+ if err != nil {+ continue+ }+ if rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) {+ return true+ }+ }+ return false+}++func (a *Agent) runDockerBuildJob(job *jobs.Job, spec docker.ImageBuildSpec) {+ exit := 0+ emitDone := func(errStr string) {+ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseDone,+ ExitCode: &exit,+ Error: errStr,+ Extra: map[string]interface{}{"tag": spec.Tag},+ })+ }+ cctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)+ defer cancel()+ cmd, err := a.docker.BuildImageCmd(cctx, spec)+ if err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ _ = job.Push(a.ws, jobs.Event{Phase: jobs.PhaseStart, Message: fmt.Sprintf("docker build -t %s", spec.Tag)})+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ if cerr := cmd.Wait(); cerr != nil {+ exit = exitCodeOfCmd(cerr)+ if exit == 0 {+ exit = -1+ }+ emitDone(cerr.Error())+ return+ }+ emitDone("")+}++// exitCodeOfCmd duplicates exitCodeOf from package_handlers.go to+// avoid an import cycle in this file. They're trivial enough that the+// duplication is cheaper than refactoring callers.+func exitCodeOfCmd(err error) int {+ var ee *exec.ExitError+ if errors.As(err, &ee) {+ return ee.ExitCode()+ }+ return -1+}++// ───── docker:volume:create ───────────────────────────────────────++func (a *Agent) handleDockerVolumeCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if a.docker == nil {+ return nil, errors.New("docker not available")+ }+ var p struct {+ Name string `json:"name"`+ Driver string `json:"driver"`+ Labels map[string]string `json:"labels"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if strings.TrimSpace(p.Name) == "" {+ return nil, errors.New("name is required")+ }+ if strings.ContainsAny(p.Name, ";&|`$<>\n\r\"'\\ /") {+ return nil, fmt.Errorf("invalid volume name: %q", p.Name)+ }+ vol, err := a.docker.CreateVolume(ctx, p.Name, p.Driver, p.Labels)+ if err != nil {+ return nil, fmt.Errorf("create volume: %w", err)+ }+ return vol, nil+}++// ───── docker:network:create ──────────────────────────────────────++func (a *Agent) handleDockerNetworkCreate(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if a.docker == nil {+ return nil, errors.New("docker not available")+ }+ var spec docker.NetworkCreateSpec+ if err := json.Unmarshal(params, &spec); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if strings.TrimSpace(spec.Name) == "" {+ return nil, errors.New("name is required")+ }+ if strings.ContainsAny(spec.Name, ";&|`$<>\n\r\"'\\ /") {+ return nil, fmt.Errorf("invalid network name: %q", spec.Name)+ }+ id, err := a.docker.CreateNetwork(ctx, spec)+ if err != nil {+ return nil, fmt.Errorf("create network: %w", err)+ }+ return map[string]interface{}{+ "id": id,+ "name": spec.Name,+ "driver": spec.Driver,+ }, nil+}diff --git a/agent/internal/agent/package_handlers.go b/agent/internal/agent/package_handlers.gonew file mode 100644index 00000000..407920d1--- /dev/null+++ b/agent/internal/agent/package_handlers.go@@ -0,0 +1,564 @@+package agent++// Phase 1c additions — package manager actions beyond the original+// install/remove/list trio: search, info, update-cache, plus a+// streaming variant of install/upgrade that emits progress on a job+// channel for the Packages tab and one-click templates.+//+// The existing handlePackagesInstall (single-name, synchronous,+// idempotent short-circuit) is left alone so the workflow engine's+// agent_command callers still get a structured result. New callers+// wanting progress streaming use packages:install_async / packages:upgrade.++import (+ "bufio"+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "os/exec"+ "strings"+ "sync"+ "time"++ "github.com/serverkit/agent/internal/jobs"+)++// extendedPackageManager carries the new-action arg patterns alongside+// the existing packageManager. We don't fold these into packageManager+// itself to keep the original definition (and its callers) untouched.+type extendedPackageManager struct {+ bin string+ updateCache []string+ upgradeAll []string+ upgradePkg []string // appended with package name(s)+ searchCmd []string+ infoCmd []string // appended with name+}++func extendedFor(pm *packageManager) *extendedPackageManager {+ switch pm.bin {+ case "apt-get":+ return &extendedPackageManager{+ bin: "apt-get",+ updateCache: []string{"update"},+ upgradeAll: []string{"upgrade", "-y", "-o", "Dpkg::Options::=--force-confold"},+ upgradePkg: []string{"install", "--only-upgrade", "-y", "-o", "Dpkg::Options::=--force-confold"},+ searchCmd: []string{"search"}, // run via apt-cache below+ infoCmd: []string{"show"}, // run via apt-cache below+ }+ case "dnf", "yum":+ return &extendedPackageManager{+ bin: pm.bin,+ updateCache: []string{"check-update"},+ upgradeAll: []string{"upgrade", "-y"},+ upgradePkg: []string{"upgrade", "-y"},+ searchCmd: []string{"search"},+ infoCmd: []string{"info"},+ }+ case "apk":+ return &extendedPackageManager{+ bin: "apk",+ updateCache: []string{"update"},+ upgradeAll: []string{"upgrade"},+ upgradePkg: []string{"upgrade"},+ searchCmd: []string{"search", "-v"},+ infoCmd: []string{"info"},+ }+ case "pacman":+ return &extendedPackageManager{+ bin: "pacman",+ updateCache: []string{"-Sy"},+ upgradeAll: []string{"-Syu", "--noconfirm"},+ upgradePkg: []string{"-S", "--noconfirm"},+ searchCmd: []string{"-Ss"},+ infoCmd: []string{"-Si"},+ }+ case "zypper":+ return &extendedPackageManager{+ bin: "zypper",+ updateCache: []string{"refresh"},+ upgradeAll: []string{"update", "-y"},+ upgradePkg: []string{"update", "-y"},+ searchCmd: []string{"se"},+ infoCmd: []string{"info"},+ }+ }+ return nil+}++// ───── packages:update_cache ──────────────────────────────────────++func (a *Agent) handlePackagesUpdateCache(ctx context.Context, params json.RawMessage) (interface{}, error) {+ pm, err := detectPackageManager()+ if err != nil {+ return nil, err+ }+ ext := extendedFor(pm)+ if ext == nil {+ return nil, fmt.Errorf("update_cache: manager %q not supported", pm.bin)+ }+ a.pkgLock.Lock()+ defer a.pkgLock.Unlock()++ cctx, cancel := context.WithTimeout(ctx, 2*time.Minute)+ defer cancel()+ cmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, ext.updateCache...)+ if err != nil {+ return nil, err+ }+ out, err := cmd.CombinedOutput()+ tail := truncate(string(out), 4096)+ if err != nil && !isCheckUpdateExit100(ext.bin, err) {+ // dnf check-update returns 100 when updates are available; that+ // isn't a failure, just an "actionable" exit. Anything else is+ // treated as a real error.+ if classifySudoError(string(out)) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }+ return nil, fmt.Errorf("%s %s: %w (%s)", ext.bin, strings.Join(ext.updateCache, " "), err, tail)+ }+ return map[string]interface{}{+ "manager": ext.bin,+ "output": tail,+ }, nil+}++// dnf check-update conventionally exits 100 when there are updates+// pending, 0 when nothing to do. We treat both as success.+func isCheckUpdateExit100(bin string, err error) bool {+ if bin != "dnf" && bin != "yum" {+ return false+ }+ var ee *exec.ExitError+ if errors.As(err, &ee) {+ return ee.ExitCode() == 100+ }+ return false+}++// ───── packages:search ────────────────────────────────────────────++func (a *Agent) handlePackagesSearch(ctx context.Context, params json.RawMessage) (interface{}, error) {+ var p struct {+ Query string `json:"query"`+ Limit int `json:"limit"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ q := strings.TrimSpace(p.Query)+ if q == "" {+ return nil, errors.New("query is required")+ }+ if err := validatePackageName(q); err != nil {+ // Reject metachars; reuse the install validator since search+ // goes straight to argv.+ return nil, err+ }+ if p.Limit <= 0 || p.Limit > 500 {+ p.Limit = 500+ }++ pm, err := detectPackageManager()+ if err != nil {+ return nil, err+ }+ ext := extendedFor(pm)+ if ext == nil {+ return nil, fmt.Errorf("search: manager %q not supported", pm.bin)+ }++ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)+ defer cancel()++ bin := ext.bin+ args := append([]string{}, ext.searchCmd...)+ if pm.bin == "apt-get" {+ bin = "apt-cache"+ }+ args = append(args, q)+ out, err := exec.CommandContext(cctx, bin, args...).CombinedOutput()+ if err != nil && len(out) == 0 {+ return nil, fmt.Errorf("%s %s: %w", bin, strings.Join(args, " "), err)+ }+ lines := splitNonEmptyLines(string(out))+ if len(lines) > p.Limit {+ lines = lines[:p.Limit]+ }+ return map[string]interface{}{+ "manager": pm.bin,+ "query": q,+ "limit": p.Limit,+ "results": lines,+ }, nil+}++// ───── packages:info ──────────────────────────────────────────────++func (a *Agent) handlePackagesInfo(ctx context.Context, params json.RawMessage) (interface{}, error) {+ var p struct {+ Name string `json:"name"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validatePackageName(p.Name); err != nil {+ return nil, err+ }+ pm, err := detectPackageManager()+ if err != nil {+ return nil, err+ }+ ext := extendedFor(pm)+ if ext == nil {+ return nil, fmt.Errorf("info: manager %q not supported", pm.bin)+ }++ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)+ defer cancel()+ bin := ext.bin+ if pm.bin == "apt-get" {+ bin = "apt-cache"+ }+ args := append(append([]string{}, ext.infoCmd...), p.Name)+ out, err := exec.CommandContext(cctx, bin, args...).CombinedOutput()+ if err != nil && len(out) == 0 {+ return nil, fmt.Errorf("%s %s: %w", bin, strings.Join(args, " "), err)+ }+ return map[string]interface{}{+ "manager": pm.bin,+ "name": p.Name,+ "output": truncate(string(out), 16*1024),+ }, nil+}++// ───── packages:install_async + packages:upgrade ─────────────────++// installRequest is the shared param shape for install_async / upgrade.+// Either Names (list) or Name (single) may be set; an empty Names with+// All=true upgrades everything (only meaningful for upgrade).+type installRequest struct {+ Names []string `json:"names"`+ Name string `json:"name"`+ All bool `json:"all"`+}++func (r *installRequest) normalize() error {+ if r.Name != "" {+ r.Names = append(r.Names, r.Name)+ }+ for _, n := range r.Names {+ if err := validatePackageName(n); err != nil {+ return err+ }+ }+ return nil+}++// handlePackagesInstallAsync is a streaming variant of install: returns+// {job_id, channel} immediately and emits per-line progress on the+// channel. Idempotent like the sync variant — packages already+// installed are skipped (we still emit a status event).+func (a *Agent) handlePackagesInstallAsync(ctx context.Context, params json.RawMessage) (interface{}, error) {+ var p installRequest+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := p.normalize(); err != nil {+ return nil, err+ }+ if len(p.Names) == 0 {+ return nil, errors.New("at least one package name required")+ }+ pm, err := detectPackageManager()+ if err != nil {+ return nil, err+ }+ if a.sudoMode == SudoUnavailable {+ return nil, errSudoRequired+ }++ job := a.jobs.New(200)+ go a.runPackageInstallJob(job, pm, p.Names)+ return map[string]interface{}{+ "job_id": job.ID,+ "channel": job.Channel,+ }, nil+}++// handlePackagesUpgrade upgrades the named packages, or all packages+// when All=true. Streams progress identically to install_async.+func (a *Agent) handlePackagesUpgrade(ctx context.Context, params json.RawMessage) (interface{}, error) {+ var p installRequest+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := p.normalize(); err != nil {+ return nil, err+ }+ if !p.All && len(p.Names) == 0 {+ return nil, errors.New("either names[] or all=true required")+ }+ pm, err := detectPackageManager()+ if err != nil {+ return nil, err+ }+ ext := extendedFor(pm)+ if ext == nil {+ return nil, fmt.Errorf("upgrade: manager %q not supported", pm.bin)+ }+ if a.sudoMode == SudoUnavailable {+ return nil, errSudoRequired+ }++ job := a.jobs.New(200)+ go a.runPackageUpgradeJob(job, pm, ext, p.Names, p.All)+ return map[string]interface{}{+ "job_id": job.ID,+ "channel": job.Channel,+ }, nil+}++// runPackageInstallJob runs the apt/dnf/etc. install in the background,+// streams output line-by-line on the job channel, and emits a final+// done event with the structured result.+func (a *Agent) runPackageInstallJob(job *jobs.Job, pm *packageManager, names []string) {+ a.pkgLock.Lock()+ defer a.pkgLock.Unlock()++ exit := 0+ emitDone := func(errStr string, installed []string) {+ ev := jobs.Event{+ Phase: jobs.PhaseDone,+ ExitCode: &exit,+ Error: errStr,+ Extra: map[string]interface{}{+ "manager": pm.bin,+ "action": "install",+ "installed": installed,+ },+ }+ _ = job.Push(a.ws, ev)+ }++ // Skip already-installed packages.+ probeCtx, probeCancel := context.WithTimeout(context.Background(), 30*time.Second)+ var toInstall, alreadyInstalled []string+ for _, n := range names {+ if installed, _ := pm.isInstalled(probeCtx, n); installed {+ alreadyInstalled = append(alreadyInstalled, n)+ continue+ }+ toInstall = append(toInstall, n)+ }+ probeCancel()++ if len(alreadyInstalled) > 0 {+ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseStatus,+ Message: fmt.Sprintf("already installed: %s", strings.Join(alreadyInstalled, ", ")),+ })+ }+ if len(toInstall) == 0 {+ emitDone("", alreadyInstalled)+ return+ }++ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseStart,+ Message: fmt.Sprintf("installing %d package(s) via %s", len(toInstall), pm.bin),+ })++ // Long-running command — bound at 15 minutes.+ cctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)+ defer cancel()+ args := append(append([]string{}, pm.install...), toInstall...)+ cmd, err := sudoCommandContext(cctx, a.sudoMode, pm.bin, args...)+ if err != nil {+ exit = -1+ emitDone(err.Error(), nil)+ return+ }+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {+ exit = -1+ emitDone(err.Error(), nil)+ return+ }+ if cerr := cmd.Wait(); cerr != nil {+ exit = exitCodeOf(cerr)+ if exit == 0 {+ exit = -1+ }+ emitDone(cerr.Error(), nil)+ return+ }+ emitDone("", append(alreadyInstalled, toInstall...))+}++func (a *Agent) runPackageUpgradeJob(job *jobs.Job, pm *packageManager, ext *extendedPackageManager, names []string, all bool) {+ a.pkgLock.Lock()+ defer a.pkgLock.Unlock()++ exit := 0+ emitDone := func(errStr string) {+ ev := jobs.Event{+ Phase: jobs.PhaseDone,+ ExitCode: &exit,+ Error: errStr,+ Extra: map[string]interface{}{+ "manager": pm.bin,+ "action": "upgrade",+ "all": all,+ },+ }+ _ = job.Push(a.ws, ev)+ }++ cctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)+ defer cancel()++ // apt: refresh the package index first so upgrade sees newly+ // published versions. Other managers do this implicitly.+ if pm.bin == "apt-get" {+ updCmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, ext.updateCache...)+ if err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ if err := streamCmdOutput(updCmd, job, a.ws); err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ _ = updCmd.Wait()+ }++ var args []string+ if all {+ args = append([]string{}, ext.upgradeAll...)+ } else {+ args = append(append([]string{}, ext.upgradePkg...), names...)+ }+ cmd, err := sudoCommandContext(cctx, a.sudoMode, ext.bin, args...)+ if err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseStart,+ Message: fmt.Sprintf("%s %s", ext.bin, strings.Join(args, " ")),+ })+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ if cerr := cmd.Wait(); cerr != nil {+ exit = exitCodeOf(cerr)+ if exit == 0 {+ exit = -1+ }+ emitDone(cerr.Error())+ return+ }+ emitDone("")+}++// streamCmdOutput attaches a line-buffered stdout/stderr scanner to cmd+// and pushes batches of lines on the job channel. Lines are flushed on+// a 100ms window or 32-line threshold, whichever comes first, so the+// panel sees steady progress without one event per line at high+// throughput.+//+// Blocks until both pipes close, then returns. Caller is expected to+// invoke cmd.Wait() afterwards to reap the process and get the exit+// code. Returns an error only if cmd.Start fails or pipe setup fails.+func streamCmdOutput(cmd *exec.Cmd, job *jobs.Job, s jobs.Streamer) error {+ stdout, err := cmd.StdoutPipe()+ if err != nil {+ return err+ }+ stderr, err := cmd.StderrPipe()+ if err != nil {+ return err+ }+ if err := cmd.Start(); err != nil {+ return err+ }++ lines := make(chan string, 256)+ var wg sync.WaitGroup+ wg.Add(2)+ go scanLines(stdout, lines, &wg)+ go scanLines(stderr, lines, &wg)++ // Closer goroutine: once both scanners have returned, close the+ // channel so the batcher knows there's no more input.+ go func() {+ wg.Wait()+ close(lines)+ }()++ // Batcher: flush every 100ms or 32 lines. Runs synchronously so+ // the caller can rely on "all output emitted before we return."+ batch := make([]string, 0, 32)+ flush := func() {+ if len(batch) == 0 {+ return+ }+ _ = job.Push(s, jobs.Event{Phase: jobs.PhaseLog, Lines: append([]string{}, batch...)})+ batch = batch[:0]+ }+ ticker := time.NewTicker(100 * time.Millisecond)+ defer ticker.Stop()+ for {+ select {+ case ln, ok := <-lines:+ if !ok {+ flush()+ return nil+ }+ batch = append(batch, ln)+ if len(batch) >= 32 {+ flush()+ }+ case <-ticker.C:+ flush()+ }+ }+}++func scanLines(r io.ReadCloser, out chan<- string, wg *sync.WaitGroup) {+ defer wg.Done()+ defer r.Close()+ sc := bufio.NewScanner(r)+ sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)+ for sc.Scan() {+ out <- sc.Text()+ }+}++func exitCodeOf(err error) int {+ var ee *exec.ExitError+ if errors.As(err, &ee) {+ return ee.ExitCode()+ }+ return -1+}++func splitNonEmptyLines(s string) []string {+ var out []string+ for _, ln := range strings.Split(s, "\n") {+ ln = strings.TrimRight(ln, "\r")+ if strings.TrimSpace(ln) == "" {+ continue+ }+ out = append(out, ln)+ }+ return out+}+diff --git a/agent/internal/agent/recapabilities.go b/agent/internal/agent/recapabilities.gonew file mode 100644index 00000000..a2e7ff37--- /dev/null+++ b/agent/internal/agent/recapabilities.go@@ -0,0 +1,123 @@+package agent++// agent:recapabilities — re-runs the capability probe on demand. The+// panel calls this after the user installs a runtime / sudoers entry /+// new package manager, so new feature surfaces light up without a+// service restart.+//+// Concurrent re-probes are common (the panel may fire one per server+// detail page open) and the underlying probes spawn subprocesses, so+// we guard with a coarse mutex: if a probe is already in flight we+// return the cached set with reprobe="in_progress" instead of+// queueing.++import (+ "context"+ "encoding/json"+ "time"++ "github.com/serverkit/agent/internal/capabilities"+ "github.com/serverkit/agent/pkg/protocol"+)++func (a *Agent) handleAgentRecapabilities(ctx context.Context, params json.RawMessage) (interface{}, error) {+ a.capMu.Lock()+ if a.reprobing {+ caps := a.capabilities+ a.capMu.Unlock()+ return map[string]interface{}{+ "reprobe": "in_progress",+ "capabilities": caps,+ }, nil+ }+ a.reprobing = true+ a.capMu.Unlock()+ defer func() {+ a.capMu.Lock()+ a.reprobing = false+ a.capMu.Unlock()+ }()++ // Use a fresh, bounded context — the caller's request timeout+ // might be shorter than the probe takes, but we still want to+ // finish so the next subscriber sees fresh state.+ probeCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)+ defer cancel()++ // Clear the PATH lookup cache so newly installed binaries (e.g. the+ // user just ran apt install nginx) are seen by this re-probe.+ capabilities.ClearPathCache()++ fresh := capabilities.Probe(+ probeCtx,+ a.log,+ a.docker != nil,+ a.cfg.Features.FileAccess,+ a.cfg.Security.AllowedPaths,+ )++ // Re-probe sudo as well — the user may have added passwordless+ // sudoers config since boot.+ mode := probeSudoMode(probeCtx)+ fresh.Sudo = string(mode)+ fresh.ProbedAt = time.Now().UnixMilli()++ // Capabilities are additive across re-probes: if the previous+ // snapshot saw a feature the panel cared about, don't drop it just+ // because a transient probe failed (e.g. dockerd briefly+ // restarting). Only flip false→true here, never true→false.+ a.capMu.Lock()+ merged := mergeCapabilities(a.capabilities, fresh)+ a.capabilities = merged+ a.sudoMode = mode+ a.capMu.Unlock()++ // Push to the panel so the in-memory ConnectedAgent record updates+ // without an explicit refetch.+ a.sendCapabilities()++ return map[string]interface{}{+ "reprobe": "ok",+ "capabilities": merged,+ }, nil+}++// mergeCapabilities returns a payload where bool capabilities are the+// OR of prev and fresh, runtime maps are unioned, and the "presence"+// of optional fields prefers fresh values. Numeric/string fields like+// distro version are taken from fresh because the host might have been+// upgraded between probes.+//+// The asymmetry is deliberate: a transient probe failure (dockerd+// briefly down, journalctl hung) shouldn't cause a panel-side feature+// to disappear, but a real upgrade/install should be reflected. So we+// only flip false→true here, never true→false. To force a clean view+// the operator can restart the agent.+func mergeCapabilities(prev, fresh protocol.CapabilitiesMessage) protocol.CapabilitiesMessage {+ out := fresh+ if out.Capabilities == nil {+ out.Capabilities = protocol.Capabilities{}+ }+ for k, v := range prev.Capabilities {+ if v && !out.Capabilities[k] {+ out.Capabilities[k] = true+ }+ }+ if out.Runtimes == nil {+ out.Runtimes = map[string]string{}+ }+ for k, v := range prev.Runtimes {+ if _, ok := out.Runtimes[k]; !ok && v != "" {+ out.Runtimes[k] = v+ }+ }+ if out.RuntimeManagers == nil {+ out.RuntimeManagers = map[string]string{}+ }+ for k, v := range prev.RuntimeManagers {+ if _, ok := out.RuntimeManagers[k]; !ok && v != "" {+ out.RuntimeManagers[k] = v+ }+ }+ return out+}diff --git a/agent/internal/agent/sudo.go b/agent/internal/agent/sudo.gonew file mode 100644index 00000000..8fef5666--- /dev/null+++ b/agent/internal/agent/sudo.go@@ -0,0 +1,124 @@+package agent++// Privilege escalation helpers. The agent's install script lays down a+// dedicated `serverkit-agent` user, so handlers that touch system state+// (systemctl, apt, dnf, journalctl on system journals) need to escalate+// when the agent isn't running as root. We use passwordless sudo (-n)+// so a hung password prompt can't tie up a request.+//+// The decision is made once at startup: probe whether `sudo -n true`+// succeeds, cache the result, and surface it on the capabilities+// payload as one of "root", "passwordless", or "unavailable" so the+// panel can warn users *before* they try to install something.+//+// When the mode is "unavailable", privileged handlers fail fast with a+// "sudo_required" error instead of spawning a subprocess that would+// deadlock waiting for a password.++import (+ "context"+ "errors"+ "os"+ "os/exec"+ "runtime"+ "strings"+ "time"+)++// SudoMode describes how the agent escalates privileges.+type SudoMode string++const (+ SudoRoot SudoMode = "root" // EUID == 0+ SudoPasswordless SudoMode = "passwordless" // sudo -n works+ SudoUnavailable SudoMode = "unavailable" // no escalation possible+)++// errSudoRequired is returned by privileged handlers when escalation+// isn't available. Wrapped with extra context by the calling handler.+var errSudoRequired = errors.New("sudo required: agent is running as a non-root user and passwordless sudo is not configured")++// probeSudoMode determines the agent's escalation capability. Called+// once at startup; the result is cached in Agent.sudoMode.+func probeSudoMode(ctx context.Context) SudoMode {+ if runtime.GOOS != "linux" {+ // Non-linux hosts don't run the privileged handlers anyway —+ // systemd/packages capabilities are gated off on those.+ if isAdminWindows() {+ return SudoRoot+ }+ return SudoUnavailable+ }+ if os.Geteuid() == 0 {+ return SudoRoot+ }+ if _, err := exec.LookPath("sudo"); err != nil {+ return SudoUnavailable+ }+ cctx, cancel := context.WithTimeout(ctx, 5*time.Second)+ defer cancel()+ cmd := exec.CommandContext(cctx, "sudo", "-n", "true")+ if err := cmd.Run(); err != nil {+ return SudoUnavailable+ }+ return SudoPasswordless+}++// isAdminWindows is a placeholder: the privileged handlers are gated by+// runtime.GOOS == "linux" anyway, so the only effect is the value+// surfaced on the capabilities payload. Returning false everywhere on+// Windows is safe.+func isAdminWindows() bool { return false }++// sudoCommandContext returns an exec.Cmd that runs `name args...` with+// privilege escalation according to the agent's sudo mode. When the+// mode is "unavailable", it returns nil and a sudo_required error —+// callers must check both.+//+// The returned Cmd has DEBIAN_FRONTEND=noninteractive in its env so+// dpkg conffile prompts don't hang installs in production. Callers+// that need additional env should append to cmd.Env after the call.+func sudoCommandContext(ctx context.Context, mode SudoMode, name string, args ...string) (*exec.Cmd, error) {+ switch mode {+ case SudoRoot:+ cmd := exec.CommandContext(ctx, name, args...)+ cmd.Env = privilegedEnv()+ return cmd, nil+ case SudoPasswordless:+ full := append([]string{"-n", name}, args...)+ cmd := exec.CommandContext(ctx, "sudo", full...)+ cmd.Env = privilegedEnv()+ return cmd, nil+ default:+ return nil, errSudoRequired+ }+}++// privilegedEnv builds the env block used for privileged commands.+// Inherits the parent process env and adds DEBIAN_FRONTEND so apt+// upgrades don't stop on conffile prompts.+func privilegedEnv() []string {+ out := append([]string{}, os.Environ()...)+ out = append(out, "DEBIAN_FRONTEND=noninteractive")+ return out+}++// classifySudoError matches stderr text from a failed escalation+// attempt and returns true when sudo specifically refused (password+// required, terminal required, no permission). Used to wrap downstream+// errors with a clean "sudo_required" code instead of leaking the raw+// sudo banner to the panel.+func classifySudoError(stderr string) bool {+ low := strings.ToLower(stderr)+ for _, marker := range []string{+ "a password is required",+ "a terminal is required",+ "sudo: not allowed",+ "sudo: must be setuid root",+ } {+ if strings.Contains(low, marker) {+ return true+ }+ }+ return false+}diff --git a/agent/internal/agent/systemd_handlers.go b/agent/internal/agent/systemd_handlers.gonew file mode 100644index 00000000..5cb7c9df--- /dev/null+++ b/agent/internal/agent/systemd_handlers.go@@ -0,0 +1,363 @@+package agent++// Phase 1c additions — systemd actions beyond status/start/stop/restart/+// enable/disable: daemon-reload, list-units, journal logs (bounded fetch+// and follow-stream variants).+//+// list-units prefers `systemctl --output=json` (systemd 244+) for clean+// parsing and falls back to plain text on older systems. The choice is+// probed once and cached on the agent so we don't pay the fork cost on+// every list call.++import (+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "os/exec"+ "strings"+ "time"++ "github.com/serverkit/agent/internal/jobs"+ "github.com/serverkit/agent/pkg/protocol"+)++// runSystemctlPrivileged is the sudo-aware variant of runSystemctl. It+// preserves the existing 30-second timeout for read operations; long+// operations (start/stop/restart/daemon-reload) override via timeout+// param.+func (a *Agent) runSystemctlPrivileged(ctx context.Context, timeout time.Duration, args ...string) (string, error) {+ cctx, cancel := context.WithTimeout(ctx, timeout)+ defer cancel()+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "systemctl", args...)+ if err != nil {+ return "", err+ }+ out, err := cmd.CombinedOutput()+ return strings.TrimSpace(string(out)), err+}++// ───── systemd:daemon_reload ──────────────────────────────────────++func (a *Agent) handleSystemdDaemonReload(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if err := systemctlAvailable(); err != nil {+ return nil, err+ }+ out, err := a.runSystemctlPrivileged(ctx, 5*time.Minute, "daemon-reload")+ if err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }+ return nil, fmt.Errorf("systemctl daemon-reload: %w (%s)", err, out)+ }+ return map[string]interface{}{+ "action": "daemon_reloaded",+ "output": out,+ }, nil+}++// ───── systemd:list_units ─────────────────────────────────────────++// systemctlUnit is the canonical row shape returned by list_units+// regardless of whether we got JSON or plain text from systemctl.+type systemctlUnit struct {+ Unit string `json:"unit"`+ Load string `json:"load,omitempty"`+ Active string `json:"active,omitempty"`+ Sub string `json:"sub,omitempty"`+ Description string `json:"description,omitempty"`+}++func (a *Agent) handleSystemdListUnits(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if err := systemctlAvailable(); err != nil {+ return nil, err+ }+ var p struct {+ State string `json:"state"` // optional filter: failed, active, inactive…+ Type string `json:"type"` // unit type: service (default), socket, timer…+ }+ _ = json.Unmarshal(params, &p)+ if p.Type == "" {+ p.Type = "service"+ }+ if err := validateUnitName(p.Type); err != nil {+ return nil, fmt.Errorf("type: %w", err)+ }+ if p.State != "" {+ if err := validateUnitName(p.State); err != nil {+ return nil, fmt.Errorf("state: %w", err)+ }+ }++ args := []string{"list-units", "--all", "--no-legend", "--no-pager", "--type=" + p.Type}+ if p.State != "" {+ args = append(args, "--state="+p.State)+ }++ useJSON := a.detectSystemctlJSON(ctx)+ if useJSON {+ jsonArgs := append(append([]string{}, args...), "--output=json")+ out, err := a.runSystemctlPrivileged(ctx, 30*time.Second, jsonArgs...)+ if err == nil {+ var rows []map[string]interface{}+ if jerr := json.Unmarshal([]byte(out), &rows); jerr == nil {+ units := make([]systemctlUnit, 0, len(rows))+ for _, r := range rows {+ u := systemctlUnit{}+ if v, ok := r["unit"].(string); ok {+ u.Unit = v+ }+ if v, ok := r["load"].(string); ok {+ u.Load = v+ }+ if v, ok := r["active"].(string); ok {+ u.Active = v+ }+ if v, ok := r["sub"].(string); ok {+ u.Sub = v+ }+ if v, ok := r["description"].(string); ok {+ u.Description = v+ }+ units = append(units, u)+ }+ return map[string]interface{}{"units": units, "format": "json"}, nil+ }+ }+ // JSON failed (older systemd, malformed output) — fall through+ // to plain text and remember the choice.+ a.capMu.Lock()+ a.capabilities.SystemdJSON = false+ a.systemdJSON = false+ a.capMu.Unlock()+ }++ // Plain text fallback. Columns: UNIT LOAD ACTIVE SUB DESCRIPTION.+ out, err := a.runSystemctlPrivileged(ctx, 30*time.Second, args...)+ if err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }+ return nil, fmt.Errorf("systemctl list-units: %w (%s)", err, truncate(out, 1024))+ }+ units := parsePlainListUnits(out)+ return map[string]interface{}{"units": units, "format": "plain"}, nil+}++// detectSystemctlJSON probes once whether `systemctl --output=json` is+// supported. Caches the result on the agent + advertises via the+// capabilities payload so the panel can show an "older systemd" hint.+func (a *Agent) detectSystemctlJSON(ctx context.Context) bool {+ a.systemdJSONOnce.Do(func() {+ cctx, cancel := context.WithTimeout(ctx, 5*time.Second)+ defer cancel()+ err := exec.CommandContext(cctx, "systemctl", "list-units", "--no-legend", "--no-pager", "--output=json", "--type=service").Run()+ ok := err == nil+ a.capMu.Lock()+ a.systemdJSON = ok+ a.capabilities.SystemdJSON = ok+ a.capMu.Unlock()+ })+ a.capMu.Lock()+ defer a.capMu.Unlock()+ return a.systemdJSON+}++func parsePlainListUnits(out string) []systemctlUnit {+ units := []systemctlUnit{}+ for _, line := range strings.Split(out, "\n") {+ line = strings.TrimSpace(line)+ if line == "" || strings.HasPrefix(line, "●") {+ continue+ }+ fields := strings.Fields(line)+ if len(fields) < 4 {+ continue+ }+ u := systemctlUnit{+ Unit: fields[0],+ Load: fields[1],+ Active: fields[2],+ Sub: fields[3],+ }+ if len(fields) > 4 {+ u.Description = strings.Join(fields[4:], " ")+ }+ units = append(units, u)+ }+ return units+}++// ───── systemd:logs (bounded fetch) ──────────────────────────────++func (a *Agent) handleSystemdLogs(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if err := systemctlAvailable(); err != nil {+ return nil, err+ }+ var p struct {+ Unit string `json:"unit"`+ Lines int `json:"lines"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validateUnitName(p.Unit); err != nil {+ return nil, err+ }+ if p.Lines <= 0 {+ p.Lines = 200+ }+ if p.Lines > 5000 {+ p.Lines = 5000+ }++ if _, err := exec.LookPath("journalctl"); err != nil {+ return nil, errors.New("journalctl not on PATH")+ }++ cctx, cancel := context.WithTimeout(ctx, 30*time.Second)+ defer cancel()+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "journalctl",+ "-u", p.Unit, "--no-pager", "-n", fmt.Sprintf("%d", p.Lines), "-o", "json")+ if err != nil {+ return nil, err+ }+ out, err := cmd.CombinedOutput()+ if err != nil {+ if classifySudoError(string(out)) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }+ return nil, fmt.Errorf("journalctl -u %s: %w (%s)", p.Unit, err, truncate(string(out), 1024))+ }++ // journalctl -o json prints one JSON object per line. Parse each+ // into a flat shape the panel can render directly.+ type entry struct {+ Time string `json:"time"`+ Priority string `json:"priority"`+ PID string `json:"pid"`+ Message string `json:"message"`+ }+ var entries []entry+ for _, line := range strings.Split(string(out), "\n") {+ line = strings.TrimSpace(line)+ if line == "" {+ continue+ }+ var raw map[string]interface{}+ if err := json.Unmarshal([]byte(line), &raw); err != nil {+ continue+ }+ e := entry{+ Time: stringField(raw, "__REALTIME_TIMESTAMP"),+ Priority: stringField(raw, "PRIORITY"),+ PID: stringField(raw, "_PID"),+ Message: stringField(raw, "MESSAGE"),+ }+ entries = append(entries, e)+ }+ return map[string]interface{}{+ "unit": p.Unit,+ "lines": p.Lines,+ "entries": entries,+ }, nil+}++func stringField(m map[string]interface{}, k string) string {+ v, ok := m[k]+ if !ok {+ return ""+ }+ switch t := v.(type) {+ case string:+ return t+ case float64:+ return fmt.Sprintf("%.0f", t)+ default:+ return fmt.Sprintf("%v", t)+ }+}++// ───── systemd:logs_follow (streaming) ───────────────────────────++// handleSystemdLogsFollow returns a job channel and starts streaming+// `journalctl -fu <unit>` lines on it. The job ends when either the+// caller unsubscribes (which we detect by closing job.Done) or a fixed+// 1-hour cap elapses to prevent runaway logs.+//+// The pattern mirrors handlePackagesInstallAsync: hand back+// {job_id, channel} immediately, work happens in a goroutine.+func (a *Agent) handleSystemdLogsFollow(ctx context.Context, params json.RawMessage) (interface{}, error) {+ if err := systemctlAvailable(); err != nil {+ return nil, err+ }+ var p struct {+ Unit string `json:"unit"`+ }+ if err := json.Unmarshal(params, &p); err != nil {+ return nil, fmt.Errorf("invalid params: %w", err)+ }+ if err := validateUnitName(p.Unit); err != nil {+ return nil, err+ }+ if _, err := exec.LookPath("journalctl"); err != nil {+ return nil, errors.New("journalctl not on PATH")+ }++ job := a.jobs.New(500)+ // The protocol channel format is documented but we override to use+ // the job: namespace so the panel's existing job-channel+ // infrastructure handles it. The systemd:<unit>:logs format is+ // reserved for a future multi-subscriber broadcast variant.+ _ = protocol.ChannelSystemdLogs+ go a.runSystemdLogsFollowJob(job, p.Unit)+ return map[string]interface{}{+ "job_id": job.ID,+ "channel": job.Channel,+ "unit": p.Unit,+ }, nil+}++func (a *Agent) runSystemdLogsFollowJob(job *jobs.Job, unit string) {+ exit := 0+ emitDone := func(errStr string) {+ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseDone,+ ExitCode: &exit,+ Error: errStr,+ Extra: map[string]interface{}{"unit": unit},+ })+ }++ // Cap any single follow at 1 hour. Panel can re-subscribe.+ cctx, cancel := context.WithTimeout(context.Background(), 1*time.Hour)+ defer cancel()+ cmd, err := sudoCommandContext(cctx, a.sudoMode, "journalctl",+ "-fu", unit, "--no-pager", "-o", "short-iso")+ if err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ _ = job.Push(a.ws, jobs.Event{+ Phase: jobs.PhaseStart,+ Message: fmt.Sprintf("following journal for %s", unit),+ })+ if err := streamCmdOutput(cmd, job, a.ws); err != nil {+ exit = -1+ emitDone(err.Error())+ return+ }+ if cerr := cmd.Wait(); cerr != nil {+ exit = exitCodeOf(cerr)+ // journalctl returns non-zero when killed by the deadline; that's+ // a graceful end, not an error.+ if cctx.Err() == context.DeadlineExceeded {+ emitDone("")+ return+ }+ emitDone(cerr.Error())+ return+ }+ emitDone("")+}diff --git a/agent/internal/agent/workflow_handlers.go b/agent/internal/agent/workflow_handlers.goindex 1d0766e5..1857cf91 100644--- a/agent/internal/agent/workflow_handlers.go+++ b/agent/internal/agent/workflow_handlers.go@@ -270,6 +270,12 @@ func (a *Agent) handleSystemdStatus(ctx context.Context, params json.RawMessage)}, nil}+// systemdMutateTimeout is the per-action timeout for state-changing+// systemctl calls (start/stop/restart/enable/disable). Cold service+// starts (postgresql, mongodb) routinely take 30-90s, so the original+// 30s ceiling was too tight; bump to 2 minutes.+const systemdMutateTimeout = 2 * time.Minute+func (a *Agent) handleSystemdStart(ctx context.Context, params json.RawMessage) (interface{}, error) {if err := systemctlAvailable(); err != nil {return nil, err@@ -278,7 +284,10 @@ func (a *Agent) handleSystemdStart(ctx context.Context, params json.RawMessage)if err != nil {return nil, err}- if out, err := runSystemctl(ctx, "start", unit); err != nil {+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "start", unit); err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }return nil, fmt.Errorf("systemctl start %s: %w (%s)", unit, err, out)}return map[string]interface{}{"unit": unit, "action": "started"}, nil@@ -292,7 +301,10 @@ func (a *Agent) handleSystemdStop(ctx context.Context, params json.RawMessage) (if err != nil {return nil, err}- if out, err := runSystemctl(ctx, "stop", unit); err != nil {+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "stop", unit); err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }return nil, fmt.Errorf("systemctl stop %s: %w (%s)", unit, err, out)}return map[string]interface{}{"unit": unit, "action": "stopped"}, nil@@ -306,7 +318,10 @@ func (a *Agent) handleSystemdRestart(ctx context.Context, params json.RawMessageif err != nil {return nil, err}- if out, err := runSystemctl(ctx, "restart", unit); err != nil {+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "restart", unit); err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }return nil, fmt.Errorf("systemctl restart %s: %w (%s)", unit, err, out)}return map[string]interface{}{"unit": unit, "action": "restarted"}, nil@@ -320,7 +335,10 @@ func (a *Agent) handleSystemdEnable(ctx context.Context, params json.RawMessage)if err != nil {return nil, err}- if out, err := runSystemctl(ctx, "enable", unit); err != nil {+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "enable", unit); err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }return nil, fmt.Errorf("systemctl enable %s: %w (%s)", unit, err, out)}return map[string]interface{}{"unit": unit, "action": "enabled"}, nil@@ -334,7 +352,10 @@ func (a *Agent) handleSystemdDisable(ctx context.Context, params json.RawMessageif err != nil {return nil, err}- if out, err := runSystemctl(ctx, "disable", unit); err != nil {+ if out, err := a.runSystemctlPrivileged(ctx, systemdMutateTimeout, "disable", unit); err != nil {+ if classifySudoError(out) {+ return nil, fmt.Errorf("sudo refused: %w", errSudoRequired)+ }return nil, fmt.Errorf("systemctl disable %s: %w (%s)", unit, err, out)}return map[string]interface{}{"unit": unit, "action": "disabled"}, nildiff --git a/agent/internal/capabilities/capabilities.go b/agent/internal/capabilities/capabilities.goindex da527071..92232958 100644--- a/agent/internal/capabilities/capabilities.go+++ b/agent/internal/capabilities/capabilities.go@@ -283,3 +283,14 @@ func hasOnPath(name string) bool {}var pathCache sync.Map++// ClearPathCache empties the binary-on-PATH cache. Called by agent:+// recapabilities so a binary that was installed since the last probe+// (e.g. the user just ran apt install nginx) is detected fresh+// instead of returning the stale "not found" result.+func ClearPathCache() {+ pathCache.Range(func(k, _ interface{}) bool {+ pathCache.Delete(k)+ return true+ })+}diff --git a/agent/internal/docker/client.go b/agent/internal/docker/client.goindex a415798b..b546ecec 100644--- a/agent/internal/docker/client.go+++ b/agent/internal/docker/client.go@@ -11,8 +11,10 @@ import ("github.com/docker/docker/api/types"containertypes "github.com/docker/docker/api/types/container""github.com/docker/docker/api/types/filters"+ networktypes "github.com/docker/docker/api/types/network"volumetypes "github.com/docker/docker/api/types/volume""github.com/docker/docker/client"+ "github.com/docker/go-connections/nat""github.com/serverkit/agent/internal/config""github.com/serverkit/agent/internal/logger")@@ -440,6 +442,239 @@ func (c *Client) Close() error {return c.cli.Close()}+// ───── container:create / container:exec / image:build / network:create++// ContainerCreateSpec is the curated input shape for CreateContainer.+// We deliberately don't expose raw HostConfig — the panel sends the+// fields a one-click template needs and we map them. Privileged /+// CapAdd / Devices are intentionally absent in v1; if a user needs+// them they should run `docker create` directly.+type ContainerCreateSpec struct {+ Image string `json:"image"`+ Name string `json:"name,omitempty"`+ Command []string `json:"command,omitempty"`+ Env []string `json:"env,omitempty"` // KEY=VAL+ Labels map[string]string `json:"labels,omitempty"`+ RestartPolicy string `json:"restart_policy,omitempty"` // no, on-failure, always, unless-stopped+ Network string `json:"network,omitempty"`+ Ports []ContainerPort `json:"ports,omitempty"`+ Volumes []ContainerMount `json:"volumes,omitempty"`+ WorkingDir string `json:"working_dir,omitempty"`+}++type ContainerPort struct {+ Host uint16 `json:"host"`+ Container uint16 `json:"container"`+ Proto string `json:"proto,omitempty"` // "tcp" (default) or "udp"+}++type ContainerMount struct {+ Source string `json:"src"`+ Target string `json:"dst"`+ Mode string `json:"mode,omitempty"` // "ro" or "" for rw+}++// CreateContainer wires a curated spec to the Docker SDK's+// ContainerCreate. Returns the new container ID.+func (c *Client) CreateContainer(ctx context.Context, spec ContainerCreateSpec) (string, error) {+ if strings.TrimSpace(spec.Image) == "" {+ return "", fmt.Errorf("image is required")+ }++ exposed := nat.PortSet{}+ bindings := nat.PortMap{}+ for _, p := range spec.Ports {+ proto := p.Proto+ if proto == "" {+ proto = "tcp"+ }+ port, err := nat.NewPort(proto, fmt.Sprintf("%d", p.Container))+ if err != nil {+ return "", fmt.Errorf("invalid port %d/%s: %w", p.Container, proto, err)+ }+ exposed[port] = struct{}{}+ bindings[port] = []nat.PortBinding{{HostIP: "0.0.0.0", HostPort: fmt.Sprintf("%d", p.Host)}}+ }++ binds := make([]string, 0, len(spec.Volumes))+ for _, v := range spec.Volumes {+ bind := v.Source + ":" + v.Target+ if v.Mode != "" {+ bind += ":" + v.Mode+ }+ binds = append(binds, bind)+ }++ cfg := &containertypes.Config{+ Image: spec.Image,+ Cmd: spec.Command,+ Env: spec.Env,+ Labels: spec.Labels,+ WorkingDir: spec.WorkingDir,+ ExposedPorts: exposed,+ }+ hostCfg := &containertypes.HostConfig{+ PortBindings: bindings,+ Binds: binds,+ RestartPolicy: containertypes.RestartPolicy{+ Name: spec.RestartPolicy,+ },+ }+ var netCfg *networktypes.NetworkingConfig+ if spec.Network != "" {+ netCfg = &networktypes.NetworkingConfig{+ EndpointsConfig: map[string]*networktypes.EndpointSettings{+ spec.Network: {},+ },+ }+ }+ resp, err := c.cli.ContainerCreate(ctx, cfg, hostCfg, netCfg, nil, spec.Name)+ if err != nil {+ return "", err+ }+ return resp.ID, nil+}++// ContainerExecResult is the bounded result of an exec call.+type ContainerExecResult struct {+ Stdout string `json:"stdout"`+ Stderr string `json:"stderr"`+ ExitCode int `json:"exit_code"`+}++// ExecContainer runs a command inside a running container, captures+// stdout/stderr (capped to outputCap bytes), and returns the exit code.+// User and WorkingDir are optional; pass an empty string to inherit.+func (c *Client) ExecContainer(ctx context.Context, id string, cmd []string, user, workingDir string, outputCap int) (ContainerExecResult, error) {+ if outputCap <= 0 {+ outputCap = 1024 * 1024 // 1MB default+ }+ createResp, err := c.cli.ContainerExecCreate(ctx, id, types.ExecConfig{+ Cmd: cmd,+ AttachStdout: true,+ AttachStderr: true,+ User: user,+ WorkingDir: workingDir,+ })+ if err != nil {+ return ContainerExecResult{}, err+ }+ hijack, err := c.cli.ContainerExecAttach(ctx, createResp.ID, types.ExecStartCheck{})+ if err != nil {+ return ContainerExecResult{}, err+ }+ defer hijack.Close()++ // Read multiplexed stream: docker frames stdout/stderr together+ // with an 8-byte header. stdcopy.StdCopy demultiplexes, but to+ // avoid an extra import we use a bounded ReadAll and ship the raw+ // stream — the panel only needs the combined output anyway.+ buf := &boundedBuffer{cap: outputCap}+ _, _ = io.Copy(buf, hijack.Reader)++ insp, err := c.cli.ContainerExecInspect(ctx, createResp.ID)+ if err != nil {+ return ContainerExecResult{}, err+ }+ return ContainerExecResult{+ Stdout: buf.String(),+ ExitCode: insp.ExitCode,+ }, nil+}++// boundedBuffer is a tiny io.Writer that drops bytes past a cap. Used+// instead of bytes.Buffer to keep exec output from blowing memory on a+// chatty command like `find /`.+type boundedBuffer struct {+ cap int+ data []byte+}++func (b *boundedBuffer) Write(p []byte) (int, error) {+ remaining := b.cap - len(b.data)+ if remaining <= 0 {+ return len(p), nil+ }+ if len(p) > remaining {+ b.data = append(b.data, p[:remaining]...)+ return len(p), nil+ }+ b.data = append(b.data, p...)+ return len(p), nil+}++func (b *boundedBuffer) String() string { return string(b.data) }++// ImageBuildSpec carries the curated input for BuildImage.+type ImageBuildSpec struct {+ ContextPath string `json:"context_path"`+ Dockerfile string `json:"dockerfile,omitempty"`+ Tag string `json:"tag"`+ BuildArgs map[string]string `json:"build_args,omitempty"`+ NoCache bool `json:"no_cache,omitempty"`+ Pull bool `json:"pull,omitempty"`+}++// BuildImageCmd builds the *exec.Cmd for a `docker build` invocation+// based on spec. The caller streams stdout/stderr (we use the same+// jobs streaming helper as packages). Returning a Cmd rather than a+// reader keeps this file from importing the docker SDK's archive+// package, which pulls in containerd/moby deps that aren't in our+// go.mod.+func (c *Client) BuildImageCmd(ctx context.Context, spec ImageBuildSpec) (*exec.Cmd, error) {+ if strings.TrimSpace(spec.ContextPath) == "" {+ return nil, fmt.Errorf("context_path is required")+ }+ if strings.TrimSpace(spec.Tag) == "" {+ return nil, fmt.Errorf("tag is required")+ }+ args := []string{"build", "-t", spec.Tag}+ if spec.Dockerfile != "" {+ args = append(args, "-f", spec.Dockerfile)+ }+ for k, v := range spec.BuildArgs {+ args = append(args, "--build-arg", k+"="+v)+ }+ if spec.NoCache {+ args = append(args, "--no-cache")+ }+ if spec.Pull {+ args = append(args, "--pull")+ }+ args = append(args, spec.ContextPath)+ return exec.CommandContext(ctx, "docker", args...), nil+}++// NetworkCreateSpec carries curated input for CreateNetwork.+type NetworkCreateSpec struct {+ Name string `json:"name"`+ Driver string `json:"driver,omitempty"` // bridge (default), overlay, host+ Internal bool `json:"internal,omitempty"`+ Attachable bool `json:"attachable,omitempty"`+ Labels map[string]string `json:"labels,omitempty"`+}++// CreateNetwork creates a Docker network and returns its ID.+func (c *Client) CreateNetwork(ctx context.Context, spec NetworkCreateSpec) (string, error) {+ if strings.TrimSpace(spec.Name) == "" {+ return "", fmt.Errorf("name is required")+ }+ driver := spec.Driver+ if driver == "" {+ driver = "bridge"+ }+ resp, err := c.cli.NetworkCreate(ctx, spec.Name, types.NetworkCreate{+ Driver: driver,+ Internal: spec.Internal,+ Attachable: spec.Attachable,+ Labels: spec.Labels,+ })+ if err != nil {+ return "", err+ }+ return resp.ID, nil+}+// calculateCPUPercent calculates CPU usage percentagefunc calculateCPUPercent(stats *types.StatsJSON) float64 {cpuDelta := float64(stats.CPUStats.CPUUsage.TotalUsage - stats.PreCPUStats.CPUUsage.TotalUsage)diff --git a/agent/internal/jobs/jobs.go b/agent/internal/jobs/jobs.gonew file mode 100644index 00000000..0614ee35--- /dev/null+++ b/agent/internal/jobs/jobs.go@@ -0,0 +1,196 @@+// Package jobs tracks long-running operations (package installs, image+// builds, pyenv installs) so the panel can subscribe to a streaming+// channel and receive progress events as they happen, plus a replay of+// recent events when subscribing mid-flight.+//+// A Job is created when a handler kicks off async work (e.g.+// packages:install) and returns {job_id, channel} to the caller. The+// handler then emits Event values via Job.Push, which:+// - sends the event to the agent's stream transport (so any active+// subscriber sees it live), AND+// - records the event in a bounded ring buffer (so a late subscriber+// can be caught up via Replay).+//+// The package is small on purpose — no goroutines, no timers, no I/O.+// Callers own concurrency. The only synchronization is a mutex around+// the registry map and per-job buffer mutex.+package jobs++import (+ "crypto/rand"+ "encoding/hex"+ "fmt"+ "sync"+ "time"+)++// newID returns a 16-byte hex string suitable as a job identifier.+// Falls back to a timestamp if /dev/urandom is unavailable, matching+// the agent's auth.GenerateNonce style without taking a dep on it.+func newID() string {+ b := make([]byte, 16)+ if _, err := rand.Read(b); err != nil {+ return fmt.Sprintf("%d-%d", time.Now().UnixNano(), time.Now().UnixMilli())+ }+ return hex.EncodeToString(b)+}++// Phase enumerates lifecycle phases emitted by streaming jobs. The+// panel uses these to drive its progress UI.+const (+ PhaseStart = "start"+ PhaseLog = "log"+ PhaseStatus = "status"+ PhaseDone = "done"+)++// Event is the wire shape pushed onto a job's channel. Fields are kept+// minimal and JSON-tagged so the panel can render terminal-style output+// without per-handler parsers. Free-form Extra is for handlers that+// want to attach structured data (e.g. installed package list) to the+// final event.+type Event struct {+ Phase string `json:"phase"`+ Lines []string `json:"lines,omitempty"`+ Message string `json:"message,omitempty"`+ Percent *int `json:"percent,omitempty"`+ ExitCode *int `json:"exit_code,omitempty"`+ Error string `json:"error,omitempty"`+ Extra map[string]interface{} `json:"extra,omitempty"`+}++// Job is one in-flight long-running operation. It owns a ring buffer+// of recent events so late subscribers can replay missed history.+type Job struct {+ ID string+ Channel string++ mu sync.Mutex+ events []Event // ring buffer+ cap int+ head int // index of the next slot to write+ full bool // whether we've wrapped past cap++ doneOnce sync.Once+ done chan struct{}+}++// Streamer is the slice of the agent transport that jobs need. Wraps+// SendStream so handlers don't have to import the transport package+// directly.+type Streamer interface {+ SendStream(channel string, data interface{}) error+}++// Registry tracks active and recently-completed jobs by ID. The bounded+// retention means a panel that subscribes to a job channel a few+// seconds after it completed still sees the final event. After enough+// new jobs land, the old job ages out and Replay returns nothing — at+// which point the panel knows the job is gone and should show "no+// progress available."+type Registry struct {+ mu sync.Mutex+ jobs map[string]*Job+ // keep the last MaxJobs jobs in memory so a brief subscribe-after-finish+ // race still serves the final "done" event.+ maxJobs int+ order []string // FIFO of job IDs; trimmed when len > maxJobs+}++// NewRegistry returns a Registry retaining up to maxJobs jobs.+func NewRegistry(maxJobs int) *Registry {+ if maxJobs <= 0 {+ maxJobs = 64+ }+ return &Registry{+ jobs: make(map[string]*Job),+ maxJobs: maxJobs,+ }+}++// New creates and registers a new Job. bufferCap is the ring-buffer+// size for replay (suggested 200).+func (r *Registry) New(bufferCap int) *Job {+ if bufferCap <= 0 {+ bufferCap = 200+ }+ id := newID()+ j := &Job{+ ID: id,+ Channel: "job:" + id,+ events: make([]Event, bufferCap),+ cap: bufferCap,+ done: make(chan struct{}),+ }+ r.mu.Lock()+ r.jobs[id] = j+ r.order = append(r.order, id)+ // Trim oldest jobs if we're over capacity.+ for len(r.order) > r.maxJobs {+ oldest := r.order[0]+ r.order = r.order[1:]+ delete(r.jobs, oldest)+ }+ r.mu.Unlock()+ return j+}++// Get returns the job with the given ID, or nil if unknown.+func (r *Registry) Get(id string) *Job {+ r.mu.Lock()+ defer r.mu.Unlock()+ return r.jobs[id]+}++// LookupByChannel returns the job whose Channel matches the given+// channel name (e.g. "job:<id>"), or nil. Used by Subscribe handlers+// to decide whether to replay buffered events.+func (r *Registry) LookupByChannel(channel string) *Job {+ if len(channel) <= 4 || channel[:4] != "job:" {+ return nil+ }+ return r.Get(channel[4:])+}++// Push records an event in the ring buffer and pushes it on the+// transport's stream channel. Panic-safe: a nil streamer just records+// the event, useful for tests.+func (j *Job) Push(s Streamer, ev Event) error {+ j.mu.Lock()+ j.events[j.head] = ev+ j.head = (j.head + 1) % j.cap+ if j.head == 0 {+ j.full = true+ }+ j.mu.Unlock()++ if ev.Phase == PhaseDone {+ j.doneOnce.Do(func() { close(j.done) })+ }++ if s == nil {+ return nil+ }+ return s.SendStream(j.Channel, ev)+}++// Replay returns a copy of the buffered events in chronological order.+// Used when a late subscriber wants to catch up.+func (j *Job) Replay() []Event {+ j.mu.Lock()+ defer j.mu.Unlock()+ if !j.full {+ out := make([]Event, j.head)+ copy(out, j.events[:j.head])+ return out+ }+ // Ring is full: oldest is at head, newest is just before head.+ out := make([]Event, 0, j.cap)+ out = append(out, j.events[j.head:]...)+ out = append(out, j.events[:j.head]...)+ return out+}++// Done returns a channel closed when the job emits a final event with+// Phase == PhaseDone. Useful for tests.+func (j *Job) Done() <-chan struct{} { return j.done }diff --git a/agent/internal/jobs/jobs_test.go b/agent/internal/jobs/jobs_test.gonew file mode 100644index 00000000..aee2b9fb--- /dev/null+++ b/agent/internal/jobs/jobs_test.go@@ -0,0 +1,114 @@+package jobs++import (+ "strconv"+ "sync"+ "testing"+)++type recorder struct {+ mu sync.Mutex+ sent []Event+}++func (r *recorder) SendStream(channel string, data interface{}) error {+ ev, _ := data.(Event)+ r.mu.Lock()+ r.sent = append(r.sent, ev)+ r.mu.Unlock()+ return nil+}++func TestRegistryNewAssignsUniqueChannel(t *testing.T) {+ r := NewRegistry(8)+ a := r.New(0)+ b := r.New(0)+ if a.ID == b.ID {+ t.Fatal("expected unique IDs")+ }+ if a.Channel != "job:"+a.ID || b.Channel != "job:"+b.ID {+ t.Fatalf("unexpected channels: %q %q", a.Channel, b.Channel)+ }+ if r.LookupByChannel(a.Channel) != a {+ t.Fatal("LookupByChannel did not round-trip")+ }+ if r.LookupByChannel("metrics") != nil {+ t.Fatal("non-job channel should return nil")+ }+}++func TestPushAndReplayPreserveOrder(t *testing.T) {+ r := NewRegistry(8)+ j := r.New(4)+ rec := &recorder{}++ for i := 0; i < 3; i++ {+ if err := j.Push(rec, Event{Phase: PhaseLog, Message: strconv.Itoa(i)}); err != nil {+ t.Fatal(err)+ }+ }+ got := j.Replay()+ if len(got) != 3 {+ t.Fatalf("want 3 events, got %d", len(got))+ }+ for i, ev := range got {+ if ev.Message != strconv.Itoa(i) {+ t.Fatalf("event %d out of order: %q", i, ev.Message)+ }+ }+ if len(rec.sent) != 3 {+ t.Fatalf("transport got %d events, want 3", len(rec.sent))+ }+}++func TestRingBufferDropsOldest(t *testing.T) {+ r := NewRegistry(8)+ j := r.New(3)+ rec := &recorder{}+ for i := 0; i < 5; i++ {+ _ = j.Push(rec, Event{Phase: PhaseLog, Message: strconv.Itoa(i)})+ }+ got := j.Replay()+ if len(got) != 3 {+ t.Fatalf("ring should hold 3 events, got %d", len(got))+ }+ // Oldest two events (0,1) should have been dropped; expect 2,3,4.+ for i, ev := range got {+ want := strconv.Itoa(i + 2)+ if ev.Message != want {+ t.Fatalf("ring order broken at %d: got %q want %q", i, ev.Message, want)+ }+ }+}++func TestDoneClosedOnTerminalEvent(t *testing.T) {+ r := NewRegistry(8)+ j := r.New(4)+ select {+ case <-j.Done():+ t.Fatal("done before terminal event")+ default:+ }+ exit := 0+ _ = j.Push(nil, Event{Phase: PhaseDone, ExitCode: &exit})+ select {+ case <-j.Done():+ default:+ t.Fatal("done not closed after terminal event")+ }+ // Idempotent: second done event must not panic.+ _ = j.Push(nil, Event{Phase: PhaseDone, ExitCode: &exit})+}++func TestRegistryEvictsOldestJobs(t *testing.T) {+ r := NewRegistry(2)+ j1 := r.New(0)+ j2 := r.New(0)+ j3 := r.New(0)+ if r.Get(j1.ID) != nil {+ t.Fatal("j1 should have been evicted")+ }+ if r.Get(j2.ID) == nil || r.Get(j3.ID) == nil {+ t.Fatal("j2/j3 should still be present")+ }+}diff --git a/agent/pkg/protocol/messages.go b/agent/pkg/protocol/messages.goindex 4931b7dc..118c791d 100644--- a/agent/pkg/protocol/messages.go+++ b/agent/pkg/protocol/messages.go@@ -179,6 +179,25 @@ type CapabilitiesMessage struct {// panel's file manager can render the available browse roots without// guessing. Empty/missing => the panel must hide remote file features.AllowedPaths []string `json:"allowed_paths,omitempty"`+ // Sudo describes how the agent escalates privileges for handlers+ // that need root (systemd, packages). Values: "root" (already root),+ // "passwordless" (sudo -n works), "unavailable" (no escalation —+ // privileged handlers will fail). Empty/missing means the panel+ // should treat it as "unavailable" for safety.+ Sudo string `json:"sudo,omitempty"`+ // RuntimeManagers reports which version manager (if any) is+ // installed for each runtime, e.g. {"python": "pyenv"} on Linux or+ // {"python": "pyenv-win"} on Windows. Empty/missing key means no+ // manager installed; the panel can offer the bootstrap action.+ RuntimeManagers map[string]string `json:"runtime_managers,omitempty"`+ // SystemdJSON indicates whether `systemctl --output=json` is+ // supported (systemd >= 244). When false, list_units falls back to+ // parsing the plain --no-legend table.+ SystemdJSON bool `json:"systemd_json,omitempty"`+ // ProbedAt is the unix milliseconds timestamp when the capabilities+ // payload was computed. Lets the panel distinguish a fresh re-probe+ // from a cached set replayed on reconnect.+ ProbedAt int64 `json:"probed_at,omitempty"`}// SystemInfo contains detailed system information@@ -244,18 +263,50 @@ const (// Linux-only; the agent picks the right manager (apt/dnf/apk/…)// based on what's on PATH. Calls are idempotent — installing an// already-installed package is a no-op success.+ //+ // Install/Upgrade are long-running and stream progress on the+ // returned job channel ("job:<id>") rather than blocking — the+ // command result returns {job_id, channel} immediately.ActionPackagesInstall = "packages:install"ActionPackagesRemove = "packages:remove"ActionPackagesListInstalled = "packages:list_installed"+ ActionPackagesUpdateCache = "packages:update_cache"+ // ActionPackagesInstallAsync is the streaming variant of+ // ActionPackagesInstall: takes names[] (and/or a single name),+ // returns {job_id, channel} immediately, and emits per-line install+ // progress on the channel. Use this for the Packages tab UI; the+ // synchronous variant is retained for the workflow engine's+ // agent_command nodes which expect a structured result.+ ActionPackagesInstallAsync = "packages:install_async"+ ActionPackagesUpgrade = "packages:upgrade"+ ActionPackagesSearch = "packages:search"+ ActionPackagesInfo = "packages:info"// Systemd unit actions. Linux-only and require systemd as PID 1// (the capability probe already gates this).- ActionSystemdStatus = "systemd:status"- ActionSystemdStart = "systemd:start"- ActionSystemdStop = "systemd:stop"- ActionSystemdRestart = "systemd:restart"- ActionSystemdEnable = "systemd:enable"- ActionSystemdDisable = "systemd:disable"+ ActionSystemdStatus = "systemd:status"+ ActionSystemdStart = "systemd:start"+ ActionSystemdStop = "systemd:stop"+ ActionSystemdRestart = "systemd:restart"+ ActionSystemdEnable = "systemd:enable"+ ActionSystemdDisable = "systemd:disable"+ ActionSystemdDaemonReload = "systemd:daemon_reload"+ ActionSystemdListUnits = "systemd:list_units"+ ActionSystemdLogs = "systemd:logs"+ ActionSystemdLogsFollow = "systemd:logs_follow"++ // Runtime version managers (Phase 5). Currently scoped to Python+ // via pyenv on Linux and pyenv-win on Windows. Install/Bootstrap+ // stream on a job channel like packages.+ ActionRuntimesList = "runtimes:list"+ ActionRuntimesPyenvBootstrap = "runtimes:pyenv:bootstrap"+ ActionRuntimesPythonInstalled = "runtimes:python:installed"+ ActionRuntimesPythonAvailable = "runtimes:python:available"+ ActionRuntimesPythonInstall = "runtimes:python:install"+ ActionRuntimesPythonUninstall = "runtimes:python:uninstall"+ ActionRuntimesPythonSetGlobal = "runtimes:python:set_global"+ ActionRuntimesPythonSetLocal = "runtimes:python:set_local"+ ActionRuntimesPythonCurrent = "runtimes:python:current"// Cron actions — manage entries in the agent host's user crontab.// Linux-only; non-Linux agents return an "unsupported" error.@@ -288,7 +339,8 @@ const (ActionTerminalClose = "terminal:close"// Agent actions- ActionAgentUpdate = "agent:update"+ ActionAgentUpdate = "agent:update"+ ActionAgentRecapabilities = "agent:recapabilities"// GUI / desktop capture actions. These are the agent-side primitives// that panel extensions (e.g. serverkit-gui) call into. Implementation@@ -305,6 +357,15 @@ const (ChannelContainerLogs = "container:%s:logs"ChannelContainerStats = "container:%s:stats"ChannelTerminal = "terminal:%s"+ // ChannelSystemdLogs streams journalctl -fu <unit> events. Lifecycle+ // mirrors ChannelContainerLogs: subscribe starts the follow, unsubscribe+ // (or socket close) stops it.+ ChannelSystemdLogs = "systemd:%s:logs"+ // ChannelJob is used for long-running operations (package install,+ // image build, pyenv install) that return {job_id, channel} from+ // their command result and stream progress events on the channel.+ // Late subscribers receive a replay of the last N buffered events.+ ChannelJob = "job:%s")// CredentialUpdateMessage is sent by server to rotate credentialsdiff --git a/backend/app/api/servers.py b/backend/app/api/servers.pyindex 2b0c3a17..d1c2db9f 100644--- a/backend/app/api/servers.py+++ b/backend/app/api/servers.py@@ -2298,6 +2298,184 @@ def remote_cloudflared_delete(server_id, tunnel_ref):return _agent_result(result)+# ==================== Remote Capability Refresh ====================+#+# Lets the panel ask the agent to re-run its capability probe on+# demand — useful after the user installs a runtime, sudoers entry,+# or new package manager and wants new tabs to light up without an+# agent service restart. The agent's response is the freshly merged+# capabilities map; the agent additionally pushes via the persistent+# Capabilities message so all panel listeners stay in sync.++@servers_bp.route('/<server_id>/refresh-capabilities', methods=['POST'])+@jwt_required()+def remote_refresh_capabilities(server_id):+ user_id = get_jwt_identity()+ result = agent_registry.send_command(+ server_id=server_id, action='agent:recapabilities',+ params={}, user_id=user_id, timeout=20.0,+ )+ return _agent_result(result)+++# ==================== Remote Packages ====================+#+# Exposes the agent's packages:* surface for the Packages tab.+# Long-running operations (install/upgrade) return {job_id, channel};+# the frontend subscribes to Socket.IO room+# server_<id>_<channel> for live progress events.++from app.services.remote_packages_service import RemotePackagesService+++@servers_bp.route('/<server_id>/packages', methods=['GET'])+@jwt_required()+def remote_packages_list(server_id):+ user_id = get_jwt_identity()+ result = RemotePackagesService.list_installed(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/search', methods=['GET'])+@jwt_required()+def remote_packages_search(server_id):+ user_id = get_jwt_identity()+ query = (request.args.get('q') or '').strip()+ if not query:+ return jsonify({'error': 'q is required'}), 400+ try:+ limit = int(request.args.get('limit', 100))+ except (TypeError, ValueError):+ limit = 100+ result = RemotePackagesService.search(server_id, query, limit=limit, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/info/<name>', methods=['GET'])+@jwt_required()+def remote_packages_info(server_id, name):+ user_id = get_jwt_identity()+ result = RemotePackagesService.info(server_id, name, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/update-cache', methods=['POST'])+@jwt_required()+@developer_required+def remote_packages_update_cache(server_id):+ user_id = get_jwt_identity()+ result = RemotePackagesService.update_cache(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/install', methods=['POST'])+@jwt_required()+@developer_required+def remote_packages_install(server_id):+ """Streaming install. Body: {names: ['nginx', 'redis-server']}.+ Returns {job_id, channel} immediately; the panel subscribes to the+ matching Socket.IO room for live install output."""+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ names = data.get('names') or []+ if isinstance(names, str):+ names = [names]+ if not names:+ return jsonify({'error': 'names is required'}), 400+ result = RemotePackagesService.install_async(server_id, names, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/remove', methods=['POST'])+@jwt_required()+@developer_required+def remote_packages_remove(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ name = (data.get('name') or '').strip()+ if not name:+ return jsonify({'error': 'name is required'}), 400+ result = RemotePackagesService.remove(server_id, name, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/upgrade', methods=['POST'])+@jwt_required()+@developer_required+def remote_packages_upgrade(server_id):+ """Streaming upgrade. Body: {all: bool, names?: [...]}. Returns+ {job_id, channel}."""+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ names = data.get('names') or []+ all_pkgs = bool(data.get('all', False))+ if not all_pkgs and not names:+ return jsonify({'error': 'either all=true or names=[...] required'}), 400+ result = RemotePackagesService.upgrade(+ server_id,+ names=names if names else None,+ all_packages=all_pkgs,+ user_id=user_id,+ )+ return _agent_result(result)+++# ==================== Remote Services (systemd) ====================++from app.services.remote_systemd_service import RemoteSystemdService+++@servers_bp.route('/<server_id>/services', methods=['GET'])+@jwt_required()+def remote_services_list(server_id):+ user_id = get_jwt_identity()+ state = request.args.get('state')+ type_ = request.args.get('type', 'service')+ result = RemoteSystemdService.list_units(server_id, state=state, type_=type_, user_id=user_id)+ return _agent_result(result)+++# Static-suffix routes must come before the generic <unit>/<action>+# route so Werkzeug picks the right matcher in registration order.++@servers_bp.route('/<server_id>/services/daemon-reload', methods=['POST'])+@jwt_required()+@developer_required+def remote_services_daemon_reload(server_id):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.daemon_reload(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>/logs', methods=['GET'])+@jwt_required()+def remote_services_logs(server_id, unit):+ user_id = get_jwt_identity()+ try:+ lines = int(request.args.get('lines', 200))+ except (TypeError, ValueError):+ lines = 200+ result = RemoteSystemdService.logs(server_id, unit, lines=lines, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>', methods=['GET'])+@jwt_required()+def remote_services_status(server_id, unit):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.status(server_id, unit, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>/<action>', methods=['POST'])+@jwt_required()+@developer_required+def remote_services_control(server_id, unit, action):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.control(server_id, unit, action, user_id=user_id)+ return _agent_result(result)++# ==================== Remote File Operations ====================## Endpoints under /servers/<id>/files/ proxy to the agent's file:*diff --git a/backend/app/services/remote_packages_service.py b/backend/app/services/remote_packages_service.pynew file mode 100644index 00000000..655ce7f7--- /dev/null+++ b/backend/app/services/remote_packages_service.py@@ -0,0 +1,117 @@+"""+Remote Packages Service.++Routes /api/v1/servers/<id>/packages/* requests through the agent+registry to the host's package manager (apt/dnf/apk/pacman/zypper).++Long-running operations (install_async, upgrade) return+{job_id, channel} immediately and stream progress on the channel —+the panel re-broadcasts those events to Socket.IO subscribers via+agent_gateway.++Short reads (list_installed, search, info, update_cache) are+synchronous round-trips matching the cron service shape.+"""++from typing import Any, Dict, Iterable, List, Optional++from app.services.agent_registry import agent_registry+++class RemotePackagesService:+ """Thin dispatcher to the agent's packages:* handlers."""++ @staticmethod+ def _send(server_id: str, action: str, params: Optional[Dict[str, Any]] = None,+ user_id: Optional[int] = None, timeout: float = 30.0) -> Dict[str, Any]:+ return agent_registry.send_command(+ server_id=server_id,+ action=action,+ params=params or {},+ user_id=user_id,+ timeout=timeout,+ )++ # ---- read paths -------------------------------------------------++ @staticmethod+ def list_installed(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ # The agent's list_installed shells `apt-get list --installed` /+ # `dnf list installed` / etc., which can return ~250KB on a+ # populated server. 30s budget is generous; usually subsecond.+ return RemotePackagesService._send(+ server_id, 'packages:list_installed', user_id=user_id, timeout=30.0,+ )++ @staticmethod+ def search(server_id: str, query: str, limit: int = 100,+ user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemotePackagesService._send(+ server_id, 'packages:search',+ params={'query': query, 'limit': limit},+ user_id=user_id,+ timeout=30.0,+ )++ @staticmethod+ def info(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemotePackagesService._send(+ server_id, 'packages:info',+ params={'name': name},+ user_id=user_id,+ timeout=30.0,+ )++ # ---- write paths ------------------------------------------------++ @staticmethod+ def update_cache(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemotePackagesService._send(+ server_id, 'packages:update_cache', user_id=user_id, timeout=180.0,+ )++ @staticmethod+ def install(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ # Synchronous single-name install for callers that want a+ # structured result (workflow_engine agent_command nodes).+ return RemotePackagesService._send(+ server_id, 'packages:install',+ params={'name': name},+ user_id=user_id,+ timeout=15 * 60.0,+ )++ @staticmethod+ def install_async(server_id: str, names: Iterable[str],+ user_id: Optional[int] = None) -> Dict[str, Any]:+ # Streaming variant: returns {job_id, channel}.+ return RemotePackagesService._send(+ server_id, 'packages:install_async',+ params={'names': list(names)},+ user_id=user_id,+ timeout=10.0,+ )++ @staticmethod+ def remove(server_id: str, name: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemotePackagesService._send(+ server_id, 'packages:remove',+ params={'name': name},+ user_id=user_id,+ timeout=10 * 60.0,+ )++ @staticmethod+ def upgrade(server_id: str, names: Optional[List[str]] = None, all_packages: bool = False,+ user_id: Optional[int] = None) -> Dict[str, Any]:+ params: Dict[str, Any] = {}+ if all_packages:+ params['all'] = True+ if names:+ params['names'] = list(names)+ return RemotePackagesService._send(+ server_id, 'packages:upgrade',+ params=params,+ user_id=user_id,+ timeout=10.0,+ )diff --git a/backend/app/services/remote_systemd_service.py b/backend/app/services/remote_systemd_service.pynew file mode 100644index 00000000..40091565--- /dev/null+++ b/backend/app/services/remote_systemd_service.py@@ -0,0 +1,89 @@+"""+Remote Systemd Service.++Wraps the agent's systemd:* handlers behind a simple Python surface so+the API layer can call control_unit('nginx', 'restart') instead of+threading actions and params manually.++list_units returns canonical unit rows in either JSON or plain-parsed+format — the agent flips automatically based on systemd version. The+panel doesn't need to care which.+"""++from typing import Any, Dict, Optional++from app.services.agent_registry import agent_registry+++_VALID_ACTIONS = {'start', 'stop', 'restart', 'enable', 'disable'}+++class RemoteSystemdService:+ """Thin dispatcher to systemd:* on a remote agent."""++ @staticmethod+ def _send(server_id: str, action: str, params: Optional[Dict[str, Any]] = None,+ user_id: Optional[int] = None, timeout: float = 30.0) -> Dict[str, Any]:+ return agent_registry.send_command(+ server_id=server_id,+ action=action,+ params=params or {},+ user_id=user_id,+ timeout=timeout,+ )++ @staticmethod+ def list_units(server_id: str, state: Optional[str] = None, type_: str = 'service',+ user_id: Optional[int] = None) -> Dict[str, Any]:+ params: Dict[str, Any] = {'type': type_}+ if state:+ params['state'] = state+ return RemoteSystemdService._send(+ server_id, 'systemd:list_units', params=params,+ user_id=user_id, timeout=30.0,+ )++ @staticmethod+ def status(server_id: str, unit: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemoteSystemdService._send(+ server_id, 'systemd:status', params={'unit': unit},+ user_id=user_id, timeout=15.0,+ )++ @staticmethod+ def control(server_id: str, unit: str, action: str,+ user_id: Optional[int] = None) -> Dict[str, Any]:+ if action not in _VALID_ACTIONS:+ return {'success': False, 'error': f'invalid action: {action}', 'code': 'INVALID_ACTION'}+ # 2-minute timeout matches the agent's per-action ceiling for+ # cold-starts on heavyweight units (postgresql etc.).+ return RemoteSystemdService._send(+ server_id, f'systemd:{action}', params={'unit': unit},+ user_id=user_id, timeout=130.0,+ )++ @staticmethod+ def daemon_reload(server_id: str, user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemoteSystemdService._send(+ server_id, 'systemd:daemon_reload',+ user_id=user_id, timeout=310.0,+ )++ @staticmethod+ def logs(server_id: str, unit: str, lines: int = 200,+ user_id: Optional[int] = None) -> Dict[str, Any]:+ return RemoteSystemdService._send(+ server_id, 'systemd:logs',+ params={'unit': unit, 'lines': int(lines)},+ user_id=user_id, timeout=30.0,+ )++ @staticmethod+ def logs_follow(server_id: str, unit: str,+ user_id: Optional[int] = None) -> Dict[str, Any]:+ # Returns {job_id, channel}; the panel re-broadcasts on Socket.IO.+ return RemoteSystemdService._send(+ server_id, 'systemd:logs_follow',+ params={'unit': unit},+ user_id=user_id, timeout=10.0,+ )