dyngai/handoffkit / plugins/handoffkit/skills/handoffkit-scaffold
handoffkit-scaffold
VerifiedBuilt 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/supervisor.go
View on GitHubpackage runtime
import (
"context"
"fmt"
"sync"
"github.com/dyngai/handoffkit/sketch"
)
// node is one agent's place in the supervision tree.
type node struct {
parent sketch.Address
depth int
children map[sketch.Address]struct{}
inbox sketch.Mailbox
ctx context.Context
cancel context.CancelFunc
}
// Nursery is a structured-concurrency Supervisor. It owns a tree of agents and
// turns the design's safety levers into running code:
//
// - Spawn enforces a depth/lineage guard. A coordinator sits at depth 0; with
// maxDepth == 1 it may fan out to leaf workers at depth 1 that cannot spawn
// further (a worker spawning would reach depth 2 and is rejected). This is
// the "depth-capped, no lateral delegation" default from primitives.md, made
// mechanical rather than aspirational.
// - Route enforces who-may-message-whom: only parent<->child edges are
// deliverable, so a worker cannot message a sibling (lateral delegation) or
// an arbitrary node across the tree. External seeding (From == "") is allowed
// only into roots, so a driver can inject work without bypassing child
// topology.
// - Cancel unwinds an agent and its whole spawned subtree by cancelling each
// descendant's context (the supervised run loops exit) and dropping them from
// the tree and the delivery table.
//
// A Nursery is the answer to "an unconstrained agent mesh produces spawn cascades
// and unbounded lineage": the topology is a value you can inspect and bound, not
// an emergent property of who happened to call whom. It is safe for concurrent
// use. It implements both sketch.Supervisor and runtime.Dispatcher, so an
// agent's outputs can be delivered through its topology guard by passing the
// Nursery to runtime.Run.
type Nursery struct {
mu sync.Mutex
router *Router
nodes map[sketch.Address]*node
maxDepth int
rootCtx context.Context
}
// NewNursery returns a Nursery whose agents derive their contexts from ctx (a
// nil ctx is treated as context.Background()). maxDepth bounds lineage depth:
// the root is depth 0, so maxDepth == 1 is the canonical coordinator + leaf
// workers shape. A negative maxDepth is clamped to 0 (root-only, no children).
func NewNursery(ctx context.Context, maxDepth int) *Nursery {
if ctx == nil {
ctx = context.Background()
}
if maxDepth < 0 {
maxDepth = 0
}
return &Nursery{
router: NewRouter(),
nodes: make(map[sketch.Address]*node),
maxDepth: maxDepth,
rootCtx: ctx,
}
}
// Spawn registers a under parent, enforcing the depth/lineage guard, and binds
// its inbox in the delivery table. Pass parent == "" to register a root (depth
// 0). It returns an error if parent is unknown, the address is already spawned,
// or the spawn would exceed maxDepth.
func (n *Nursery) Spawn(_ context.Context, parent sketch.Address, a sketch.Agent) (sketch.Address, error) {
if a == nil {
return "", fmt.Errorf("handoffkit: spawn of a nil agent")
}
addr := a.Address()
if addr == "" {
return "", fmt.Errorf("handoffkit: spawn of an agent with an empty address")
}
n.mu.Lock()
defer n.mu.Unlock()
if _, exists := n.nodes[addr]; exists {
return "", fmt.Errorf("handoffkit: address %q already spawned", addr)
}
depth := 0
var pnode *node
if parent != "" {
pnode = n.nodes[parent]
if pnode == nil {
return "", fmt.Errorf("handoffkit: parent %q is not registered", parent)
}
depth = pnode.depth + 1
}
if depth > n.maxDepth {
return "", fmt.Errorf(
"handoffkit: spawn of %q under %q would reach depth %d, exceeding the cap %d (depth/lineage guard)",
addr, parent, depth, n.maxDepth)
}
cctx, cancel := context.WithCancel(n.rootCtx)
inbox := a.Inbox()
n.nodes[addr] = &node{
parent: parent,
depth: depth,
children: make(map[sketch.Address]struct{}),
inbox: inbox,
ctx: cctx,
cancel: cancel,
}
if pnode != nil {
pnode.children[addr] = struct{}{}
}
n.router.Register(addr, inbox)
return addr, nil
}
// Route enforces the topology, then delegates delivery to the inner Router. A
// message is deliverable only if its From/To form a parent<->child edge, or it
// is external seeding (From == "") into a root. It errors on an unknown
// destination, an unknown non-empty sender, or a topology violation (e.g. a
// sibling-to-sibling lateral message).
func (n *Nursery) Route(ctx context.Context, m sketch.Msg) error {
if n == nil {
return fmt.Errorf("handoffkit: route on a nil Nursery")
}
if ctx == nil {
ctx = context.Background()
}
var (
toCtx context.Context
toMailbox sketch.Mailbox
routeErr error
)
n.mu.Lock()
to, toOK := n.nodes[m.To]
if !toOK {
routeErr = fmt.Errorf("handoffkit: no agent registered for destination %q", m.To)
} else {
toCtx = to.ctx
toMailbox = to.inbox
}
var from *node
var fromOK bool
if m.From != "" {
from, fromOK = n.nodes[m.From]
}
switch {
case routeErr != nil:
case m.From == "":
// External seeding: a driver injecting work into a root agent.
if to.parent != "" {
routeErr = fmt.Errorf(
"handoffkit: external seed may target only root agents, not child %q",
m.To)
}
case !fromOK:
routeErr = fmt.Errorf("handoffkit: message from unregistered sender %q", m.From)
case to.parent == m.From || from.parent == m.To:
// Parent -> child, or child -> parent: the only allowed edges.
default:
routeErr = fmt.Errorf(
"handoffkit: topology violation: %q may not message %q (only parent<->child edges are routable)",
m.From, m.To)
}
n.mu.Unlock()
if routeErr != nil {
return routeErr
}
if toMailbox == nil {
return fmt.Errorf("handoffkit: nil mailbox registered for address %q", m.To)
}
if err := toCtx.Err(); err != nil {
return err
}
// Deliver outside the lock: Send may block on an unbuffered/full mailbox.
// Tie delivery to the destination's supervised context so Cancel can wake
// an in-flight send even when the caller passed a non-cancellable context.
routeCtx, cleanup := deliveryContext(ctx, toCtx)
defer cleanup()
if err := toCtx.Err(); err != nil {
return err
}
return toMailbox.Send(routeCtx, m)
}
func deliveryContext(ctx, toCtx context.Context) (context.Context, func()) {
switch {
case ctx.Done() == nil:
return toCtx, func() {}
case toCtx.Done() == nil:
return ctx, func() {}
default:
routeCtx, cancel := context.WithCancel(ctx)
stop := context.AfterFunc(toCtx, cancel)
return routeCtx, func() {
stop()
cancel()
}
}
}
// Context returns the supervised context for addr, derived from the Nursery root
// and cancelled when addr (or an ancestor) is Cancel-ed. Pass it to runtime.Run
// so the run loop participates in subtree cancellation. ok is false for an
// unknown (or already-cancelled) address.
func (n *Nursery) Context(addr sketch.Address) (context.Context, bool) {
n.mu.Lock()
defer n.mu.Unlock()
nd, ok := n.nodes[addr]
if !ok || nd.ctx.Err() != nil {
return nil, false
}
return nd.ctx, true
}
// Depth returns the tree depth of addr (root == 0). ok is false if unknown.
func (n *Nursery) Depth(addr sketch.Address) (int, bool) {
n.mu.Lock()
defer n.mu.Unlock()
nd, ok := n.nodes[addr]
if !ok {
return 0, false
}
return nd.depth, true
}
// Cancel unwinds root and its whole spawned subtree: each descendant's context
// is cancelled (its supervised run loop exits), and the agents are removed from
// the tree and the delivery table. It errors only if root is unknown.
func (n *Nursery) Cancel(_ context.Context, root sketch.Address) error {
n.mu.Lock()
defer n.mu.Unlock()
if _, ok := n.nodes[root]; !ok {
return fmt.Errorf("handoffkit: cancel of unregistered address %q", root)
}
// Detach root from its parent so a parent's child set stays accurate; the
// recursion then drops the subtree wholesale.
if nd := n.nodes[root]; nd.parent != "" {
if p := n.nodes[nd.parent]; p != nil {
delete(p.children, root)
}
}
n.cancelSubtreeLocked(root)
return nil
}
// cancelSubtreeLocked cancels addr and every descendant depth-first. The caller
// holds n.mu.
func (n *Nursery) cancelSubtreeLocked(addr sketch.Address) {
nd, ok := n.nodes[addr]
if !ok {
return
}
for child := range nd.children {
n.cancelSubtreeLocked(child)
}
nd.cancel()
delete(n.nodes, addr)
n.router.Unregister(addr)
}
var (
_ sketch.Supervisor = (*Nursery)(nil)
_ Dispatcher = (*Nursery)(nil)
)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |