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/join.go

View on GitHub
package runtime

import (
	"context"
	"strings"

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

// JoinAgent is a fan-in barrier: it buffers inbound messages and emits ONE
// combined message only after `need` have arrived, then resets for the next
// batch. Between arrivals its single-owner Run loop pauses (blocked on the
// inbox): "wait for all my dependencies" expressed as an agent that stays
// silent until its inbox has delivered enough. Because Run calls Step
// sequentially for a given agent, the buffer needs no lock.
type JoinAgent struct {
	addr    sketch.Address
	inbox   sketch.Mailbox
	next    sketch.Address
	need    int
	combine func([]sketch.Msg) sketch.Msg
	rounds  map[string][]sketch.Msg
}

// NewJoinAgent builds a barrier that emits combine(batch) to next after every
// `need` inbound messages (need is clamped to >= 1). The emitted message's
// From/To are set to the join's address and next; combine controls its payload
// (and any Ctx). A nil combine joins the batch payloads with newlines.
func NewJoinAgent(addr sketch.Address, inbox sketch.Mailbox, next sketch.Address, need int, combine func([]sketch.Msg) sketch.Msg) *JoinAgent {
	if need < 1 {
		need = 1
	}
	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 &JoinAgent{addr: addr, inbox: inbox, next: next, need: need, combine: combine}
}

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

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

// Step buffers the inbound message for in.CorrelationID and, once `need` have
// accumulated for that round, emits the combined batch and resets that round.
// Messages with an empty CorrelationID share the legacy unkeyed stream;
// overlapping rounds must use distinct non-empty correlation ids.
func (a *JoinAgent) Step(_ context.Context, in sketch.Msg) ([]sketch.Msg, error) {
	if a.rounds == nil {
		a.rounds = make(map[string][]sketch.Msg)
	}

	key := in.CorrelationID
	batch := append(a.rounds[key], in)
	a.rounds[key] = batch
	if len(batch) < a.need {
		return nil, nil
	}

	// Run combine before clearing the round: if a user-supplied combine panics,
	// the batch is not silently dropped.
	out := a.combine(batch)
	delete(a.rounds, key)
	out.From = a.addr
	out.To = a.next
	out.CorrelationID = key
	return []sketch.Msg{out}, nil
}

var _ sketch.Agent = (*JoinAgent)(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