Documentation
¶
Overview ¶
Package trace defines the cycle-trace event schema emitted by the cogos kernel's homeostatic metabolic cycle onto the kernel bus (http://localhost:6931/v1/bus) for external consumers such as the Mod³ dashboard.
This package only declares the wire types and constructor helpers. Wiring these events into the state-transition path (internal/engine/process.go) and the tool-dispatch/assessment paths (agent_harness.go, agent_tools*.go) is performed in a later wave — see .cog/mem/semantic/plans/audio-loop-and-trace-wiring.cog.md (task B5).
Design notes:
- The package deliberately has no dependency on cogos-internal packages (engine, harness, bus) so that both the engine and the root cogos package can import it without creating an import cycle.
- State values are accepted as fmt.Stringer so callers can pass engine.ProcessState (an int enum with a String() method) directly.
- The envelope is transport-agnostic. The actual bus-publish call is owned by task D2 / B5 and is out of scope here.
Index ¶
- type AssessmentEvent
- type CycleEvent
- func NewAssessment(source, cycleID, action string, confidence float64, rationale string) (CycleEvent, error)
- func NewStateTransition(source, cycleID string, from, to fmt.Stringer, reason string) (CycleEvent, error)
- func NewToolDispatch(source, cycleID, tool string, args json.RawMessage, duration time.Duration, ...) (CycleEvent, error)
- type Kind
- type StateTransitionEvent
- type ToolDispatchEvent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AssessmentEvent ¶
type AssessmentEvent struct {
Action string `json:"action"`
Confidence float64 `json:"confidence"`
Rationale string `json:"rationale,omitempty"`
}
AssessmentEvent mirrors the Assessment struct in agent_harness.go. The Action field uses the vocabulary the harness already emits: "observe" | "propose" | "execute" | "sleep" | "wait" (and synonyms such as "consolidate" | "repair" | "escalate").
type CycleEvent ¶
type CycleEvent struct {
ID string `json:"id"`
Timestamp time.Time `json:"ts"`
Source string `json:"source"` // identity name (e.g. "cog")
CycleID string `json:"cycle_id"` // correlates events within one metabolic-cycle iteration
Kind Kind `json:"kind"`
Payload json.RawMessage `json:"payload"`
}
CycleEvent is the common envelope for cycle-trace events emitted onto the kernel bus. All events within a single metabolic-cycle iteration share a CycleID so consumers can correlate them.
func NewAssessment ¶
func NewAssessment(source, cycleID, action string, confidence float64, rationale string) (CycleEvent, error)
NewAssessment builds a CycleEvent wrapping an AssessmentEvent.
func NewStateTransition ¶
func NewStateTransition(source, cycleID string, from, to fmt.Stringer, reason string) (CycleEvent, error)
NewStateTransition builds a CycleEvent wrapping a StateTransitionEvent. from and to accept any fmt.Stringer so that engine.ProcessState values can be passed directly without introducing an import dependency.
func NewToolDispatch ¶
func NewToolDispatch(source, cycleID, tool string, args json.RawMessage, duration time.Duration, err error) (CycleEvent, error)
NewToolDispatch builds a CycleEvent wrapping a ToolDispatchEvent. args may be nil; if non-nil it is expected to already be valid JSON.
type StateTransitionEvent ¶
type StateTransitionEvent struct {
From string `json:"from"`
To string `json:"to"`
Reason string `json:"reason,omitempty"`
}
StateTransitionEvent describes a move between process states (engine.StateActive / StateReceptive / StateConsolidating / StateDormant).
type ToolDispatchEvent ¶
type ToolDispatchEvent struct {
Tool string `json:"tool"`
Args json.RawMessage `json:"args,omitempty"`
DurationMS int64 `json:"duration_ms"`
Error string `json:"error,omitempty"`
}
ToolDispatchEvent describes a single tool invocation issued by the agent harness (see agent_tools*.go).
Source Files