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

View on GitHub
package runtime

import (
	"context"
	"errors"
	"fmt"
	"sync"

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

// Broker is point-to-MANY: Publish fans each message out to every subscriber's
// mailbox, so each subscriber is woken for every event. It is the
// broadcast counterpart to Router (point-to-point: one address → one mailbox).
//
//	Router, handoff / dispatch: a message goes to exactly ONE recipient.
//	Broker, pub/sub awareness:  a message goes to EVERY subscriber.
//
// Publish is synchronous fan-out with per-subscriber backpressure: a slow
// subscriber blocks the publisher. Buffer subscriber mailboxes to decouple.
//
// Broadcast is the blackboard creeping back in, reach for it only where
// agents genuinely need ambient awareness, not for ordinary coordination.
//
// A Broker holds a mutex; do not copy it after first use.
type Broker struct {
	mu   sync.RWMutex
	subs []sketch.Mailbox
}

// NewBroker returns an empty broker.
func NewBroker() *Broker { return &Broker{} }

// Subscribe registers a mailbox to receive every published message. A nil
// mailbox is ignored: it could never receive anything and would panic Publish.
func (b *Broker) Subscribe(mb sketch.Mailbox) {
	if mb == nil {
		return
	}
	b.mu.Lock()
	defer b.mu.Unlock()
	b.subs = append(b.subs, mb)
}

// Publish delivers the message to every subscriber, in subscription order,
// honoring ctx. A failing subscriber does not stop delivery to the others (true
// fan-out over errors). Delivery is sequential, though, so a blocking subscriber
// (full mailbox, no receiver) stalls the rest until ctx; see the backpressure
// note above and buffer subscriber mailboxes to decouple. It returns the joined
// error (each tagged with the subscriber index), or nil if all succeed or there
// are none.
//
// It operates on a snapshot of the subscribers taken at entry, so a subscriber
// added concurrently may or may not receive this message.
//
// Each subscriber receives independent message state: the Msg struct is copied
// by value, and mutable Ctx slice fields have distinct backing storage.
func (b *Broker) Publish(ctx context.Context, msg sketch.Msg) error {
	b.mu.RLock()
	subs := make([]sketch.Mailbox, len(b.subs))
	copy(subs, b.subs)
	b.mu.RUnlock()

	var errs []error
	for i, mb := range subs {
		if err := mb.Send(ctx, cloneBrokerMsg(msg)); err != nil {
			errs = append(errs, fmt.Errorf("subscriber %d: %w", i, err))
		}
	}
	return errors.Join(errs...)
}

func cloneBrokerMsg(msg sketch.Msg) sketch.Msg {
	msg.Ctx.Thread = cloneBrokerThread(msg.Ctx.Thread)
	msg.Ctx.Refs = cloneBrokerRefs(msg.Ctx.Refs)
	return msg
}

func cloneBrokerThread(thread []sketch.Turn) []sketch.Turn {
	if thread == nil {
		return nil
	}
	cloned := make([]sketch.Turn, len(thread))
	copy(cloned, thread)
	return cloned
}

func cloneBrokerRefs(refs []sketch.MemoryRef) []sketch.MemoryRef {
	if refs == nil {
		return nil
	}
	cloned := make([]sketch.MemoryRef, len(refs))
	copy(cloned, refs)
	return cloned
}
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