Skip to content

dyngai/handoffkit / plugins/handoffkit/skills/handoffkit-scaffold

handoffkit-scaffold

Verified

Built by DynG AI for PlatformPilot.ai-style Go agent runtimes. Use when the user wants to scaffold HandoffKit runtime primitives into a Go project: channel-backed mailboxes, select, router, broker, join/quorum barriers, trace, budget, corpus/compactor, supervisor/nursery, dead letters, and sketch interfaces. Trigger words include PlatformPilot scaffold, scaffold handoffkit, add the HandoffKit runtime, set up message-passing agents, or drop in CSP agent primitives.

references/_src/runtime/quorum.go

View on GitHub
package runtime

import (
	"context"
	"strings"

	"github.com/dyngai/handoffkit/sketch"
)

// QuorumAgent is a fan-in that proceeds on the FIRST `need` of `total` expected
// replies rather than waiting for all of them, the opposite end of the spectrum
// from JoinAgent's all-N barrier. It is the shape behind hedged/speculative
// requests and N-of-M voting: fire `total` agents at a problem and act on the
// earliest quorum, treating the stragglers as already-too-late.
//
// Per round it emits combine(first `need` arrivals) exactly ONCE, then drains
// the remaining `total - need` messages without emitting (so slow upstreams do
// not block and the next round starts aligned), and resets. need == 1 is
// first-result-wins (a race); need == total degenerates to a JoinAgent-style
// barrier (but still single-shot per round). Because Run calls Step sequentially
// for one agent, the buffer and counters need no lock.
type QuorumAgent struct {
	addr    sketch.Address
	inbox   sketch.Mailbox
	next    sketch.Address
	need    int
	total   int
	combine func([]sketch.Msg) sketch.Msg
	rounds  map[string]*quorumRound
}

type quorumRound struct {
	buf     []sketch.Msg
	seen    int
	emitted bool
}

// NewQuorumAgent builds a quorum that emits combine(first `need`) to next once
// per round of `total` messages. need is clamped to >= 1; total is clamped to >=
// need (so a round always contains at least the quorum). The emitted message's
// From/To are set to the quorum's address and next; combine controls its payload
// and Ctx. A nil combine joins the quorum payloads with newlines.
func NewQuorumAgent(addr sketch.Address, inbox sketch.Mailbox, next sketch.Address, need, total int, combine func([]sketch.Msg) sketch.Msg) *QuorumAgent {
	if need < 1 {
		need = 1
	}
	if total < need {
		total = need
	}
	if combine == nil {
		combine = func(batch []sketch.Msg) sketch.Msg {
			parts := make([]string, len(batch))
			for i, m := range batch {
				parts[i] = m.Payload
			}
			return sketch.Msg{Payload: strings.Join(parts, "\n")}
		}
	}
	return &QuorumAgent{addr: addr, inbox: inbox, next: next, need: need, total: total, combine: combine}
}

// Address implements sketch.Agent.
func (a *QuorumAgent) Address() sketch.Address { return a.addr }

// Inbox implements sketch.Agent.
func (a *QuorumAgent) Inbox() sketch.Mailbox { return a.inbox }

// Step counts the arrival for in.CorrelationID; emits the combined quorum once
// the `need`-th message of that round has arrived; and forgets the round after
// the `total`-th arrival. Arrivals after the quorum is met are drained
// (counted) for that same correlation id but not emitted, the stragglers a
// quorum deliberately ignores. Messages with an empty CorrelationID share the
// legacy unkeyed stream; overlapping rounds must use distinct correlation ids.
func (a *QuorumAgent) Step(_ context.Context, in sketch.Msg) ([]sketch.Msg, error) {
	if a.rounds == nil {
		a.rounds = make(map[string]*quorumRound)
	}

	key := in.CorrelationID
	round := a.rounds[key]
	if round == nil {
		round = &quorumRound{}
		a.rounds[key] = round
	}
	round.seen++

	var out []sketch.Msg
	if !round.emitted {
		round.buf = append(round.buf, in)
		if len(round.buf) >= a.need {
			// Run combine before clearing the buffer so a panicking user combine
			// does not silently drop the quorum.
			m := a.combine(round.buf)
			round.buf = nil
			round.emitted = true
			m.From = a.addr
			m.To = a.next
			m.CorrelationID = key
			out = []sketch.Msg{m}
		}
	}

	if round.seen >= a.total { // round complete: reset for the next one
		delete(a.rounds, key)
	}
	return out, nil
}

var _ sketch.Agent = (*QuorumAgent)(nil)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall