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

View on GitHub
package runtime

import (
	"context"
	"fmt"
	"reflect"
	"time"

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

type stdSelector struct{}

// NewSelector returns a Selector that composes waits with reflect.Select, the
// agent analogue of Go's `select`. ctx cancellation is added as an implicit
// final case. Mailbox cases must use a sketch.Mailbox that also implements
// runtime.Receiver, such as ChanMailbox; this lets the selector wait on the
// mailbox's underlying receive channel without polling Recv. A context with a
// nil Done() (e.g. context.Background()) provides no cancellation, so to
// guarantee a Select cannot block forever, pass a cancellable context OR include
// an After/Done case. runtime.Run rejects non-positive idle durations and
// supplies an idle After, so its loop is safe. See tradeoffs.md §4.
func NewSelector() sketch.Selector { return stdSelector{} }

func (stdSelector) Run(ctx context.Context, sel sketch.Select) (int, error) {
	if ctx == nil {
		ctx = context.Background()
	}
	// Prioritize cancellation: if ctx is already cancelled, return rather than
	// run a ready case.
	if err := ctx.Err(); err != nil {
		return -1, err
	}
	const (
		kindMailbox = iota
		kindDone
		kindAfter
		kindCtx
	)
	// meta snapshots each case's handler at build time so dispatch after the
	// blocking select does not re-read sel.Cases. The build loop below still reads
	// sel.Cases synchronously before blocking, so a Select must not be mutated
	// concurrently with Run, as with any shared value.
	type meta struct {
		orig    int
		kind    int
		onRecv  func(sketch.Msg) error
		onDone  func() error
		onAfter func() error
	}

	rcases := make([]reflect.SelectCase, 0, len(sel.Cases)+1)
	metas := make([]meta, 0, len(sel.Cases)+1)

	// Stop any timers on return so a losing After case doesn't leak a timer until
	// it fires; this matters in hot loops like runtime.Run that re-Select often.
	var timers []*time.Timer
	defer func() {
		for _, t := range timers {
			t.Stop()
		}
	}()

	for i, c := range sel.Cases {
		// A Case must set at most one effective wait source. An After of zero or
		// less is treated as unset.
		waitSources := 0
		if c.Mailbox != nil {
			waitSources++
		}
		if c.Done != nil {
			waitSources++
		}
		if c.After > 0 {
			waitSources++
		}
		if waitSources > 1 {
			return -1, fmt.Errorf("handoffkit: case %d sets multiple wait sources; set exactly one of Mailbox, Done, or After", i)
		}

		switch {
		case c.Mailbox != nil:
			rv, ok := c.Mailbox.(Receiver)
			if !ok {
				return -1, fmt.Errorf("handoffkit: mailbox in case %d is not a runtime.Receiver", i)
			}
			rcases = append(rcases, reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(rv.C())})
			metas = append(metas, meta{orig: i, kind: kindMailbox, onRecv: c.OnRecv})
		case c.Done != nil:
			rcases = append(rcases, reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(c.Done)})
			metas = append(metas, meta{orig: i, kind: kindDone, onDone: c.OnDone})
		case c.After > 0:
			tm := time.NewTimer(c.After)
			timers = append(timers, tm)
			rcases = append(rcases, reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(tm.C)})
			metas = append(metas, meta{orig: i, kind: kindAfter, onAfter: c.OnAfter})
		}
	}

	// Implicit cancellation case. An unbounded wait is a budget leak, not a hang.
	if done := ctx.Done(); done != nil {
		rcases = append(rcases, reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(done)})
		metas = append(metas, meta{orig: -1, kind: kindCtx})
	}
	if len(rcases) == 0 {
		return -1, fmt.Errorf("handoffkit: select has no live cases and context has no Done channel")
	}

	chosen, recv, recvOK := reflect.Select(rcases)
	m := metas[chosen]
	switch m.kind {
	case kindCtx:
		return -1, ctx.Err()
	case kindMailbox:
		if !recvOK {
			// The mailbox channel is closed: deliver no message rather than a
			// phantom zero-value receive. The case still "fires" (we return its
			// index) but OnRecv does not run, so callers like runtime.Run see no
			// message and can treat it as "inbox closed".
			return m.orig, nil
		}
		if m.onRecv != nil {
			msg, _ := recv.Interface().(sketch.Msg)
			return m.orig, m.onRecv(msg)
		}
	case kindDone:
		if m.onDone != nil {
			return m.orig, m.onDone()
		}
	case kindAfter:
		if m.onAfter != nil {
			return m.orig, m.onAfter()
		}
	}
	return m.orig, 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