Repository Public
1package actions23import (4 "regexp"5 "strings"6)78const (9 Low = "low"10 Medium = "medium"11 High = "high"12 Critical = "critical"13)1415// Lock scopes: at most one non-terminal action holds the lock of a target.16const (17 LockNode = "node"18 LockService = "service"19 LockJob = "job"20 LockNone = "none"21)2223// Type is one entry of the catalog (docs/DESIGN-BRIEF.md §4).24type Type struct {25 Name string26 Title string27 Description string28 Criticality string29 TargetKinds []string // node | service | job | inference_server30 Params Spec31 TimeoutS int // maximum execution time on the agent32 LockScope string33 // ServerSide types are executed by the orchestrator itself: no agent command is ever issued.34 ServerSide bool35 // Internal types are created by the platform only (job.run is created by POST /jobs).36 Internal bool37 // MaintenanceRelated types are allowed on a node in maintenance mode.38 MaintenanceRelated bool39 ExtraPermissions []string40 Available bool41 UnavailableReason string42}4344// Permission required to request the type: actions.run.<criticality>.45func (t Type) Permission() string { return "actions.run." + t.Criticality }4647// Flags derived from the criticality, exactly as the design brief states:48// high and critical need a step-up; critical also needs a justification, the49// confirmation (target alias typed by the user, compared server-side) and the50// approval of a second person.51func (t Type) RequiresStepUp() bool { return t.Criticality == High || t.Criticality == Critical }52func (t Type) RequiresJustification() bool { return t.Criticality == Critical }53func (t Type) RequiresConfirmation() bool { return t.Criticality == Critical }54func (t Type) RequiresApproval() bool { return t.Criticality == Critical }5556// Capability is what the agent must declare in agents.capabilities for the57// type to be dispatched. Job templates are declared as "job.run:<template>".58func (t Type) Capability(params map[string]any) string {59 if t.Name == "job.run" {60 tpl, _ := params["template"].(string)61 return JobCapability(tpl)62 }63 return t.Name64}6566const jobCapPrefix = "job.run:"6768// JobCapability is the capability string of a job template.69func JobCapability(template string) string { return jobCapPrefix + template }7071// TemplateOf extracts the template name from a capability string.72func TemplateOf(capability string) (string, bool) {73 t, ok := strings.CutPrefix(capability, jobCapPrefix)74 return t, ok && TemplateName.MatchString(t)75}7677var (78 logicalName = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)79 // TemplateName is the shape of a job template name.80 TemplateName = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)81 modelName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$`)82)8384var none = Spec{Props: map[string]Prop{}}8586// Catalog lists every action type, in display order.87var Catalog = []Type{88 {Name: "inventory.refresh", Title: "Refresh inventory", Description: "Asks the agent for an immediate hardware and software inventory.",89 Criticality: Low, TargetKinds: []string{"node"}, Params: none, TimeoutS: 60, LockScope: LockNode, Available: true},90 {Name: "diagnostic.run", Title: "Run diagnostic", Description: "Bounded, read-only diagnostic collection.",91 Criticality: Low, TargetKinds: []string{"node"}, TimeoutS: 120, LockScope: LockNode, Available: true,92 Params: Spec{Props: map[string]Prop{"profile": {Type: "string", Enum: []string{"basic", "network", "disk"}, Description: "Diagnostic profile."}}, Required: []string{"profile"}}},93 {Name: "service.health_check", Title: "Check service health", Description: "Runs the health probe of a managed service.",94 Criticality: Low, TargetKinds: []string{"service"}, Params: none, TimeoutS: 30, LockScope: LockService, Available: true},95 {Name: "service.logs.tail", Title: "Tail service logs", Description: "Bounded, redacted read of the last log lines of a managed service (at most 500 lines and 256 KiB).",96 Criticality: Low, TargetKinds: []string{"service"}, TimeoutS: 30, LockScope: LockNone, Available: true, ExtraPermissions: []string{"logs.read"},97 Params: Spec{Props: map[string]Prop{"lines": {Type: "integer", Min: i64(1), Max: i64(500), Description: "Number of lines (default 200)."}}}},98 {Name: "service.restart", Title: "Restart service", Description: "Restarts a managed service through its manager.",99 Criticality: Medium, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},100 {Name: "service.start", Title: "Start service", Description: "Starts a managed service through its manager.",101 Criticality: Medium, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},102 {Name: "service.stop", Title: "Stop service", Description: "Stops a managed service through its manager.",103 Criticality: High, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},104 {Name: "agent.restart", Title: "Restart agent", Description: "Restarts the agent process on the node.",105 Criticality: Medium, TargetKinds: []string{"node"}, Params: none, TimeoutS: 60, LockScope: LockNode, Available: true},106 {Name: "cache.purge", Title: "Purge cache", Description: "Purges one logical cache from the agent's allowlist (a name, never a path).",107 Criticality: Medium, TargetKinds: []string{"node"}, TimeoutS: 300, LockScope: LockNode, Available: true,108 Params: Spec{Props: map[string]Prop{"cache": {Type: "string", Pattern: logicalName, MaxLen: 64, Description: "Logical cache name."}}, Required: []string{"cache"}}},109 {Name: "node.maintenance.set", Title: "Set maintenance mode", Description: "Turns the maintenance mode of a node on or off. Executed by the server; no command is sent to the agent.",110 Criticality: Medium, TargetKinds: []string{"node"}, TimeoutS: 30, LockScope: LockNode, Available: true, ServerSide: true, MaintenanceRelated: true,111 Params: Spec{Props: map[string]Prop{"enabled": {Type: "boolean", Description: "Target state."},112 "reason": {Type: "string", MaxLen: 500, Description: "Why (shown on the node)."}}, Required: []string{"enabled"}}},113 {Name: "job.run", Title: "Run job", Description: "One run of a job template declared by the agent. Created by POST /jobs only.",114 Criticality: Medium, TargetKinds: []string{"job"}, TimeoutS: 3600, LockScope: LockJob, Available: true, Internal: true,115 Params: Spec{Props: map[string]Prop{"template": {Type: "string", Pattern: TemplateName, MaxLen: 64},116 "params": {Type: "object", MaxBytes: 16 << 10, Description: "Template parameters, validated by the agent."}}, Required: []string{"template"}}},117 {Name: "job.cancel", Title: "Cancel job", Description: "Cancels a job. Executed by the server: a queued job is cancelled at once, a running one is asked to stop cooperatively through its job.run command.",118 Criticality: Medium, TargetKinds: []string{"job"}, Params: none, TimeoutS: 30, LockScope: LockNone, Available: true, ServerSide: true, MaintenanceRelated: true},119 {Name: "model.server.start", Title: "Start model server", Description: "Starts an inference server through the agent's adapter.",120 Criticality: High, TargetKinds: []string{"node"}, TimeoutS: 600, LockScope: LockNode, Available: true,121 Params: Spec{Props: map[string]Prop{"model": {Type: "string", Pattern: modelName, MaxLen: 128, Description: "Model name from the agent's allowlist."},122 "port": {Type: "integer", Min: i64(1024), Max: i64(65535)},123 "mem_bytes": {Type: "integer", Min: i64(1), Max: i64(1 << 42), Description: "Estimated memory need; when given it is checked against the memory currently free on the node."}},124 Required: []string{"model"}}},125 {Name: "model.server.stop", Title: "Stop model server", Description: "Stops an inference server through the agent's adapter.",126 Criticality: High, TargetKinds: []string{"inference_server"}, Params: none, TimeoutS: 120, LockScope: LockNode, Available: true},127 {Name: "deploy.release", Title: "Deploy release", Description: "Deploys an approved version of a service.",128 Criticality: High, TargetKinds: []string{"service"}, Params: none, TimeoutS: 900, LockScope: LockService, Available: false,129 UnavailableReason: "Not enabled in this version."},130 {Name: "system.update.schedule", Title: "Schedule system update", Description: "Schedules an operating system update.",131 Criticality: High, TargetKinds: []string{"node"}, Params: none, TimeoutS: 300, LockScope: LockNode, Available: false,132 UnavailableReason: "Not enabled in this version."},133 {Name: "system.reboot", Title: "Reboot node", Description: "Reboots the node. Disabled locally on agents by default.",134 Criticality: Critical, TargetKinds: []string{"node"}, Params: none, TimeoutS: 600, LockScope: LockNode, Available: true},135 {Name: "system.shutdown", Title: "Shut down node", Description: "Shuts the node down. Disabled locally on agents by default.",136 Criticality: Critical, TargetKinds: []string{"node"}, Params: none, TimeoutS: 600, LockScope: LockNode, Available: true},137}138139var byName = func() map[string]Type {140 m := make(map[string]Type, len(Catalog))141 for _, t := range Catalog {142 m[t.Name] = t143 }144 return m145}()146147// Lookup returns a catalogued type.148func Lookup(name string) (Type, bool) { t, ok := byName[name]; return t, ok }149