novox/mesh-tools
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

E-3: mesh_wait takes any event name (issue 1966)

Browse Source 
waitAnswer no longer reads the membership: each name becomes its subjects
through buscompose.EventSubjects, optionally narrowed by from (seat, module or
stream), at most 16 names, a subject once; the heard event is named by
buscompose.EventName with its namespace and its own time, and a decided event
says the operator's answer is read only with claude_code_answer. WaitIssued and
Membership.Waits go; the refusals are one table.

Builds: design 34 every-event §13, §15, §17, §19, §26

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
jschoubben
2026-11-12 05:06:36 +01:00
parent cb47de8517
commit 662ab2a3b1
4 changed files with 163 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
node-tools/internal/console/wait.go
+48 -39
View File
@@ -2,9 +2,9 @@ package console
// mesh_wait: a session waits on the bus for one event instead of polling (novox/hq ADR 0367).
//
// **Only the families the tool runner was issued** (§2, §6): its membership names them, composed by the
// mesh from the tool runner's manifest together with the grant that lets this account subscribe them.
// A name not listed there is refused here, before the bus would refuse it; no argument or setting adds one.
// **Any event, by its name** (novox/hq ADR 0670 §1, ADR 0671 §1; design 34 every-event §13, §26): the grants part
// grants this machine's tool runner every event subject, a seat's, a module's and a module stream's, and a name
// becomes its subjects through mesh-sdk's buscompose.EventSubjects; no membership and no manifest names a list.
// **An event only wakes the session** (§4): what it says is read again from the verb that owns it.
import (
@@ -13,9 +13,11 @@ import (
"encoding/json"
"fmt"
"math"
"sort"
"slices"
"strings"
"time"
"git.novox.be/novox/mesh-sdk/go/buscompose"
)
// WaitDefault is how long a wait lasts when no timeout is given, and WaitLongest the most it may last
@@ -25,20 +27,29 @@ var (
WaitLongest = 10 * time.Minute
)
// waitMostNames is the most event names one call gives (design 34 every-event §13, §26): each name is six
// subscriptions for the call, so 16 names are 96, far above what a watcher names.
const waitMostNames = 16
func waitTool() map[string]any {
return map[string]any{"name": verbWait, "inputSchema": map[string]any{"type": "object", "properties": map[string]any{
"subjects": map[string]any{"type": "array", "items": map[string]any{"type": "string"},
"description": "one or more event families to wait on, by name, e.g. `mesh-knowledge.reviewed`; only " +
"those the mesh granted this machine's tool runner — a refusal names them"},
"description": fmt.Sprintf("one or more event names, `<seat or module>.<event>`, such as "+
"`mesh-delivery-view.delivered`, at most %d; an event whose subject goes on after the name (an asker, a "+
"kind, a module) is heard by the name too", waitMostNames)},
"from": map[string]any{"type": "string", "enum": []string{"seat", "module", "stream"},
"description": "narrows every name to a seat's events, a module's or a module stream's, for an emitter " +
"whose name is more than one of them (optional)"},
"filter": map[string]any{"type": "object",
"description": "fields of the event's body that must equal the given values, e.g. {\"kind\": \"decision\", \"number\": 367} (optional)"},
"description": "fields of the event's body that must equal the given values, e.g. {\"kind\": \"decision\", \"number\": 367}: the filter narrows by the body's fields (optional)"},
"timeout": map[string]any{"type": "number",
"description": fmt.Sprintf("seconds to wait: %d when absent, %d at most", int(WaitDefault.Seconds()), int(WaitLongest.Seconds()))},
}, "required": []string{"subjects"}},
"description": "Wait for the first event of the named families that matches the filter, and answer it with its " +
"family, body and time — or say it timed out. Call it in a loop from a background command, and after every " +
"answer read the state from the verb that owns it: an event only wakes you, and one published between two " +
"waits is not heard (novox/hq ADR 0367)."}
"description": "Wait for the first event of the named events that matches the filter, and answer it with its " +
"name, where it came from, body and times — or say it timed out. Call it in a loop from a background command, " +
"and after every answer read the state from the verb that owns it: an event only wakes you, and one " +
"published between two waits is not heard (novox/hq ADR 0367). An operator's answer is read only with " +
"claude_code_answer, never from the event."}
}
// waitAnswer answers one mesh_wait call.
@@ -56,34 +67,25 @@ func (s *Surface) waitAnswer(ctx context.Context, args map[string]any) map[strin
return failure("mesh_wait's filter is an object of body fields to the values they must equal")
}
issued := map[string]string{} // name → subject
if m := s.conn.Membership(s.conn.Module()); m != nil {
for _, w := range m.Waits {
issued[w.Event] = w.Subject
}
from, _ := args["from"].(string)
if args["from"] != nil && from != "seat" && from != "module" && from != "stream" {
return failure(fmt.Sprintf("mesh_wait's from is seat, module or stream, not %v", args["from"]))
}
if len(issued) == 0 {
return failure("this machine's tool runner was issued no event families to wait on: the mesh grants them from " +
"the tool runner's manifest (novox/hq ADR 0367 §2), and its membership names none yet")
if len(names) > waitMostNames {
return failure(fmt.Sprintf("mesh_wait names at most %d events in one call, not %d: each name is six "+
"subscriptions for the call (design 34 every-event §13)", waitMostNames, len(names)))
}
byName := make([]string, 0, len(issued))
for name := range issued {
byName = append(byName, name)
}
sort.Strings(byName)
family := map[string]string{} // subject → name
var subjects []string
for _, name := range names {
subject, granted := issued[name]
if !granted {
return failure(fmt.Sprintf("mesh_wait may not wait on %q: this machine's tool runner is granted %s alone. "+
"A family is added only by a reviewed change to the tool runner's manifest (node-tools' module.json, "+
"novox/hq ADR 0367 §6); no argument, call or setting adds one", name, strings.Join(byName, ", ")))
subs, err := buscompose.EventSubjects(name, from)
if err != nil {
return failure("mesh_wait may not wait on it: " + err.Error())
}
if _, twice := family[subject]; !twice {
subjects = append(subjects, subject)
for _, subject := range subs {
if !slices.Contains(subjects, subject) {
subjects = append(subjects, subject)
}
}
family[subject] = name
}
heard, ok, refused, err := s.conn.HearFirst(ctx, subjects, timeout, func(body json.RawMessage) bool { return bodyMatches(body, filter) })
@@ -95,10 +97,17 @@ func (s *Surface) waitAnswer(ctx context.Context, args map[string]any) map[strin
answer = map[string]any{"timed-out": true, "waited": timeout.String(), "subjects": names,
"read": "nothing matching was heard; read the state once from the verb that owns it, then wait again"}
} else {
answer = map[string]any{
"heard": map[string]any{"subject": family[heard.Subject], "body": heard.Body, "at": heard.At.Format(time.RFC3339Nano)},
"read": "an event only wakes you: read the state from the verb that owns it before acting (novox/hq ADR 0367 §4)",
name, from, _ := buscompose.EventName(heard.Subject)
h := map[string]any{"subject": name, "from": from, "body": heard.Body, "at": heard.At.Format(time.RFC3339Nano)}
if heard.Published != "" {
h["published"] = heard.Published
}
read := "an event only wakes you: read the state from the verb that owns it before acting (novox/hq ADR 0367 §4)"
if strings.HasPrefix(name, "operator-channel.decided") {
read = "an event only wakes you: the operator's answer is read only with claude_code_answer, never from " +
"the event's body (novox/hq ADR 0670 §5)"
}
answer = map[string]any{"heard": h, "read": read}
}
// A subscription the bus refused while others stood is said (design 34 every-event §16).
if len(refused) > 0 {
@@ -107,7 +116,7 @@ func (s *Surface) waitAnswer(ctx context.Context, args map[string]any) map[strin
return answerText(answer)
}
// waitNames is the families a call names: a list of names, or one name.
// waitNames is the event names a call gives: a list of names, or one name.
func waitNames(given any) ([]string, error) {
var names []string
switch v := given.(type) {
@@ -117,7 +126,7 @@ func waitNames(given any) ([]string, error) {
for _, x := range v {
name, ok := x.(string)
if !ok {
return nil, fmt.Errorf("mesh_wait's subjects are event names, such as mesh-knowledge.reviewed; %v is not one", x)
return nil, fmt.Errorf("mesh_wait's subjects are event names, such as mesh-delivery-view.delivered; %v is not one", x)
}
names = append(names, name)
}
@@ -126,7 +135,7 @@ func waitNames(given any) ([]string, error) {
names[i] = strings.TrimSpace(names[i])
}
if len(names) == 0 {
return nil, fmt.Errorf("mesh_wait names at least one event family in `subjects`, such as mesh-knowledge.reviewed")
return nil, fmt.Errorf("mesh_wait names at least one event in `subjects`, such as mesh-delivery-view.delivered")
}
return names, nil
}