core

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AddressKindAgent = model.AddressKindAgent
	AddressKindRole  = model.AddressKindRole
	AddressKindGroup = model.AddressKindGroup
)

Variables

View Source 
var (
	ErrNotFound                = model.ErrNotFound
	ErrTerminalState           = model.ErrTerminalState
	ErrStaleTaskVersion        = model.ErrStaleTaskVersion
	ErrLeaseHolderMismatch     = model.ErrLeaseHolderMismatch
	ErrLeaseNotActive          = model.ErrLeaseNotActive
	ErrOwnerMismatch           = model.ErrOwnerMismatch
	ErrActionTaskRequired      = model.ErrActionTaskRequired
	ErrActionReconcileRequired = model.ErrActionReconcileRequired
	ErrResponseTaskRequired    = model.ErrResponseTaskRequired
	ErrPolicyDenied            = model.ErrPolicyDenied
	ErrPolicyObligationFailed  = model.ErrPolicyObligationFailed
	ErrHandoffCycle            = model.ErrHandoffCycle
	ErrHandoffDepthExceeded    = model.ErrHandoffDepthExceeded
	ErrInvalidCommand          = model.ErrInvalidCommand
	ErrInvalidTransition       = model.ErrInvalidTransition
	ErrCompletionCriteriaUnmet = model.ErrCompletionCriteriaUnmet
	ErrDependencyUnmet         = model.ErrDependencyUnmet
	ErrDependencyFailed        = model.ErrDependencyFailed
	ErrInvalidConfiguration    = model.ErrInvalidConfiguration
)

Package-level error vars re-exported from model so that internal/core files can reference them without an explicit model import on every call site.

View Source 
var (
	ErrInvalidAddress = model.ErrInvalidAddress
	ErrNoRecipients   = model.ErrNoRecipients
)
View Source 
var ErrSubscriptionClosed = errors.New("orchestrator: blackboard subscription already closed")

ErrSubscriptionClosed is returned by a subscription's cancel func if the caller cancels twice.

View Source 
var ErrWaitTimeout = errors.New("orchestrator: blackboard wait timed out")

ErrWaitTimeout is returned by WaitForBlackboard when the timeout elapses before the predicate is satisfied.

Functions

func ResolveRecipients 

func ResolveRecipients(agents []AgentProfile, to Address) ([]string, error)

ResolveRecipients expands an Address into the set of concrete agent IDs among the supplied profiles. The result is deduplicated and stable in input order. Returns ErrNoRecipients when zero agents match a well-formed address.

Types

type AckEnvelopeCommand 

type AckEnvelopeCommand = mailboxsvc.AckEnvelopeCommand

type AcquireTaskExecutionCommand 

type AcquireTaskExecutionCommand = executionsvc.AcquireTaskExecutionCommand

type AcquireTaskExecutionResult 

type AcquireTaskExecutionResult = executionsvc.AcquireResult

type ActionAttemptStore 

type ActionAttemptStore = ports.ActionAttemptStore

type Address 

type Address = model.Address

type AddressKind 

type AddressKind = model.AddressKind

type AdvanceRunCommand 

type AdvanceRunCommand = runsvc.AdvanceRunCommand

type AgentInstanceStore added in v0.9.0 

type AgentInstanceStore = ports.AgentInstanceStore

type AgentProfile 

type AgentProfile = model.AgentProfile

type AgentProfileStore added in v0.8.0 

type AgentProfileStore = ports.AgentProfileStore

type ApprovalFactory 

type ApprovalFactory func(model.Task, string, string) (model.ApprovalRequest, model.ResumeToken)

ApprovalFactory creates an approval request and matching resume token for a task.

type ApprovalStore 

type ApprovalStore = ports.ApprovalStore

type BlackboardCommittedReader 

type BlackboardCommittedReader = ports.BlackboardCommittedReader

type BlackboardFilter 

type BlackboardFilter = model.BlackboardSelector

BlackboardFilter is the subset of BlackboardSelector used to match new items for streaming subscribers. RunID is implicit (set when subscribing).

type BlackboardNotifier 

type BlackboardNotifier interface {
	NotifyBlackboard() []model.BlackboardItem
}

BlackboardNotifier is implemented by command results that produced blackboard items needing commit-time fan-out to in-memory subscribers. Domain handlers opt in by adding NotifyBlackboard() to their public result type instead of having core type-switch on every new result.

type BlackboardReadWriter 

type BlackboardReadWriter = ports.BlackboardReadWriter

type BlackboardStore 

type BlackboardStore = ports.BlackboardReadWriter

type BlackboardSubscriber 

type BlackboardSubscriber = ports.BlackboardSubscriber

type BlackboardWaiter 

type BlackboardWaiter = ports.BlackboardWaiter

type CapabilityReporter added in v0.10.0 

type CapabilityReporter = ports.CapabilityReporter

type CapabilityStore added in v0.8.0 

type CapabilityStore = ports.CapabilityStore

type CompleteActionAttemptCommand 

type CompleteActionAttemptCommand = actionsvc.CompleteActionAttemptCommand

type Config 

type Config struct {
	StoreProvider StoreProvider
	PolicyEngine  PolicyEngine
	OutputGateway OutputGateway
	Pipeline      PipelineComponents
}

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns an empty Config with all fields zero. Callers can supply their own implementations for StoreProvider, PolicyEngine, OutputGateway, or Pipeline; any unset field falls back to the in-memory defaults wired by NewRuntime.

type CreateTaskCommand 

type CreateTaskCommand = runsvc.CreateTaskCommand

type DeadLetterCommand 

type DeadLetterCommand = mailboxsvc.DeadLetterCommand

type DeadLetterStore added in v0.8.0 

type DeadLetterStore = ports.DeadLetterStore

type DecideApprovalCommand 

type DecideApprovalCommand = approvalsvc.DecideApprovalCommand

type DispatchTaskCommand 

type DispatchTaskCommand = mailboxsvc.DispatchTaskCommand

type Dispatcher 

type Dispatcher = ports.Dispatcher

type EndTraceSpanCommand 

type EndTraceSpanCommand = tracesvc.EndTraceSpanCommand

type EventStore 

type EventStore = ports.EventStore

type FanOutDispatchTaskCommand 

type FanOutDispatchTaskCommand = mailboxsvc.FanOutDispatchTaskCommand

type HandoffCommand 

type HandoffCommand = handoffsvc.HandoffCommand

type HandoffStore added in v0.9.0 

type HandoffStore = ports.HandoffStore

type HeartbeatTaskExecutionCommand 

type HeartbeatTaskExecutionCommand = executionsvc.HeartbeatTaskExecutionCommand

type IDGenerator 

type IDGenerator func(prefix string) string

IDGenerator is the runtime capability required by handlers that create model IDs.

type IntentAnalyzer 

type IntentAnalyzer = ports.IntentAnalyzer

type LeaseStore 

type LeaseStore = ports.LeaseStore

type MailboxOutbox 

type MailboxOutbox = model.TaskEnvelope

type MailboxOutboxStore 

type MailboxOutboxStore = ports.MailboxOutboxStore

type OutputGateway 

type OutputGateway = ports.OutputGateway

type OutputGatewayProvider 

type OutputGatewayProvider func() OutputGateway

OutputGatewayProvider returns the currently configured output gateway.

type PipelineComponents 

type PipelineComponents = ports.PipelineComponents

type PipelineProvider 

type PipelineProvider func() PipelineComponents

PipelineProvider returns the currently configured pipeline components.

type PlanValidator 

type PlanValidator = ports.PlanValidator

type Planner 

type Planner = ports.Planner

type PolicyEngine 

type PolicyEngine = ports.PolicyEngine

type Projector 

type Projector = ports.Projector

type ProviderCloser added in v0.10.0 

type ProviderCloser = ports.ProviderCloser

type PublishResponseCommand 

type PublishResponseCommand = responsesvc.PublishCommand

type RecoverResumeTokenCommand 

type RecoverResumeTokenCommand = approvalsvc.RecoverResumeTokenCommand

type ReleaseTaskExecutionCommand 

type ReleaseTaskExecutionCommand = executionsvc.ReleaseTaskExecutionCommand

type RequestApprovalCommand 

type RequestApprovalCommand = approvalsvc.RequestApprovalCommand

type RequestApprovalResult 

type RequestApprovalResult = approvalsvc.RequestApprovalResult

type ResumeTokenStore 

type ResumeTokenStore = ports.ResumeTokenStore

type RunStore 

type RunStore = ports.RunStore

type Runtime 

type Runtime struct {
	*storedel.Delegates
	// contains filtered or unexported fields
}

func New 

func New(configs ...Config) *Runtime

New constructs a Runtime. With no arguments it uses the default in-memory configuration; pass a Config to override individual fields.

func NewMemoryRuntime 

func NewMemoryRuntime() *Runtime

func NewRuntime 

func NewRuntime(config Config) *Runtime

func (*Runtime) AckEnvelope 

func (r *Runtime) AckEnvelope(ctx context.Context, cmd AckEnvelopeCommand) error

func (*Runtime) AcquireTaskExecution 

func (r *Runtime) AcquireTaskExecution(ctx context.Context, cmd AcquireTaskExecutionCommand) (model.TaskExecutionLease, bool, error)

func (*Runtime) ActiveLeaseCount 

func (r *Runtime) ActiveLeaseCount(ctx context.Context, runID, taskID string) int

func (*Runtime) AdvanceRun 

func (r *Runtime) AdvanceRun(ctx context.Context, cmd AdvanceRunCommand) (model.Run, error)

func (*Runtime) Agents 

func (r *Runtime) Agents() []AgentProfile

func (*Runtime) AppendUsage added in v0.9.0 

func (r *Runtime) AppendUsage(ctx context.Context, record model.UsageRecord) error

AppendUsage persists one usage-metering record in its own unit of work. It is the write half of the UsageStore contract; the worker runtime calls it after every engine run so the metering ledger reflects real token consumption.

func (*Runtime) Begin 

func (r *Runtime) Begin(ctx context.Context) (UnitOfWork, error)

func (*Runtime) Close added in v0.10.0 

func (r *Runtime) Close(ctx context.Context) error

func (*Runtime) CompleteActionAttempt 

func (r *Runtime) CompleteActionAttempt(ctx context.Context, cmd CompleteActionAttemptCommand) (model.ActionAttempt, error)

func (*Runtime) CreateTask 

func (r *Runtime) CreateTask(ctx context.Context, cmd CreateTaskCommand) (model.Task, error)

func (*Runtime) DeadLetter 

func (r *Runtime) DeadLetter(ctx context.Context, cmd DeadLetterCommand) error

func (*Runtime) DecideApproval 

func (r *Runtime) DecideApproval(ctx context.Context, cmd DecideApprovalCommand) error

func (*Runtime) DispatchTask 

func (r *Runtime) DispatchTask(ctx context.Context, cmd DispatchTaskCommand) (model.TaskEnvelope, error)

func (*Runtime) DispatchTaskFanOut 

func (r *Runtime) DispatchTaskFanOut(ctx context.Context, cmd FanOutDispatchTaskCommand) ([]model.TaskEnvelope, error)

DispatchTaskFanOut resolves cmd.To against the registered agent profiles and writes one envelope per recipient. The task transitions to Dispatched once (the receivers compete for the lease via AcquireTaskExecution).

func (*Runtime) DrainResponseOutbox 

func (r *Runtime) DrainResponseOutbox(ctx context.Context) (int, error)

func (*Runtime) EndTraceSpan 

func (r *Runtime) EndTraceSpan(ctx context.Context, cmd EndTraceSpanCommand) error

func (*Runtime) Events 

func (r *Runtime) Events(ctx context.Context, runID string) []model.Event

func (*Runtime) ExecuteCommand 

func (r *Runtime) ExecuteCommand(ctx context.Context, command RuntimeCommand) (any, error)

ExecuteCommand routes command through the UoW command bus. PublishResponseCommand is the one deliberate exception: response publication is a three-phase flow (prepare+commit, gateway call made without holding the runtime lock, finalize in a fresh UoW) and so cannot run inside a single UoW handler — see Runtime.PublishResponse.

func (*Runtime) HeartbeatTaskExecution 

func (r *Runtime) HeartbeatTaskExecution(ctx context.Context, cmd HeartbeatTaskExecutionCommand) error

func (*Runtime) InvokeTool 

func (r *Runtime) InvokeTool(ctx context.Context, cmd ToolInvocation) (ToolInvocationResult, error)

func (*Runtime) PendingResumeTokens added in v0.9.0 

func (r *Runtime) PendingResumeTokens(ctx context.Context, sel model.ResumeTokenSelector) ([]model.ResumeToken, error)

PendingResumeTokens lists unconsumed resume tokens matching sel — the crash-recovery enumeration primitive: a restarting host lists pending tokens and feeds each to RecoverResumeToken instead of hand-rolling store access.

func (*Runtime) PublishResponse 

func (r *Runtime) PublishResponse(ctx context.Context, cmd PublishResponseCommand) error

PublishResponse drives the multi-phase response publication flow: 

Phase 1: load + validate + authorize, then commit so the runtime lock
         is released before the gateway call.
Phase 2: invoke the configured output gateway without holding any lock,
         so gateway implementations may re-enter the runtime.
Phase 3: persist the success/failure outcome in a fresh UoW.

func (*Runtime) QueryUsage added in v0.9.0 

func (r *Runtime) QueryUsage(ctx context.Context, sel model.UsageSelector) ([]model.UsageRecord, error)

QueryUsage returns the usage records matching sel.

func (*Runtime) QueueRun 

func (r *Runtime) QueueRun(ctx context.Context, cmd StartRunCommand) (model.Run, error)

func (*Runtime) ReadyTasks 

func (r *Runtime) ReadyTasks(ctx context.Context, runID string) []model.Task

func (*Runtime) Recover 

func (r *Runtime) Recover(ctx context.Context, runID string) (model.Projection, error)

func (*Runtime) RecoverResumeToken 

func (r *Runtime) RecoverResumeToken(ctx context.Context, cmd RecoverResumeTokenCommand) (model.ResumeToken, error)

func (*Runtime) RegisterAgent 

func (r *Runtime) RegisterAgent(profile AgentProfile)

func (*Runtime) RegisterFlow 

func (r *Runtime) RegisterFlow(flow model.Flow) error

RegisterFlow stores a Flow definition by name. Flows compose preset adapters; they cannot bypass runtime invariants — Runner always enforces TaskStore, PolicyEngine, TaskExecutionLease, Handoff, ResponseLayer, and OutputGateway, so this function holds no rejection logic for v0.8.0+.

func (*Runtime) RegisterTool 

func (r *Runtime) RegisterTool(tool model.Tool)

func (*Runtime) ReleaseTaskExecution 

func (r *Runtime) ReleaseTaskExecution(ctx context.Context, cmd ReleaseTaskExecutionCommand) error

func (*Runtime) Replay 

func (r *Runtime) Replay(ctx context.Context, runID string, mode model.ReplayMode) (model.Projection, error)

func (*Runtime) ReplayRunState 

func (r *Runtime) ReplayRunState(ctx context.Context, runID string) (model.Projection, error)

func (*Runtime) RequestApproval 

func (r *Runtime) RequestApproval(ctx context.Context, cmd RequestApprovalCommand) (model.ApprovalRequest, model.ResumeToken, error)

func (*Runtime) RequestHandoff 

func (r *Runtime) RequestHandoff(ctx context.Context, cmd HandoffCommand) error

func (*Runtime) ResponseOutbox 

func (r *Runtime) ResponseOutbox(ctx context.Context, runID string) []model.UserMessage

func (*Runtime) Run 

func (r *Runtime) Run(ctx context.Context, runID string) (model.Run, error)

func (*Runtime) RunEvents 

func (r *Runtime) RunEvents(ctx context.Context, runID string) ([]model.Event, error)

func (*Runtime) RunTimeline 

func (r *Runtime) RunTimeline(ctx context.Context, runID string) ([]model.RunTimelineItem, error)

func (*Runtime) SelectItems 

func (r *Runtime) SelectItems(ctx context.Context, runID string, selector model.BlackboardSelector) ([]model.BlackboardItem, error)

SelectItems is the public BlackboardStore read API backed by the configured store provider.

func (*Runtime) SetMessagePolicy 

func (r *Runtime) SetMessagePolicy(policy model.MessagePolicyChecker)

func (*Runtime) SetOutputGateway 

func (r *Runtime) SetOutputGateway(gateway OutputGateway)

func (*Runtime) SetPipeline 

func (r *Runtime) SetPipeline(components PipelineComponents)

func (*Runtime) SetPolicyEngine 

func (r *Runtime) SetPolicyEngine(policy PolicyEngine)

func (*Runtime) StartActionAttempt 

func (r *Runtime) StartActionAttempt(ctx context.Context, cmd StartActionAttemptCommand) (model.ActionAttempt, error)

func (*Runtime) StartRun 

func (r *Runtime) StartRun(ctx context.Context, cmd StartRunCommand) (model.Run, model.Task, error)

func (*Runtime) StartTraceSpan 

func (r *Runtime) StartTraceSpan(ctx context.Context, cmd StartTraceSpanCommand) (model.TraceSpan, error)

func (*Runtime) StoreCapabilities added in v0.10.0 

func (r *Runtime) StoreCapabilities(ctx context.Context) (ports.StoreCapabilities, error)

func (*Runtime) StoreProvider 

func (r *Runtime) StoreProvider() StoreProvider

func (*Runtime) SubmitResponseOutput 

func (r *Runtime) SubmitResponseOutput(ctx context.Context, cmd SubmitResponseOutputCommand) error

func (*Runtime) SubmitTypedReport 

func (r *Runtime) SubmitTypedReport(ctx context.Context, cmd SubmitTypedReportCommand) error

func (*Runtime) SubmitUserInput 

func (r *Runtime) SubmitUserInput(ctx context.Context, cmd SubmitUserInputCommand) error

func (*Runtime) Subscribe 

func (r *Runtime) Subscribe(ctx context.Context, runID string, filter BlackboardFilter) (<-chan model.BlackboardItem, func() error, error)

Subscribe streams future blackboard writes for runID that match filter. The caller MUST drain the channel and call cancel() when done; on full buffer (default 32) the runtime drops the oldest match (non-blocking writer).

func (*Runtime) SumUsageCredits added in v0.9.0 

func (r *Runtime) SumUsageCredits(ctx context.Context, sel model.UsageSelector) (int64, error)

SumUsageCredits returns the credit sum over records matching sel.

func (*Runtime) Task 

func (r *Runtime) Task(ctx context.Context, runID, taskID string) (model.Task, error)

func (*Runtime) TraceSpans 

func (r *Runtime) TraceSpans(ctx context.Context, runID string) []model.TraceSpan

func (*Runtime) TransitionRun 

func (r *Runtime) TransitionRun(ctx context.Context, cmd TransitionRunCommand) error

func (*Runtime) TransitionTask 

func (r *Runtime) TransitionTask(ctx context.Context, cmd TransitionTaskCommand) error

func (*Runtime) WaitForBlackboard 

func (r *Runtime) WaitForBlackboard(
	ctx context.Context,
	runID string,
	filter BlackboardFilter,
	predicate func([]model.BlackboardItem) bool,
	timeout time.Duration,
) ([]model.BlackboardItem, error)

WaitForBlackboard blocks until predicate returns true for the accumulated matching items, or the context/timeout expires. It subscribes before replaying existing items so writes committed during the replay window are either present in the replay result or delivered by the stream. Items are de-duplicated by ID to avoid double-counting writes that appear in both paths.

timeout=0 means "no timeout" — only ctx.Done() will end the wait.

func (*Runtime) WriteItem 

func (r *Runtime) WriteItem(ctx context.Context, item model.BlackboardItem) error

WriteItem is the public BlackboardStore API. It goes through the UoW command path so policy, trace, and events are all recorded.

type RuntimeCommand 

type RuntimeCommand interface {
	CommandName() string
}

type StartActionAttemptCommand 

type StartActionAttemptCommand = actionsvc.StartActionAttemptCommand

type StartRunCommand 

type StartRunCommand = runsvc.StartRunCommand

type StartRunResult 

type StartRunResult = runsvc.StartRunResult

type StartTraceSpanCommand 

type StartTraceSpanCommand = tracesvc.StartTraceSpanCommand

type StoreProvider 

type StoreProvider = ports.StoreProvider

type SubmitResponseOutputCommand 

type SubmitResponseOutputCommand = responsesvc.SubmitOutputCommand

type SubmitTypedReportCommand 

type SubmitTypedReportCommand = reportsvc.SubmitTypedCommand

type SubmitUserInputCommand 

type SubmitUserInputCommand = userinputsvc.SubmitUserInputCommand

type TaskMonitor 

type TaskMonitor = ports.TaskMonitor

type TaskMonitorProvider 

type TaskMonitorProvider func() TaskMonitor

TaskMonitorProvider returns the currently configured task monitor.

type TaskRouter 

type TaskRouter = ports.TaskRouter

type TaskStore 

type TaskStore = ports.TaskStore

type TeamStateStore added in v0.9.0 

type TeamStateStore = ports.TeamStateStore

type ToolInvocation 

type ToolInvocation = toolgatesvc.Invocation

type ToolInvocationResult 

type ToolInvocationResult = toolgatesvc.InvocationResult

type TraceStore 

type TraceStore = ports.TraceStore

type TransitionRunCommand 

type TransitionRunCommand = tasksvc.TransitionRunCommand

type TransitionTaskCommand 

type TransitionTaskCommand = tasksvc.TransitionTaskCommand

type UnitOfWork 

type UnitOfWork = ports.UnitOfWork

type UoWAuthorizer 

type UoWAuthorizer func(context.Context, ports.UnitOfWork, model.PolicyRequest) (model.PolicyDecision, error)

UoWAuthorizer is the runtime policy boundary exposed to migrated handlers.

type UoWTraceRecorder 

type UoWTraceRecorder func(context.Context, ports.UnitOfWork, string, string, string, string) error

UoWTraceRecorder records a completed trace span inside the active UnitOfWork.

type UsageStore added in v0.8.0 

type UsageStore = ports.UsageStore

type UserMessageOutboxScanner 

type UserMessageOutboxScanner = ports.UserMessageOutboxScanner

type UserMessageStore 

type UserMessageStore = ports.UserMessageStore

type UserTimelineProjector 

type UserTimelineProjector interface {
	ProjectUserTimeline(context.Context, []model.Event) ([]model.RunTimelineItem, error)
}

type WriteBlackboardItemCommand 

type WriteBlackboardItemCommand = blackboardsvc.WriteItemCommand

Source Files

View all Source files

Directories

Path Synopsis
Package adapter is the only bidirectional bridge between the public api types and the internal core model.
 Package adapter is the only bidirectional bridge between the public api types and the internal core model.
Package governance provides pure policy-effect helpers that operate only through ports.UnitOfWork.
 Package governance provides pure policy-effect helpers that operate only through ports.UnitOfWork.

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.