From 3f3974c5ea16e19a03f7b3afc6dac2e40909fe9f Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 19 Nov 2026 11:54:53 -0500 Subject: [PATCH] Hear a boost on the agent's line in a Ping A boost on the agent's comment in a served project reaches the agent, but the same boost on its line in a Ping was discarded at the gate as no_route: a Ping is never a served project, and the boosted rule required one. The boosted rule now stays open outside a served project for the connector that hears the agent's Pings. Decide asks the Ping read, as it does for a line, and admits the boost only in a Ping, from an operator or a person let into that Ping, on a line the agent wrote. A boost in an unserved project is still discarded as no_route, and a connector that does not hear Pings still discards it unread. The operator's boost there may answer a declared ask, as it does in a project; it is never the owner's word. --- internal/connector/admission/boost_test.go | 33 ++- internal/connector/admission/doc.go | 7 +- internal/connector/admission/gate.go | 8 +- internal/connector/admission/matrix.go | 11 +- .../connector/admission/ping_boosts_test.go | 195 ++++++++++++++++++ internal/connector/admission/verdict.go | 33 ++- skills/basecamp-connect/subagent.md | 4 +- 7 files changed, 266 insertions(+), 25 deletions(-) create mode 100644 internal/connector/admission/ping_boosts_test.go diff --git a/internal/connector/admission/boost_test.go b/internal/connector/admission/boost_test.go index ac18d1144..69f45c363 100644 --- a/internal/connector/admission/boost_test.go +++ b/internal/connector/admission/boost_test.go @@ -240,17 +240,28 @@ func TestNoAgentWakesAnAgentByBoosting(t *testing.T) { } func TestABoostSettledFromItsPointerCostsNoRead(t *testing.T) { - t.Run("in a project connect.json does not serve", func(t *testing.T) { - f := newFakeReads() - boostOn(f, "Comment", agentID, operatorID) - ev := boostEvent(operatorID) - ev.BucketID = unservedProj - - v := decide(t, newAdmitter(t, basePolicy(), f), ev) - assert.Equal(t, StateDiscarded, v.State, "never blocked: a holding reply to a boost answers nobody") - assert.Equal(t, ReasonNoRoute, v.Reason) - assert.Zero(t, f.totalReads()) - }) + // A connector that hears Pings asks whether the bucket is one, since a + // boost in a Ping is heard (ping_boosts_test.go); nothing past that read. + for name, hears := range map[string]bool{"in a project connect.json does not serve": false, "in a project connect.json does not serve, by a connector that hears Pings": true} { + t.Run(name, func(t *testing.T) { + f := newFakeReads() + boostOn(f, "Comment", agentID, operatorID) + ev := boostEvent(operatorID) + ev.BucketID = unservedProj + p := basePolicy() + p.HearsPings = hears + + v := decide(t, newAdmitter(t, p, f), ev) + assert.Equal(t, StateDiscarded, v.State, "never blocked: a holding reply to a boost answers nobody") + assert.Equal(t, ReasonNoRoute, v.Reason) + if hears { + assert.Equal(t, 1, f.pingCalls) + assert.Equal(t, 1, f.totalReads(), "the Ping read alone") + } else { + assert.Zero(t, f.totalReads()) + } + }) + } t.Run("on one of the recording's events", func(t *testing.T) { f := newFakeReads() diff --git a/internal/connector/admission/doc.go b/internal/connector/admission/doc.go index d397c20a7..57e211d40 100644 --- a/internal/connector/admission/doc.go +++ b/internal/connector/admission/doc.go @@ -13,7 +13,9 @@ // 2. A chat line in a bucket connect.json does not serve is read as a Ping // (Reads.Pings), because where the line was said decides whose word // counts, and that comes before anyone's trust is read. A bucket that -// is no Ping goes on as an unserved project's; its answer is cached. +// is no Ping goes on as an unserved project's; its answer is cached. A +// boost there is read the same way by the connector that hears Pings, +// and is heard only in a Ping. // 3. In project trust mode a performer the policy does not name is confirmed // as a non-client member of the project. That is a read, cached per // project, and it is the one trust decision the pointer alone cannot make. @@ -29,7 +31,8 @@ // completed (trusted completer and a stake: the served project's // watch_completions flag, an assignment, or a subscription), or boosted // (a boost on the recording itself, which the agent wrote, given by the -// trusted performer; a boost on one of a recording's events is not), or, +// trusted performer, in a served project or on the agent's line in a +// Ping; a boost on one of a recording's events is not), or, // in a Ping, pinged (an operator's line in a direct Ping, the agent and // its writer alone; in a group Ping, and from a participant anywhere, // only a mention counts), or campfire (a trusted human's new line in a diff --git a/internal/connector/admission/gate.go b/internal/connector/admission/gate.go index 820ebf726..1e95b3161 100644 --- a/internal/connector/admission/gate.go +++ b/internal/connector/admission/gate.go @@ -20,7 +20,8 @@ type GateResult struct { Agent bool // InPing says the performer is trusted only as a participant of the Ping // the event's bucket is keyed as (Policy.Pings): only once the Ping read - // confirms the bucket is a Ping, and only by mention. + // confirms the bucket is a Ping, and only by mention or by boosting the + // agent's own line there. InPing bool } @@ -99,7 +100,8 @@ func Gate(ev Event, p Policy, m Matrix) GateResult { case role == RoleOperator: // Named in the allowlist; Validate keeps one out of operator mode. case !served && p.pingParticipant(ev.BucketID, performer): - // Let into this one Ping, by mention (matchPing). Before project + // Let into this one Ping, by mention or a boost on the agent's + // line there (matchPing, matchPingBoost). Before project // trust, which would ask a Ping for members it does not have; a // served bucket is a project, whatever a Ping entry is keyed on. inPing = true @@ -109,7 +111,7 @@ func Gate(ev Event, p Policy, m Matrix) GateResult { drop(ReasonUntrustedPerformer) continue } - if rule.RequiresServed && !served { + if rule.RequiresServed && !served && (!rule.HeardInPings || !p.HearsPings) { drop(ReasonNoRoute) continue } diff --git a/internal/connector/admission/matrix.go b/internal/connector/admission/matrix.go index 577c9ae25..aae19e757 100644 --- a/internal/connector/admission/matrix.go +++ b/internal/connector/admission/matrix.go @@ -38,6 +38,11 @@ type Rule struct { // trigger is discarded there, so it is cheaper to discard it before any // read. RequiresServed bool + // HeardInPings keeps a RequiresServed rule open outside a served project + // for a connector that hears the agent's Pings (Policy.HearsPings), so + // that the Ping read can say whether the bucket is a Ping. Decide admits + // it there only in a Ping, and discards it as no_route anywhere else. + HeardInPings bool // Acknowledge says a person asked for something, so the worker's // acknowledgement and the thirty-second guard apply. A completion, a // subscription comment or a boost is not a request. @@ -58,8 +63,10 @@ var ( // is not acknowledged. It requires a served project because nothing in an // unserved one waits on it: blocked(no_route) would post a holding reply // to a thumbs-up. Who may boost is whoever may mention the agent, in - // every trust mode, so it is not OperatorOnly. - ruleBoosted = Rule{Trigger: TriggerBoosted, RequiresServed: true} + // every trust mode, so it is not OperatorOnly. A Ping is never served, + // and the agent's lines there are answered as its comments are in a + // project, so a boost is heard in a Ping too. + ruleBoosted = Rule{Trigger: TriggerBoosted, RequiresServed: true, HeardInPings: true} // Only a line in a Ping admits under pinged, and a Ping is never a served // project, so the rule is not in the matrix: matchPing returns it. rulePinged = Rule{Trigger: TriggerPinged, Acknowledge: true} diff --git a/internal/connector/admission/ping_boosts_test.go b/internal/connector/admission/ping_boosts_test.go new file mode 100644 index 000000000..a6ff5ff7c --- /dev/null +++ b/internal/connector/admission/ping_boosts_test.go @@ -0,0 +1,195 @@ +package admission + +import ( + "testing" + + "github.com/basecamp/basecamp-sdk/go/pkg/basecamp" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// A boost in a Ping: someone boosts a line in a Ping the agent is in. It is +// heard as a boost on the agent's comment is in a project — a reply, from +// whoever may mention the agent there — and only by the connector that hears +// the agent's Pings. + +// boostInPing puts a line author wrote in the Ping whose others are people, +// boosted by booster, and returns the boost's event. +func boostInPing(t *testing.T, f *fakeReads, people []int64, author, booster int64) Event { + t.Helper() + inPing(f, people, author, "
Shall I ship the fix?
") + f.boosts[boostID] = &basecamp.Boost{ + ID: boostID, + Content: "yes, go", + CreatedAt: boostedAt, + Booster: &basecamp.Person{ID: booster, Name: "Booster"}, + Recording: &basecamp.Parent{ID: recordingID, Type: "Chat::Lines::RichText"}, + } + return Event{ + ID: eventID, EventType: "boost.created", BucketID: pingID, RecordingID: recordingID, + CreatorID: booster, Details: boostDetailsJSON(boostID, nil), + } +} + +func TestTheOperatorsBoostOnTheAgentsPingLineIsAdmittedAsAReply(t *testing.T) { + for name, people := range map[string][]int64{ + "a direct Ping": {operatorID}, + "a group Ping": {operatorID, memberID}, + } { + t.Run(name, func(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, people, agentID, operatorID) + + v := decide(t, newAdmitter(t, basePolicy(), f), ev) + + require.Equal(t, StateAdmitted, v.State, "reason %q", v.Reason) + assert.Equal(t, TriggerBoosted, v.Trigger) + assert.False(t, v.Acknowledge, "a boost is a reply, not a request") + assert.Equal(t, RoleOperator, v.Role) + assert.Equal(t, operatorID, v.RequesterID) + assert.Equal(t, &ReplyDestination{Kind: ReplyChatLine, RecordingID: pingCampfire}, v.Reply) + assert.Equal(t, PingConversationKey(pingID), v.ConversationKey) + assert.True(t, IsPingConversation(v.ConversationKey, pingID), "handed off as a Ping's") + assert.False(t, v.Served) + require.NotNil(t, v.Snapshot) + assert.Equal(t, "yes, go", v.Snapshot.Content, "the boost is the content") + assert.False(t, v.Snapshot.Owner, "a boost is never the owner's word on the connector") + assert.Empty(t, v.Snapshot.ProjectName) + // As in a project: the operator's boost names the line as the ask + // it would answer, and the ledger decides whether one was declared. + assert.Equal(t, recordingID, v.AskRecordingID) + assert.Equal(t, "Chat::Lines::RichText", f.summaryRefs[0].RecordingType) + }) + } +} + +func TestAPersonAllowedInOnePingMayBoostTheAgentsLineThere(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID, pingGuest}, agentID, pingGuest) + + v := decide(t, newAdmitter(t, guestPolicy(basePolicy()), f), ev) + + require.Equal(t, StateAdmitted, v.State, "reason %q", v.Reason) + assert.Equal(t, TriggerBoosted, v.Trigger) + assert.Equal(t, RoleParticipant, v.Role) + assert.Equal(t, pingGuest, v.RequesterID) + assert.Zero(t, v.AskRecordingID, "only the operator's boost may be a go") + assert.False(t, v.Snapshot.Owner) +} + +func TestABoostInAPingIsTrustedLikeAMentionThere(t *testing.T) { + t.Run("someone the policy does not name is discarded unread", func(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID, strangerID}, agentID, strangerID) + + v := decide(t, newAdmitter(t, basePolicy(), f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonUntrustedPerformer, v.Reason) + assert.Zero(t, f.totalReads()) + }) + + t.Run("a person let into another Ping is nobody in this one", func(t *testing.T) { + f := newFakeReads() + p := basePolicy() + p.Pings = map[int64]PingTrust{otherPing: {Participants: []int64{pingGuest}}} + ev := boostInPing(t, f, []int64{operatorID, pingGuest}, agentID, pingGuest) + + v := decide(t, newAdmitter(t, p, f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonUntrustedPerformer, v.Reason) + assert.Zero(t, f.boostCalls) + assert.Zero(t, f.summaryCalls) + }) + + t.Run("in project trust a member is nobody in a Ping", func(t *testing.T) { + f := newFakeReads() + f.members[pingID] = map[int64]bool{memberID: true} + ev := boostInPing(t, f, []int64{operatorID, memberID}, agentID, memberID) + + v := decide(t, newAdmitter(t, projectPolicy(), f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonUntrustedPerformer, v.Reason) + assert.Zero(t, f.memberCalls, "a Ping has no members to ask about") + assert.Zero(t, f.boostCalls) + }) + + t.Run("a boost whose booster is not the performer", func(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID, strangerID}, agentID, strangerID) + ev.CreatorID = operatorID + + v := decide(t, newAdmitter(t, basePolicy(), f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonUntrustedAuthor, v.Reason) + }) + + t.Run("no agent wakes the agent by boosting in a Ping", func(t *testing.T) { + for name, c := range map[string]struct { + policy Policy + ev func(Event) Event + want Reason + }{ + "the agent itself": {basePolicy(), func(ev Event) Event { ev.CreatorID = agentID; return ev }, ReasonAgentAuthored}, + "an allowed agent": {agentPolicy(), func(ev Event) Event { ev.CreatorID = peerAgent; return ev }, ReasonNoRoute}, + "a person's boost an agent performed": {basePolicy(), func(ev Event) Event { + ev.PerformedByID = ptr(otherAgent) + return ev + }, ReasonDelegated}, + } { + t.Run(name, func(t *testing.T) { + f := newFakeReads() + ev := c.ev(boostInPing(t, f, []int64{operatorID}, agentID, operatorID)) + + v := decide(t, newAdmitter(t, c.policy, f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, c.want, v.Reason) + assert.Zero(t, f.totalReads()) + }) + } + }) +} + +func TestABoostOnSomeoneElsesPingLineIsNotTheAgents(t *testing.T) { + for name, author := range map[string]int64{ + "the operator's own line": operatorID, + "someone else's line": memberID, + "another agent's line": otherAgent, + } { + t.Run(name, func(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID, memberID}, author, operatorID) + + v := decide(t, newAdmitter(t, basePolicy(), f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonNotAddressed, v.Reason) + assert.Nil(t, v.Snapshot) + assert.Zero(t, v.AskRecordingID) + }) + } +} + +// Only the connector that hears the agent's Pings hears a boost in one, so +// one boost is answered once. Any other discards it at the gate, unread. +func TestAConnectorThatDoesNotHearPingsDiscardsABoostInOne(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID}, agentID, operatorID) + p := basePolicy() + p.HearsPings = false + + v := decide(t, newAdmitter(t, p, f), ev) + assert.Equal(t, StateDiscarded, v.State) + assert.Equal(t, ReasonNoRoute, v.Reason) + assert.Zero(t, f.totalReads()) +} + +func TestABoostInAPingWithConnectJSONUnreadableIsHeld(t *testing.T) { + f := newFakeReads() + ev := boostInPing(t, f, []int64{operatorID}, agentID, operatorID) + p := basePolicy() + p.ProjectsUnknown = true + + v := decide(t, newAdmitter(t, p, f), ev) + assert.Equal(t, StateBlocked, v.State) + assert.Equal(t, ReasonConfigUnreadable, v.Reason) + assert.Zero(t, f.totalReads()) +} diff --git a/internal/connector/admission/verdict.go b/internal/connector/admission/verdict.go index 0579b9ac6..2e8b3b0e1 100644 --- a/internal/connector/admission/verdict.go +++ b/internal/connector/admission/verdict.go @@ -368,8 +368,11 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error // Where the line was said decides whose word counts, so it is settled // before anyone's trust is read: a Ping has no members to ask about. + // A boost outside a served project passed the gate only to be asked + // about here (Rule.HeardInPings): it is heard in a Ping alone. + _, served := policy.served(ev.BucketID) var ping *basecamp.Ping - if _, served := policy.served(ev.BucketID); !served && ev.EventType == eventChatLineCreated { + if !served && (ev.EventType == eventChatLineCreated || boostID > 0) { var reason Reason if ping, reason, err = d.pingOf(ctx, ev.BucketID); err != nil { return Verdict{}, err @@ -390,6 +393,11 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error return v.end(StateDiscarded, ReasonUntrustedPerformer), nil } } + if boostID > 0 && !served && ping == nil { + // A project connect.json does not serve. Never blocked: a holding + // reply to a boost answers nobody. + return v.end(StateDiscarded, ReasonNoRoute), nil + } if gate.InPing && ping == nil { // Trusted only in a Ping, and the bucket is none the agent is in. return v.end(StateDiscarded, ReasonUntrustedPerformer), nil @@ -470,10 +478,15 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error state State reason Reason ) - if ping != nil { + switch { + case ping != nil && boost != nil: + rule, state, reason = a.matchPingBoost(summary, shape) + case ping != nil: rule, author, state, reason = a.matchPing(summary, ping, gate.Role) - } else if rule, author, state, reason, err = d.match(ctx, ev, policy, gate, summary); err != nil { - return Verdict{}, err + default: + if rule, author, state, reason, err = d.match(ctx, ev, policy, gate, summary); err != nil { + return Verdict{}, err + } } if state != "" { return v.end(state, reason), nil @@ -706,6 +719,18 @@ func (a *Admitter) matchPing(summary *basecamp.RecordingSummary, ping *basecamp. return Rule{}, "", StateDiscarded, ReasonNotAddressed } +// matchPingBoost decides what a boost in a Ping is to the agent. The booster +// was an operator at the gate, or a participant connect.json lets into this +// Ping, and wrote the boost (readBoost): it is a reply when the boosted line +// is the agent's own, as a boost on the agent's comment is in a project. +// A boost on anyone else's line in a Ping says nothing to the agent. +func (a *Admitter) matchPingBoost(summary *basecamp.RecordingSummary, shape shape) (Rule, State, Reason) { + if shape == shapeChatLine && summary.Creator.ID == a.policy.AgentID { + return ruleBoosted, "", "" + } + return Rule{}, StateDiscarded, ReasonNotAddressed +} + // direct reports whether the Ping is the agent and the writer alone. People // are the others in it as the agent sees it. Basecamp carries no group flag, // so a group that has shrunk to the two of them reads as direct, which it now diff --git a/skills/basecamp-connect/subagent.md b/skills/basecamp-connect/subagent.md index faf9a1326..3832393e4 100644 --- a/skills/basecamp-connect/subagent.md +++ b/skills/basecamp-connect/subagent.md @@ -57,9 +57,7 @@ A Ping has no project and no AGENTS.md: skip the AGENTS.md paragraph below, and the repo the handoff names, or none. A group Ping's other people read the reply too. Its `role` is `operator`, or `participant` for a person the operator let into this one Ping: *A participant asks, an operator authorizes* -applies, with two differences. The operator's go there is only their -@mention of the agent saying go: a boost in a Ping never reaches the agent, -so don't say a boost is a go. And when the operator isn't among the Ping's +applies, with one difference: when the operator isn't among the Ping's people (`basecamp pings show --json -P ''`), they can't see the ask: say in the Ping that this needs the operator's word, and stop there.