hydaelyn

README

Hydaelyn

Hydaelyn is a Run/Task runner for Go.

Embed it into your application with hydaelyn.New() to run durable workflows where every state change goes through Run/Task commands, policy, leases, typed reports, handoff, response outbox, and replay.

Install

go get github.com/Viking602/go-hydaelyn@latest

Quickstart

Start a run with the default in-memory runner and inspect the append-only event stream:

package main

import (
	"context"
	"fmt"

	"github.com/Viking602/go-hydaelyn"
	"github.com/Viking602/go-hydaelyn/api"
)

func main() {
	runner := hydaelyn.New()
	run, err := runner.QueueRun(context.Background(), api.StartRunCommand{
		Request: "compare options for a Go research assistant",
	})
	if err != nil {
		panic(err)
	}
	events, err := runner.RunEvents(context.Background(), run.ID)
	if err != nil {
		panic(err)
	}
	fmt.Println(run.ID, len(events))
}

Core Concepts

Hydaelyn centers on embeddable runner primitives. New work should model execution as Run + Task + TaskExecutionLease. The optional worker package bridges TaskEnvelope execution to agent.Engine. Flow adapters are presets only; they must not bypass TaskStore, PolicyEngine, TaskExecutionLease, handoff, ResponseLayer, or OutputGateway.

Use api.Config only when overriding defaults:

runner := hydaelyn.New(api.Config{
	PolicyEngine: policy.DenySideEffectsByDefault(),
})

The old Team + Pattern runtime has been removed from the v2 public surface. Compose new work around the root hydaelyn runner API.

Examples + Read Next

Examples

• _examples/research - Local quickstart
• _examples/panel - Panel task-board collaboration
• _examples/collab - Collaboration pattern
• _examples/tooling - Tool integration
• _examples/approval - Approval flows
• _examples/durable - Durable execution

Examples live under _examples/ (leading underscore) so they are skipped by go build ./.... Build or run one explicitly with go run ./_examples/research/.

Read Next

• Quickstart - Deep-dive tutorial
• Extensions - Stage / Capability / Output / Hook guide
• Task Dataflow - Dataflow documentation
• Recipe Compiler - Recipe/YAML configuration
• Evaluation - Performance evaluation
• Durable Execution - Replay and durability

Where Hydaelyn Fits

Hydaelyn is designed to live inside your Go application. Compose the root Runner, register stable provider/tool/policy/flow contracts, and drive work through Run/Task commands.

The CLI is useful for inspection and workflow support, but the library is the primary surface. MCP can be plugged in as one integration path, not as the core execution model. V1 stays single-process, and the intended extension model is composition around the runner rather than subclassing a framework.

Development

See CONTRIBUTING.md for coding standards and contribution guidelines.

Documentation

Overview

Package hydaelyn is the root facade for the go-hydaelyn runner. It owns construction and the Runner wrapper:

runner := hydaelyn.New()

Import api for public contracts such as Config, commands, store interfaces, policy requests, and Run/Task value types.

Public packages are grouped by stable extension concern:

• hydaelyn — Runner construction, methods, and error re-exports
• api — Config, commands, interfaces, Run/Task data contracts
• [agent] — agent engine and profile contracts
• [tool] — tool contract, effect types, and tooltest helpers
• [flow] — flow preset contracts
• [policy] — unified authorization contract
• [blackboard] — blackboard item and selector contracts
• [provider] — LLM provider drivers (anthropic, openai, scripted)
• [message] — shared message/content data types
• [hook] — pre/post-turn hook contracts
• [transport] — integration transports such as MCP
• [worker] — optional Runner-to-agent.Engine execution glue

Types under internal/ are implementation details. Core storage, mailbox, transition, command-handler, and replay internals are not public extension points and cannot be imported by consumers.

Package hydaelyn is the public façade for the Hydaelyn runner.

Import github.com/Viking602/go-hydaelyn/api for public contracts such as Config, commands, interfaces, and value types. The root package owns only construction, Runner methods, and sentinel error re-exports.

Index

• Variables
• func DefaultConfig() api.Config
• type Runner
  • func New(configs ...api.Config) *Runner
  • func (r *Runner) AckEnvelope(ctx context.Context, cmd api.AckEnvelopeCommand) error
  • func (r *Runner) AcquireTaskExecution(ctx context.Context, cmd api.AcquireTaskExecutionCommand) (api.TaskExecutionLease, bool, error)
  • func (r *Runner) ActiveLeaseCount(runID, taskID string) int
  • func (r *Runner) AdvanceRun(ctx context.Context, cmd api.AdvanceRunCommand) (api.Run, error)
  • func (r *Runner) Agents() []api.AgentProfile
  • func (r *Runner) AppendEvent(ctx context.Context, event api.Event) error
  • func (r *Runner) Begin(ctx context.Context) (api.UnitOfWork, error)
  • func (r *Runner) CompleteActionAttempt(ctx context.Context, cmd api.CompleteActionAttemptCommand) (api.ActionAttempt, error)
  • func (r *Runner) CreateTask(ctx context.Context, cmd api.CreateTaskCommand) (api.Task, error)
  • func (r *Runner) DeadLetter(ctx context.Context, cmd api.DeadLetterCommand) error
  • func (r *Runner) DecideApproval(ctx context.Context, cmd api.DecideApprovalCommand) error
  • func (r *Runner) DispatchTask(ctx context.Context, cmd api.DispatchTaskCommand) (api.TaskEnvelope, error)
  • func (r *Runner) DispatchTaskFanOut(ctx context.Context, cmd api.FanOutDispatchTaskCommand) ([]api.TaskEnvelope, error)
  • func (r *Runner) DrainResponseOutbox(ctx context.Context) (int, error)
  • func (r *Runner) EndTraceSpan(ctx context.Context, cmd api.EndTraceSpanCommand) error
  • func (r *Runner) Events(runID string) []api.Event
  • func (r *Runner) ExecuteCommand(ctx context.Context, command api.Command) (any, error)
  • func (r *Runner) HeartbeatTaskExecution(ctx context.Context, cmd api.HeartbeatTaskExecutionCommand) error
  • func (r *Runner) InvokeTool(ctx context.Context, cmd api.ToolInvocation) (api.ToolInvocationResult, error)
  • func (r *Runner) ListEnvelopes(ctx context.Context, runID string) ([]api.TaskEnvelope, error)
  • func (r *Runner) ListEvents(ctx context.Context, runID string) ([]api.Event, error)
  • func (r *Runner) ListMessages(ctx context.Context, runID string) ([]api.UserMessage, error)
  • func (r *Runner) ListQueuedMessages(ctx context.Context) ([]api.UserMessage, error)
  • func (r *Runner) ListTasks(ctx context.Context, runID string) ([]api.Task, error)
  • func (r *Runner) ListTraceSpans(ctx context.Context, runID string) ([]api.TraceSpan, error)
  • func (r *Runner) LoadEnvelope(ctx context.Context, envelopeID string) (api.TaskEnvelope, error)
  • func (r *Runner) LoadMessage(ctx context.Context, runID, messageID string) (api.UserMessage, error)
  • func (r *Runner) LoadRun(ctx context.Context, runID string) (api.Run, error)
  • func (r *Runner) LoadTask(ctx context.Context, runID, taskID string) (api.Task, error)
  • func (r *Runner) PublishResponse(ctx context.Context, cmd api.PublishResponseCommand) error
  • func (r *Runner) QueueEnvelope(ctx context.Context, env api.TaskEnvelope) error
  • func (r *Runner) QueueMessage(ctx context.Context, message api.UserMessage) error
  • func (r *Runner) QueueRun(ctx context.Context, cmd api.StartRunCommand) (api.Run, error)
  • func (r *Runner) ReadyTasks(runID string) []api.Task
  • func (r *Runner) Recover(ctx context.Context, runID string) (api.Projection, error)
  • func (r *Runner) RecoverResumeToken(ctx context.Context, cmd api.RecoverResumeTokenCommand) (api.ResumeToken, error)
  • func (r *Runner) RegisterAgent(profile api.AgentProfile)
  • func (r *Runner) RegisterFlow(flow api.Flow) error
  • func (r *Runner) RegisterTool(tool api.Tool)
  • func (r *Runner) ReleaseTaskExecution(ctx context.Context, cmd api.ReleaseTaskExecutionCommand) error
  • func (r *Runner) Replay(runID string, mode api.ReplayMode) (api.Projection, error)
  • func (r *Runner) ReplayRunState(runID string) (api.Projection, error)
  • func (r *Runner) RequestApproval(ctx context.Context, cmd api.RequestApprovalCommand) (api.ApprovalRequest, api.ResumeToken, error)
  • func (r *Runner) RequestHandoff(ctx context.Context, cmd api.HandoffCommand) error
  • func (r *Runner) ResponseOutbox(runID string) []api.UserMessage
  • func (r *Runner) ResumeTokens() map[string]api.ResumeToken
  • func (r *Runner) Run(ctx context.Context, runID string) (api.Run, error)
  • func (r *Runner) RunEvents(ctx context.Context, runID string) ([]api.Event, error)
  • func (r *Runner) RunTimeline(ctx context.Context, runID string) ([]api.RunTimelineItem, error)
  • func (r *Runner) SaveRun(ctx context.Context, run api.Run) error
  • func (r *Runner) SaveTask(ctx context.Context, task api.Task) error
  • func (r *Runner) SaveTraceSpan(ctx context.Context, span api.TraceSpan) error
  • func (r *Runner) SelectItems(ctx context.Context, runID string, selector api.BlackboardSelector) ([]api.BlackboardItem, error)
  • func (r *Runner) SetMessagePolicy(policy api.MessagePolicyChecker)
  • func (r *Runner) SetOutputGateway(gateway api.OutputGateway)
  • func (r *Runner) SetPipeline(components api.PipelineComponents)
  • func (r *Runner) SetPolicyEngine(policy api.PolicyEngine)
  • func (r *Runner) StartActionAttempt(ctx context.Context, cmd api.StartActionAttemptCommand) (api.ActionAttempt, error)
  • func (r *Runner) StartRun(ctx context.Context, cmd api.StartRunCommand) (api.Run, api.Task, error)
  • func (r *Runner) StartTraceSpan(ctx context.Context, cmd api.StartTraceSpanCommand) (api.TraceSpan, error)
  • func (r *Runner) StoreProvider() api.StoreProvider
  • func (r *Runner) SubmitResponseOutput(ctx context.Context, cmd api.SubmitResponseOutputCommand) error
  • func (r *Runner) SubmitTypedReport(ctx context.Context, cmd api.SubmitTypedReportCommand) error
  • func (r *Runner) SubmitUserInput(ctx context.Context, cmd api.SubmitUserInputCommand) error
  • func (r *Runner) Subscribe(ctx context.Context, runID string, filter api.BlackboardFilter) (<-chan api.BlackboardItem, func() error, error)
  • func (r *Runner) Task(ctx context.Context, runID, taskID string) (api.Task, error)
  • func (r *Runner) TraceSpans(runID string) []api.TraceSpan
  • func (r *Runner) TransitionRun(ctx context.Context, cmd api.TransitionRunCommand) error
  • func (r *Runner) TransitionTask(ctx context.Context, cmd api.TransitionTaskCommand) error
  • func (r *Runner) UpdateEnvelope(ctx context.Context, env api.TaskEnvelope) error
  • func (r *Runner) UpdateMessage(ctx context.Context, message api.UserMessage) error
  • func (r *Runner) WaitForBlackboard(ctx context.Context, runID string, filter api.BlackboardFilter, ...) ([]api.BlackboardItem, error)
  • func (r *Runner) WriteItem(ctx context.Context, item api.BlackboardItem) error

Variables

var (
	ErrNotFound                = api.ErrNotFound
	ErrTerminalState           = api.ErrTerminalState
	ErrStaleTaskVersion        = api.ErrStaleTaskVersion
	ErrLeaseHolderMismatch     = api.ErrLeaseHolderMismatch
	ErrLeaseNotActive          = api.ErrLeaseNotActive
	ErrOwnerMismatch           = api.ErrOwnerMismatch
	ErrActionTaskRequired      = api.ErrActionTaskRequired
	ErrActionReconcileRequired = api.ErrActionReconcileRequired
	ErrResponseTaskRequired    = api.ErrResponseTaskRequired
	ErrPolicyDenied            = api.ErrPolicyDenied
	ErrPolicyObligationFailed  = api.ErrPolicyObligationFailed
	ErrFlowBypass              = api.ErrFlowBypass
	ErrHandoffCycle            = api.ErrHandoffCycle
	ErrHandoffDepthExceeded    = api.ErrHandoffDepthExceeded
	ErrInvalidCommand          = api.ErrInvalidCommand
	ErrInvalidTransition       = api.ErrInvalidTransition
	ErrCompletionCriteriaUnmet = api.ErrCompletionCriteriaUnmet
	ErrDependencyUnmet         = api.ErrDependencyUnmet
	ErrDependencyFailed        = api.ErrDependencyFailed
	ErrInvalidConfiguration    = api.ErrInvalidConfiguration
	ErrInvalidAddress          = api.ErrInvalidAddress
	ErrNoRecipients            = api.ErrNoRecipients
	ErrSubscriptionClosed      = api.ErrSubscriptionClosed
	ErrWaitTimeout             = api.ErrWaitTimeout
)

Public sentinel errors are owned by api and re-exported here for callers that only need root-level construction and error checks.

Functions

func DefaultConfig

func DefaultConfig() api.Config

DefaultConfig returns an empty api.Config; useful as a baseline before overriding individual fields.

Types

type Runner

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

Runner is the public façade over the internal runtime. All public contract values crossing this boundary use api package types, not internal/core types.

func New

func New(configs ...api.Config) *Runner

New constructs the primary Run/Task runner. With no arguments it uses the default in-memory configuration; pass api.Config values to override defaults.

func (*Runner) AckEnvelope

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

func (*Runner) AcquireTaskExecution

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

func (*Runner) ActiveLeaseCount

func (r *Runner) ActiveLeaseCount(runID, taskID string) int

func (*Runner) AdvanceRun

func (r *Runner) AdvanceRun(ctx context.Context, cmd api.AdvanceRunCommand) (api.Run, error)

func (*Runner) Agents

func (r *Runner) Agents() []api.AgentProfile

func (*Runner) AppendEvent

func (r *Runner) AppendEvent(ctx context.Context, event api.Event) error

func (*Runner) Begin

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

func (*Runner) CompleteActionAttempt

func (r *Runner) CompleteActionAttempt(ctx context.Context, cmd api.CompleteActionAttemptCommand) (api.ActionAttempt, error)

func (*Runner) CreateTask

func (r *Runner) CreateTask(ctx context.Context, cmd api.CreateTaskCommand) (api.Task, error)

func (*Runner) DeadLetter

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

func (*Runner) DecideApproval

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

func (*Runner) DispatchTask

func (r *Runner) DispatchTask(ctx context.Context, cmd api.DispatchTaskCommand) (api.TaskEnvelope, error)

func (*Runner) DispatchTaskFanOut

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

func (*Runner) DrainResponseOutbox

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

func (*Runner) EndTraceSpan

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

func (*Runner) Events

func (r *Runner) Events(runID string) []api.Event

func (*Runner) ExecuteCommand

func (r *Runner) ExecuteCommand(ctx context.Context, command api.Command) (any, error)

func (*Runner) HeartbeatTaskExecution

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

func (*Runner) InvokeTool

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

func (*Runner) ListEnvelopes

func (r *Runner) ListEnvelopes(ctx context.Context, runID string) ([]api.TaskEnvelope, error)

func (*Runner) ListEvents

func (r *Runner) ListEvents(ctx context.Context, runID string) ([]api.Event, error)

func (*Runner) ListMessages

func (r *Runner) ListMessages(ctx context.Context, runID string) ([]api.UserMessage, error)

func (*Runner) ListQueuedMessages

func (r *Runner) ListQueuedMessages(ctx context.Context) ([]api.UserMessage, error)

func (*Runner) ListTasks

func (r *Runner) ListTasks(ctx context.Context, runID string) ([]api.Task, error)

func (*Runner) ListTraceSpans

func (r *Runner) ListTraceSpans(ctx context.Context, runID string) ([]api.TraceSpan, error)

func (*Runner) LoadEnvelope

func (r *Runner) LoadEnvelope(ctx context.Context, envelopeID string) (api.TaskEnvelope, error)

func (*Runner) LoadMessage

func (r *Runner) LoadMessage(ctx context.Context, runID, messageID string) (api.UserMessage, error)

func (*Runner) LoadRun

func (r *Runner) LoadRun(ctx context.Context, runID string) (api.Run, error)

func (*Runner) LoadTask

func (r *Runner) LoadTask(ctx context.Context, runID, taskID string) (api.Task, error)

func (*Runner) PublishResponse

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

func (*Runner) QueueEnvelope

func (r *Runner) QueueEnvelope(ctx context.Context, env api.TaskEnvelope) error

func (*Runner) QueueMessage

func (r *Runner) QueueMessage(ctx context.Context, message api.UserMessage) error

func (*Runner) QueueRun

func (r *Runner) QueueRun(ctx context.Context, cmd api.StartRunCommand) (api.Run, error)

func (*Runner) ReadyTasks

func (r *Runner) ReadyTasks(runID string) []api.Task

func (*Runner) Recover

func (r *Runner) Recover(ctx context.Context, runID string) (api.Projection, error)

func (*Runner) RecoverResumeToken

func (r *Runner) RecoverResumeToken(ctx context.Context, cmd api.RecoverResumeTokenCommand) (api.ResumeToken, error)

func (*Runner) RegisterAgent

func (r *Runner) RegisterAgent(profile api.AgentProfile)

func (*Runner) RegisterFlow

func (r *Runner) RegisterFlow(flow api.Flow) error

func (*Runner) RegisterTool

func (r *Runner) RegisterTool(tool api.Tool)

func (*Runner) ReleaseTaskExecution

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

func (*Runner) Replay

func (r *Runner) Replay(runID string, mode api.ReplayMode) (api.Projection, error)

func (*Runner) ReplayRunState

func (r *Runner) ReplayRunState(runID string) (api.Projection, error)

func (*Runner) RequestApproval

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

func (*Runner) RequestHandoff

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

func (*Runner) ResponseOutbox

func (r *Runner) ResponseOutbox(runID string) []api.UserMessage

func (*Runner) ResumeTokens

func (r *Runner) ResumeTokens() map[string]api.ResumeToken

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, runID string) (api.Run, error)

func (*Runner) RunEvents

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

func (*Runner) RunTimeline

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

func (*Runner) SaveRun

func (r *Runner) SaveRun(ctx context.Context, run api.Run) error

func (*Runner) SaveTask

func (r *Runner) SaveTask(ctx context.Context, task api.Task) error

func (*Runner) SaveTraceSpan

func (r *Runner) SaveTraceSpan(ctx context.Context, span api.TraceSpan) error

func (*Runner) SelectItems

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

func (*Runner) SetMessagePolicy

func (r *Runner) SetMessagePolicy(policy api.MessagePolicyChecker)

func (*Runner) SetOutputGateway

func (r *Runner) SetOutputGateway(gateway api.OutputGateway)

func (*Runner) SetPipeline

func (r *Runner) SetPipeline(components api.PipelineComponents)

func (*Runner) SetPolicyEngine

func (r *Runner) SetPolicyEngine(policy api.PolicyEngine)

func (*Runner) StartActionAttempt

func (r *Runner) StartActionAttempt(ctx context.Context, cmd api.StartActionAttemptCommand) (api.ActionAttempt, error)

func (*Runner) StartRun

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

func (*Runner) StartTraceSpan

func (r *Runner) StartTraceSpan(ctx context.Context, cmd api.StartTraceSpanCommand) (api.TraceSpan, error)

func (*Runner) StoreProvider

func (r *Runner) StoreProvider() api.StoreProvider

func (*Runner) SubmitResponseOutput

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

func (*Runner) SubmitTypedReport

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

func (*Runner) SubmitUserInput

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

func (*Runner) Subscribe

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

func (*Runner) Task

func (r *Runner) Task(ctx context.Context, runID, taskID string) (api.Task, error)

func (*Runner) TraceSpans

func (r *Runner) TraceSpans(runID string) []api.TraceSpan

func (*Runner) TransitionRun

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

func (*Runner) TransitionTask

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

func (*Runner) UpdateEnvelope

func (r *Runner) UpdateEnvelope(ctx context.Context, env api.TaskEnvelope) error

func (*Runner) UpdateMessage

func (r *Runner) UpdateMessage(ctx context.Context, message api.UserMessage) error

func (*Runner) WaitForBlackboard

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

func (*Runner) WriteItem

func (r *Runner) WriteItem(ctx context.Context, item api.BlackboardItem) error