spawn

Documentation

Overview

Package spawn is the operator-granted budget for agent-initiated EPHEMERAL sub-agents — the governance layer that makes agent spawning a gated capability rather than a free-for-all (the differentiator vs free programmatic spawn).

This package is the DATA LAYER only (slice 1): the persisted per-island grant + its budget. Default posture is deny — an island with no grant cannot spawn at all (the spawn route isn't reachable by an in-island token). An operator adds a grant with explicit limits; the spawn handler (a later slice) enforces them and ledgers each spawn. Granting is OPERATOR-ONLY — an in-island token can never create or modify a grant (only spawn within one).

Index

• type Grant
• type Store
  • func Load() (*Store, error)
  • func Update(fn func(*Store) error) (*Store, error)
  • func (s *Store) Consume(island string)
  • func (s *Store) Get(island string) (Grant, bool)
  • func (s *Store) List() []Grant
  • func (s *Store) Remove(island string) bool
  • func (s *Store) Set(g Grant) error

Types

type Grant

type Grant struct {
	Island string `json:"island"`
	// MaxConcurrent caps live ephemeral sub-agents at once (the primary safety
	// limit). Must be > 0 for a grant to permit any spawning.
	MaxConcurrent int `json:"max_concurrent"`
	// MaxTotal caps lifetime spawns for this grant; 0 = unlimited within the grant.
	MaxTotal int `json:"max_total,omitempty"`
	// Types restricts which agent types may be spawned; empty = any spawnable type.
	Types []string `json:"types,omitempty"`
	// TTL is each sub-agent's max lifetime before it's reaped; 0 = no time cap
	// (still reaped on exit / parent removal / revoke).
	TTL time.Duration `json:"ttl,omitempty"`
	// PerAgentMemory / PerAgentCPUs cap EACH sub-agent's resources, so a granted
	// orchestrator can't spawn N workers that collectively OOM the host (see the
	// resource-vs-cap signals). Docker-style strings, e.g. "512m" / "1.0". Empty =
	// inherit the daemon/island default.
	PerAgentMemory string `json:"per_agent_memory,omitempty"`
	PerAgentCPUs   string `json:"per_agent_cpus,omitempty"`

	// Used is the LIFETIME count of sub-agents spawned under this grant — the
	// max_total backstop. Incremented atomically by the spawn handler; reset when
	// the grant is replaced (a fresh grant is a fresh budget).
	Used int `json:"used,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	CreatedBy string    `json:"created_by,omitempty"`
}

Grant is one island's ephemeral-sub-agent budget. Zero/empty fields mean "unset" per the field docs; an island with no Grant at all cannot spawn.

type Store

type Store struct {
	Grants map[string]Grant `json:"grants"`
}

Store is the persisted set of per-island grants, keyed by island name.

func Load

func Load() (*Store, error)

Load returns a snapshot of the store (empty when none exists yet).

func Update

func Update(fn func(*Store) error) (*Store, error)

Update runs fn against the store under a process-wide lock and persists the result atomically — use it for every read-modify-write (grant/revoke).

func (*Store) Consume

func (s *Store) Consume(island string)

Consume increments an island's lifetime spawn counter (Used) — the max_total backstop. The caller has already verified the budget under the per-island lock (so this is part of the atomic check-and-reserve). No-op if no grant. Use within Update.

func (*Store) Get

func (s *Store) Get(island string) (Grant, bool)

Get returns the grant for an island (ok=false when none — the deny default).

func (*Store) List

func (s *Store) List() []Grant

List returns all grants.

func (*Store) Remove

func (s *Store) Remove(island string) bool

Remove deletes an island's grant (revoke). Returns whether one existed.

func (*Store) Set

func (s *Store) Set(g Grant) error

Set upserts a grant, stamping CreatedAt. MaxConcurrent must be > 0 (a grant that permits nothing is a revoke). Use within Update.