runtime

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Index

Constants

View Source 
const AutonomousIterationStepPrefix = "auto:iter:"

AutonomousIterationStepPrefix prefixes the StepOutputs keys the autonomous tool loop writes at every iteration boundary. The value under "auto:iter:<n>" is the JSON-serialized conversation ([]llm.Message) after iteration n completed - one LLM response plus every tool call it requested - externalized to the blob store above the step-output threshold like any other step output. RetryFailedRun resumes a crashed autonomous run from the highest persisted iteration instead of requiring a HITL gate checkpoint.

Variables

View Source 
var (
	ErrRunAlreadyCompleted = errors.New("runtime: run already completed")
	ErrRunInProgress       = errors.New("runtime: run is already running")
	ErrRunPaused           = errors.New("runtime: run is paused")
	ErrRunFailed           = errors.New("runtime: run has failed")
	ErrRunCancelled        = errors.New("runtime: run is cancelled")
	// ErrLLMGatewayRequired reports that a run needs an LLM call but no
	// gateway is wired. It is a permanent configuration error: blind retries
	// can never succeed, so checkpoint-continue paths classify it as
	// permanent (run marked Failed) instead of keeping the run Running for a
	// transient retry.
	ErrLLMGatewayRequired = errors.New("runtime: llm gateway is required")
)

Functions

func ClearOrphanedCheckpointState added in v0.3.0 

func ClearOrphanedCheckpointState(snapshot *runstate.RunSnapshot)

ClearOrphanedCheckpointState removes tool_approval checkpoint metadata when the serialized conversation was already consumed and cannot be resumed.

func ContextWithEventTee added in v0.3.0 

func ContextWithEventTee(ctx context.Context, sink core.EventSink) context.Context

ContextWithEventTee attaches a side-channel EventSink used by Framework.StreamRun to observe runtime events without requiring an EventHub subscription.

func ContextWithRunLeaseOwner added in v0.3.0 

func ContextWithRunLeaseOwner(ctx context.Context, owner string) context.Context

ContextWithRunLeaseOwner stamps the identity of the worker holding the run's distributed lease onto the context, so run snapshots created while the lease is held record ownership. MarkAbandonedRuns only reaps Running runs carrying this marker; runs executed without lease coordination never look like zombies.

func ContextWithRunResumedEmitted added in v0.3.0 

func ContextWithRunResumedEmitted(ctx context.Context) context.Context

ContextWithRunResumedEmitted marks that RunResumed was already emitted for this resume call so continueAfterCheckpoint does not double-emit.

func ContextWithStreamDetached added in v0.3.0 

func ContextWithStreamDetached(ctx context.Context) context.Context

ContextWithStreamDetached marks the stream to keep executing to a terminal state in the background when the caller's context is cancelled (e.g. client disconnect), instead of marking the run Cancelled.

func ContextWithTrustMode added in v0.3.0 

func ContextWithTrustMode(ctx context.Context, mode TrustMode) context.Context

func EmitWithLifecycleRetry added in v0.3.0 

func EmitWithLifecycleRetry(ctx context.Context, sink core.EventSink, event core.Event) error

EmitWithLifecycleRetry delivers one event via sink. Critical lifecycle events are retried a limited number of times with backoff so a transient sink outage (e.g. a DB blip) does not silently drop them; all other events are delivered on a best-effort single attempt.

func EventTeeFromContext added in v0.3.0 

func EventTeeFromContext(ctx context.Context) core.EventSink

EventTeeFromContext returns the side-channel sink attached by ContextWithEventTee, or nil. The Framework-level event sink consults it so engine, workflow-runner, and facade emissions all reach a StreamRun tee.

func HasAutonomousIterationProgress added in v0.3.1 

func HasAutonomousIterationProgress(snapshot runstate.RunSnapshot) bool

HasAutonomousIterationProgress reports whether the snapshot carries at least one persisted autonomous iteration boundary.

func IsCriticalLifecycleEvent added in v0.3.0 

func IsCriticalLifecycleEvent(typ core.EventType) bool

IsCriticalLifecycleEvent reports whether typ is a run-lifecycle event whose silent loss would corrupt downstream state tracking (RunCompleted / RunPaused / RunFailed / RunCancelled). Delivery of these events is retried with backoff before being given up.

func RunLeaseOwnerFromContext added in v0.3.0 

func RunLeaseOwnerFromContext(ctx context.Context) string

RunLeaseOwnerFromContext returns the lease owner attached by ContextWithRunLeaseOwner, or "".

Types

type Dependencies 

type Dependencies struct {
	LLM                   llm.Gateway
	Tools                 ToolRegistry
	Memory                map[string]memory.Repository
	TierMemory            map[string]tier.Manager
	Cognitive             map[string]memory.CognitiveMemory
	Runs                  runstate.Repository
	Blobs                 runstate.BlobStore
	Events                core.EventSink
	HumanGate             core.HumanGate
	ToolApprovalEvaluator core.ToolApprovalEvaluator
	Policy                security.Policy
	Audit                 audit.Sink
	ToolPolicy            governance.ToolPolicy
	OutputRedactor        governance.OutputRedactor
	// LLMPayloadCapture controls whether LLMCalled events include message and
	// prompt plaintext. Default false: payloads carry only message count,
	// per-message lengths, and a truncated content hash.
	LLMPayloadCapture bool
	// Recorder receives metric observations. If nil, metrics are discarded.
	Recorder observability.Recorder
	// Tracer receives distributed tracing spans. If nil, tracing is a no-op.
	Tracer observability.Tracer
	// Logger receives structured log messages for warning and error paths.
	// If nil, messages are silently discarded.
	Logger log.Logger
	// EnqueueMemoryReconcile enqueues async tier reconcile jobs after tier writes.
	EnqueueMemoryReconcile func(context.Context, async.Job) error
	// ToolOutputTransforms are optional per-tool reshapers applied before LLM/memory.
	ToolOutputTransforms map[string]contextwindow.ToolOutputTransform
	// InterjectDrain controls when mid-turn interjections enter the tool loop.
	InterjectDrain interjection.DrainPolicy
	// ToolOrchestrator optional approval cache / post-attempt hooks (sandbox is host-owned).
	ToolOrchestrator toolorch.ToolOrchestrator
	// ApprovalStore caches allow/deny decisions; when nil and orchestrator is a
	// StoreOrchestrator, that store is used. Otherwise a memory store is created
	// when HITLDenyLimit or orchestrator needs it.
	ApprovalStore toolorch.ApprovalStore
	// TurnStopHook optional host veto after a candidate final answer.
	TurnStopHook core.TurnStopHook
	// ToolCatalog optional deferred tool catalog for meta-tool discovery.
	ToolCatalog toolcatalog.Catalog
	// DeferredTools enables catalog deferral (default true when ToolCatalog set).
	DeferredTools bool
}

type Engine 

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

func NewEngine 

func NewEngine(scenario core.Scenario, deps Dependencies) (*Engine, error)

func (*Engine) ClearCheckpointState added in v0.3.0 

func (e *Engine) ClearCheckpointState(ctx context.Context, runID string) error

ClearCheckpointState removes any pending checkpoint metadata (and a stored human amendment) for a run without resuming execution. It is used when a run is resumed/approved but the caller chose not to continue execution, so a later Run() must not re-enter or act on the now-consumed checkpoint.

func (*Engine) ClearRunScopedState added in v0.3.0 

func (e *Engine) ClearRunScopedState(runID string)

ClearRunScopedState exposes clearRunScopedState for the framework facade, whose workflow-mode terminal transitions (completeWorkflowRun, markWorkflowFailed) persist outside the engine's own terminal helpers but share the same run-scoped bookkeeping.

func (*Engine) ContinueAfterCheckpoint added in v0.1.2 

func (e *Engine) ContinueAfterCheckpoint(ctx context.Context, runID string) (RunResult, error)

ContinueAfterCheckpoint resumes execution for a run that was approved at a checkpoint.

func (*Engine) ContinueAfterCheckpointPhase added in v0.3.0 

func (e *Engine) ContinueAfterCheckpointPhase(ctx context.Context, runID string) (RunResult, error)

ContinueAfterCheckpointPhase resumes a checkpointed agent phase without marking the run Completed. Callers embedding the runtime inside a workflow must persist the returned output as a workflow step and finish the run themselves.

func (*Engine) EmitRunResumedForSnapshot added in v0.3.0 

func (e *Engine) EmitRunResumedForSnapshot(ctx context.Context, snapshot runstate.RunSnapshot)

EmitRunResumedForSnapshot exposes RunResumed emission for Framework resume entry points that may continue via workflow paths (AF-REQ-02/06).

func (*Engine) Interject added in v0.3.0 

func (e *Engine) Interject(runID, text string) error

Interject queues a mid-turn user message for runID. Drain timing follows Engine.interjectDrain (Codex-style steer alignment). The run must exist and still be active (Running): messages for unknown or terminal/paused runs are rejected instead of being buffered forever.

func (*Engine) LateConfig added in v0.3.0 

func (e *Engine) LateConfig() (map[string]contextwindow.ToolOutputTransform, interjection.DrainPolicy)

LateConfig returns a copy of runtime-mutable engine config for engine rebuild.

func (*Engine) MarkRunCancelled added in v0.4.4 

func (e *Engine) MarkRunCancelled(ctx context.Context, runID string)

MarkRunCancelled exposes the engine's terminal cancellation transition to facade-owned workflow execution paths.

func (*Engine) ReconcileTierMemory added in v0.1.9 

func (e *Engine) ReconcileTierMemory(ctx context.Context, runID, memoryName, agentName string) error

func (*Engine) RememberHITLReject added in v0.3.0 

func (e *Engine) RememberHITLReject(ctx context.Context, runID string)

RememberHITLReject records a human rejection against the approval cache and deny breaker. Used when ResumeAndContinue receives DecisionReject.

func (*Engine) ResolveAgentName added in v0.3.0 

func (e *Engine) ResolveAgentName(name string) (string, error)

func (*Engine) ResumeAutonomousFromIteration added in v0.3.1 

func (e *Engine) ResumeAutonomousFromIteration(ctx context.Context, runID string) (RunResult, error)

ResumeAutonomousFromIteration re-enters an autonomous run that failed mid-loop without a HITL gate checkpoint. It loads the conversation persisted at the highest iteration boundary and continues the tool loop from there: completed iterations are never re-sent to the LLM.

The resumed loop starts with a fresh tool-call tracker and replan budget: neither is part of the iteration checkpoint, so governance rate caps and the replan limit reset across a crash recovery, same as a process restart.

Side-effect semantics are at-least-once at iteration granularity: a crash after an iteration's tool calls executed but before the boundary was persisted replays that whole iteration (the LLM call included) on resume. Tools with side effects should deduplicate on the run-scoped idempotency key the runtime passes through the tool-call context.

func (*Engine) RewindConversationMemory added in v0.3.0 

func (e *Engine) RewindConversationMemory(ctx context.Context, runID, agentName string, keep int) error

RewindConversationMemory truncates a run-scoped conversation memory to the first keep messages, dropping any later turns. It is used by workflow time-travel to align conversation memory with rewound step outputs. It is a no-op for non-conversation or tier-backed memory.

func (*Engine) Run 

func (e *Engine) Run(ctx context.Context, req RunRequest) (RunResult, error)

func (*Engine) RunAgent 

func (e *Engine) RunAgent(ctx context.Context, agentName string, input core.AgentInput) (core.AgentOutput, error)

func (*Engine) RunHybrid added in v0.1.1 

func (e *Engine) RunHybrid(ctx context.Context, req RunRequest) (RunResult, error)

RunHybrid continues an existing run – created and partially populated by a workflow phase – by executing the autonomous agent. It does NOT create a new RunSnapshot; instead it loads the one already saved for req.RunID, updates it on completion.

func (*Engine) RunStructured 

func (e *Engine) RunStructured(ctx context.Context, req RunRequest) (RunResult, error)

func (*Engine) Scenario added in v0.3.0 

func (e *Engine) Scenario() core.Scenario

Scenario returns the scenario the engine was constructed with.

func (*Engine) SetInterjectDrainPolicy added in v0.3.0 

func (e *Engine) SetInterjectDrainPolicy(policy interjection.DrainPolicy)

SetInterjectDrainPolicy overrides the drain policy (tests / late config). Safe for concurrent use with the tool loop.

func (*Engine) SetToolOutputTransform added in v0.3.0 

func (e *Engine) SetToolOutputTransform(tool string, fn contextwindow.ToolOutputTransform)

SetToolOutputTransform registers or replaces a per-tool output transform. Safe for concurrent use with the tool loop (tests / late config).

func (*Engine) Stream 

func (e *Engine) Stream(ctx context.Context, req RunRequest) (<-chan llm.ChatChunk, error)

type Logger added in v0.1.1 

type Logger = log.Logger

Logger is the runtime logging port. Prefer pkg/log.Logger in new code.

type RunPausedError added in v0.1.2 

type RunPausedError struct {
	RunID string
	Token string
	Kind  string
}

RunPausedError indicates the run paused and requires human approval before continuing.

func (RunPausedError) Error added in v0.1.2 

func (e RunPausedError) Error() string

type RunRequest 

type RunRequest struct {
	RunID     string          `json:"run_id"`
	Agent     string          `json:"agent,omitempty"`
	Prompt    string          `json:"prompt,omitempty"`
	Context   json.RawMessage `json:"context,omitempty"`
	TrustMode TrustMode       `json:"trust_mode,omitempty"`
	// EpisodeID identifies a platform Episode (one QA test run) that may span
	// multiple Runs or HITL resumes. Distinct from thread_id (Fork only).
	EpisodeID string `json:"episode_id,omitempty"`
	// TriggerKind describes how the run was started (for example manual, webhook, resume).
	TriggerKind string `json:"trigger_kind,omitempty"`
	// SessionID optionally groups Episodes under a longer-lived product session.
	SessionID string `json:"session_id,omitempty"`
}

type RunResult 

type RunResult struct {
	RunID            string             `json:"run_id"`
	Status           runstate.RunStatus `json:"status"`
	Token            string             `json:"token,omitempty"`
	Output           string             `json:"output,omitempty"`
	StructuredOutput json.RawMessage    `json:"structured_output,omitempty"`
}

type ToolRegistry 

type ToolRegistry interface {
	ResolveTool(ctx context.Context, tool core.Tool) (core.ToolExecutor, bool, error)
}

type TrustMode added in v0.3.0 

type TrustMode string

TrustMode controls run-scoped tool approval overrides. 

const (
	TrustModeDefault   TrustMode = ""
	TrustModeFullTrust TrustMode = "full_trust"
)

func TrustModeFromContext added in v0.3.0 

func TrustModeFromContext(ctx context.Context) TrustMode

Source Files

View all Source files

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.