G1: tools runner_start, runner_run, runner_accept, runner_ask_again over the runner's seat verbs

Each tool asks its served verb with the same arguments and answers its answer; the verb records the hand act, as for runner_rerun. Declared in the manifest.
The seat has no verb release: no tool for it.
Lead answer A-486 (G-22-lead-answers-2.md): tools are how a module is spoken to.

Builds: design 47 G §83, §84, A-486
This commit is contained in:
2026-11-18 02:22:54 +01:00
parent 09be0bc27f
commit 59ca36e55b
6 changed files with 150 additions and 1 deletions
@@ -152,6 +152,7 @@ func main() {
tools = append(tools, UnloggedTools(stdio.State(seat.StatePipelines), stdio.Log(seat.StateStepLog), meshhandactsclient.Recorder{Ask: stdio.Ask},
func(f string, a ...any) { fmt.Fprintf(os.Stderr, "[mesh-delivery-pipeline-tools] "+f+"\n", a...) })...)
tools = append(tools, CancelTool(r.List, stdio.Ask), RerunTool(stdio.Ask))
tools = append(tools, VerbTools(stdio.Ask)...)
tools = append(tools, TestRunsTools(stdio.Ask)...)
tools = append(tools, HealthTool(r.Pipelines, kept{stdio.State(pipeline.StateConsumers)}, time.Now))
if err := stdio.Serve("", tools); err != nil {
@@ -32,13 +32,16 @@ func TestTools(t *testing.T) {
names = append(names, tl.Name)
}
names = append(names, CancelTool(nil, nil).Name, RerunTool(nil).Name)
for _, tl := range VerbTools(nil) {
names = append(names, tl.Name)
}
// RN25 (§468, §76; A-164): the health check is the bundle's runner_health.
names = append(names, HealthTool(none{}, none{}, nil).Name)
// §606, §549: the unlogged entries are listed and appended by hand.
for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) {
names = append(names, tl.Name)
}
want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_health runner_unlogged runner_unlogged_append"
want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_ask_again runner_health runner_unlogged runner_unlogged_append"
if got := strings.Join(names, " "); got != want {
t.Errorf("tools %q, want %q", got, want)
}
@@ -0,0 +1,81 @@
package main
import (
"encoding/json"
"errors"
"strings"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// VerbTools are runner_start, runner_run, runner_accept and runner_ask_again: the runner's seat verbs start, run, accept and
// ask-again, reachable as tools (design 47 G §83, §482), as runner_rerun reaches rerun. Each asks its verb over the bus with
// the arguments it was given and answers the verb's answer; the verb records the hand act and refuses what it refuses.
func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.Tool {
str := map[string]any{"type": "string"}
obj := func(required []string, props map[string]any) map[string]any {
return map[string]any{"type": "object", "properties": props, "required": required}
}
return []stdio.Tool{
verbTool[seat.StartInput](ask, "start", seat.VerbStart,
"Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it.",
obj([]string{"branch", "module", "why"}, map[string]any{"branch": str, "module": str, "why": str}),
func(in seat.StartInput) string {
if in.Branch == "" || in.Module == "" {
return "start names the watched branch and the module"
}
return whyOf(in.Why)
}),
verbTool[seat.RunInput](ask, "run", seat.VerbRun,
"Start a run on request by the seat verb run: the members (module, branch, commit as the seat's Member) and optionally why.",
obj([]string{"members"}, map[string]any{"members": map[string]any{"type": "array", "items": map[string]any{"type": "object"}}, "why": str}),
func(in seat.RunInput) string {
if len(in.Members) == 0 {
return "run names its members"
}
return ""
}),
verbTool[seat.AcceptInput](ask, "accept", seat.VerbAccept,
"Accept one step of a pipeline by hand by the seat verb accept: the pipeline's key, the step, the artifact where the step is per artifact, and why.",
obj([]string{"pipeline", "step", "why"}, map[string]any{"pipeline": str, "step": str, "artifact": str, "why": str}),
func(in seat.AcceptInput) string {
if in.Pipeline == "" || in.Step == "" {
return "accept names the pipeline and the step"
}
return whyOf(in.Why)
}),
verbTool[seat.AskAgainInput](ask, "ask_again", seat.VerbAskAgain,
"Ask a declined approval step of a pipeline once more by the seat verb ask-again: the pipeline's key and why.",
obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "why": str}),
func(in seat.AskAgainInput) string {
if in.Pipeline == "" {
return "ask-again names the pipeline"
}
return whyOf(in.Why)
}),
}
}
func whyOf(why string) string {
if strings.TrimSpace(why) == "" {
return "a hand act names why"
}
return ""
}
// verbTool is one tool over one seat verb: it decodes the arguments into the verb's input, refuses what the check refuses
// before asking, and answers the verb's answer.
func verbTool[T any](ask func(string, any) (json.RawMessage, error), name, verb, description string, input map[string]any, check func(T) string) stdio.Tool {
return stdio.Tool{Name: Prefix + "_" + name, Description: description, Input: input,
Run: func(args map[string]any) (any, error) {
in, err := as[T](args)
if err != nil {
return nil, err
}
if msg := check(in); msg != "" {
return nil, errors.New(msg)
}
return ask("seat:"+seat.Seat+"."+verb, in)
}}
}
@@ -0,0 +1,59 @@
package main
import (
"encoding/json"
"strings"
"testing"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
)
// Each tool asks its seat verb with the arguments it was given and refuses, before asking, a call the verb would refuse.
func TestVerbTools(t *testing.T) {
for _, c := range []struct {
name, tool, key, refusal string
args map[string]any
body any
}{
{"start", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "module": "i3", "why": "cancelled"},
seat.StartInput{Branch: "main", Module: "i3", Why: "cancelled"}},
{"start no why", "runner_start", "", "names why", map[string]any{"branch": "main", "module": "i3"}, nil},
{"start no module", "runner_start", "", "branch and the module", map[string]any{"branch": "main", "why": "x"}, nil},
{"run", "runner_run", "seat:mesh-pipeline-runner.run", "", map[string]any{"members": []any{map[string]any{}}, "why": "x"},
seat.RunInput{Members: []seat.Member{{}}, Why: "x"}},
{"run no members", "runner_run", "", "members", map[string]any{}, nil},
{"accept", "runner_accept", "seat:mesh-pipeline-runner.accept", "", map[string]any{"pipeline": "p", "step": "lint", "artifact": "a", "why": "x"},
seat.AcceptInput{Pipeline: "p", Step: "lint", Artifact: "a", Why: "x"}},
{"accept no step", "runner_accept", "", "pipeline and the step", map[string]any{"pipeline": "p", "why": "x"}, nil},
{"ask-again", "runner_ask_again", "seat:mesh-pipeline-runner.ask-again", "", map[string]any{"pipeline": "p", "why": "x"},
seat.AskAgainInput{Pipeline: "p", Why: "x"}},
{"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil},
} {
t.Run(c.name, func(t *testing.T) {
var key string
var body any
ask := func(k string, b any) (json.RawMessage, error) {
key, body = k, b
return json.RawMessage(`{"ok":1}`), nil
}
var run func(map[string]any) (any, error)
for _, tl := range VerbTools(ask) {
if tl.Name == c.tool {
run = tl.Run
}
}
out, err := run(c.args)
if c.refusal != "" {
if err == nil || !strings.Contains(err.Error(), c.refusal) || key != "" {
t.Fatalf("want refusal %q and no ask, got %v (asked %q)", c.refusal, err, key)
}
return
}
want, _ := json.Marshal(c.body)
got, _ := json.Marshal(body)
if err != nil || key != c.key || string(got) != string(want) || out == nil {
t.Fatalf("asked %q with %s, want %s, err %v", key, got, want, err)
}
})
}
}
@@ -114,6 +114,7 @@ func TestManifest(t *testing.T) {
{"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})},
// RN25 (§539): the runner's tools carry the prefix runner_.
{"first-view tools", equalSets(m.Tools, []string{"runner_first_views", "runner_first_view_again", "runner_health", "runner_unlogged", "runner_unlogged_append",
"runner_start", "runner_run", "runner_accept", "runner_ask_again",
"runner_test_runs", "runner_test_runs_drop"})},
// A-305 (ADR 0227 rule 8, ADR 0240 rule 2): the process is judged by its unit, as every process of mesh-delivery,
// never by a tool of its own; runner_health stays a tool.
@@ -30,6 +30,10 @@
"runner_health",
"runner_unlogged",
"runner_unlogged_append",
"runner_start",
"runner_run",
"runner_accept",
"runner_ask_again",
"runner_test_runs",
"runner_test_runs_drop"
],