Documentation
¶
Overview ¶
Package icmtypes holds tiny shared value types used by both the nexus.workflows.icm plugin (events.go) and its session and predicates subpackages (artifact sidecars, run state, predicate failure events).
It exists solely to break would-be import cycles: leaf packages (session, predicates) cannot import the main icm package because the main icm package imports them. Anything both halves need to agree on lives here.
Index ¶
- Constants
- func FormatFanoutItem(ev ICMFanoutItem) (phase, content string)
- func FormatPredicateFailed(ev ICMPredicateFailed) (phase, content string)
- func FormatRunCompleted(ev ICMRunCompleted) (phase, content string)
- func FormatRunHalted(ev ICMRunHalted) (phase, content string)
- func FormatRunStarted(ev ICMRunStarted) (phase, content string)
- func FormatStageCompleted(ev ICMStageCompleted) (phase, content string)
- func FormatStageFailed(ev ICMStageFailed) (phase, content string)
- func FormatStageIteration(ev ICMStageIteration) (phase, content string)
- func FormatStageStarted(ev ICMStageStarted) (phase, content string)
- func FormatTurn(ev ICMTurn) (phase, content string)
- func InstanceSuffix(instanceID string) string
- func PredicateSchemaName(instanceID, stageID, predicateName string) string
- func StageOutputSchemaName(instanceID, stageID string) string
- func StagePostureName(instanceID, stageID string) string
- type ConditionResult
- type ICMFanoutItem
- type ICMPredicateFailed
- type ICMRunCompleted
- type ICMRunHalted
- type ICMRunStarted
- type ICMStageCompleted
- type ICMStageFailed
- type ICMStageIteration
- type ICMStageStarted
- type ICMTurn
Constants ¶
const ( ICMRunStartedVersion = 1 ICMRunCompletedVersion = 1 ICMRunHaltedVersion = 1 ICMStageStartedVersion = 1 ICMStageCompletedVersion = 1 ICMStageFailedVersion = 1 ICMStageIterationVersion = 1 ICMTurnVersion = 1 ICMFanoutItemVersion = 1 )
Schema-version constants for the icm.* lifecycle event payloads. ICM emits these on top of the generic plan.created/plan.progress surface so basic UIs see stage-level transitions while richer UIs render iteration/turn/item detail.
These constants and their payload structs live in icmtypes so the runtime sub-package (which contains the orchestrator) can emit them without forming the icm → runtime → icm import cycle.
const ICMPredicateFailedVersion = 1
ICMPredicateFailedVersion is the schema version emitted with each ICMPredicateFailed event payload.
Variables ¶
This section is empty.
Functions ¶
func FormatFanoutItem ¶
func FormatFanoutItem(ev ICMFanoutItem) (phase, content string)
FormatFanoutItem renders an ICMFanoutItem event for any item lifecycle boundary (active, completed, failed).
func FormatPredicateFailed ¶
func FormatPredicateFailed(ev ICMPredicateFailed) (phase, content string)
FormatPredicateFailed renders an ICMPredicateFailed event with the container ("output.validators", "loop.until", or "verifier") and the predicate name. The feedback string can be long — the caller may truncate before sending to a constrained UI.
func FormatRunCompleted ¶
func FormatRunCompleted(ev ICMRunCompleted) (phase, content string)
FormatRunCompleted renders an ICMRunCompleted event.
func FormatRunHalted ¶
func FormatRunHalted(ev ICMRunHalted) (phase, content string)
FormatRunHalted renders an ICMRunHalted event.
func FormatRunStarted ¶
func FormatRunStarted(ev ICMRunStarted) (phase, content string)
FormatRunStarted renders an ICMRunStarted event.
func FormatStageCompleted ¶
func FormatStageCompleted(ev ICMStageCompleted) (phase, content string)
FormatStageCompleted renders an ICMStageCompleted event. Includes iteration count and convergence flag when relevant.
func FormatStageFailed ¶
func FormatStageFailed(ev ICMStageFailed) (phase, content string)
FormatStageFailed renders an ICMStageFailed event.
func FormatStageIteration ¶
func FormatStageIteration(ev ICMStageIteration) (phase, content string)
FormatStageIteration renders an ICMStageIteration event. The first iteration of a stage has no exit failures yet; later iterations list the failing predicate names so the reader sees what didn't converge.
func FormatStageStarted ¶
func FormatStageStarted(ev ICMStageStarted) (phase, content string)
FormatStageStarted renders an ICMStageStarted event as a one-line progress string suitable for the thinking-step stream. Phase ("icm.stage") is returned alongside so subscribers can label the row consistently.
func FormatTurn ¶
FormatTurn renders an ICMTurn event. Turns are the inner retry layer inside a single stage invocation; the failures here come from output.validators that rejected the artifact.
func InstanceSuffix ¶
InstanceSuffix returns the portion of a plugin instance ID after the last "/" separator. Multi-instance ICM plugins use the form "nexus.workflows.icm/<suffix>" (e.g. "nexus.workflows.icm/script"); the default instance has no suffix.
Lives in icmtypes so registration (runtime) and dispatch (predicates) can both call the same helper without forming an import cycle.
func PredicateSchemaName ¶
PredicateSchemaName returns the canonical schema-registry name for a per-predicate JSON schema (output validator or loop `until` condition using type=schema). Format: "<stage_posture>.<predicate_name>".
Predicates author the workspace-relative file path in YAML; the icm plugin reads + registers each schema under the name produced here at Ready(). The predicate dispatcher MUST use this same helper to look up the registered schema — the raw file path is registration-time metadata, not a runtime lookup key.
func StageOutputSchemaName ¶
StageOutputSchemaName returns the engine SchemaRegistry key used for a stage's `output` schema (when output.format=json and output.schema is set). The synthesized "output" predicate that backs that schema shares this name with the predicate variant — see PredicateSchemaName.
func StagePostureName ¶
StagePostureName returns the registry name a stage (or verifier) posture is registered under. Default instance: "icm.<stageID>". Suffixed instance: "icm.<suffix>.<stageID>".
Both registration in the plugin and lookup in the orchestrator must pass through this helper to stay in sync.
Types ¶
type ConditionResult ¶
type ConditionResult struct {
Type string `json:"type"`
Name string `json:"name,omitempty"`
Verdict string `json:"verdict"`
Feedback string `json:"feedback,omitempty"`
Score *float64 `json:"score,omitempty"`
}
ConditionResult is the persisted form of a predicate outcome. It appears in icm.* event payloads and in the per-artifact .icm.json sidecar.
type ICMFanoutItem ¶
type ICMFanoutItem struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
ItemID string `json:"item_id"`
Index int `json:"index"`
Total int `json:"total"`
Status string `json:"status"` // active | completed | failed
Error string `json:"error,omitempty"`
}
ICMFanoutItem fires at each item lifecycle boundary in a fan-out stage (active → completed | failed).
type ICMPredicateFailed ¶
type ICMPredicateFailed struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
ItemID string `json:"item_id,omitempty"`
Container string `json:"container"` // output.validators | loop.until | verifier
PredicateName string `json:"predicate_name"`
PredicateType string `json:"predicate_type"`
Feedback string `json:"feedback,omitempty"`
}
ICMPredicateFailed fires whenever any predicate evaluation returns Verdict=false. Single source of truth for failure visibility — pass paths are not emitted.
Lives in icmtypes (rather than the main icm package) so the predicates sub-package can emit it without forming an import cycle (predicates → icm → predicates). The main icm package re-exports this type via a type alias for ergonomic use by subscribers.
type ICMRunCompleted ¶
type ICMRunCompleted struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StagesRun int `json:"stages_run"`
AggregatePath string `json:"aggregate_path,omitempty"`
ElapsedSeconds int64 `json:"elapsed_seconds"`
}
ICMRunCompleted fires once all stages finish without halt.
type ICMRunHalted ¶
type ICMRunHalted struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
Reason string `json:"reason"`
HaltedAtStage string `json:"halted_at_stage,omitempty"`
Cancelled bool `json:"cancelled,omitempty"`
ElapsedSeconds int64 `json:"elapsed_seconds"`
}
ICMRunHalted fires when a stage error policy halts the run, a human gate rejects, or the run context is cancelled.
type ICMRunStarted ¶
type ICMRunStarted struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
InstanceID string `json:"instance_id"`
WorkspaceRoot string `json:"workspace_root"`
WorkspaceName string `json:"workspace_name"`
Stages int `json:"stages"`
}
ICMRunStarted is emitted after workspace load + plan.created, before the first stage dispatches.
type ICMStageCompleted ¶
type ICMStageCompleted struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
ArtifactPath string `json:"artifact_path,omitempty"`
IterationsRun int `json:"iterations_run,omitempty"`
ConvergenceFailed bool `json:"convergence_failed,omitempty"`
}
ICMStageCompleted fires after the artifact is written and any end gate resolves.
type ICMStageFailed ¶
type ICMStageFailed struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
Reason string `json:"reason"`
}
ICMStageFailed fires when a stage halts due to dispatch error policy, rejected gate, or predicate exhaustion under loop on_exhausted: error.
type ICMStageIteration ¶
type ICMStageIteration struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
ItemID string `json:"item_id,omitempty"`
Iteration int `json:"iteration"`
MaxIterations int `json:"max_iterations"`
ExitFailures []ConditionResult `json:"exit_failures,omitempty"`
}
ICMStageIteration fires once per loop iteration, immediately before the iteration's runInvocation. ItemID is populated for fan-out + loop composition.
type ICMStageStarted ¶
type ICMStageStarted struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
PostureName string `json:"posture_name"`
Order int `json:"order"`
}
ICMStageStarted fires when stage execution begins (before any human_gate: start gate).
type ICMTurn ¶
type ICMTurn struct {
SchemaVersion int `json:"_schema_version"`
RunID string `json:"run_id"`
StageID string `json:"stage_id"`
ItemID string `json:"item_id,omitempty"`
Iteration int `json:"iteration,omitempty"`
Turn int `json:"turn"`
MaxTurns int `json:"max_turns"`
LastFailures []ConditionResult `json:"last_failures,omitempty"`
}
ICMTurn fires after each turn within an invocation (richer UIs only; stage-level progress already surfaces via plan.progress).