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

View on GitHub
package runtime

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

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

// Router maps addresses to mailboxes and delivers point-to-point. It does not
// enforce a topology ("who may message whom"); that is the Supervisor's job. A
// production Supervisor would layer topology and depth/lineage guards on top
// (see docs/primitives.md).
type Router struct {
	mu    sync.RWMutex
	boxes map[sketch.Address]sketch.Mailbox
}

// NewRouter returns an empty router.
func NewRouter() *Router {
	return &Router{boxes: make(map[sketch.Address]sketch.Mailbox)}
}

// Register binds an address to a mailbox.
func (r *Router) Register(addr sketch.Address, mb sketch.Mailbox) {
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.boxes == nil { // tolerate a zero-value Router built without NewRouter
		r.boxes = make(map[sketch.Address]sketch.Mailbox)
	}
	r.boxes[addr] = mb
}

// Unregister removes an address binding. It is a no-op if the address is
// unknown, so a Nursery can drop a cancelled agent's mailbox idempotently.
func (r *Router) Unregister(addr sketch.Address) {
	r.mu.Lock()
	defer r.mu.Unlock()
	delete(r.boxes, addr)
}

// Dispatcher delivers a message to its destination, transferring ownership.
// *Router is the bare point-to-point delivery; *Nursery wraps it with a
// who-may-message-whom topology guard. runtime.Run takes a Dispatcher so an
// agent's outputs can be delivered through either.
type Dispatcher interface {
	Route(ctx context.Context, m sketch.Msg) error
}

// Route delivers m to its destination mailbox, transferring ownership.
func (r *Router) Route(ctx context.Context, m sketch.Msg) error {
	if r == nil {
		return fmt.Errorf("handoffkit: route on a nil Router")
	}
	r.mu.RLock()
	mb, ok := r.boxes[m.To]
	r.mu.RUnlock()
	if !ok {
		return fmt.Errorf("handoffkit: no mailbox registered for address %q", m.To)
	}
	if mb == nil {
		return fmt.Errorf("handoffkit: nil mailbox registered for address %q", m.To)
	}
	return mb.Send(ctx, m)
}

// errIdle ends an agent's run loop after an idle period with no inbound work.
var errIdle = errors.New("handoffkit: idle")

// errInvalidIdle rejects Run loops that would otherwise omit the idle timeout
// and wait forever when called with a non-cancellable context.
var errInvalidIdle = errors.New("handoffkit: idle duration must be positive")

// tryRecv does a non-blocking receive from a mailbox via its Receiver channel.
// ok is false if nothing is ready, the mailbox is closed, or it exposes no
// channel.
func tryRecv(mb sketch.Mailbox) (sketch.Msg, bool) {
	r, ok := mb.(Receiver)
	if !ok {
		return sketch.Msg{}, false
	}
	select {
	case msg, recvOK := <-r.C():
		if !recvOK {
			return sketch.Msg{}, false // closed
		}
		return msg, true
	default:
		return sketch.Msg{}, false
	}
}

// Run drives one agent's single-owner loop: it waits on the inbox (or ctx
// cancellation / idle timeout) via a Selector, Steps on each inbound message,
// and routes the outputs to their destinations. It returns nil on idle or
// cancellation, or the first error a Step/Route produces. idle must be positive;
// zero or negative durations are rejected because Select treats them as no
// timeout case.
func Run(ctx context.Context, a sketch.Agent, r Dispatcher, idle time.Duration) error {
	return RunTraced(ctx, a, r, idle, nil)
}

// RunTraced is Run with an optional Tracer invoked on every message the agent
// receives (TraceRecv) and emits (TraceSend), a complete record of what the
// agent saw and communicated. A nil tracer is the zero-overhead Run path.
func RunTraced(ctx context.Context, a sketch.Agent, r Dispatcher, idle time.Duration, trace Tracer) error {
	if idle <= 0 {
		return fmt.Errorf("%w: %s", errInvalidIdle, idle)
	}
	sel := NewSelector()
	for {
		var got sketch.Msg
		var have bool
		_, err := sel.Run(ctx, sketch.Select{Cases: []sketch.Case{
			{Mailbox: a.Inbox(), OnRecv: func(m sketch.Msg) error { got, have = m, true; return nil }},
			{After: idle, OnAfter: func() error { return errIdle }},
		}})
		switch {
		case errors.Is(err, errIdle):
			// The idle timer and a freshly-arrived message can both be ready in
			// the same Select; if the timer was chosen, drain one ready message
			// before exiting so it is not orphaned in the inbox.
			if msg, ok := tryRecv(a.Inbox()); ok {
				got, have = msg, true
			} else {
				return nil
			}
		case errors.Is(err, context.Canceled),
			errors.Is(err, context.DeadlineExceeded):
			return nil
		case err != nil:
			return err
		}
		if !have {
			return nil
		}
		if trace != nil {
			trace(TraceEvent{Agent: a.Address(), Dir: TraceRecv, Msg: cloneTraceMsg(got)})
		}
		outs, err := a.Step(ctx, got)
		if err != nil {
			if isContextShutdown(err) {
				return nil
			}
			return err
		}
		for _, o := range outs {
			routed := o
			routed.From = a.Address()
			if trace != nil {
				// TraceSend records what the agent emitted; delivery (Route below)
				// is a separate step that may still fail.
				trace(TraceEvent{Agent: a.Address(), Dir: TraceSend, Msg: cloneTraceMsg(routed)})
			}
			if routed.To == "" {
				continue // terminal output; nothing to route
			}
			if err := r.Route(ctx, routed); err != nil {
				if isContextShutdown(err) {
					return nil
				}
				return err
			}
		}
	}
}

func isContextShutdown(err error) bool {
	return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
}
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