Documentation
¶
Overview ¶
Package plugin defines the extension system for Cortex.
Extensions are notified of lifecycle events (run started, tool called, persona resolved, etc.) and can react to them — logging, metrics, tracing, auditing, etc.
Each lifecycle hook is a separate interface so extensions opt in only to the events they care about.
Index ¶
- type AgentHandoff
- type BehaviorTriggered
- type CheckpointCreated
- type CheckpointResolved
- type CognitivePhaseChanged
- type Extension
- type MessageDelivered
- type MessageRefused
- type MessageSent
- type OrchestrationCompleted
- type OrchestrationStarted
- type PersonaResolved
- type PublicationRejected
- type Registry
- func (r *Registry) EmitAgentHandoff(ctx context.Context, orchID id.OrchestrationID, ...)
- func (r *Registry) EmitBehaviorTriggered(ctx context.Context, runID id.AgentRunID, behaviorName string)
- func (r *Registry) EmitCheckpointCreated(ctx context.Context, cpID id.CheckpointID, runID id.AgentRunID, reason string)
- func (r *Registry) EmitCheckpointResolved(ctx context.Context, cpID id.CheckpointID, decision string)
- func (r *Registry) EmitCognitivePhaseChanged(ctx context.Context, runID id.AgentRunID, fromPhase, toPhase string)
- func (r *Registry) EmitMessageDelivered(ctx context.Context, msgID id.MessageID, to string)
- func (r *Registry) EmitMessageRefused(ctx context.Context, msgID id.MessageID, to, reason string)
- func (r *Registry) EmitMessageSent(ctx context.Context, msgID id.MessageID, from, to, performative string)
- func (r *Registry) EmitOrchestrationCompleted(ctx context.Context, orchID id.OrchestrationID, elapsed time.Duration)
- func (r *Registry) EmitOrchestrationStarted(ctx context.Context, orchID id.OrchestrationID, strategy string)
- func (r *Registry) EmitPersonaResolved(ctx context.Context, agentID id.AgentID, personaName string)
- func (r *Registry) EmitPublicationRejected(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, ...)
- func (r *Registry) EmitRunCompleted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, output string, ...)
- func (r *Registry) EmitRunFailed(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, runErr error)
- func (r *Registry) EmitRunStarted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, input string)
- func (r *Registry) EmitRunTerminated(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, ...)
- func (r *Registry) EmitShutdown(ctx context.Context)
- func (r *Registry) EmitStepCompleted(ctx context.Context, runID id.AgentRunID, stepIndex int, elapsed time.Duration)
- func (r *Registry) EmitStepStarted(ctx context.Context, runID id.AgentRunID, stepIndex int)
- func (r *Registry) EmitToolCalled(ctx context.Context, runID id.AgentRunID, toolName string, args any)
- func (r *Registry) EmitToolCompleted(ctx context.Context, runID id.AgentRunID, toolName, result string, ...)
- func (r *Registry) EmitToolDenied(ctx context.Context, runID id.AgentRunID, toolName, reason string)
- func (r *Registry) EmitToolFailed(ctx context.Context, runID id.AgentRunID, toolName string, toolErr error)
- func (r *Registry) Extensions() []Extension
- func (r *Registry) Register(e Extension)
- type RunCompleted
- type RunFailed
- type RunStarted
- type RunTerminated
- type Shutdown
- type StepCompleted
- type StepStarted
- type ToolCalled
- type ToolCompleted
- type ToolDenied
- type ToolFailed
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentHandoff ¶
type AgentHandoff interface {
OnAgentHandoff(ctx context.Context, orchID id.OrchestrationID, fromAgent, toAgent string, payload string) error
}
AgentHandoff is called when one agent hands off to another.
type BehaviorTriggered ¶
type BehaviorTriggered interface {
OnBehaviorTriggered(ctx context.Context, runID id.AgentRunID, behaviorName string) error
}
BehaviorTriggered is called when a behavior fires during a run.
type CheckpointCreated ¶
type CheckpointCreated interface {
OnCheckpointCreated(ctx context.Context, cpID id.CheckpointID, runID id.AgentRunID, reason string) error
}
CheckpointCreated is called when a checkpoint is created.
type CheckpointResolved ¶
type CheckpointResolved interface {
OnCheckpointResolved(ctx context.Context, cpID id.CheckpointID, decision string) error
}
CheckpointResolved is called when a checkpoint is resolved.
type CognitivePhaseChanged ¶
type CognitivePhaseChanged interface {
OnCognitivePhaseChanged(ctx context.Context, runID id.AgentRunID, fromPhase, toPhase string) error
}
CognitivePhaseChanged is called when the cognitive engine switches phases.
type Extension ¶
type Extension interface {
Name() string
}
Extension is the base interface all Cortex plugins must implement.
type MessageDelivered ¶
type MessageDelivered interface {
OnMessageDelivered(ctx context.Context, msgID id.MessageID, to string) error
}
MessageDelivered is called when an envelope reaches a receiver: an inbox row for an informative, a started run for a directive.
type MessageRefused ¶
type MessageRefused interface {
OnMessageRefused(ctx context.Context, msgID id.MessageID, to, reason string) error
}
MessageRefused is called when delivery is refused or fails: an exhausted hop budget, an unroutable address, a recipient that broke.
type MessageSent ¶
type MessageSent interface {
OnMessageSent(ctx context.Context, msgID id.MessageID, from, to, performative string) error
}
MessageSent is called when an envelope is accepted and queued.
type OrchestrationCompleted ¶
type OrchestrationCompleted interface {
OnOrchestrationCompleted(ctx context.Context, orchID id.OrchestrationID, elapsed time.Duration) error
}
OrchestrationCompleted is called when orchestration finishes.
type OrchestrationStarted ¶
type OrchestrationStarted interface {
OnOrchestrationStarted(ctx context.Context, orchID id.OrchestrationID, strategy string) error
}
OrchestrationStarted is called when multi-agent orchestration begins.
type PersonaResolved ¶
type PersonaResolved interface {
OnPersonaResolved(ctx context.Context, agentID id.AgentID, personaName string) error
}
PersonaResolved is called when a persona is resolved for a run.
type PublicationRejected ¶
type PublicationRejected interface {
OnPublicationRejected(context.Context, id.AgentID, id.AgentRunID, run.StopReason) error
}
PublicationRejected observes a failed content check. runID is empty when the check precedes run creation. The reason never contains candidate content.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered extensions and dispatches lifecycle events. It type-caches extensions at registration time so emit calls iterate only over extensions that implement the relevant hook.
func NewRegistry ¶
NewRegistry creates an extension registry with the given logger.
func (*Registry) EmitAgentHandoff ¶
func (*Registry) EmitBehaviorTriggered ¶
func (*Registry) EmitCheckpointCreated ¶
func (r *Registry) EmitCheckpointCreated(ctx context.Context, cpID id.CheckpointID, runID id.AgentRunID, reason string)
func (*Registry) EmitCheckpointResolved ¶
func (*Registry) EmitCognitivePhaseChanged ¶
func (*Registry) EmitMessageDelivered ¶
func (*Registry) EmitMessageRefused ¶
func (*Registry) EmitMessageSent ¶
func (*Registry) EmitOrchestrationCompleted ¶
func (*Registry) EmitOrchestrationStarted ¶
func (*Registry) EmitPersonaResolved ¶
func (*Registry) EmitPublicationRejected ¶
func (r *Registry) EmitPublicationRejected(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, reason run.StopReason)
EmitPublicationRejected emits bounded policy diagnostics, without content.
func (*Registry) EmitRunCompleted ¶
func (*Registry) EmitRunFailed ¶
func (*Registry) EmitRunStarted ¶
func (*Registry) EmitRunTerminated ¶
func (r *Registry) EmitRunTerminated(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, summary run.TerminalSummary)
EmitRunTerminated notifies observers only after the caller persists the outcome.
func (*Registry) EmitShutdown ¶
func (*Registry) EmitStepCompleted ¶
func (*Registry) EmitStepStarted ¶
func (*Registry) EmitToolCalled ¶
func (*Registry) EmitToolCompleted ¶
func (*Registry) EmitToolDenied ¶
func (r *Registry) EmitToolDenied(ctx context.Context, runID id.AgentRunID, toolName, reason string)
EmitToolDenied notifies extensions that an authorizer refused a tool call. It is purely observational: hooks record the denial, they cannot veto it. The authorizer already decided.
func (*Registry) EmitToolFailed ¶
func (*Registry) Extensions ¶
Extensions returns all registered extensions.
type RunCompleted ¶
type RunCompleted interface {
OnRunCompleted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, output string, elapsed time.Duration) error
}
RunCompleted is called when an agent run finishes successfully.
type RunFailed ¶
type RunFailed interface {
OnRunFailed(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, err error) error
}
RunFailed is called when an agent run fails.
type RunStarted ¶
type RunStarted interface {
OnRunStarted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, input string) error
}
RunStarted is called when an agent run begins.
type RunTerminated ¶
type RunTerminated interface {
OnRunTerminated(context.Context, id.AgentID, id.AgentRunID, run.TerminalSummary) error
}
RunTerminated observes a persisted terminal state, including incomplete and cancelled runs. It does not imply verification or durable hook delivery.
type StepCompleted ¶
type StepCompleted interface {
OnStepCompleted(ctx context.Context, runID id.AgentRunID, stepIndex int, elapsed time.Duration) error
}
StepCompleted is called when a reasoning step finishes.
type StepStarted ¶
type StepStarted interface {
OnStepStarted(ctx context.Context, runID id.AgentRunID, stepIndex int) error
}
StepStarted is called when a reasoning step begins.
type ToolCalled ¶
type ToolCalled interface {
OnToolCalled(ctx context.Context, runID id.AgentRunID, toolName string, args any) error
}
ToolCalled is called when a tool invocation begins.
type ToolCompleted ¶
type ToolCompleted interface {
OnToolCompleted(ctx context.Context, runID id.AgentRunID, toolName string, result string, elapsed time.Duration) error
}
ToolCompleted is called when a tool invocation finishes successfully.
type ToolDenied ¶
type ToolDenied interface {
OnToolDenied(ctx context.Context, runID id.AgentRunID, toolName, reason string) error
}
ToolDenied is called when an authorizer refuses a tool call. A denial that leaves no record is the one an operator will want later.
type ToolFailed ¶
type ToolFailed interface {
OnToolFailed(ctx context.Context, runID id.AgentRunID, toolName string, err error) error
}
ToolFailed is called when a tool invocation fails.
Source Files