agentosplan

package
v0.0.0-...-c4ca558 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MIMEApplicationJSON = "application/json"
	MIMETextPlain       = "text/plain"
)

MIME types for artifact payload encoding.

View Source 
const (
	SignalPayloadNodeID = agentoscore.SignalPayloadNodeID
	SignalPayloadReason = agentoscore.SignalPayloadReason
)

Variables

This section is empty.

Functions

func ArtifactIDFromRef 

func ArtifactIDFromRef(planID, idempotencyKey string) string

ArtifactIDFromRef creates the stable artifact identity used when callers do not provide one explicitly. Artifact IDs are globally addressed, so the plan identity participates in the generated ID.

func ArtifactOutputDocument 

func ArtifactOutputDocument(refs []agentoscore.ArtifactRef) map[string]any

ArtifactOutputDocument returns the stable JSON document shape validated by capability output schemas.

func ArtifactPublishIdempotencyKey 

func ArtifactPublishIdempotencyKey(planID, nodeID, runID, artifactName string) (string, error)

ArtifactPublishIdempotencyKey creates the stable idempotency key for publishing one node output artifact.

func ArtifactSchemaRegistrationIdempotencyKey 

func ArtifactSchemaRegistrationIdempotencyKey(schema agentos.ArtifactSchema) (string, error)

ArtifactSchemaRegistrationIdempotencyKey returns a stable key for one schema declaration. A changed schema intentionally produces a different key.

func AuditIDFromRef 

func AuditIDFromRef(ref AuditRef) string

AuditIDFromRef creates the stable audit identity used when callers do not provide one explicitly. Idempotency is tenant and plan scoped.

func BudgetExceeded 

func BudgetExceeded(policy agentos.PlanPolicy, usage agentos.PlanBudgetUsage) bool

BudgetExceeded reports whether a plan has spent beyond its configured budget.

func BudgetExceededControlIdempotencyKey 

func BudgetExceededControlIdempotencyKey(planID string, usage agentos.PlanBudgetUsage, budgetCents int64) (string, error)

BudgetExceededControlIdempotencyKey creates the parent idempotency key for propagating cancellation after a plan budget guard trips.

func BudgetExceededReason 

func BudgetExceededReason(policy agentos.PlanPolicy, usage agentos.PlanBudgetUsage) string

BudgetExceededReason returns a stable public failure reason for budget guard failures.

func BuildPlanDebugTraces 

func BuildPlanDebugTraces(events []agentos.PlanEvent) ([]agentos.PlanDebugTrace, error)

BuildPlanDebugTraces projects typed debug records from durable PlanEvents.

func BuildPlanMetricSamplesFromState 

func BuildPlanMetricSamplesFromState(ctx context.Context, spec *agentos.RunPlanSpec, state PlanMetricProjectionState, events []agentos.PlanEvent) ([]PlanMetricSample, PlanMetricProjectionState, error)

BuildPlanMetricSamplesFromState projects metrics from an incremental event batch and returns the next durable projection state.

func CapabilityRegistrationIdempotencyKey 

func CapabilityRegistrationIdempotencyKey(capability *agentos.Capability) (string, error)

CapabilityRegistrationIdempotencyKey returns a stable key for one capability declaration. A changed declaration intentionally produces a different key.

func DecodeArtifactPayload 

func DecodeArtifactPayload(data []byte, mediaType string) (any, error)

DecodeArtifactPayload converts stored artifact bytes back into their public payload representation.

func DecodeWireJSON 

func DecodeWireJSON[T any](data []byte) (T, error)

DecodeWireJSON decodes public RunPlan authoring JSON without accepting unknown struct fields. Free-form maps such as RunSpec.Input remain open.

func DecodeWireYAML 

func DecodeWireYAML[T any](data []byte) (T, error)

DecodeWireYAML decodes public RunPlan authoring YAML using the same strict field contract as JSON.

func DescribeRunPlan 

func DescribeRunPlan(spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) (agentos.RunPlanDescription, error)

DescribeRunPlan builds the public topology/control-plane view from the latest durable plan snapshot.

func DigestArtifactPayload 

func DigestArtifactPayload(payload []byte) string

DigestArtifactPayload returns the stable digest recorded on ArtifactRef.

func EncodeArtifactPayload 

func EncodeArtifactPayload(payload any, mediaType string) (data []byte, normalizedMediaType string, err error)

EncodeArtifactPayload converts an artifact payload into stable bytes for storage and idempotency metadata.

func NodeControlIdempotencyKey 

func NodeControlIdempotencyKey(planID, nodeID string, operation agentoscore.ControlOperation, parentKey string) (string, error)

NodeControlIdempotencyKey creates the stable idempotency key for propagating one plan-level control operation to one backend-owned child run.

func NodeStartIdempotencyKey 

func NodeStartIdempotencyKey(planID, nodeID string, attempt int32) (string, error)

NodeStartIdempotencyKey creates the stable idempotency key for starting one backend-owned child run.

func NodeTimeoutControlIdempotencyKey 

func NodeTimeoutControlIdempotencyKey(planID, nodeID, runID string) (string, error)

NodeTimeoutControlIdempotencyKey creates the stable idempotency key for canceling a timed-out child run.

func NormalizeArtifactSchema 

func NormalizeArtifactSchema(schema agentos.ArtifactSchema) (agentos.ArtifactSchema, error)

NormalizeArtifactSchema checks one schema declaration and returns its canonical JSON representation for stable hashing and durable storage.

func NormalizeDurableTimestamp 

func NormalizeDurableTimestamp(timestamp time.Time) time.Time

NormalizeDurableTimestamp returns the canonical timestamp precision used by durable stores. Postgres timestamptz stores microseconds, and JSON snapshots constrained against timestamp columns must match that precision exactly.

func NormalizePlanEventAppendRequest 

func NormalizePlanEventAppendRequest(event *agentos.PlanEvent) agentos.PlanEvent

NormalizePlanEventAppendRequest removes durable-store-owned identity fields before an append request is persisted or compared for idempotency.

func PlanAuditRecordFromAuditRecord 

func PlanAuditRecordFromAuditRecord(record *AuditRecord) agentos.PlanAuditRecord

PlanAuditRecordFromAuditRecord projects an internal audit record into the public AgentOS audit DTO.

func PlanCommandIDFromRef 

func PlanCommandIDFromRef(ref PlanCommandRef) string

PlanCommandIDFromRef creates the stable command identity used when callers do not provide one explicitly. Idempotency is tenant and plan scoped.

func PlanDebugTraceFromEvent 

func PlanDebugTraceFromEvent(event *agentos.PlanEvent) (agentos.PlanDebugTrace, bool, error)

PlanDebugTraceFromEvent extracts typed debug details from one durable event.

func PlanEventFromStateEvent 

func PlanEventFromStateEvent(spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus, event *StateEvent) (agentos.PlanEvent, string, error)

func PlanSignalCancelControlIdempotencyKey 

func PlanSignalCancelControlIdempotencyKey(planID string, signal *agentoscore.Signal) (string, error)

PlanSignalCancelControlIdempotencyKey creates the parent idempotency key for cancellation propagated by a terminal plan signal such as operator reject.

func PlanSignalNodeID 

func PlanSignalNodeID(signal *agentoscore.Signal) (string, error)

PlanSignalNodeID returns the target node id from a node-scoped plan signal.

func PlanSignalReason 

func PlanSignalReason(signal *agentoscore.Signal) string

PlanSignalReason returns an optional human/system reason from a plan signal.

func PlanTimedOut 

func PlanTimedOut(policy agentos.PlanPolicy, startedAt, now time.Time) bool

PlanTimedOut reports whether the plan-level wall-clock timeout has elapsed.

func PlanTimeoutControlIdempotencyKey 

func PlanTimeoutControlIdempotencyKey(planID string, startedAt time.Time, timeoutSeconds int64) (string, error)

PlanTimeoutControlIdempotencyKey creates the parent idempotency key for propagating cancellation after a plan-level timeout guard trips.

func PlanTimeoutReason 

func PlanTimeoutReason(policy agentos.PlanPolicy) string

PlanTimeoutReason returns a stable public failure reason for plan-level timeout failures.

func RegisterArtifactSchemas 

func RegisterArtifactSchemas(ctx context.Context, registry ArtifactSchemaRegistry, schemas []agentos.ArtifactSchema) error

RegisterArtifactSchemas registers a batch of schema declarations using content-addressed idempotency keys.

func RegisterCapabilities 

func RegisterCapabilities(ctx context.Context, registry CapabilityRegistry, capabilities []agentos.Capability) error

RegisterCapabilities registers a batch of backend capabilities into a durable catalog using content-addressed idempotency keys.

func ResolveRunInput 

func ResolveRunInput(ctx context.Context, store ArtifactStore, expressions ValueExpressionCompiler, spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus, node *agentos.PlanNodeSpec, edges []agentos.PlanEdgeSpec) (map[string]any, error)

ResolveRunInput applies plan/node input mappings and dereferences artifact refs before a backend-owned child run starts.

func ScopePlanEventToSpec 

func ScopePlanEventToSpec(event *agentos.PlanEvent, spec *agentos.RunPlanSpec) (agentos.PlanEvent, error)

ScopePlanEventToSpec assigns the durable plan scope to an append request and rejects caller-provided scope that does not match the stored plan.

func StateEventIdempotencyKey 

func StateEventIdempotencyKey(planID string, event *StateEvent) (string, error)

StateEventIdempotencyKey creates a stable key for activity retries and workflow replays that attempt to persist the same reducer transition.

func ValidateArtifactPayloadsAgainstSchemas 

func ValidateArtifactPayloadsAgainstSchemas(ctx context.Context, store ArtifactStore, catalog ArtifactSchemaCatalog, plan *agentos.RunPlanSpec, node *agentos.PlanNodeSpec, refs []agentoscore.ArtifactRef) error

ValidateArtifactPayloadsAgainstSchemas validates stored artifact payloads against their declared schema_ref contracts.

func ValidateArtifactPublishIdempotency 

func ValidateArtifactPublishIdempotency(existing, requested *agentoscore.ArtifactRef) error

ValidateArtifactPublishIdempotency verifies that a repeated artifact publish request is the same durable artifact request that originally claimed the key.

func ValidateArtifactSchema 

func ValidateArtifactSchema(schema agentos.ArtifactSchema) error

ValidateArtifactSchema checks one schema declaration before registration.

func ValidateArtifactSchemaRefs 

func ValidateArtifactSchemaRefs(ctx context.Context, catalog ArtifactSchemaCatalog, nodeID string, specs []agentos.ArtifactSpec) error

ValidateArtifactSchemaRefs verifies that every declared schema_ref resolves to a valid JSON Schema document.

func ValidateArtifactSchemaRegistrationIdempotency 

func ValidateArtifactSchemaRegistrationIdempotency(existing, requested agentos.ArtifactSchema) error

ValidateArtifactSchemaRegistrationIdempotency rejects replaying one idempotency key for a different schema declaration.

func ValidateArtifactSpecs 

func ValidateArtifactSpecs(nodeID string, specs []agentos.ArtifactSpec) error

ValidateArtifactSpecs validates declared node output contracts.

func ValidateArtifactsAgainstSpecs 

func ValidateArtifactsAgainstSpecs(nodeID string, specs []agentos.ArtifactSpec, refs []agentoscore.ArtifactRef) error

ValidateArtifactsAgainstSpecs validates published artifact refs against a node's declared output contract. An empty contract intentionally accepts any well-formed artifact refs so legacy-free callers can opt into strict outputs by declaring Outputs.

func ValidateAuditIdempotency 

func ValidateAuditIdempotency(existing, requested *AuditRecord) error

ValidateAuditIdempotency verifies that an audit idempotency key is replayed for the same control-plane action.

func ValidateAuditNodeRunInPlan 

func ValidateAuditNodeRunInPlan(record *AuditRecord, spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) error

ValidateAuditNodeRunInPlan validates node/run ownership against an in-memory durable plan snapshot.

func ValidateAuditNodeRunPair 

func ValidateAuditNodeRunPair(record *AuditRecord) error

ValidateAuditNodeRunPair validates the control-plane ownership shape for node-scoped audit records. Plan-level audits leave both fields empty; child run audits must identify both the node and the backend-owned run.

func ValidateAuditRef 

func ValidateAuditRef(ref AuditRef) error

func ValidateCapability 

func ValidateCapability(capability *agentos.Capability) error

ValidateCapability checks the public capability declaration before it is inserted into a catalog or used by a RunPlan validator.

func ValidateCapabilityOutputArtifacts 

func ValidateCapabilityOutputArtifacts(nodeID string, outputSchema json.RawMessage, refs []agentoscore.ArtifactRef) error

ValidateCapabilityOutputArtifacts validates published artifact refs against a capability output JSON Schema. The validated document shape is: 

{"artifacts": [agentoscore.ArtifactRef JSON objects]}

func ValidateCapabilityRegistrationIdempotency 

func ValidateCapabilityRegistrationIdempotency(existing, requested *agentos.Capability) error

ValidateCapabilityRegistrationIdempotency rejects replaying one idempotency key for a different capability declaration.

func ValidateNewRefOnlyArtifactPublish 

func ValidateNewRefOnlyArtifactPublish(ref *agentoscore.ArtifactRef) error

ValidateNewRefOnlyArtifactPublish rejects first-time ref-only artifact publishes that attempt to claim blob metadata without writing payload through the ArtifactStore. Idempotent replays of an existing artifact are validated against the stored ref before this check is needed.

func ValidatePlanArtifactScope 

func ValidatePlanArtifactScope(scope *agentos.PlanArtifactScope) error

ValidatePlanArtifactScope validates durable artifact query scope.

func ValidatePlanAuditScope 

func ValidatePlanAuditScope(scope *agentos.PlanAuditScope) error

ValidatePlanAuditScope validates durable audit query scope.

func ValidatePlanCommandDeliveredAudit 

func ValidatePlanCommandDeliveredAudit(command *PlanCommandRecord, audit *AuditRecord) error

ValidatePlanCommandDeliveredAudit verifies that the audit record for a delivered command matches the original command envelope.

func ValidatePlanCommandIdempotency 

func ValidatePlanCommandIdempotency(existing, requested *PlanCommandRecord) error

ValidatePlanCommandIdempotency verifies that a command idempotency key is replayed for the same durable control-plane command.

func ValidatePlanCommandRef 

func ValidatePlanCommandRef(ref PlanCommandRef) error

func ValidatePlanCommandStatusTransition 

func ValidatePlanCommandStatusTransition(current, next PlanCommandStatus) error

ValidatePlanCommandStatusTransition enforces the durable outbox lifecycle. Delivered is terminal; failed commands remain recoverable and may later be delivered or have their failure reason refreshed.

func ValidatePlanDebugTraceScope 

func ValidatePlanDebugTraceScope(scope *agentos.PlanDebugTraceScope) error

ValidatePlanDebugTraceScope validates durable debug trace query scope.

func ValidatePlanEventIdempotency 

func ValidatePlanEventIdempotency(existing, requested *agentos.PlanEvent) error

ValidatePlanEventIdempotency verifies that a repeated event append request is the same durable event request that originally claimed the key. Store- assigned identity fields are only compared when the replay explicitly sets them.

func ValidatePlanEventScope 

func ValidatePlanEventScope(scope *agentos.PlanEventScope) error

ValidatePlanEventScope validates durable event history query scope.

func ValidatePlanMetricCheckpointRef 

func ValidatePlanMetricCheckpointRef(checkpoint *PlanMetricCheckpoint, exporterID string, ref agentos.PlanRef) error

ValidatePlanMetricCheckpointRef verifies checkpoint ownership and tenant scope before exporter state is trusted.

func ValidatePlanMetricSample 

func ValidatePlanMetricSample(sample *PlanMetricSample) error

ValidatePlanMetricSample verifies the durable identity and tenant scope of a projected PlanMetricSample before a sink records it.

func ValidatePlanMetricSampleIdempotency 

func ValidatePlanMetricSampleIdempotency(existing, requested *PlanMetricSample) error

ValidatePlanMetricSampleIdempotency verifies that a replayed metric sample is the same durable fact as the existing sample for its idempotency key.

func ValidatePlanRef 

func ValidatePlanRef(ref agentos.PlanRef) error

ValidatePlanRef requires the public control-plane reference to carry tenant scope. PlanID alone is not a sufficient production boundary.

func ValidatePlanSignal 

func ValidatePlanSignal(signal *agentoscore.Signal) error

ValidatePlanSignal validates signals owned by the RunPlan control plane.

func ValidatePlanStartIdempotency 

func ValidatePlanStartIdempotency(existing, requested *agentos.RunPlanSpec) error

ValidatePlanStartIdempotency verifies that a repeated plan start request is the same durable request that originally claimed the idempotency key.

func ValidatePlanStateIdentity 

func ValidatePlanStateIdentity(existing, requested *agentos.RunPlanSpec) error

ValidatePlanStateIdentity verifies that a workflow-owned state snapshot keeps the immutable plan identity and request envelope unchanged. Topology may evolve through validated PlanDelta application, so Nodes and Edges are not part of this comparison.

func ValidatePlanStreamScope 

func ValidatePlanStreamScope(scope *agentos.PlanStreamScope) error

ValidatePlanStreamScope validates event replay/subscribe scope.

func ValidatePlanTenantAccess 

func ValidatePlanTenantAccess(ref agentos.PlanRef, spec *agentos.RunPlanSpec) error

ValidatePlanTenantAccess returns ErrPlanRouteNotFound for tenant mismatches so callers cannot distinguish missing plans from plans outside their scope.

func ValidatePlanTransitionIdempotency 

func ValidatePlanTransitionIdempotency(existingDigest string, requested PlanTransitionSnapshotIdentity) error

ValidatePlanTransitionIdempotency verifies that a replayed reducer transition carries the same durable snapshot that originally claimed the transition idempotency key.

func ValidateRunPlanScope 

func ValidateRunPlanScope(spec *agentos.RunPlanSpec) error

ValidateRunPlanScope requires durable plans to carry their tenant boundary.

func Variables 

func Variables(spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) map[string]any

Variables returns the fixed CEL environment for plan evaluation.

Types

type ArtifactPlanDeltaProvider 

type ArtifactPlanDeltaProvider struct {
	Store ArtifactStore
}

ArtifactPlanDeltaProvider materializes plan expansion proposals from explicit plan_delta artifacts published by completed child runs.

func NewArtifactPlanDeltaProvider 

func NewArtifactPlanDeltaProvider(store ArtifactStore) ArtifactPlanDeltaProvider

func (ArtifactPlanDeltaProvider) NextPlanDelta 

func (p ArtifactPlanDeltaProvider) NextPlanDelta(ctx context.Context, input *PlanDeltaInput) (delta PlanDelta, expanded bool, err error)

type ArtifactSchemaCatalog 

type ArtifactSchemaCatalog interface {
	GetArtifactSchema(ctx context.Context, schemaRef string) (json.RawMessage, bool, error)
}

ArtifactSchemaCatalog resolves JSON Schemas referenced by ArtifactSpec.

type ArtifactSchemaRegistry 

type ArtifactSchemaRegistry interface {
	RegisterArtifactSchema(ctx context.Context, schema agentos.ArtifactSchema, idempotencyKey string) (agentos.ArtifactSchema, bool, error)
}

ArtifactSchemaRegistry persists schema declarations referenced by RunPlan artifact contracts.

type ArtifactStore 

type ArtifactStore interface {
	Put(ctx context.Context, artifact *agentoscore.ArtifactRef, payload any, idempotencyKey string) (agentoscore.ArtifactRef, error)
	Get(ctx context.Context, scope *agentos.PlanArtifactScope) (agentoscore.ArtifactRef, any, error)
	List(ctx context.Context, scope *agentos.PlanArtifactScope) ([]agentoscore.ArtifactRef, error)
}

ArtifactStore stores artifacts outside workflow history. Reads must carry the full account/project plan scope because artifact IDs are not a tenant boundary.

type AuditAction 

type AuditAction string

AuditAction identifies durable control-plane actions. 

const (
	AuditActionPlanStart   AuditAction = "plan.start"
	AuditActionPlanSignal  AuditAction = "plan.signal"
	AuditActionPlanControl AuditAction = "plan.control"
)

type AuditRecord 

type AuditRecord struct {
	AuditID        string
	PlanID         string
	AccountID      string
	ProjectID      string
	RunID          string
	NodeID         string
	ActorID        string
	Action         AuditAction
	IdempotencyKey string
	Payload        map[string]any
	CreatedAt      time.Time
}

AuditRecord is a durable control-plane audit entry.

func AuditRecordFromPlanCommand 

func AuditRecordFromPlanCommand(command *PlanCommandRecord) AuditRecord

AuditRecordFromPlanCommand returns the durable audit record that must exist before a command may become delivered. Delivered commands are terminal, so this keeps the control-plane outbox and audit trail in lockstep.

type AuditRef 

type AuditRef struct {
	PlanID         string
	AccountID      string
	ProjectID      string
	IdempotencyKey string
}

AuditRef identifies one idempotent audit record inside a tenant-scoped plan.

func AuditRefFromRecord 

func AuditRefFromRecord(record *AuditRecord) AuditRef

type AuditStore 

type AuditStore interface {
	RecordAudit(ctx context.Context, record *AuditRecord) (AuditRecord, bool, error)
	GetAuditRecord(ctx context.Context, ref AuditRef) (AuditRecord, bool, error)
	ListAuditRecords(ctx context.Context, scope *agentos.PlanAuditScope) ([]agentos.PlanAuditRecord, error)
}

AuditStore persists idempotent control-plane audit records. List operations must carry the full account/project plan scope.

type CELCompiler 

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

CELCompiler compiles deterministic CEL expressions for RunPlan conditions.

func NewCELCompiler 

func NewCELCompiler() (*CELCompiler, error)

NewCELCompiler creates a CEL compiler with the fixed AgentOS plan variables.

func (*CELCompiler) Compile 

func (c *CELCompiler) Compile(expression string) (Expression, error)

Compile validates one expression.

func (*CELCompiler) CompileValue 

func (c *CELCompiler) CompileValue(expression string) (ValueExpression, error)

CompileValue validates one expression that may return any deterministic value.

type CapabilityCatalog 

type CapabilityCatalog interface {
	GetCapability(ctx context.Context, backend agentos.BackendRef, name string) (agentos.Capability, bool, error)
}

CapabilityCatalog exposes backend capabilities available to RunPlan nodes.

type CapabilityRegistry 

type CapabilityRegistry interface {
	RegisterCapability(ctx context.Context, capability *agentos.Capability, idempotencyKey string) (agentos.Capability, bool, error)
}

CapabilityRegistry persists backend capability declarations.

type CapabilitySelectionTrace 

type CapabilitySelectionTrace struct {
	Backend         agentos.BackendRef             `json:"backend"`
	Capability      string                         `json:"capability"`
	Signals         []agentoscore.SignalType       `json:"signals,omitempty"`
	Controls        []agentoscore.ControlOperation `json:"controls,omitempty"`
	HasInputSchema  bool                           `json:"has_input_schema,omitempty"`
	HasOutputSchema bool                           `json:"has_output_schema,omitempty"`
}

CapabilitySelectionTrace is the durable debug view for a selected backend capability without embedding potentially large JSON schemas in event history.

func NewCapabilitySelectionTrace 

func NewCapabilitySelectionTrace(capability *agentos.Capability) CapabilitySelectionTrace

NewCapabilitySelectionTrace creates the event-safe trace projection for a capability selected during plan validation.

type ConditionEvaluationTrace 

type ConditionEvaluationTrace struct {
	Scope       string              `json:"scope"`
	NodeID      string              `json:"node_id,omitempty"`
	EdgeID      string              `json:"edge_id,omitempty"`
	From        string              `json:"from,omitempty"`
	To          string              `json:"to,omitempty"`
	Expression  string              `json:"expression"`
	Result      bool                `json:"result"`
	On          agentos.EdgeTrigger `json:"on,omitempty"`
	ParentState string              `json:"parent_state,omitempty"`
}

ConditionEvaluationTrace records one deterministic CEL condition result used by the scheduler.

type ContinuationDecision 

type ContinuationDecision struct {
	ShouldContinue bool
	Reason         string
}

ContinuationDecision explains whether the current workflow run should continue as new before accumulating more history.

func EvaluateContinuationPolicy 

func EvaluateContinuationPolicy(policy agentos.PlanPolicy, snapshot ContinuationSnapshot) ContinuationDecision

EvaluateContinuationPolicy evaluates PlanPolicy history guards from deterministic workflow snapshots.

type ContinuationSnapshot 

type ContinuationSnapshot struct {
	AppliedTransitions int32
	HistoryEvents      int
}

ContinuationSnapshot is deterministic input for RunPlan continuation policy.

type EventKind 

type EventKind string

EventKind identifies one reducer event. 

const (
	EventPlanStarted         EventKind = "plan.started"
	EventPlanBlocked         EventKind = "plan.blocked"
	EventPlanExpanded        EventKind = "plan.expanded"
	EventPlanApproved        EventKind = "plan.approved"
	EventPlanRejected        EventKind = "plan.rejected"
	EventPlanSucceeded       EventKind = "plan.succeeded"
	EventPlanFailed          EventKind = "plan.failed"
	EventPlanCanceled        EventKind = "plan.canceled"
	EventNodeReady           EventKind = "node.ready"
	EventNodeStarted         EventKind = "node.started"
	EventNodeSucceeded       EventKind = "node.succeeded"
	EventNodeFailed          EventKind = "node.failed"
	EventNodeRetryScheduled  EventKind = "node.retry_scheduled"
	EventNodeSkipped         EventKind = "node.skipped"
	EventNodeCanceled        EventKind = "node.canceled"
	EventNodeInputResolved   EventKind = "node.input_resolved"
	EventCapabilitySelected  EventKind = "capability.selected"
	EventConditionsEvaluated EventKind = "conditions.evaluated"
	EventArtifactsPublished  EventKind = "artifacts.published"
	EventBudgetReported      EventKind = "budget.reported"
)

type ExecutablePlan 

type ExecutablePlan struct {
	Spec        agentos.RunPlanSpec
	NodeByID    map[string]agentos.PlanNodeSpec
	EdgesByTo   map[string][]agentos.PlanEdgeSpec
	EdgesByFrom map[string][]agentos.PlanEdgeSpec
	Order       []string
}

ExecutablePlan is a validated, deterministic RunPlan view.

func ApplyDelta 

func ApplyDelta(ctx context.Context, validator Validator, current *agentos.RunPlanSpec, delta PlanDelta, expansionCount int32) (agentos.RunPlanSpec, ExecutablePlan, error)

ApplyDelta validates and appends nodes/edges under the plan policy limits.

type Expression 

type Expression interface {
	Evaluate(ctx context.Context, vars map[string]any) (bool, error)
}

Expression evaluates a deterministic AgentOS boolean expression.

type ExpressionCompiler 

type ExpressionCompiler interface {
	Compile(expression string) (Expression, error)
}

ExpressionCompiler validates and compiles deterministic AgentOS expressions.

type InputMappingTrace 

type InputMappingTrace struct {
	Target         string `json:"target"`
	SourceNodeID   string `json:"source_node_id,omitempty"`
	SourceArtifact string `json:"source_artifact,omitempty"`
	SourcePath     string `json:"source_path,omitempty"`
	Expression     string `json:"expression,omitempty"`
	Required       bool   `json:"required,omitempty"`
}

InputMappingTrace is the redacted debug form of one mapping rule.

type InputResolutionTrace 

type InputResolutionTrace struct {
	InputDigest  string              `json:"input_digest,omitempty"`
	InputKeys    []string            `json:"input_keys,omitempty"`
	MappingCount int                 `json:"mapping_count,omitempty"`
	Mappings     []InputMappingTrace `json:"mappings,omitempty"`
}

InputResolutionTrace describes how a node input was resolved without storing full input payloads in workflow history or durable events.

func NewInputResolutionTrace 

func NewInputResolutionTrace(resolved map[string]any, nodeMappings []agentos.InputMapping, edges []agentos.PlanEdgeSpec) InputResolutionTrace

NewInputResolutionTrace creates a redacted trace for resolved input mapping.

type IterationDecision 

type IterationDecision struct {
	ShouldFail bool
	Reason     string
}

IterationDecision explains whether the current workflow run exceeded its bounded execution policy.

func EvaluateIterationPolicy 

func EvaluateIterationPolicy(policy agentos.PlanPolicy, snapshot IterationSnapshot) IterationDecision

EvaluateIterationPolicy evaluates PlanPolicy loop guards.

type IterationSnapshot 

type IterationSnapshot struct {
	Iterations int32
}

IterationSnapshot is deterministic input for RunPlan loop guard policy.

type MemoryArtifactStore 

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

MemoryArtifactStore stores artifacts in-process. Production runtimes should inject a durable store.

func NewMemoryArtifactStore 

func NewMemoryArtifactStore() *MemoryArtifactStore

NewMemoryArtifactStore creates an in-memory artifact store.

func (*MemoryArtifactStore) Get 

func (s *MemoryArtifactStore) Get(_ context.Context, scope *agentos.PlanArtifactScope) (agentoscore.ArtifactRef, any, error)

Get retrieves one artifact inside a plan scope.

func (*MemoryArtifactStore) List 

func (s *MemoryArtifactStore) List(_ context.Context, scope *agentos.PlanArtifactScope) ([]agentoscore.ArtifactRef, error)

List returns artifacts associated with a plan scope.

func (*MemoryArtifactStore) Put 

func (s *MemoryArtifactStore) Put(_ context.Context, artifact *agentoscore.ArtifactRef, payload any, idempotencyKey string) (agentoscore.ArtifactRef, error)

Put stores one artifact payload.

type MemoryPlanStore 

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

MemoryPlanStore is an explicit in-process PlanIndex, PlanTransitionStore, PlanStateStore, and PlanEventStore for unit tests and embedded demos.

func NewMemoryPlanStore 

func NewMemoryPlanStore() *MemoryPlanStore

NewMemoryPlanStore creates an empty in-memory plan store.

func (*MemoryPlanStore) AppendPlanEvent 

func (s *MemoryPlanStore) AppendPlanEvent(_ context.Context, event *agentos.PlanEvent, idempotencyKey string) (agentos.PlanEvent, error)

func (*MemoryPlanStore) CreatePlan 

func (s *MemoryPlanStore) CreatePlan(_ context.Context, spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) (agentos.RunPlanStatus, bool, error)

func (*MemoryPlanStore) GetAuditRecord 

func (s *MemoryPlanStore) GetAuditRecord(_ context.Context, ref AuditRef) (AuditRecord, bool, error)

func (*MemoryPlanStore) GetPlan 

func (s *MemoryPlanStore) GetPlan(_ context.Context, planID string) (agentos.RunPlanSpec, agentos.RunPlanStatus, bool, error)

func (*MemoryPlanStore) GetPlanByRef 

func (s *MemoryPlanStore) GetPlanByRef(_ context.Context, ref agentos.PlanRef) (agentos.RunPlanSpec, agentos.RunPlanStatus, bool, error)

func (*MemoryPlanStore) GetPlanCommand 

func (s *MemoryPlanStore) GetPlanCommand(_ context.Context, ref PlanCommandRef) (PlanCommandRecord, bool, error)

func (*MemoryPlanStore) GetPlanMetricCheckpoint 

func (s *MemoryPlanStore) GetPlanMetricCheckpoint(_ context.Context, exporterID string, ref agentos.PlanRef) (PlanMetricCheckpoint, bool, error)

func (*MemoryPlanStore) ListAuditRecords 

func (s *MemoryPlanStore) ListAuditRecords(_ context.Context, scope *agentos.PlanAuditScope) ([]agentos.PlanAuditRecord, error)

func (*MemoryPlanStore) ListPlanEvents 

func (s *MemoryPlanStore) ListPlanEvents(_ context.Context, scope *agentos.PlanStreamScope, limit int) ([]agentos.PlanEvent, error)

func (*MemoryPlanStore) ListPlanRefs 

func (s *MemoryPlanStore) ListPlanRefs(_ context.Context, scope *PlanRefScope) ([]agentos.PlanRef, error)

func (*MemoryPlanStore) ListRecoverablePlanCommands 

func (s *MemoryPlanStore) ListRecoverablePlanCommands(_ context.Context, scope *PlanCommandScope) ([]PlanCommandRecord, error)

func (*MemoryPlanStore) LoadPlanState 

func (s *MemoryPlanStore) LoadPlanState(_ context.Context, planID string) (PlanStateSnapshot, bool, error)

func (*MemoryPlanStore) MarkPlanCommandDelivered 

func (s *MemoryPlanStore) MarkPlanCommandDelivered(_ context.Context, ref PlanCommandRef) (PlanCommandRecord, error)

func (*MemoryPlanStore) MarkPlanCommandFailed 

func (s *MemoryPlanStore) MarkPlanCommandFailed(_ context.Context, ref PlanCommandRef, reason string) (PlanCommandRecord, error)

func (*MemoryPlanStore) PersistPlanTransition 

func (s *MemoryPlanStore) PersistPlanTransition(_ context.Context, snapshot *PlanStateSnapshot, event *agentos.PlanEvent, idempotencyKey string) (agentos.PlanEvent, error)

func (*MemoryPlanStore) RecordAudit 

func (s *MemoryPlanStore) RecordAudit(_ context.Context, record *AuditRecord) (AuditRecord, bool, error)

func (*MemoryPlanStore) RecordPlanCommand 

func (s *MemoryPlanStore) RecordPlanCommand(_ context.Context, command *PlanCommandRecord) (PlanCommandRecord, bool, error)

func (*MemoryPlanStore) SavePlanMetricCheckpoint 

func (s *MemoryPlanStore) SavePlanMetricCheckpoint(_ context.Context, checkpoint *PlanMetricCheckpoint) error

func (*MemoryPlanStore) SavePlanState 

func (s *MemoryPlanStore) SavePlanState(_ context.Context, snapshot *PlanStateSnapshot) error

type PlanCommandRecord 

type PlanCommandRecord struct {
	CommandID      string
	PlanID         string
	AccountID      string
	ProjectID      string
	ActorID        string
	Action         AuditAction
	IdempotencyKey string
	Payload        map[string]any
	Status         PlanCommandStatus
	FailureReason  string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

PlanCommandRecord is the durable command/outbox entry written before delivering a control-plane operation to PlanWorkflow or starting it.

type PlanCommandRef 

type PlanCommandRef struct {
	PlanID         string
	AccountID      string
	ProjectID      string
	IdempotencyKey string
}

PlanCommandRef identifies one durable command in a tenant-scoped plan.

func PlanCommandRefFromRecord 

func PlanCommandRefFromRecord(command *PlanCommandRecord) PlanCommandRef

type PlanCommandScope 

type PlanCommandScope struct {
	PlanID    string
	AccountID string
	ProjectID string
	Action    AuditAction
	Statuses  []PlanCommandStatus
	Limit     int
}

PlanCommandScope selects recoverable command outbox entries.

type PlanCommandStatus 

type PlanCommandStatus string

PlanCommandStatus is the durable outbox state for a control-plane command. 

const (
	PlanCommandPending   PlanCommandStatus = "pending"
	PlanCommandDelivered PlanCommandStatus = "delivered"
	PlanCommandFailed    PlanCommandStatus = "failed"
)

func NormalizeNewPlanCommandStatus 

func NormalizeNewPlanCommandStatus(status PlanCommandStatus) (PlanCommandStatus, error)

NormalizeNewPlanCommandStatus validates the lifecycle state assigned to a new outbox command. Commands are written before delivery, so they always enter the durable log as pending.

func RecoverablePlanCommandStatuses 

func RecoverablePlanCommandStatuses(scope *PlanCommandScope) ([]PlanCommandStatus, error)

RecoverablePlanCommandStatuses validates a command query scope and returns the statuses that a command reconciler may redeliver.

type PlanCommandStore 

type PlanCommandStore interface {
	RecordPlanCommand(ctx context.Context, command *PlanCommandRecord) (PlanCommandRecord, bool, error)
	GetPlanCommand(ctx context.Context, ref PlanCommandRef) (PlanCommandRecord, bool, error)
	ListRecoverablePlanCommands(ctx context.Context, scope *PlanCommandScope) ([]PlanCommandRecord, error)
	MarkPlanCommandDelivered(ctx context.Context, ref PlanCommandRef) (PlanCommandRecord, error)
	MarkPlanCommandFailed(ctx context.Context, ref PlanCommandRef, reason string) (PlanCommandRecord, error)
}

PlanCommandStore persists recoverable plan start/signal/control commands.

type PlanDelta 

type PlanDelta = agentos.PlanDeltaSpec

PlanDelta is the only supported dynamic expansion unit. It is intended to be produced and validated inside PlanWorkflow, not patched arbitrarily by clients.

func DecodePlanDeltaPayload 

func DecodePlanDeltaPayload(payload any) (PlanDelta, error)

type PlanDeltaInput 

type PlanDeltaInput struct {
	Spec           agentos.RunPlanSpec
	Status         agentos.RunPlanStatus
	Node           agentos.PlanNodeSpec
	RunStatus      agentos.RunStatus
	Artifacts      []agentoscore.ArtifactRef
	ExpansionCount int32
}

PlanDeltaInput is deterministic context for workflow-owned dynamic expansion.

type PlanDeltaProvider 

type PlanDeltaProvider interface {
	NextPlanDelta(ctx context.Context, input *PlanDeltaInput) (PlanDelta, bool, error)
}

PlanDeltaProvider derives bounded expansion proposals for PlanWorkflow. The workflow still owns validation and application of the returned delta.

type PlanEventPublisher 

type PlanEventPublisher interface {
	PublishPlanEvent(ctx context.Context, event *agentos.PlanEvent) error
}

PlanEventPublisher publishes live PlanEvents after the durable event source has assigned sequence and event identity.

type PlanEventStore 

type PlanEventStore interface {
	AppendPlanEvent(ctx context.Context, event *agentos.PlanEvent, idempotencyKey string) (agentos.PlanEvent, error)
	ListPlanEvents(ctx context.Context, scope *agentos.PlanStreamScope, limit int) ([]agentos.PlanEvent, error)
}

PlanEventStore is the durable event source for RunPlan timelines. Reads must carry the full account/project plan scope; PlanID alone is not a production isolation boundary.

type PlanEventSubscriber 

type PlanEventSubscriber interface {
	SubscribePlanEvents(ctx context.Context, scope *agentos.PlanStreamScope) (PlanEventSubscription, error)
}

PlanEventSubscriber subscribes to the live PlanEvent tail.

type PlanEventSubscription 

type PlanEventSubscription interface {
	Events() <-chan agentos.PlanEvent
	Close() error
}

PlanEventSubscription is the typed live tail for public RunPlan events. Public Runtime APIs project these typed events into agentoscore.Event only at the subscription boundary.

type PlanIndex 

type PlanIndex interface {
	CreatePlan(ctx context.Context, spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) (agentos.RunPlanStatus, bool, error)
	GetPlanByRef(ctx context.Context, ref agentos.PlanRef) (agentos.RunPlanSpec, agentos.RunPlanStatus, bool, error)
	GetPlan(ctx context.Context, planID string) (agentos.RunPlanSpec, agentos.RunPlanStatus, bool, error)
}

PlanIndex stores durable plan identity and the latest aggregate status.

type PlanMetricCheckpoint 

type PlanMetricCheckpoint struct {
	ExporterID string
	PlanID     string
	AccountID  string
	ProjectID  string
	Sequence   int64
	Projection PlanMetricProjectionState
	UpdatedAt  time.Time
}

PlanMetricCheckpoint stores the exporter-owned cursor and projection state for one durable RunPlan event stream.

type PlanMetricCheckpointStore 

type PlanMetricCheckpointStore interface {
	GetPlanMetricCheckpoint(ctx context.Context, exporterID string, ref agentos.PlanRef) (PlanMetricCheckpoint, bool, error)
	SavePlanMetricCheckpoint(ctx context.Context, checkpoint *PlanMetricCheckpoint) error
}

PlanMetricCheckpointStore persists metric projection checkpoints.

type PlanMetricName 

type PlanMetricName string

PlanMetricName identifies one durable RunPlan metric projection. Samples are projected from persisted PlanEvents, so exporters can consume them idempotently by event sequence without coupling metrics to Temporal replay. 

const (
	PlanMetricPlanStartedTotal        PlanMetricName = "agentos_plan_started_total"
	PlanMetricPlanCompletedTotal      PlanMetricName = "agentos_plan_completed_total"
	PlanMetricPlanDurationSeconds     PlanMetricName = "agentos_plan_duration_seconds"
	PlanMetricPlanQueueLatencySeconds PlanMetricName = "agentos_plan_queue_latency_seconds"
	PlanMetricNodeStartedTotal        PlanMetricName = "agentos_plan_node_started_total"
	PlanMetricNodeCompletedTotal      PlanMetricName = "agentos_plan_node_completed_total"
	PlanMetricNodeDurationSeconds     PlanMetricName = "agentos_plan_node_duration_seconds"
	PlanMetricNodeQueueLatencySeconds PlanMetricName = "agentos_plan_node_queue_latency_seconds"
	PlanMetricBackendErrorsTotal      PlanMetricName = "agentos_plan_backend_errors_total"
	PlanMetricArtifactPublishedBytes  PlanMetricName = "agentos_plan_artifact_published_bytes"
	PlanMetricBudgetDeltaCents        PlanMetricName = "agentos_plan_budget_delta_cents"
	PlanMetricBudgetSpentCents        PlanMetricName = "agentos_plan_budget_spent_cents"
	PlanMetricDynamicExpansionsTotal  PlanMetricName = "agentos_plan_dynamic_expansions_total"
	PlanMetricNodeRetryScheduledTotal PlanMetricName = "agentos_plan_node_retry_scheduled_total"
)

type PlanMetricNodeStartState 

type PlanMetricNodeStartState struct {
	NodeID    string    `json:"node_id"`
	RunID     string    `json:"run_id,omitempty"`
	StartedAt time.Time `json:"started_at"`
}

PlanMetricNodeStartState remembers the start timestamp for one backend-owned child run so duration metrics can be computed when its terminal event arrives in a later exporter batch.

type PlanMetricProjectionState 

type PlanMetricProjectionState struct {
	PlanStartedAt time.Time                  `json:"plan_started_at"`
	NodeStartedAt []PlanMetricNodeStartState `json:"node_started_at,omitempty"`
}

PlanMetricProjectionState is the durable state required to continue metric projection from a per-plan event checkpoint without rereading the full event history.

type PlanMetricSample 

type PlanMetricSample struct {
	Name      PlanMetricName
	Value     float64
	Unit      string
	PlanID    string
	AccountID string
	ProjectID string
	NodeID    string
	RunID     string
	EventID   string
	Sequence  int64
	Timestamp time.Time
	Labels    map[string]string
}

PlanMetricSample is a low-cardinality metric event. Plan/node/run/event identity fields are intentionally not labels; Prometheus exporters can use them for idempotent projection checkpoints without creating unbounded label cardinality.

func BuildPlanMetricSamples 

func BuildPlanMetricSamples(ctx context.Context, spec *agentos.RunPlanSpec, events []agentos.PlanEvent) ([]PlanMetricSample, error)

BuildPlanMetricSamples projects operational metrics from a durable RunPlan event history. Samples keep event identity so downstream exporters can de-duplicate on EventID/Sequence.

func BuildPlanMetricSamplesAfter 

func BuildPlanMetricSamplesAfter(ctx context.Context, spec *agentos.RunPlanSpec, events []agentos.PlanEvent, afterSequence int64) ([]PlanMetricSample, error)

BuildPlanMetricSamplesAfter projects metrics for events after a durable checkpoint while still reading earlier history to reconstruct durations and other stateful measurements.

func NormalizePlanMetricSample 

func NormalizePlanMetricSample(sample *PlanMetricSample) PlanMetricSample

NormalizePlanMetricSample returns the canonical representation used for durable metric sample idempotency.

func (*PlanMetricSample) Key 

func (s *PlanMetricSample) Key() PlanMetricSampleKey

Key returns the durable idempotency identity for this sample.

type PlanMetricSampleKey 

type PlanMetricSampleKey struct {
	Name     PlanMetricName
	PlanID   string
	NodeID   string
	RunID    string
	EventID  string
	Sequence int64
}

PlanMetricSampleKey is the stable idempotency identity for a projected metric sample. A single PlanEvent can emit multiple metric names, so event identity alone is not sufficient.

type PlanMetricsExportResult 

type PlanMetricsExportResult struct {
	PlansScanned     int
	EventsScanned    int
	SamplesRecorded  int
	CheckpointsSaved int
}

PlanMetricsExportResult summarizes one exporter catch-up pass.

type PlanMetricsExporter 

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

PlanMetricsExporter projects durable PlanEvents into an idempotent metrics sink. It is intentionally outside Temporal workflows so replay and activity retries cannot double-count metrics.

func NewPlanMetricsExporter 

func NewPlanMetricsExporter(cfg *PlanMetricsExporterConfig) (*PlanMetricsExporter, error)

NewPlanMetricsExporter creates a metrics exporter with explicit durable dependencies. BatchSize must be positive; callers should size it according to their event history and sink throughput.

func (*PlanMetricsExporter) Export 

func (e *PlanMetricsExporter) Export(ctx context.Context, scope *PlanRefScope) (PlanMetricsExportResult, error)

Export catches up all plans selected by scope. A returned error means the failing plan checkpoint was not advanced beyond the last fully recorded sample batch.

type PlanMetricsExporterConfig 

type PlanMetricsExporterConfig struct {
	ExporterID  string
	PlanRefs    PlanRefStore
	Plans       PlanIndex
	PlanEvents  PlanEventStore
	Checkpoints PlanMetricCheckpointStore
	Sink        PlanMetricsSink
	BatchSize   int
}

PlanMetricsExporterConfig wires the durable RunPlan metric exporter.

type PlanMetricsExporterLoop 

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

PlanMetricsExporterLoop owns periodic durable RunPlan metric projection.

func StartPlanMetricsExporterLoop 

func StartPlanMetricsExporterLoop(parent context.Context, exporter PlanMetricsExporterRunner, cfg *PlanMetricsExporterLoopConfig, observer PlanMetricsExporterObserver) (*PlanMetricsExporterLoop, error)

StartPlanMetricsExporterLoop starts a background metric exporter loop.

func (*PlanMetricsExporterLoop) Stop 

func (l *PlanMetricsExporterLoop) Stop()

Stop cancels the loop and waits for it to exit.

type PlanMetricsExporterLoopConfig 

type PlanMetricsExporterLoopConfig struct {
	Interval          time.Duration
	Scope             PlanRefScope
	ExportImmediately bool
}

PlanMetricsExporterLoopConfig controls periodic metric projection.

type PlanMetricsExporterObserver 

type PlanMetricsExporterObserver interface {
	PlanMetricsExportSucceeded(PlanMetricsExportResult)
	PlanMetricsExportFailed(error)
}

PlanMetricsExporterObserver receives metric export pass outcomes.

type PlanMetricsExporterRunner 

type PlanMetricsExporterRunner interface {
	Export(ctx context.Context, scope *PlanRefScope) (PlanMetricsExportResult, error)
}

PlanMetricsExporterRunner projects durable RunPlan events into a metric sink.

type PlanMetricsSink 

type PlanMetricsSink interface {
	RecordPlanMetric(ctx context.Context, sample *PlanMetricSample) error
}

PlanMetricsSink receives idempotent durable metric samples. Implementations must de-duplicate by PlanMetricSample.Key before mutating non-idempotent counters or external metrics systems.

type PlanRefScope 

type PlanRefScope struct {
	AccountID       string
	ProjectID       string
	LifecycleStates []string
	UpdatedAfter    time.Time
	Limit           int
}

PlanRefScope selects durable plans for internal control-plane projectors.

type PlanRefStore 

type PlanRefStore interface {
	ListPlanRefs(ctx context.Context, scope *PlanRefScope) ([]agentos.PlanRef, error)
}

PlanRefStore lists durable plan identities without exposing implementation tables to projectors.

type PlanStateSnapshot 

type PlanStateSnapshot struct {
	Spec   agentos.RunPlanSpec
	Status agentos.RunPlanStatus
}

PlanStateSnapshot is the durable replay/audit snapshot written by plan activities.

type PlanStateStore 

type PlanStateStore interface {
	SavePlanState(ctx context.Context, snapshot *PlanStateSnapshot) error
	LoadPlanState(ctx context.Context, planID string) (PlanStateSnapshot, bool, error)
}

PlanStateStore persists the latest deterministic reducer snapshot.

type PlanTransitionSnapshotIdentity 

type PlanTransitionSnapshotIdentity struct {
	Digest string
	JSON   []byte
}

PlanTransitionSnapshotIdentity is the immutable content-addressed identity for the reducer snapshot claimed by one transition idempotency key.

func NewPlanTransitionSnapshotIdentity 

func NewPlanTransitionSnapshotIdentity(snapshot *PlanStateSnapshot, idempotencyKey string) (PlanTransitionSnapshotIdentity, error)

NewPlanTransitionSnapshotIdentity returns the stable snapshot identity that must be persisted with a state-transition event. Replays compare this digest instead of the latest plan state because the latest state can advance after the transition being retried.

type PlanTransitionStore 

type PlanTransitionStore interface {
	PersistPlanTransition(ctx context.Context, snapshot *PlanStateSnapshot, event *agentos.PlanEvent, idempotencyKey string) (agentos.PlanEvent, error)
}

PlanTransitionStore atomically persists one reducer snapshot and its durable public event. Implementations must not expose a newer state without the corresponding event in the durable stream.

type RunPlanCompiler 

type RunPlanCompiler struct {
	Validator Validator
}

RunPlanCompiler parses serialized plans into validated executable plans.

func (RunPlanCompiler) CompileDeltaJSON 

func (c RunPlanCompiler) CompileDeltaJSON(ctx context.Context, base *agentos.RunPlanSpec, data []byte, expansionCount int32) (agentos.RunPlanSpec, ExecutablePlan, error)

CompileDeltaJSON decodes JSON PlanDelta and validates the expanded plan.

func (RunPlanCompiler) CompileDeltaYAML 

func (c RunPlanCompiler) CompileDeltaYAML(ctx context.Context, base *agentos.RunPlanSpec, data []byte, expansionCount int32) (agentos.RunPlanSpec, ExecutablePlan, error)

CompileDeltaYAML decodes YAML PlanDelta and validates the expanded plan.

func (RunPlanCompiler) CompileJSON 

func (c RunPlanCompiler) CompileJSON(ctx context.Context, data []byte) (ExecutablePlan, error)

CompileJSON compiles JSON into an executable RunPlan.

func (RunPlanCompiler) CompileYAML 

func (c RunPlanCompiler) CompileYAML(ctx context.Context, data []byte) (ExecutablePlan, error)

CompileYAML compiles YAML into an executable RunPlan.

type Runner 

type Runner interface {
	Start(ctx context.Context, spec *agentos.RunSpec) (agentos.RunStatus, error)
	Signal(ctx context.Context, runID string, signal *agentoscore.Signal) error
	Status(ctx context.Context, runID string) (agentos.RunStatus, error)
	Control(ctx context.Context, runID string, control *agentoscore.ControlRequest) error
	Subscribe(ctx context.Context, scope agentoscore.StreamScope) (agentoscore.Subscription, error)
}

Runner starts and controls backend-owned child runs.

type Scheduler 

type Scheduler struct {
	Expressions ExpressionCompiler
}

Scheduler calculates ready nodes from deterministic plan state.

func (Scheduler) Decide 

func (s Scheduler) Decide(ctx context.Context, plan *ExecutablePlan, status *agentos.RunPlanStatus, vars map[string]any) (SchedulerDecision, error)

Decide returns ready and skipped nodes for one deterministic scheduler tick.

func (Scheduler) ReadyNodes 

func (s Scheduler) ReadyNodes(ctx context.Context, plan *ExecutablePlan, status *agentos.RunPlanStatus, vars map[string]any) ([]agentos.PlanNodeSpec, error)

ReadyNodes returns pending nodes whose active dependencies and conditions are satisfied.

type SchedulerDecision 

type SchedulerDecision struct {
	Ready           []agentos.PlanNodeSpec
	Skipped         []SkippedNode
	ConditionTraces []ConditionEvaluationTrace
}

SchedulerDecision contains deterministic scheduling transitions for one tick.

type SkippedNode 

type SkippedNode struct {
	NodeID string
	Reason string
}

SkippedNode records one node that can no longer become runnable.

type State 

type State struct {
	Status agentos.RunPlanStatus
	// contains filtered or unexported fields
}

State is the deterministic reducer state for a RunPlan.

func NewState 

func NewState(spec *agentos.RunPlanSpec, now time.Time) State

NewState initializes state from a validated or unvalidated plan spec.

func NewStateFromStatus 

func NewStateFromStatus(spec *agentos.RunPlanSpec, status *agentos.RunPlanStatus) (State, error)

NewStateFromStatus restores reducer state from a durable snapshot status.

func (*State) AppliedTransitions 

func (s *State) AppliedTransitions() int32

AppliedTransitions returns the reducer transitions applied since this State was created or restored.

func (*State) Apply 

func (s *State) Apply(event *StateEvent) error

Apply applies one deterministic state transition.

func (*State) NodeStatus 

func (s *State) NodeStatus(nodeID string) (agentos.PlanNodeStatus, bool)

NodeStatus returns one node status.

type StateEvent 

type StateEvent struct {
	Kind                   EventKind                  `json:"kind"`
	NodeID                 string                     `json:"node_id,omitempty"`
	RunID                  string                     `json:"run_id,omitempty"`
	Reason                 string                     `json:"reason,omitempty"`
	Attempt                int32                      `json:"attempt,omitempty"`
	Expansion              PlanDelta                  `json:"expansion"`
	Artifacts              []agentoscore.ArtifactRef  `json:"artifacts,omitempty"`
	BudgetDelta            agentos.PlanBudgetUsage    `json:"budget_delta"`
	InputTrace             InputResolutionTrace       `json:"input_trace"`
	Capability             CapabilitySelectionTrace   `json:"capability"`
	ConditionTraces        []ConditionEvaluationTrace `json:"condition_traces,omitempty"`
	PreviousLifecycleState string                     `json:"previous_lifecycle_state,omitempty"`
	NextLifecycleState     string                     `json:"next_lifecycle_state,omitempty"`
	At                     time.Time                  `json:"at"`
}

StateEvent transitions plan state.

type StaticArtifactSchemaCatalog 

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

StaticArtifactSchemaCatalog is an explicit in-memory schema catalog for tests, CLI validation, and embedded setups that do not need a durable schema registry.

func NewStaticArtifactSchemaCatalog 

func NewStaticArtifactSchemaCatalog(schemas []agentos.ArtifactSchema) (*StaticArtifactSchemaCatalog, error)

NewStaticArtifactSchemaCatalog creates a catalog from public schema declarations.

func (*StaticArtifactSchemaCatalog) GetArtifactSchema 

func (c *StaticArtifactSchemaCatalog) GetArtifactSchema(_ context.Context, schemaRef string) (json.RawMessage, bool, error)

GetArtifactSchema returns a copy of the schema document for schemaRef.

func (*StaticArtifactSchemaCatalog) RegisterArtifactSchema 

func (c *StaticArtifactSchemaCatalog) RegisterArtifactSchema(_ context.Context, schema agentos.ArtifactSchema, idempotencyKey string) (agentos.ArtifactSchema, bool, error)

RegisterArtifactSchema adds or replaces one schema declaration.

type StaticCapabilityCatalog 

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

StaticCapabilityCatalog is an in-memory capability catalog for tests, CLI validation, and embedded demos.

func NewStaticCapabilityCatalog 

func NewStaticCapabilityCatalog(capabilities []agentos.Capability) (*StaticCapabilityCatalog, error)

NewStaticCapabilityCatalog creates a catalog from capabilities.

func (*StaticCapabilityCatalog) GetCapability 

func (c *StaticCapabilityCatalog) GetCapability(_ context.Context, backend agentos.BackendRef, name string) (agentos.Capability, bool, error)

GetCapability returns a registered capability.

func (*StaticCapabilityCatalog) RegisterCapability 

func (c *StaticCapabilityCatalog) RegisterCapability(_ context.Context, capability *agentos.Capability, _ string) (agentos.Capability, bool, error)

RegisterCapability adds or replaces one capability.

type Validator 

type Validator struct {
	Expressions     ExpressionCompiler
	Capabilities    CapabilityCatalog
	ArtifactSchemas ArtifactSchemaCatalog
}

Validator validates RunPlan specs against topology, policy, expressions, capabilities, and artifact contracts.

func (Validator) Validate 

func (v Validator) Validate(ctx context.Context, spec *agentos.RunPlanSpec) (ExecutablePlan, error)

Validate returns a deterministic executable plan or a precise validation error.

type ValueExpression 

type ValueExpression interface {
	EvaluateValue(ctx context.Context, vars map[string]any) (any, error)
}

ValueExpression evaluates a deterministic AgentOS expression to a value.

type ValueExpressionCompiler 

type ValueExpressionCompiler interface {
	CompileValue(expression string) (ValueExpression, error)
}

ValueExpressionCompiler validates and compiles deterministic value expressions.

Source Files

View all Source files

Directories

Path Synopsis

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.