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

View on GitHub
// Package runtime implements the sketch interfaces with Go concurrency
// primitives: channel-backed mailboxes, reflect.Select-based waits, routed
// dispatch, pub/sub brokers, join and quorum barriers, budgets, supervision,
// dead letters, tracing, and corpus-backed compaction.
//
// It is a small reference runtime, intended to make "Mailbox = Go channel" and
// "Select = Go select" concrete while keeping agent coordination explicit.
package runtime

import (
	"context"
	"errors"
	"sync"

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

// ChanMailbox is the channel-backed Mailbox, the literal "Mailbox = Go channel"
// claim made concrete. Buffer 0 yields an unbuffered rendezvous (Send blocks
// until a Recv is ready, giving backpressure for free); buffer > 0 decouples
// sender and receiver for fan-out worker pools.
type ChanMailbox struct {
	ch        chan sketch.Msg
	closeOnce sync.Once
}

// NewMailbox returns a mailbox with the given buffer (0 = unbuffered rendezvous).
// A negative buffer is clamped to 0 rather than panicking in make().
func NewMailbox(buffer int) *ChanMailbox {
	if buffer < 0 {
		buffer = 0
	}
	return &ChanMailbox{ch: make(chan sketch.Msg, buffer)}
}

// ErrClosed is returned by Send when the mailbox has been closed.
var ErrClosed = errors.New("handoffkit: send on closed mailbox")

// Send delivers msg, blocking per the buffering policy and honoring ctx. If the
// mailbox is closed (now, or concurrently mid-send) it returns ErrClosed rather
// than panicking, so a closed mailbox is a clean error, not a crash.
func (m *ChanMailbox) Send(ctx context.Context, msg sketch.Msg) (err error) {
	if ctx == nil {
		ctx = context.Background()
	}
	if err := ctx.Err(); err != nil {
		return err
	}
	// Only the channel send can panic here (send on closed); the nil-ctx guard
	// above keeps a nil context from panicking and being mislabeled ErrClosed.
	defer func() {
		if recover() != nil {
			err = ErrClosed
		}
	}()
	select {
	case m.ch <- msg:
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

// Recv returns the next message; ok is false once the mailbox is closed/drained.
func (m *ChanMailbox) Recv(ctx context.Context) (sketch.Msg, bool, error) {
	if ctx == nil {
		ctx = context.Background()
	}
	if err := ctx.Err(); err != nil {
		return sketch.Msg{}, false, err
	}
	select {
	case msg, ok := <-m.ch:
		return msg, ok, nil
	case <-ctx.Done():
		return sketch.Msg{}, false, ctx.Err()
	}
}

// Close closes the mailbox. It is idempotent: extra calls are no-ops, so a
// double close cannot panic. Only the sender side should close; receivers see
// ok == false once the mailbox is drained.
func (m *ChanMailbox) Close() error {
	m.closeOnce.Do(func() { close(m.ch) })
	return nil
}

// C exposes the receive channel so the Selector can compose waits over it with
// reflect.Select. This accessor is the seam that makes `select`-style
// composition work across mailboxes.
func (m *ChanMailbox) C() <-chan sketch.Msg { return m.ch }

// Receiver is implemented by mailboxes whose channel the Selector can wait on.
type Receiver interface {
	C() <-chan sketch.Msg
}

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