plugin

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(logger log.Logger) *Registry

func (r *Registry) EmitAgentHandoff(ctx context.Context, orchID id.OrchestrationID, fromAgent, toAgent, payload string)

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, reason run.StopReason)

func (r *Registry) EmitRunCompleted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, output string, elapsed time.Duration)

func (r *Registry) EmitRunFailed(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, runErr error)

func (r *Registry) EmitRunReady(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n run.ReadyNotice)

func (r *Registry) EmitRunReclaimable(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n run.ReclaimNotice)

func (r *Registry) EmitRunStarted(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, input string)

func (r *Registry) EmitRunSuspended(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n suspension.Notice)

func (r *Registry) EmitRunTerminated(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, summary run.TerminalSummary)

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, elapsed time.Duration)

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 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 RunReady ¶ added in v1.10.0

type RunReady interface {
	OnRunReady(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n run.ReadyNotice) error
}

RunReady is called when a paused run becomes ready to continue: a reviewer decided its checkpoint, or a caller supplied its external results. It fires once the ready state is written, with ctx carrying the run's own scope. A host usually answers it by queueing a job that calls engine.ContinueRun, on any replica. The same decision made twice at once can fire it twice; only one ContinueRun wins, and the other is refused with cortex.ErrRunNotContinuable, so a duplicate costs one refused job.

type RunReclaimable ¶ added in v1.10.0

type RunReclaimable interface {
	OnRunReclaimable(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n run.ReclaimNotice) error
}

RunReclaimable is called when a running run is left for another worker to take over: its worker released it while shutting down (n.HandOff), or its lease lapsed and the sweeper moved it. It fires once the reclaimable state is written, with ctx carrying the run's own scope. A host usually answers it by queueing a job that calls engine.ContinueRun, on any replica.

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 RunSuspended ¶ added in v1.10.0

type RunSuspended interface {
	OnRunSuspended(ctx context.Context, agentID id.AgentID, runID id.AgentRunID, n suspension.Notice) error
}

RunSuspended is called when a run pauses, for every reason it can: an approval, an external tool, or a reply from another agent. It fires once the run is really paused, so a read of the run from inside the hook shows it paused, and it never fires for a pause that failed.

It is the one hook that covers every pause. CheckpointCreated fires only for approvals, and a host that tells people a run is waiting on them needs to hear about the other two as well.

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 Shutdown ¶

type Shutdown interface {
	OnShutdown(ctx context.Context) error
}

Shutdown is called during graceful shutdown.

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.