workspace

package
v0.32.3 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package workspace is the pure-Go loader and validator for an ICM workspace folder. It has no Nexus runtime dependencies; given an absolute path it returns a fully validated *Workflow value or a *LoadErrors aggregate. All field references, regex patterns, JSON schemas, and gojq expressions are resolved at load time so the orchestrator can dispatch without re-parsing.

Callers (the icm plugin) are responsible for tilde-expansion via engine.ExpandPath before invoking the loader; this package only sees absolute paths.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Validate

func Validate(root string, opts ...LoaderOption) error

Validate runs LoadWorkspace but discards the result. Useful in CI and the `icm_validate` LLM tool.

Types

type AgentBudget

type AgentBudget struct {
	TimeoutSeconds int `yaml:"timeout_seconds,omitempty"`
	MaxTokens      int `yaml:"max_tokens,omitempty"`
	MaxToolCalls   int `yaml:"max_tool_calls,omitempty"`
}

AgentBudget mirrors posture.ResourceBudget without importing the runtime package. Zero values mean "use default".

type AgentSpec

type AgentSpec struct {
	// Posture is an optional registered-posture name. The loader
	// validates shape only; existence is checked at runtime.
	Posture string `yaml:"posture,omitempty"`
	// ModelRole maps to the engine model registry (not a raw model name).
	ModelRole string `yaml:"model_role,omitempty"`
	// Tools are tool names resolved against the catalog at dispatch.
	Tools []string `yaml:"tools,omitempty"`
	// PromptOverlay is appended to the base operator prompt for this stage.
	PromptOverlay string `yaml:"prompt_overlay,omitempty"`
	// Budget bounds runtime resource use; mirrors posture.ResourceBudget.
	Budget AgentBudget `yaml:"budget,omitempty"`
	// MaxRecursionDepth caps sub-agent nesting (0 = registry default).
	MaxRecursionDepth int `yaml:"max_recursion_depth,omitempty"`
}

AgentSpec configures the sub-agent that runs this stage. All fields are optional; absent fields fall back to workspace defaults, then to library defaults at dispatch.

type ErrorPolicy

type ErrorPolicy string

ErrorPolicy governs how the orchestrator handles non-validator stage failures: LLM API errors, malformed output that can't be parsed for schema validation, tool call failures, fan-out source not resolving to an array.

const (
	// ErrorHalt stops the run (default).
	ErrorHalt ErrorPolicy = "halt"
	// ErrorRetry retries the current turn.
	ErrorRetry ErrorPolicy = "retry"
	// ErrorHumanGate pauses for a human decision.
	ErrorHumanGate ErrorPolicy = "human_gate"
)

type ExhaustedAction

type ExhaustedAction string

ExhaustedAction governs behaviour when MaxIterations runs out.

const (
	// ExhaustedHumanGate raises a HITL gate (default).
	ExhaustedHumanGate ExhaustedAction = "human_gate"
	// ExhaustedError treats convergence failure as a stage error.
	ExhaustedError ExhaustedAction = "error"
)

type FanOutConfig

type FanOutConfig struct {
	// Source is an artifact reference "<stage_id>/<filename>" resolved
	// against the active session at dispatch; must point at JSON.
	Source string `yaml:"source"`
	// JSONPath optionally navigates into the source document to locate
	// the array. Defaults to "." (whole document) when empty.
	JSONPath string `yaml:"jsonpath"`
	// ItemVar is the variable name the per-invocation item receives in
	// the XML payload.
	ItemVar string `yaml:"item_var"`
	// ItemID is an optional gojq expression evaluated against each item
	// to name the per-item folder. Falls back to "item_NN".
	ItemID string `yaml:"item_id"`
	// MaxParallel caps concurrent item invocations. Defaults to 1.
	MaxParallel int `yaml:"max_parallel"`
	// OnItemFailure controls what happens when an item fails after
	// exhausting its turn/loop budgets.
	OnItemFailure ItemFailureAction `yaml:"on_item_failure"`
	// contains filtered or unexported fields
}

FanOutConfig declares the stage runs once per item in a list, dispatching a fresh sub-agent per item. Distinct from LoopConfig: loop is convergence-driven, fan-out is data-driven. They compose — a stage with both fans out per item, and each item independently iterates.

func (*FanOutConfig) CompiledItemID

func (f *FanOutConfig) CompiledItemID() *gojq.Code

CompiledItemID returns the pre-compiled gojq program for ItemID. Nil when no item_id was declared.

func (*FanOutConfig) CompiledJSONPath

func (f *FanOutConfig) CompiledJSONPath() *gojq.Code

CompiledJSONPath returns the pre-compiled gojq program for JSONPath. Nil when JSONPath is empty (meaning "the whole source document").

type HumanGate

type HumanGate string

HumanGate declares where human review fires at the stage boundary. On looping stages this fires at the bounds of the entire stage, not per iteration; use a Human predicate in Loop.Until for per-iteration review.

const (
	HumanGateNone  HumanGate = "none"
	HumanGateStart HumanGate = "start"
	HumanGateEnd   HumanGate = "end"
	HumanGateBoth  HumanGate = "both"
)

type InputScope

type InputScope struct {
	// Grounding paths are relative to the stage's grounding/ folder.
	Grounding []string `yaml:"grounding"`
	// SharedGrounding paths are relative to shared/grounding/.
	SharedGrounding []string `yaml:"shared_grounding"`
	// Artifacts are logical refs "<stage_id>/<filename>".
	Artifacts []string `yaml:"artifacts"`
	// Skills are skill names; resolved through the precedence chain.
	Skills []string `yaml:"skills"`
}

InputScope declares what files the stage reads. Existence is verified at load time; missing files cause load errors.

type ItemFailureAction

type ItemFailureAction string

ItemFailureAction enumerates fan-out per-item failure handling.

const (
	// ItemFailureContinue skips the failed item and continues (default).
	ItemFailureContinue ItemFailureAction = "continue"
	// ItemFailureHalt aborts the whole fan-out.
	ItemFailureHalt ItemFailureAction = "halt"
)

type LayerNames

type LayerNames struct {
	// Operator is the operator system-prompt filename. Default "operator.md".
	Operator string `yaml:"operator"`
	// Workspace is the workspace doc filename. Default "workspace.md".
	Workspace string `yaml:"workspace"`
	// Contract is the per-stage contract filename. Default "contract.md".
	Contract string `yaml:"contract"`
	// Grounding is the per-stage grounding folder name. Default "grounding".
	Grounding string `yaml:"grounding"`
}

LayerNames maps the conceptual workspace layers to their on-disk filenames. Defaults are baked into the loader; icm.yaml overrides any subset.

type LoadError

type LoadError struct {
	// Path is the file the error originates from.
	Path string
	// Line is 0 when not applicable.
	Line int
	// Stage is the stage ID when applicable, "" otherwise.
	Stage string
	// Msg is the human-readable description.
	Msg string
	// Cause is the underlying error, if any.
	Cause error
}

LoadError carries a single workspace validation failure. Loader collects all errors before returning so the user can fix the workspace in one pass.

func (*LoadError) Error

func (e *LoadError) Error() string

Error renders the LoadError as "<path>:<line>: <msg>".

func (*LoadError) Unwrap

func (e *LoadError) Unwrap() error

Unwrap exposes the underlying cause for errors.Is/As.

type LoadErrors

type LoadErrors struct {
	Errors []*LoadError
}

LoadErrors aggregates multiple LoadError values from a single load.

func (*LoadErrors) Error

func (es *LoadErrors) Error() string

Error renders the aggregate. Single-error aggregates render as the inner error; multi-error aggregates render as a header + bullet list.

type Loader

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

Loader is the entry point for reading a workspace from disk. A Loader instance lets callers inject options (e.g. embedded default operator bytes) without per-call wiring.

func NewLoader

func NewLoader(opts ...LoaderOption) *Loader

NewLoader builds a Loader with the given options.

func (*Loader) Load

func (l *Loader) Load(root string) (*Workflow, error)

Load reads the workspace at root and returns a fully validated *Workflow. All file references resolve at load time; regex patterns compile; gojq expressions compile; JSON schemas parse + compile. Errors are aggregated rather than short-circuited.

type LoaderOption

type LoaderOption func(*Loader)

LoaderOption configures a Loader.

func WithDefaultOperatorBytes

func WithDefaultOperatorBytes(b []byte) LoaderOption

WithDefaultOperatorBytes supplies the embedded fallback operator.md content used when the workspace omits its own operator file. The plugin package embeds the file (workspace cannot reach across to a sibling package's go:embed) and forwards the bytes here.

type LoopConfig

type LoopConfig struct {
	MaxIterations int             `yaml:"max_iterations"`
	Until         []Predicate     `yaml:"until"`
	OnExhausted   ExhaustedAction `yaml:"on_exhausted"`
}

LoopConfig declares that the entire stage iterates until the Until predicates all pass, or MaxIterations is reached.

type OperatorConfig

type OperatorConfig struct {
	// Body is the rendered template source (workspace body + overlay if any).
	Body string
	// Source tells the operator where Body originated.
	// One of: "workspace", "default", "default+overlay", "workspace+overlay".
	Source string
	// Overlay is the appended overlay text, if any.
	Overlay string
}

OperatorConfig is the resolved operator system-prompt template. Body is raw template text; the orchestrator renders it through text/template at sub-agent spawn time.

type OutputFormat

type OutputFormat string

OutputFormat enumerates artifact serialization formats.

const (
	OutputText OutputFormat = "text"
	OutputJSON OutputFormat = "json"
)

type OutputSpec

type OutputSpec struct {
	Format     OutputFormat `yaml:"format"`
	Schema     string       `yaml:"schema"`
	Persist    PersistMode  `yaml:"persist"`
	Filename   string       `yaml:"filename"`
	Validators []Predicate  `yaml:"validators"`
}

OutputSpec defines what the stage writes and how it's validated.

type PersistMode

type PersistMode string

PersistMode controls where the stage output is preserved between stages.

const (
	PersistContext PersistMode = "context"
	PersistFileRef PersistMode = "file_ref"
	PersistBoth    PersistMode = "both"
)

type Predicate

type Predicate struct {
	Type PredicateType `yaml:"type"`

	// Name disambiguates multiple predicates of the same type in failure
	// feedback. Defaults to "<type>_<index>".
	Name string `yaml:"name,omitempty"`

	// SchemaPath is the JSON-schema file path (valid for type=schema).
	SchemaPath string `yaml:"schema,omitempty"`

	// Regex predicate fields.
	Pattern string      `yaml:"pattern,omitempty"`
	Anchor  RegexAnchor `yaml:"anchor,omitempty"`
	Message string      `yaml:"message,omitempty"`

	// LLM predicate fields.
	Rubric string `yaml:"rubric,omitempty"`
	// Model is reinterpreted as a posture name (not raw model name) in
	// Nexus' role-based model registry world.
	Model string `yaml:"model,omitempty"`

	// Command predicate fields.
	Run string `yaml:"run,omitempty"`
	// TimeoutSeconds overrides the plugin's default command timeout.
	TimeoutSeconds int `yaml:"timeout_seconds,omitempty"`

	// Native predicate fields.
	Handler string         `yaml:"handler,omitempty"`
	Args    map[string]any `yaml:"args,omitempty"`

	// Human predicate fields.
	Prompt                    string `yaml:"prompt,omitempty"`
	RequireFeedbackOnContinue *bool  `yaml:"require_feedback_on_continue,omitempty"`
	// contains filtered or unexported fields
}

Predicate is the unified shape for output validators and loop exit conditions. The Type field discriminates; only the relevant per-type fields are populated. The loader validates that required fields for the declared type are present and compiles regex/jq/schema at load.

func (*Predicate) CompiledRegex

func (p *Predicate) CompiledRegex() *regexp.Regexp

CompiledRegex returns the pre-compiled pattern for a regex predicate. Nil for non-regex predicates or when the pattern failed to compile.

func (*Predicate) SetCompiledRegex

func (p *Predicate) SetCompiledRegex(re *regexp.Regexp)

SetCompiledRegex installs a pre-compiled regex on the predicate. The loader calls this internally; callers synthesizing predicates outside the loader (e.g. tests, or future stage-output predicate synthesizers) use it to wire the regex without re-exporting the field.

type PredicateType

type PredicateType string

PredicateType enumerates the six predicate kinds.

const (
	PredSchema  PredicateType = "schema"
	PredRegex   PredicateType = "regex"
	PredNative  PredicateType = "native"
	PredCommand PredicateType = "command"
	PredLLM     PredicateType = "llm"
	PredHuman   PredicateType = "human"
)

type RegexAnchor

type RegexAnchor string

RegexAnchor scopes regex evaluation within the candidate body.

const (
	AnchorFirstLine RegexAnchor = "first_line"
	AnchorLastLine  RegexAnchor = "last_line"
	AnchorWhole     RegexAnchor = "whole"
)

type Skill

type Skill struct {
	// Name is from SKILL.md frontmatter; must match folder name.
	Name string
	// Description is from SKILL.md frontmatter.
	Description string
	// Source identifies which discovery layer found this skill.
	Source SkillSource
	// Path is the absolute path to the skill folder.
	Path string
	// Body is the SKILL.md content after frontmatter.
	Body string
	// References enumerates files under references/, available on demand.
	References []SkillRef
}

Skill is a resolved skill bundle: a folder with a SKILL.md and an optional references/ subfolder. SKILL.md loads inline into the agent's context; references load on demand via a tool.

type SkillRef

type SkillRef struct {
	// Path is relative to the skill's references/ folder.
	Path string
	// Description is optional, sourced from a leading frontmatter or comment.
	Description string
}

SkillRef is one entry under a skill's references/ folder.

type SkillSource

type SkillSource string

SkillSource enumerates the skill discovery layers in precedence order.

const (
	// SkillStageLocal: stages/NN_slug/skills/<name>/
	SkillStageLocal SkillSource = "stage"
	// SkillWorkspace: shared/skills/<name>/
	SkillWorkspace SkillSource = "workspace"
)

type Stage

type Stage struct {
	// ID is derived from the folder name (e.g. "02_script") and may be
	// echoed in front-matter id.
	ID string
	// Display is the optional human-readable label. Derived from
	// front-matter display, the contract body's first non-empty line, or
	// (last-ditch) ID.
	Display string
	// Folder is the absolute path to the stage folder.
	Folder string
	// Role is the contract body (after frontmatter), rendered into the
	// operator prompt at dispatch.
	Role string
	// Turns governs inner-loop behavior within a single stage invocation.
	Turns TurnConfig
	// HumanGate declares where human review fires at the stage boundary.
	HumanGate HumanGate
	// OnError governs non-validator stage failure handling.
	OnError ErrorPolicy
	// Loop is nil for non-looping stages.
	Loop *LoopConfig
	// FanOut is nil for non-fan-out stages.
	FanOut *FanOutConfig
	// Output declares what the stage writes and how it's validated.
	Output OutputSpec
	// Inputs declares what files the stage reads.
	Inputs InputScope
	// Agent configures the sub-agent (model role, tools, posture, budget).
	Agent AgentSpec
	// Verifiers are verifier IDs declared for this stage.
	Verifiers []string
	// Skills are resolved skill bundles keyed by name. Stage-local can
	// shadow workspace-shared.
	Skills map[string]*Skill
}

Stage is a single step in the workflow. Each stage runs as a sub-agent with a scoped context (operator prompt + this stage's grounding + declared prior artifacts).

type TurnConfig

type TurnConfig struct {
	Policy TurnPolicy `yaml:"policy"`
	// Max defaults to 1 for Fixed and 3 for UntilValid.
	Max int `yaml:"max"`
}

TurnConfig governs inner-loop behavior within a single stage invocation. See LoopConfig for cross-invocation iteration.

type TurnPolicy

type TurnPolicy string

TurnPolicy enumerates how the inner-turn loop terminates.

const (
	// TurnsFixed runs Turns.Max turns unconditionally (default).
	TurnsFixed TurnPolicy = "fixed"
	// TurnsUntilValid retries up to Turns.Max times while validators fail.
	TurnsUntilValid TurnPolicy = "until_valid"
	// TurnsUntilHumanApproves loops while the human reviewer rejects.
	TurnsUntilHumanApproves TurnPolicy = "until_human_approves"
)

type Workflow

type Workflow struct {
	// Root is the absolute path of the workspace root.
	Root string
	// LayerNames are the resolved file/folder name overrides.
	LayerNames LayerNames
	// Operator is the resolved operator system-prompt template.
	Operator OperatorConfig
	// Defaults are the workspace-level defaults from icm.yaml.
	Defaults WorkspaceDefaults
	// WorkspaceDoc is the raw body of workspace.md.
	WorkspaceDoc string
	// Stages are in execution order (sorted by numeric folder prefix).
	Stages []Stage
	// Verifiers are keyed by ID.
	Verifiers map[string]*Stage
}

Workflow is the in-memory representation of a loaded workspace. Produced by LoadWorkspace; consumed by the orchestrator.

func LoadWorkspace

func LoadWorkspace(root string, opts ...LoaderOption) (*Workflow, error)

LoadWorkspace reads a workspace folder and produces a validated *Workflow. Returns *LoadErrors (a multi-error) when validation fails. The workspace is not modified.

type WorkspaceDefaults

type WorkspaceDefaults struct {
	// TurnPolicy is the default per-stage turn policy.
	TurnPolicy TurnPolicy `yaml:"turn_policy"`
	// HumanGate is the default per-stage human-gate position.
	HumanGate HumanGate `yaml:"human_gate"`
	// OnError is the default per-stage error policy.
	OnError ErrorPolicy `yaml:"on_error"`
	// JudgePosture is the posture name used for `type: llm` predicates
	// when the predicate does not name an explicit `model:` posture.
	JudgePosture string `yaml:"judge_posture"`
	// Agent is the default agent spec applied when a stage omits one.
	Agent AgentSpec `yaml:"agent"`
}

WorkspaceDefaults are the workspace-level defaults from icm.yaml. Stage-level fields override these; absent fields fall back to library defaults at dispatch.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL