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_test.go

View on GitHub
package runtime

import (
	"context"
	"errors"
	"strings"
	"testing"
	"time"

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

// A waiting mailbox message wins over a not-yet-elapsed timeout, and OnRecv
// receives the exact message.
func TestSelector_MailboxFires(t *testing.T) {
	mb := NewMailbox(1)
	if err := mb.Send(context.Background(), sketch.Msg{Payload: "hi"}); err != nil {
		t.Fatalf("seed Send: %v", err)
	}

	var got sketch.Msg
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(m sketch.Msg) error { got = m; return nil }},
		{After: time.Second, OnAfter: func() error { return errors.New("timeout should not fire") }},
	}})
	if err != nil {
		t.Fatalf("Run: %v", err)
	}
	if idx != 0 {
		t.Fatalf("chosen case = %d, want 0", idx)
	}
	if got.Payload != "hi" {
		t.Fatalf("OnRecv payload = %q, want %q", got.Payload, "hi")
	}
}

// With no message waiting, the After case fires and OnAfter runs.
func TestSelector_AfterFires(t *testing.T) {
	mb := NewMailbox(1) // empty

	fired := false
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(sketch.Msg) error { return errors.New("mailbox should not fire") }},
		{After: 20 * time.Millisecond, OnAfter: func() error { fired = true; return nil }},
	}})
	if err != nil {
		t.Fatalf("Run: %v", err)
	}
	if idx != 1 {
		t.Fatalf("chosen case = %d, want 1", idx)
	}
	if !fired {
		t.Fatal("OnAfter was not invoked")
	}
}

// A cancelled context selects the implicit final case: Run returns -1 and the
// context error, so no Select can block forever (tradeoffs.md §4).
func TestSelector_ContextCancelWins(t *testing.T) {
	mb := NewMailbox(1) // empty, would otherwise block
	ctx, cancel := context.WithCancel(context.Background())
	cancel()

	idx, err := NewSelector().Run(ctx, sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(sketch.Msg) error { return nil }},
	}})
	if !errors.Is(err, context.Canceled) {
		t.Fatalf("err = %v, want context.Canceled", err)
	}
	if idx != -1 {
		t.Fatalf("chosen case = %d, want -1 on cancellation", idx)
	}
}

func TestSelector_RejectsMultipleWaitSources(t *testing.T) {
	mb := NewMailbox(1)
	if err := mb.Send(context.Background(), sketch.Msg{Payload: "hi"}); err != nil {
		t.Fatalf("seed Send: %v", err)
	}
	done := make(chan struct{})
	close(done)

	var fired bool
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{
			Mailbox: mb,
			OnRecv:  func(sketch.Msg) error { fired = true; return nil },
			Done:    done,
			OnDone:  func() error { fired = true; return nil },
			After:   time.Second,
			OnAfter: func() error { fired = true; return nil },
		},
	}})
	if err == nil {
		t.Fatal("expected an error for a case with multiple wait sources")
	}
	if !strings.Contains(err.Error(), "multiple wait sources") {
		t.Fatalf("err = %v, want multiple wait sources", err)
	}
	if idx != -1 {
		t.Fatalf("chosen case = %d, want -1 on error", idx)
	}
	if fired {
		t.Fatal("handler fired for an invalid case")
	}
}

func TestSelector_NoLiveCasesWithNilContextDoneErrors(t *testing.T) {
	done := make(chan error, 1)
	go func() {
		_, err := NewSelector().Run(context.Background(), sketch.Select{})
		done <- err
	}()

	select {
	case err := <-done:
		if err == nil {
			t.Fatal("expected an error for a select with no live cases")
		}
		if !strings.Contains(err.Error(), "no live cases") {
			t.Fatalf("err = %v, want no live cases", err)
		}
	case <-time.After(200 * time.Millisecond):
		t.Fatal("Run blocked with no live cases and a context whose Done channel is nil")
	}
}

// A ready Done channel fires its OnDone handler.
func TestSelector_DoneFires(t *testing.T) {
	done := make(chan struct{})
	close(done)

	fired := false
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Done: done, OnDone: func() error { fired = true; return nil }},
	}})
	if err != nil {
		t.Fatalf("Run: %v", err)
	}
	if idx != 0 || !fired {
		t.Fatalf("Done case did not fire: idx=%d fired=%v", idx, fired)
	}
}

// An error returned by a case handler propagates out of Run.
func TestSelector_HandlerErrorPropagates(t *testing.T) {
	mb := NewMailbox(1)
	if err := mb.Send(context.Background(), sketch.Msg{Payload: "x"}); err != nil {
		t.Fatalf("seed Send: %v", err)
	}

	boom := errors.New("boom")
	_, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(sketch.Msg) error { return boom }},
	}})
	if !errors.Is(err, boom) {
		t.Fatalf("err = %v, want boom", err)
	}
}

// nonReceiverMailbox satisfies sketch.Mailbox but NOT runtime.Receiver, so the
// Selector cannot wait on it and must report a clear error.
type nonReceiverMailbox struct{}

func (nonReceiverMailbox) Send(context.Context, sketch.Msg) error { return nil }
func (nonReceiverMailbox) Recv(context.Context) (sketch.Msg, bool, error) {
	return sketch.Msg{}, false, nil
}
func (nonReceiverMailbox) Close() error { return nil }

func TestSelector_NonReceiverMailboxErrors(t *testing.T) {
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Mailbox: nonReceiverMailbox{}, OnRecv: func(sketch.Msg) error { return nil }},
	}})
	if err == nil {
		t.Fatal("expected an error for a non-Receiver mailbox")
	}
	if !strings.Contains(err.Error(), "runtime.Receiver") {
		t.Fatalf("err = %v, want runtime.Receiver requirement", err)
	}
	if idx != -1 {
		t.Fatalf("chosen case = %d, want -1 on error", idx)
	}
}

// A closed mailbox must NOT fire OnRecv with a phantom zero-value message: the
// case fires (its index is returned) but no message is delivered, so a caller
// like runtime.Run sees "no message" and can treat it as inbox-closed.
func TestSelector_ClosedMailboxNoPhantomReceive(t *testing.T) {
	mb := NewMailbox(1)
	if err := mb.Close(); err != nil {
		t.Fatalf("Close: %v", err)
	}

	fired := false
	idx, err := NewSelector().Run(context.Background(), sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(sketch.Msg) error { fired = true; return nil }},
	}})
	if err != nil {
		t.Fatalf("Run: %v", err)
	}
	if fired {
		t.Fatal("OnRecv fired on a closed mailbox (phantom zero-value receive)")
	}
	if idx != 0 {
		t.Fatalf("chosen case = %d, want 0 (the closed mailbox case)", idx)
	}
}

// A nil context is treated as context.Background() instead of panicking.
func TestSelector_NilContext(t *testing.T) {
	mb := NewMailbox(1)
	if err := mb.Send(context.Background(), sketch.Msg{Payload: "x"}); err != nil {
		t.Fatalf("seed: %v", err)
	}

	var got string
	_, err := NewSelector().Run(nil, sketch.Select{Cases: []sketch.Case{
		{Mailbox: mb, OnRecv: func(m sketch.Msg) error { got = m.Payload; return nil }},
	}})
	if err != nil {
		t.Fatalf("Run(nil ctx): %v", err)
	}
	if got != "x" {
		t.Fatalf("got %q, want x", got)
	}
}
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