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

View on GitHub
package runtime

import (
	"context"
	"fmt"
	"sort"
	"sync"

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

// MergeFunc reconciles a delta into the value stored for a key. existing is the
// current value and ok reports whether the key was already present.
//
// For concurrent Merges to be conflict-free it must behave as an ASSOCIATIVE,
// COMMUTATIVE, and IDEMPOTENT join over logical values: applying deltas in any
// grouping or arrival order, and replaying a delta, must converge to the same
// result. This is the contract that lets the Corpus be shared state without a
// per-agent lock dance (sketch/handoffkit.go: Corpus).
type MergeFunc func(existing any, ok bool, delta any) (merged any, err error)

// LastWriteWins replaces the stored value with the delta. It is order-dependent
// (NOT associative, commutative, and idempotent), so it is correct only for a
// key with a single writer (for example a per-handoff artifact key minted by
// one agent). Do not use it for a key multiple agents Merge concurrently; use a
// policy such as UnionStrings there.
func LastWriteWins(_ any, _ bool, delta any) (any, error) { return delta, nil }

// UnionStrings merges grow-only string sets (a G-Set): the result is the union
// of the existing set and the delta, sorted for a stable Get. It accepts a
// string or a []string on either side. It is associative, commutative, and
// idempotent, so concurrent Merges of the same key are conflict-free regardless
// of order, the canonical "shared knowledge, reconciled without locks" case.
func UnionStrings(existing any, ok bool, delta any) (any, error) {
	set := make(map[string]struct{})
	add := func(v any) error {
		switch t := v.(type) {
		case nil:
		case string:
			set[t] = struct{}{}
		case []string:
			for _, s := range t {
				set[s] = struct{}{}
			}
		default:
			return fmt.Errorf("handoffkit: UnionStrings needs string or []string, got %T", v)
		}
		return nil
	}
	if ok {
		if err := add(existing); err != nil {
			return nil, err
		}
	}
	if err := add(delta); err != nil {
		return nil, err
	}
	out := make([]string, 0, len(set))
	for s := range set {
		out = append(out, s)
	}
	sort.Strings(out)
	return out, nil
}

// MemCorpus is an in-memory sketch.Corpus: a namespaced key/value store whose
// writes are reconciled by a MergeFunc. It is the repo's one deliberate use of
// shared state, the blackboard the design keeps for knowledge (knowledge stays
// put and is referenced, not channelled as prose). It is intentionally local and
// small: enough to make MemoryRef resolve and to make merge policy explicit and
// testable.
type MemCorpus struct {
	mu    sync.RWMutex
	merge MergeFunc
	data  map[sketch.MemoryRef]any
}

// NewCorpus returns a MemCorpus using merge to reconcile writes. A nil merge
// defaults to LastWriteWins (single-writer keys).
func NewCorpus(merge MergeFunc) *MemCorpus {
	if merge == nil {
		merge = LastWriteWins
	}
	return &MemCorpus{merge: merge, data: make(map[sketch.MemoryRef]any)}
}

// cloneCorpusValue copies known mutable values before they cross the Corpus
// boundary. Unknown values keep their normal interface semantics.
func cloneCorpusValue(v any) any {
	switch t := v.(type) {
	case []byte:
		return append([]byte(nil), t...)
	case []string:
		return append([]string(nil), t...)
	case []sketch.Turn:
		return append([]sketch.Turn(nil), t...)
	case []sketch.MemoryRef:
		return append([]sketch.MemoryRef(nil), t...)
	case sketch.HandoffContext:
		t.Thread = append([]sketch.Turn(nil), t.Thread...)
		t.Refs = append([]sketch.MemoryRef(nil), t.Refs...)
		return t
	default:
		return v
	}
}

// Get returns the value stored at ref. ok is false if the ref was never written.
func (c *MemCorpus) Get(ctx context.Context, ref sketch.MemoryRef) (any, bool, error) {
	if ctx == nil {
		ctx = context.Background()
	}
	if err := ctx.Err(); err != nil {
		return nil, false, err
	}
	c.mu.RLock()
	defer c.mu.RUnlock()
	v, ok := c.data[ref]
	if !ok {
		return nil, false, nil
	}
	return cloneCorpusValue(v), true, nil
}

// Merge reconciles delta into ref via the corpus MergeFunc. Concurrent Merges
// are serialized under the lock; the conflict-free property comes from the
// MergeFunc being associative, commutative, and idempotent, not from the lock
// (the lock only guards the map).
func (c *MemCorpus) Merge(ctx context.Context, ref sketch.MemoryRef, delta any) error {
	if ctx == nil {
		ctx = context.Background()
	}
	if err := ctx.Err(); err != nil {
		return err
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	existing, ok := c.data[ref]
	merged, err := c.merge(cloneCorpusValue(existing), ok, cloneCorpusValue(delta))
	if err != nil {
		return err
	}
	c.data[ref] = cloneCorpusValue(merged)
	return nil
}

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