feat(nest): @-addressing, addressed-crow-must-respond, deliver back to requester (#11)

nestapi.go

@@ -15,6 +15,22 @@ var crowPostable = map[string]bool{
 	"claim":   true,
 	"deliver": true,
 	"refer":   true,
+	"decline": true,
+}
+
+// nestReplySystem tells an addressed crow the response contract: its reply
+// must open with a KIND line the harness reads (must-respond).
+const markerNestReply = "This is a chatroom request."
+const nestReplySystem = crowSystem + `
+` + markerNestReply + ` Start your reply on its own first line with exactly:
+KIND: claim   (you will do it)
+KIND: deliver (here is the result)
+KIND: decline (with a reason)
+Then, on the next line, your message text.`
+
+// nestMembers lists who may be addressed in a nest: its crows plus the owner.
+func nestMembers(nest Nest) []string {
+	return append(append([]string{}, nest.Crows...), "owner")
 }
 
 func (s *Server) getNestMessages(w http.ResponseWriter, r *http.Request) {
@@ -61,6 +77,9 @@ func (s *Server) postNestMessage(w http.ResponseWriter, r *http.Request) {
 
 	body.Text = strings.TrimSpace(body.Text)
 	body.To = strings.TrimSpace(body.To)
+	if body.To == "" {
+		body.To = parseAddressing(body.Text, nestMembers(nest))
+	}
 
 	// Guardrails (EVENTS.md: Nest messages → Guardrails)
 	if n := utf8.RuneCountInString(body.Text); n < 1 || n > s.p.G.MaxItemChars {
@@ -88,6 +107,14 @@ func (s *Server) postNestMessage(w http.ResponseWriter, r *http.Request) {
 	// Tagging (A1, EVENTS.md): Jev first, header fallback, say as last resort.
 	kind, taggedBy := s.tagKind(body.Kind, body.Text)
 
+	// claim/deliver/decline answer a request: with no explicit address they go
+	// back to whoever posted the message they refer to (EVENTS.md deliver rule).
+	if body.To == "" && (kind == "claim" || kind == "deliver" || kind == "decline") && body.RefersTo != "" {
+		if origin, found := s.msgs.ByMsgID(body.RefersTo); found {
+			body.To = origin.Author
+		}
+	}
+
 	msg := Message{
 		NestID:    nestID,
 		Kind:      kind,
@@ -106,9 +133,10 @@ func (s *Server) postNestMessage(w http.ResponseWriter, r *http.Request) {
 
 	s.emitNestMessage(record)
 
-	// Event-driven trigger: if kind is request and To is a crow, respond.
-	if kind == "request" && record.To != "" && record.To != "owner" {
-		go s.crowResponds(nest, record)
+	// Event-driven trigger: a request addressed to a member crow gets one
+	// response (must-respond) or a Sentry flag.
+	if kind == "request" && slices.Contains(nest.Crows, record.To) {
+		go s.respondToRequest(nest, record)
 	}
 
 	writeJSON(w, http.StatusCreated, map[string]any{
@@ -153,32 +181,68 @@ func (s *Server) emitNestMessage(m Message) {
 	})
 }
 
-func (s *Server) crowResponds(nest Nest, req Message) {
-	crows := s.p.Flock.pick(nest, 1)
-	if len(crows) == 0 {
-		return
-	}
-	crow := crows[0] // B4 (@-addressing) makes this the addressed crow
-	system := systemFor(crow, crowSystem, true)
-	prompt := "NEST: " + nest.Name + "\nREQUEST FROM: " + req.Author + "\nTEXT: " + req.Text
+// respondToRequest is the must-respond rule: the addressed crow answers with
+// claim, deliver or decline. A reply that isn't one of those is retried once
+// with a stricter ask; still nothing responsive and the crow gets a flag from
+// the Sentry (no crow reply is posted).
+func (s *Server) respondToRequest(nest Nest, req Message) {
+	crow := req.To
 	budget := &Budget{name: "nest-message", limit: s.p.G.TokenBudgetPerItem}
-	answer, err := s.p.Flock.ask(s.ctx, nil, crow, system, prompt, budget)
-	if err != nil {
+	system := systemFor(crow, nestReplySystem, false)
+	prompt := "NEST: " + nest.Name + "\nREQUEST FROM: " + req.Author + "\nTASK: " + req.Text + "\nRespond to " + req.Author + "."
+
+	kind, body, ok := s.nestReply(system, prompt, crow, budget)
+	if !ok {
+		nudge := prompt + "\nYour last reply did not claim, deliver or decline this request. Answer with a KIND line now."
+		kind, body, ok = s.nestReply(system, nudge, crow, budget)
+	}
+	if !ok {
+		s.postFlag(nest, crow, req)
 		return
 	}
 	reply := Message{
 		NestID:    nest.ID,
-		Kind:      "say",
+		Kind:      kind,
 		Author:    crow,
-		Text:      strings.TrimSpace(answer),
-		To:        req.Author,
+		Text:      body,
+		To:        req.Author, // responses go back to whoever requested
+		RefersTo:  req.MsgID(),
+		TaggedBy:  "header",
+		Timestamp: time.Now().UTC().Format(time.RFC3339),
+	}
+	if record, err := s.msgs.Append(reply); err == nil {
+		s.emitNestMessage(record)
+	}
+}
+
+// nestReply asks one crow once and reads its KIND header. ok means the reply
+// was responsive (claim, deliver or decline).
+func (s *Server) nestReply(system, prompt, crow string, budget *Budget) (kind, body string, ok bool) {
+	answer, err := s.p.Flock.ask(s.ctx, nil, crow, system, prompt, budget)
+	if err != nil {
+		return "", "", false
+	}
+	kind, body = splitKind(answer)
+	if !responsiveKind[kind] || strings.TrimSpace(body) == "" {
+		return "", "", false
+	}
+	return kind, strings.TrimSpace(body), true
+}
+
+// postFlag records the Sentry's breach note: an addressed crow that would not
+// answer. The quarantine/ask_owner loop lands with the watchdog epic.
+func (s *Server) postFlag(nest Nest, crow string, req Message) {
+	flag := Message{
+		NestID:    nest.ID,
+		Kind:      "flag",
+		Author:    "Sentry",
+		Text:      fmt.Sprintf("%s ignored a request from %s and did not answer after one retry. Flagged for contract breach.", crow, req.Author),
+		To:        crow,
 		RefersTo:  req.MsgID(),
 		TaggedBy:  "harness",
 		Timestamp: time.Now().UTC().Format(time.RFC3339),
 	}
-	record, err := s.msgs.Append(reply)
-	if err != nil {
-		return
+	if record, err := s.msgs.Append(flag); err == nil {
+		s.emitNestMessage(record)
 	}
-	s.emitNestMessage(record)
 }