icmtypes

package
v0.32.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 2 Imported by: 0

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

View Source
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.

View Source
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

func FormatTurn(ev ICMTurn) (phase, content string)

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

func InstanceSuffix(instanceID string) string

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

func PredicateSchemaName(instanceID, stageID, predicateName string) string

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

func StageOutputSchemaName(instanceID, stageID string) string

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

func StagePostureName(instanceID, stageID string) string

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).

Jump to

Keyboard shortcuts

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