rig

package
v0.26.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

README

pkg/rig

pkg/rig is the composition root for an agent runtime. A consumer assembles a *Rig from loop definitions, hustle definitions, a session store, primers, and a workspace placement; the Rig then creates and restores live sessions.

It owns design-time topology and lifecycle policy — what loops exist, what they're called, which one starts active, where the session is persisted, where the workspace lives — while the live runtime behavior lives behind the pkg/session contracts the Rig returns. Construction and restoration of a session are owned exclusively here; nothing else in the module can mint or resume one.

What is rig?

A Rig is an immutable design-time assembly. rig.Define(opts...) validates the options, freezes the assembly, and returns a *Rig. The two lifecycle methods are the whole public surface:

  • rig.NewSession(ctx, opts...) — bring up a brand-new live session. Optionally seed its workspace from a snapshot via WithSeedSnapshot.
  • rig.RestoreSession(ctx, id) — rebuild a prior session from its durable journal by id.

Both return a session.SessionController, which embeds session.Session (the data plane) and adds the trusted policy/lifecycle methods (SetActiveLoop, LoopController, CheckpointWorkspace, RestoreWorkspace, Shutdown).

How to use

reviewPolicy, err := gate.DefaultPermissionReviewPolicy("review-policy-v1")
if err != nil { /* ... */ }

r, err := rig.Define(
    rig.WithLoops(operatorLoop, reviewerLoop),
    rig.WithPrimers("operator"),
    rig.WithSessionStore(sessionStore),
    rig.WithExclusiveWorkspace(workspaceStore, "/repo", leaser),
    rig.WithHustles(/* ...optional hustle.Definition values... */...),
    rig.WithHustleLimits(rig.HustleLimits{ /* ... */ }),
    rig.WithPermissionClassifiers(permissionClassifiers),
    rig.WithPermissionReviewPolicy(reviewPolicy),
    rig.WithPermissionReviewSecurityCeiling("consumer-access-profile/v1"),
    // Optional: bounded evidence-tool access for classifiers that gather
    // read-only evidence. Required whenever any registered classifier's
    // definition declares evidence tools — see pkg/gate/README.md#evidence-boundaries.
    rig.WithPermissionReviewEvidence(evidenceAccess, evidenceContainment, allowedEvidenceKinds),
    // Optional: TOCTOU recheck (design §13.4) for classifiers whose evidence
    // tools observe a specific target's identity/state. Only meaningful
    // paired with WithPermissionReviewEvidence; harmless to omit if no
    // registered classifier's evidence tools are target-sensitive.
    rig.WithPermissionReviewObservations(observationVerifier),
    // Optional: circuit-breaker thresholds (design §18). Defaults every one
    // of 8 turn+session counters to rig.DefaultPermissionReviewBreakerThreshold
    // (20) when omitted but classifiers are configured.
    rig.WithPermissionReviewLimits(rig.PermissionReviewLimits{ /* ... */ }),
    rig.WithForeignBuilders(/* ...foreign.Builder for codex/claude... */...),
    rig.WithGateCaps(rig.GateCaps{MaxOpen: 16, MaxTimeout: 30*time.Second}),
    rig.WithDelegationLimits(rig.DelegationLimits{Depth: 4, Quota: 32}),
    rig.WithRestoreDecider(session.DefaultPolicyDecider{}),
)
if err != nil { /* ... */ }

ctx := context.Background()
session, err := r.NewSession(ctx)
if err != nil { /* ... */ }
defer session.Shutdown(ctx)

Restore is the same shape with the session id:

session, err := r.RestoreSession(ctx, priorSessionID)

rig.WithPermissionClassifiers, WithPermissionReviewPolicy, WithPermissionReviewEvidence, WithPermissionReviewObservations, and WithPermissionReviewSecurityCeiling are all supplied at rig.Define time above, not per restore — restore itself takes no options. Omitting every one of them (the zero-classifier rig) is how you disable permission review entirely: it preserves the pre-classifier gate behavior byte-for-byte, with no separate on/off flag to flip. See pkg/gate/README.md for the full enable/disable, evidence-boundary, observation-recheck (TOCTOU), human-fallback, audit/privacy, policy-tuning, evaluation-workflow, and restore-behavior story; that package — not this one — owns the neutral review domain these options configure.

Restore and a changed permission-review configuration

Restoring a session whose rig now has permission review configured differently than when it was opened follows the ordinary configuration-drift policy above, with one extra rule specific to this feature: turning classifiers on where the session was originally opened with none configured is always a rejected DriftWarn, never a silent auto-accept, even though the rest of that restore's drift might otherwise be all-Info. A rig only resumes with review newly enabled if it explicitly opted in — with rig.WithRestoreDecider (preferred: inspect the assessment and accept this dimension specifically) or the older, blanket rig.WithAllowConfigMismatch() (accepts every Warn-level drift, not just this one). Turning classifiers off, or restoring with the same or a differently-identified classifier set that was already enabled before, is unaffected by this rule.

Sibling packages

  • pkg/loop — loop.Definition values you pass to rig.WithLoops.
  • pkg/session — the Session / SessionController interfaces the lifecycle returns.
  • pkg/sessionstore — the *sessionstore.Store you pass to rig.WithSessionStore.
  • pkg/workspacestore — the *workspacestore.Store you pass to a workspace placement.
  • pkg/hustle — hustle.Definition values you pass to rig.WithHustles.
  • pkg/foreign — foreign.Builder values you pass to rig.WithForeignBuilders for codex/claude backends.
  • pkg/gate — the gate.Evaluator you bind into each loop.Definition via loop.WithAccessGate.

How it is designed

pkg/rig is intentionally thin. It validates options, freezes the assembly, and delegates to the private internal/sessionruntime coordinator, which owns the live loops, hub, journal, and workspace lifecycle.

        rig.Define(opts...)
                │
                │ validate + freeze
                ▼
        *rig.Rig ──► internal/sessionruntime.Lifecycle
                            │
                            │ NewSession / RestoreSession
                            ▼
                     internal/sessionruntime.Session
                       │  │  │  │
                       │  │  │  └──► pkg/workspacestore (workspace snapshots)
                       │  │  └──────► pkg/sessionstore  (journal + catalog)
                       │  └─────────► pkg/hub           (event fan-in)
                       └────────────► internal/loopruntime (loop actors)
                                            │
                                            ▼
                                       pkg/session contracts returned to caller
Validation at the boundary

Define enforces the invariants of a valid rig before any session is created:

  • At least one loop and at least one primer; the active primer must be a registered loop name.
  • Loop names are unique; the active primer is the only one if exactly one loop is supplied.
  • Every delegate a loop declares is itself a registered loop.
  • A *sessionstore.Store is required; workspace placement is optional but at most one placement may be configured.
  • Hustle lane bounds are within MaxHustleQueued; gate caps are positive.
  • Permission classifiers are supplied as one validated, ordered gate.PermissionClassifierSet and are paired with a canonical local review policy revision. Supplying only one half is rejected. Their frozen definitions are automatically registered as blocking Hustles, so WithHustleLimits is required and consumers must not also pass those same definitions to WithHustles.
  • Foreign builders and restore decider are optional with fail-secure defaults.

A bad configuration fails closed at Define rather than at session construction.

Configuration fingerprint

Define computes an immutable InitialFingerprint for each loop (model, effective system, tool names) so the rig can stamp and compare compatibility before any runtime factories execute. At restore time the rig runs the configured RestoreDecider against a DriftAssessment and records the decision as a durable ConfigurationAdopted; the default DefaultPolicyDecider accepts only when every change is Info and rejects when any is Warn.

Permission review extends the topology identity with the local review-policy revision and the classifiers in registration order. Each classifier row carries only frozen, secret-free identity: classifier name and revision, its complete definition digest, structured-output digest/revision, evidence definition and produced-name digests, and every evidence-loop bound. Classifier order is significant because combination is ordered. Evidence policies accept only sealed tool.NewEvidenceDefinition definitions with frozen ToolInfo metadata. Their factories use tool.EvidenceFactoryBindings, whose complete public capability surface is the invocation session/loop identity and an optional root-only tool.ReadWorkspaceBinding; generic workspace mutation, observations, delegation, gate/grant/control state, and extra tools are not in the factory API. Canonical static descriptions and compact portable schemas contribute to the evidence catalog digest, so either can change topology identity before a session is persisted or restored. The fingerprint stores only those versioned digests: raw prompts, schemas, descriptions, model clients and credentials, workspace paths, live review subjects, and runtime-bound tool objects are never serialized into it. At concrete binding, each tool's twice-read metadata must exactly match the frozen static name, description, and schema; drift fails closed. Automatic classifier-definition registration deliberately routes this through the same Hustle binding path as every other evidence-enabled definition.

Omitting both permission-review options preserves the pre-classifier fingerprint and gate behavior byte-for-byte. There is no implicit classifier registry or default review policy.

Documentation

Overview

Package rig is the public composition root for defining an agent rig and creating or restoring its sessions. It owns design-time topology and lifecycle policy while the returned session contracts expose live runtime behavior.

Index

Constants

View Source 
const DefaultPermissionReviewBreakerThreshold = 20

DefaultPermissionReviewBreakerThreshold is the default numeric circuit-breaker threshold Define() resolves for every turn-scoped and session-scoped counter (resolvePermissionReviewLimits in definition.go) when classifiers are configured but WithPermissionReviewLimits was never explicitly called.

View Source 
const MaxHustleQueued = 10_000

MaxHustleQueued is the largest configured waiting capacity for either hustle lane. The execution controller may allocate no queue larger than this bound.

Variables

This section is empty.

Functions

func FingerprintFrom 

func FingerprintFrom(definition loop.BoundDefinition) event.ConfigFingerprint

FingerprintFrom derives the stable, secret-free behavior fingerprint of a bound loop.

Types

type ConfigFingerprintFields 

type ConfigFingerprintFields struct {
	AgentKind     string
	RuntimeSkills bool
	WorkspaceRoot string
	// AdapterID identifies a foreign-agent adapter. Empty means native.
	AdapterID string
	// Posture identifies a foreign agent's non-interactive permission posture.
	Posture string
	// NativePermissionPolicyRev is the digest of native permission configuration.
	NativePermissionPolicyRev string
	// ExternalCapabilityRev is the digest of the identity of external capabilities
	// the composition root attached to the session — tools served by processes
	// Harness does not own, such as MCP servers. Empty means none, which is what
	// keeps it additive for every rig that attaches nothing.
	//
	// The rig neither computes nor interprets it: only the composition root knows
	// what it attached. The canonical producer is github.com/looprig/mcp's
	// mcpharness.Manager.ConfigDigest, taken after the Manager has started.
	ExternalCapabilityRev string

	// WorkspaceTrust is an opaque, secret-free label for the workspace's trust
	// posture (e.g. "trusted"/"untrusted"). Empty means unspecified.
	WorkspaceTrust string
	// PermissionStrictness is the ordered native-permission posture level; higher is
	// stricter. Zero means unknown (drift assessment fails secure). It complements
	// NativePermissionPolicyRev, which is the digest-only identity.
	PermissionStrictness event.StrictnessLevel
	// ConfinementRev is a content digest of the confinement (sandbox) configuration.
	// Empty means none. Harness compares it, never parses it.
	ConfinementRev string
	// ConfinementStrictness is the ordered confinement posture level; higher is
	// stricter. Zero means unknown.
	ConfinementStrictness event.StrictnessLevel
	// AppFields are application-defined, secret-free compatibility fields the
	// composition root attaches. Canonically encoded in sorted key order by the
	// manifest. Nil means none.
	AppFields          map[string]string
	RuntimeProfile     string
	RuntimeCatalogRev  string
	RuntimeIdentityRev string
}

ConfigFingerprintFields are immutable rig-level behavior inputs that are not part of a loop.Definition. Define freezes them for both session creation and restoration.

type DefinitionError 

type DefinitionError struct {
	Kind  DefinitionErrorKind
	Name  string
	Cause error
}

func (*DefinitionError) Error 

func (e *DefinitionError) Error() string

func (*DefinitionError) Unwrap 

func (e *DefinitionError) Unwrap() error

type DefinitionErrorKind 

type DefinitionErrorKind string
const (
	DefinitionNilOption                       DefinitionErrorKind = "nil_option"
	DefinitionMissingLoop                     DefinitionErrorKind = "missing_loop"
	DefinitionInvalidLoop                     DefinitionErrorKind = "invalid_loop"
	DefinitionDuplicateLoop                   DefinitionErrorKind = "duplicate_loop"
	DefinitionMissingPrimer                   DefinitionErrorKind = "missing_primer"
	DefinitionInvalidPrimer                   DefinitionErrorKind = "invalid_primer"
	DefinitionInvalidActivePrimer             DefinitionErrorKind = "invalid_active_primer"
	DefinitionMissingSessionStore             DefinitionErrorKind = "missing_session_store"
	DefinitionInvalidSessionStore             DefinitionErrorKind = "invalid_session_store"
	DefinitionInvalidDelegationLimits         DefinitionErrorKind = "invalid_delegation_limits"
	DefinitionInvalidForeignBuilders          DefinitionErrorKind = "invalid_foreign_builders"
	DefinitionInvalidGateCaps                 DefinitionErrorKind = "invalid_gate_caps"
	DefinitionInvalidRestoreDecider           DefinitionErrorKind = "invalid_restore_decider"
	DefinitionDuplicateOption                 DefinitionErrorKind = "duplicate_option"
	DefinitionInvalidHustle                   DefinitionErrorKind = "invalid_hustle"
	DefinitionDuplicateHustle                 DefinitionErrorKind = "duplicate_hustle"
	DefinitionMissingHustleLimits             DefinitionErrorKind = "missing_hustle_limits"
	DefinitionUnusedHustleLimits              DefinitionErrorKind = "unused_hustle_limits"
	DefinitionInvalidHustleLimits             DefinitionErrorKind = "invalid_hustle_limits"
	DefinitionInvalidHooks                    DefinitionErrorKind = "invalid_hooks"
	DefinitionMissingResourceStorage          DefinitionErrorKind = "missing_resource_storage"
	DefinitionInvalidResourceStorage          DefinitionErrorKind = "invalid_resource_storage"
	DefinitionMissingCompactionHustle         DefinitionErrorKind = "missing_compaction_hustle"
	DefinitionIncompatibleCompactionHustle    DefinitionErrorKind = "incompatible_compaction_hustle"
	DefinitionInvalidPermissionClassifiers    DefinitionErrorKind = "invalid_permission_classifiers"
	DefinitionInvalidPermissionReviewPolicy   DefinitionErrorKind = "invalid_permission_review_policy"
	DefinitionIncompletePermissionReview      DefinitionErrorKind = "incomplete_permission_review"
	DefinitionUnusedPermissionReviewLimits    DefinitionErrorKind = "unused_permission_review_limits"
	DefinitionInvalidPermissionReviewEvidence DefinitionErrorKind = "invalid_permission_review_evidence"
	DefinitionMissingPermissionReviewEvidence DefinitionErrorKind = "missing_permission_review_evidence"
	DefinitionUnusedPermissionReviewEvidence  DefinitionErrorKind = "unused_permission_review_evidence"

	// DefinitionInvalidPermissionReviewSecurityCeiling: WithPermissionReviewSecurityCeiling
	// was called with an empty (or all-whitespace) ceiling string. Rejected at
	// Define()-time rather than deferred to a later, harder-to-diagnose
	// review-context-capture failure (gate.ReviewContext's own non-empty
	// SecurityCeiling validation rule).
	DefinitionInvalidPermissionReviewSecurityCeiling DefinitionErrorKind = "invalid_permission_review_security_ceiling"
	// DefinitionMissingPermissionReviewSecurityCeiling: at least one permission
	// classifier is configured (WithPermissionClassifiers) but
	// WithPermissionReviewSecurityCeiling was never called. SecurityCeiling is a
	// consumer-owned value Harness cannot originate (Finding 2, Phase 6
	// spec-compliance review): a classifier-registered session with no ceiling
	// would otherwise fail every real evidence-tool containment check closed,
	// silently, at runtime.
	DefinitionMissingPermissionReviewSecurityCeiling DefinitionErrorKind = "missing_permission_review_security_ceiling"
	// DefinitionUnusedPermissionReviewSecurityCeiling: WithPermissionReviewSecurityCeiling
	// was called but no permission classifier is configured, mirroring
	// DefinitionUnusedPermissionReviewEvidence's "config X requires config Y"
	// symmetric check.
	DefinitionUnusedPermissionReviewSecurityCeiling DefinitionErrorKind = "unused_permission_review_security_ceiling"

	// DefinitionInvalidPermissionReviewObservations: WithPermissionReviewObservations
	// was called with a nil verifier.
	DefinitionInvalidPermissionReviewObservations DefinitionErrorKind = "invalid_permission_review_observations"
	// DefinitionUnusedPermissionReviewObservations: WithPermissionReviewObservations
	// was called but either no permission classifier is configured at all, or
	// no WithPermissionReviewEvidence was configured (design §13.4's
	// observation-recheck mechanism lives entirely inside the evidence
	// runtime — a verifier with no evidence runtime to ever record an
	// observation into is dead configuration). There is deliberately no
	// symmetric "missing" error the way DefinitionMissingPermissionReviewEvidence
	// pairs with WithPermissionReviewEvidence: see WithPermissionReviewObservations'
	// own doc comment for why "a classifier's evidence tools need this"
	// cannot be determined at Define()-time today, and how runtime instead
	// fails closed (internal/sessionruntime/gates.go's
	// verifyPermissionReviewObservations) if that ever turns out to matter
	// for a given session.
	DefinitionUnusedPermissionReviewObservations DefinitionErrorKind = "unused_permission_review_observations"
)

type DelegationLimits 

type DelegationLimits struct {
	Depth int
	Quota int
}

type GateCaps 

type GateCaps struct {
	MaxOpen    int
	MaxTimeout time.Duration
}

type HustleLimits 

type HustleLimits struct {
	BlockingConcurrent   int
	BlockingQueued       int
	BackgroundConcurrent int
	BackgroundQueued     int
	AuditTimeout         time.Duration
	FinalizationTimeout  time.Duration
	WorkerDrainTimeout   time.Duration
}

HustleLimits bounds the two independent execution lanes and their audit, finalization, and worker-drain operations.

type InvalidOffloadGCIntervalError 

type InvalidOffloadGCIntervalError struct {
	Interval time.Duration
}

InvalidOffloadGCIntervalError reports a non-positive OffloadGCPolicy.Interval. A GC cadence must be a positive duration, so the rig fails closed at definition time rather than wiring a runner that would never (or continuously) tick.

func (*InvalidOffloadGCIntervalError) Error 

func (e *InvalidOffloadGCIntervalError) Error() string

type InvalidOffloadGCTimeoutError 

type InvalidOffloadGCTimeoutError struct {
	Timeout time.Duration
}

InvalidOffloadGCTimeoutError reports a non-positive OffloadGCPolicy.Timeout. A per-pass deadline must be a positive duration, so the rig fails closed at definition time.

func (*InvalidOffloadGCTimeoutError) Error 

func (e *InvalidOffloadGCTimeoutError) Error() string

type LifecycleError 

type LifecycleError struct {
	Kind  LifecycleErrorKind
	Cause error
}

func (*LifecycleError) Error 

func (e *LifecycleError) Error() string

func (*LifecycleError) Unwrap 

func (e *LifecycleError) Unwrap() error

type LifecycleErrorKind 

type LifecycleErrorKind string
const (
	LifecycleContextDone                     LifecycleErrorKind = "context_done"
	LifecycleIDGenerationFailed              LifecycleErrorKind = "id_generation_failed"
	LifecycleLeaseFailed                     LifecycleErrorKind = "lease_failed"
	LifecycleJournalFailed                   LifecycleErrorKind = "journal_failed"
	LifecycleAppenderFailed                  LifecycleErrorKind = "appender_failed"
	LifecycleSessionFailed                   LifecycleErrorKind = "session_failed"
	LifecycleProcessNotificationsUnsupported LifecycleErrorKind = "process_notifications_unsupported"
)

type OffloadGCPolicy 

type OffloadGCPolicy struct {
	Interval time.Duration
	Timeout  time.Duration
}

OffloadGCPolicy configures session offload-blob GC: how often a GC pass runs (Interval) and the per-pass deadline (Timeout). It reaps orphaned content-addressed offload blobs — a blob left durable with no in-ledger blobptr pointer (the crash gap of the writer's blob-durable-before-pointer discipline). This is SESSION OFFLOAD GC only, never workspace-snapshot GC. Both fields must be positive.

type Option 

type Option func(*definitionState) error

func WithActivePrimer 

func WithActivePrimer(name string) Option

func WithAllowConfigMismatch 

func WithAllowConfigMismatch() Option

func WithDelegationLimits 

func WithDelegationLimits(limits DelegationLimits) Option

func WithExclusiveWorkspace 

func WithExclusiveWorkspace(store *workspacestore.Store, root string, leaser storage.Leaser) Option

WithExclusiveWorkspace declares one canonical fixed root fenced by a single exclusive root lease from leaser. The session lease is acquired first, then the root lease named workspace-roots/<sha256(canonical-root)>, so lexical/symlink aliases of the root contend.

func WithFingerprintFields 

func WithFingerprintFields(fields ConfigFingerprintFields) Option

func WithForeignBuilders 

func WithForeignBuilders(builder foreign.Builder, restored foreign.RestoredBuilder) Option

func WithForeignServicesBuilders 

func WithForeignServicesBuilders(builder foreign.ServicesBuilder, restored foreign.ServicesRestoredBuilder) Option

WithForeignServicesBuilders opts a rig into the additive foreign-engine seam. Each live/restored foreign origin receives a fresh loop-scoped broker descriptor and delivery hook at session construction; no capability is part of the immutable rig configuration. The legacy WithForeignBuilders option remains supported and receives zero services.

func WithGateCaps 

func WithGateCaps(caps GateCaps) Option

func WithHooks 

func WithHooks(set hook.Set) Option

WithHooks installs one immutable operation-hook set. Define validates and compiles the captured set after every option has resolved.

func WithHustleLimits 

func WithHustleLimits(limits HustleLimits) Option

WithHustleLimits configures the required singleton lane bounds.

func WithHustles 

func WithHustles(definitions ...hustle.Definition) Option

WithHustles adds immutable hustle definitions to the rig.

func WithLoops 

func WithLoops(definitions ...loop.Definition) Option

func WithOffloadGC 

func WithOffloadGC(policy OffloadGCPolicy) Option

WithOffloadGC arms periodic session offload-blob GC. It validates the policy (both fields positive; typed errors on failure) and compiles to the sessionruntime lifecycle option that wires the journal-admission gate + GC runner onto both new and restored sessions. It is an at-most-once rig option.

func WithPermissionClassifiers 

func WithPermissionClassifiers(classifiers gate.PermissionClassifierSet) Option

WithPermissionClassifiers installs the already-validated, ordered permission classifier registry. Registration order is behavioral and therefore remains significant in the rig fingerprint.

func WithPermissionReviewEvidence 

func WithPermissionReviewEvidence(access gate.EvidenceAccessEvaluator, containment gate.EvidenceContainmentVerifier, allowedKinds []string) Option

WithPermissionReviewEvidence installs the consumer-supplied read-only evidence-tool access boundary every registered permission classifier's evidence tools run under (design §13.1). access answers the configured access state for one prepared evidence Requirement; containment independently performs the trusted-caller containment check (resolving symlinks, rejecting ambiguous scopes, enforcing the review's own security ceiling); allowedKinds is the explicit consumer-consent allowlist of Requirement.Kind values evidence tools may declare. Both access and containment are read-only, headless, trusted-caller seams — neither receives session, gate, mutation, grant, rule, or loop-control capability (design §13.1's Access/Containment split; Access alone was omitted from the design sketch of this option's signature, but the same fail-closed requirement applies to it: hustleruntime refuses to bind an evidence catalog with a nil Access evaluator exactly as it refuses a nil Containment verifier).

Required whenever any registered classifier's definition needs evidence tools; Define fails closed (DefinitionMissingPermissionReviewEvidence) if omitted in that case, and rejects it (DefinitionUnusedPermissionReviewEvidence) when supplied but no registered classifier needs it — mirroring the existing MissingHustleLimits/UnusedHustleLimits "config X requires config Y" pairing already used elsewhere in this file.

func WithPermissionReviewLimits 

func WithPermissionReviewLimits(limits PermissionReviewLimits) Option

WithPermissionReviewLimits installs the circuit-breaker thresholds (design §18) applied to automatic permission review. It is only meaningful paired with WithPermissionClassifiers; Define() enforces that pairing (DefinitionUnusedPermissionReviewLimits) rather than this Option, because option application order is not guaranteed (classifiers may be registered before or after this call in the Define() argument list).

Omitting this option while classifiers ARE configured resolves a default of DefaultPermissionReviewBreakerThreshold on every one of the 8 numeric thresholds (resolvePermissionReviewLimits, definition.go); an explicit call always replaces that default wholesale — all 8 fields at once, never merged per-field.

func WithPermissionReviewObservations 

func WithPermissionReviewObservations(verifier gate.EvidenceObservationVerifier) Option

WithPermissionReviewObservations installs the consumer-supplied, read-only TOCTOU-recheck seam (design §13.4) every classifier-originated auto-approval's recorded observations are verified against immediately before the gate is claimed. verifier independently re-derives each previously recorded gate.ObservationRequirement's current token and fails closed (leaving the human gate open) on any mismatch or unverifiable target — see gate.EvidenceObservationVerifier's own doc comment for the full trusted-caller contract, which deliberately reuses gate.EvidenceContainmentPolicy rather than introducing a parallel policy type (the security context — canonical read root plus the review's own non-widenable ceiling — is identical to WithPermissionReviewEvidence's own Containment collaborator).

A separate option, deliberately NOT folded into WithPermissionReviewEvidence's signature: the two are independent concerns (an evidence-tool access boundary a session needs whenever ANY registered classifier declares evidence tools, versus a TOCTOU recheck a session needs only when at least one of those evidence tools is target-sensitive). Folding Observations in as a fourth WithPermissionReviewEvidence parameter would force every existing and future caller with no target-sensitive evidence tools — the common case today, since no evidence tool in this codebase declares itself target-sensitive yet — to pass an explicit nil at that call site for a concern it will never use, which is exactly the Interface Segregation violation this package's own CLAUDE.md guidance warns against.

Required (rejected as DefinitionUnusedPermissionReviewObservations) unless BOTH at least one permission classifier is registered AND WithPermissionReviewEvidence is also configured — mirroring the "config X requires config Y" pairing precedent, but ONLY in the unused direction. There is deliberately NO symmetric "missing" pairing error the way WithPermissionReviewEvidence itself is required whenever anyClassifierNeedsEvidence(state.permissionClassifiers) reports true: that check is possible because hustle.Definition.EvidenceToolPolicy() already gives Define() a real, static, per-classifier "does this need an evidence runtime at all" signal. Nothing analogous exists for "is any of THIS classifier's evidence tools target-sensitive" — no evidence tool definition in this codebase declares that today (it is a per-concrete-tool capability, tool.EvidenceObservation, probed only at runtime after a call executes, not a static Definition-level property Define() could inspect ahead of time the way it inspects EvidenceToolPolicy). Manufacturing a parallel static declarer purely to unlock a Define()-time "missing" check, before any real tool exists that would ever set it, would be speculative generality with no consumer to validate it against. Instead, runtime fails closed: internal/sessionruntime/gates.go's verifyPermissionReviewObservations treats "an observation WAS recorded but no verifier is configured" identically to a genuine mismatch — stale, human gate stays open, never a silent pass — so a consumer who adds a target-sensitive evidence tool later without also wiring this option gets an always-safe (if initially confusing, and always correctable) runtime outcome rather than a false sense of protection. If a future evidence-tool capability gives Define() a real static signal, tightening this to a "missing" pairing error too is a natural, non-breaking follow-up — see this addendum's plan section for the explicit flag.

func WithPermissionReviewPolicy 

func WithPermissionReviewPolicy(policy gate.PermissionReviewPolicy) Option

WithPermissionReviewPolicy installs the immutable local decision policy (design §20) every session forwards into the review runtime. Only the policy's Revision feeds rig identity (permissionReviewFingerprintFrom in fingerprint.go); the full value is what sessionruntime actually applies.

A policy that was never built through gate.NewPermissionReviewPolicy or gate.DefaultPermissionReviewPolicy (a hand-built literal gate.PermissionReviewPolicy{}, whose zero seal makes it fail closed at EvaluatePermissionAssessment regardless) is rejected here immediately, rather than silently accepted and left to fail closed later with a confusing runtime symptom. This is a developer-experience improvement: the security property already holds without it.

func WithPermissionReviewSecurityCeiling 

func WithPermissionReviewSecurityCeiling(ceiling string) Option

WithPermissionReviewSecurityCeiling installs the consumer-supplied, effective security posture (design §13.1/§21) every registered permission classifier's ReviewContext/ReviewBasis carries as SecurityCeiling, and every evidence-tool containment check (WithPermissionReviewEvidence's Containment collaborator) is run against.

SecurityCeiling is architecturally the SAME KIND of value as the Containment/AllowedKinds collaborators WithPermissionReviewEvidence installs — a consumer-owned concept Harness structurally cannot and should not originate (this module has no first-class "effective access posture" notion; the product composition root binds its own AccessProfile name here). It is NOT like a workspace root, which Harness genuinely owns and auto-derives. A plain string, not a provider func: a consumer's ceiling is fixed for the session's lifetime by design (YAGNI — see the design consult this option was written from).

Required whenever any permission classifier is registered (WithPermissionClassifiers); Define fails closed (DefinitionMissingPermissionReviewSecurityCeiling) if omitted in that case — before this option existed, every session instead stamped a fixed Harness-side sentinel that could never equal a real consumer's own ceiling, so every real evidence-tool containment check failed closed unconditionally (Finding 2, Phase 6 spec-compliance review). It is rejected (DefinitionUnusedPermissionReviewSecurityCeiling) when supplied but no classifiers are configured, mirroring WithPermissionReviewEvidence's own "config X requires config Y" pairing. An empty (or all-whitespace) ceiling is rejected here, immediately, at Define() time — never deferred to a later, harder-to-diagnose review-context-capture failure (gate.ReviewContext's own non-empty SecurityCeiling validation rule already fails closed on an empty value, but silently and much later).

func WithPrimers 

func WithPrimers(names ...string) Option

func WithRestoreDecider 

func WithRestoreDecider(decider session.RestoreDecider) Option

WithRestoreDecider installs the application policy that decides whether a configuration-drifted restore proceeds. It is the successor to WithAllowConfigMismatch: rather than a blanket override, the decider inspects the typed drift assessment and accepts or rejects. Omitting it leaves restore on the fail-secure session.DefaultPolicyDecider (reject on any Warn). A nil decider is rejected at definition time so the option cannot silently disarm the default.

func WithRuntimeCatalog 

func WithRuntimeCatalog(catalog loop.RuntimeCatalog) Option

WithRuntimeCatalog installs the immutable parent-scoped runtime catalog forwarded to every new and restored session.

func WithSessionResourceStorage 

func WithSessionResourceStorage(provider SessionResourceStorageProvider) Option

WithSessionResourceStorage installs the singleton durable-storage provider used by session-owned resources.

func WithSessionStore 

func WithSessionStore(store *sessionstore.Store) Option

func WithSessionWorkspaces 

func WithSessionWorkspaces(store *workspacestore.Store, baseDir string) Option

WithSessionWorkspaces declares per-session roots derived as baseDir/<sessionID>, isolated by construction (no root lease).

func WithSharedWorkspace 

func WithSharedWorkspace(store *workspacestore.Store, root string) Option

WithSharedWorkspace declares one canonical fixed root shared with concurrent harness sessions, humans, and external tools — deliberately NO root lease; every checkpoint is stamped fuzzy.

func WithSnapshots 

func WithSnapshots(policy SnapshotPolicy) Option

type PermissionReviewLimits 

type PermissionReviewLimits struct {
	MaxConsecutiveNeedsHuman int
	MaxInvalidOrFailed       int
	MaxIdenticalSubjects     int
	MaxStaleResponses        int
	InterruptOnTrip          bool
	Session                  PermissionReviewSessionLimits
}

PermissionReviewLimits are the consumer-configurable bounded per-turn and per-session circuit-breaker thresholds (design §18) — the rig-level mirror of sessionruntime.PermissionReviewBreakerLimits. They are deliberately EXCLUDED from the rig fingerprint (fingerprint.go): these are operational tuning knobs, not behavioral identity, so two rigs that agree on classifiers and policy but differ only in these thresholds compare equal.

type PermissionReviewSessionLimits 

type PermissionReviewSessionLimits struct {
	MaxConsecutiveNeedsHuman int
	MaxInvalidOrFailed       int
	MaxIdenticalSubjects     int
	MaxStaleResponses        int
}

PermissionReviewSessionLimits is PermissionReviewLimits' session-scoped counterpart (design §18: "per-turn AND per-session").

type PersistenceOverlapError 

type PersistenceOverlapError struct {
	PersistencePath string
	Root            string
}

PersistenceOverlapError reports that a discoverable persistence path is equal to or beneath the managed workspace root, so appending a boundary or checkpoint event would mutate the very tree being captured. Persistence must live OUTSIDE the workspace. PersistencePath is the offending canonical path; Root is the canonical workspace root (or per-session base dir) it overlaps.

func (*PersistenceOverlapError) Error 

func (e *PersistenceOverlapError) Error() string

type Rig 

type Rig struct {
	// contains filtered or unexported fields
}

Rig is an immutable design-time assembly that creates and restores sessions.

func Define 

func Define(options ...Option) (*Rig, error)

func (*Rig) NewSession 

func (r *Rig) NewSession(ctx context.Context, opts ...SessionOption) (session.SessionController, error)

NewSession brings up a brand-new live session. WithSeedSnapshot optionally materializes and commits a seed before any loop starts.

func (*Rig) RestoreSession 

func (r *Rig) RestoreSession(ctx context.Context, id uuid.UUID) (session.SessionController, error)

type SessionOption 

type SessionOption func(*sessionOptions) error

SessionOption configures a single Rig.NewSession call.

func WithSeedSnapshot 

func WithSeedSnapshot(ref workspacestore.Ref) SessionOption

WithSeedSnapshot materializes ref into the new session's workspace before constructing loops and journals it as the first workspace checkpoint (design §"Seeding"). It is valid only for per-session roots and an EMPTY exclusive root, never for a shared root, and the ref must resolve in the configured workspace store — all enforced at NewSession, which fails closed on a bad seed.

type SessionOptionError 

type SessionOptionError struct {
	Kind SessionOptionErrorKind
}

SessionOptionError reports an invalid NewSession option.

func (*SessionOptionError) Error 

func (e *SessionOptionError) Error() string

type SessionOptionErrorKind 

type SessionOptionErrorKind string

SessionOptionErrorKind classifies a NewSession option failure. 

const (
	// SessionOptionNil: a nil NewSession option was supplied.
	SessionOptionNil SessionOptionErrorKind = "nil_option"
	// SessionOptionDuplicateSeed: WithSeedSnapshot was supplied more than once.
	SessionOptionDuplicateSeed SessionOptionErrorKind = "duplicate_seed"
	// SessionOptionEmptySeed: WithSeedSnapshot was given an empty ref.
	SessionOptionEmptySeed SessionOptionErrorKind = "empty_seed"
)

type SessionResourceStorage 

type SessionResourceStorage struct {
	Path     string
	Identity string
}

SessionResourceStorage identifies the durable storage assigned to one session's shared resources. Path and Identity are opaque to Rig definition; the session lifecycle validates and consumes them when it resolves storage.

type SessionResourceStorageProvider 

type SessionResourceStorageProvider interface {
	StorageForSession(context.Context, uuid.UUID) (SessionResourceStorage, error)
}

SessionResourceStorageProvider resolves durable storage for a session.

A provider is retained by the immutable Rig and may be called concurrently for multiple sessions, so implementations must be safe for concurrent use. Repeated calls for the same non-zero session ID, including after process restart, must resolve the same durable storage identity. The provider retains ownership of its own state; the harness receives only the returned value and does not mutate the provider.

type SnapshotPolicy 

type SnapshotPolicy struct {
	Trigger  SnapshotTrigger
	Priority SnapshotPriority
	Timeout  time.Duration
}

type SnapshotPolicyError 

type SnapshotPolicyError struct {
	Kind  SnapshotPolicyErrorKind
	Value int
}

func (*SnapshotPolicyError) Error 

func (e *SnapshotPolicyError) Error() string

type SnapshotPolicyErrorKind 

type SnapshotPolicyErrorKind string
const (
	SnapshotPolicyRequired         SnapshotPolicyErrorKind = "required"
	SnapshotPolicyWithoutWorkspace SnapshotPolicyErrorKind = "without_workspace"
	SnapshotPolicyInvalidTrigger   SnapshotPolicyErrorKind = "invalid_trigger"
	SnapshotPolicyInvalidPriority  SnapshotPolicyErrorKind = "invalid_priority"
	SnapshotPolicyInvalidTimeout   SnapshotPolicyErrorKind = "invalid_timeout"
	SnapshotPolicySharedRequired   SnapshotPolicyErrorKind = "shared_required"
)

type SnapshotPriority 

type SnapshotPriority uint8
const (
	SnapshotBestEffort SnapshotPriority = iota
	SnapshotRequired
)

type SnapshotTrigger 

type SnapshotTrigger uint8
const (
	SnapshotTriggerUnset SnapshotTrigger = iota
	SnapshotManual
	SnapshotOnIdle
	SnapshotOnTurnDone
	SnapshotOnStepDone
)

type WorkspacePlacementError 

type WorkspacePlacementError struct {
	Kind  WorkspacePlacementErrorKind
	Name  string
	Cause error
}

WorkspacePlacementError reports an invalid workspace placement declaration at rig.Define.

func (*WorkspacePlacementError) Error 

func (e *WorkspacePlacementError) Error() string

func (*WorkspacePlacementError) Unwrap 

func (e *WorkspacePlacementError) Unwrap() error

type WorkspacePlacementErrorKind 

type WorkspacePlacementErrorKind string

WorkspacePlacementErrorKind classifies a workspace placement validation failure. 

const (
	// WorkspaceMultiplePlacements: more than one placement option was supplied. Exactly
	// one of WithExclusiveWorkspace / WithSessionWorkspaces / WithSharedWorkspace may be used.
	WorkspaceMultiplePlacements WorkspacePlacementErrorKind = "multiple_placements"
	// WorkspaceNilStore: a placement was given a nil workspace store.
	WorkspaceNilStore WorkspacePlacementErrorKind = "nil_store"
	// WorkspaceNilLeaser: an exclusive placement was given a nil root leaser.
	WorkspaceNilLeaser WorkspacePlacementErrorKind = "nil_leaser"
	// WorkspaceEmptyRoot: a placement root/base dir was empty or whitespace.
	WorkspaceEmptyRoot WorkspacePlacementErrorKind = "empty_root"
	// WorkspaceCanonicalizeFailed: a root/base dir could not be canonicalized.
	WorkspaceCanonicalizeFailed WorkspacePlacementErrorKind = "canonicalize_failed"
	// WorkspaceLeaseNameInvalid: the derived root lease name violated the storage grammar.
	WorkspaceLeaseNameInvalid WorkspacePlacementErrorKind = "lease_name_invalid"
	// WorkspaceToolWithoutPlacement: a workspace-requiring tool definition with no placement.
	WorkspaceToolWithoutPlacement WorkspacePlacementErrorKind = "workspace_tool_without_placement"
)

type WorkspaceRecoveryError 

type WorkspaceRecoveryError = session.WorkspaceRecoveryError

type WorkspaceRootBusyError 

type WorkspaceRootBusyError = session.WorkspaceRootBusyError

WorkspaceRootBusyError and WorkspaceRootLeaseLostError are re-exported at the rig composition surface while remaining canonical session lifecycle errors.

type WorkspaceRootLeaseLostError 

type WorkspaceRootLeaseLostError = session.WorkspaceRootLeaseLostError

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.