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 ¶
- func Validate(root string, opts ...LoaderOption) error
- type AgentBudget
- type AgentSpec
- type ErrorPolicy
- type ExhaustedAction
- type FanOutConfig
- type HumanGate
- type InputScope
- type ItemFailureAction
- type LayerNames
- type LoadError
- type LoadErrors
- type Loader
- type LoaderOption
- type LoopConfig
- type OperatorConfig
- type OutputFormat
- type OutputSpec
- type PersistMode
- type Predicate
- type PredicateType
- type RegexAnchor
- type Skill
- type SkillRef
- type SkillSource
- type Stage
- type TurnConfig
- type TurnPolicy
- type Workflow
- type WorkspaceDefaults
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.
type InputScope ¶
type InputScope struct {
// Grounding paths are relative to the stage's grounding/ folder.
Grounding []string `yaml:"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.
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.
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 ¶
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 ¶
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.