runtime

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package runtime holds the durable AgentHarness runtime declarations of packages/agent/src/harness/runtime/types.ts: the process-local configuration, the lane state projection, lane/operation command decisions and the Drive pass with its effect gate.

Drive procedures (agent/harness/runtime/drive) import this package. Upstream runtime/lane.ts and the drive procedures import each other, which Go does not allow; the Lane implementation that invokes drive procedures must live in a package that imports both, or hand procedures its capabilities through interfaces declared beside them.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AbortRequested

type AbortRequested = execution.AbortRequested

AbortRequested is the expected internal control flow when cancellation wins effect admission (upstream AbortRequested); it is the execution gate's refusal error.

type CommandKind

type CommandKind string

CommandKind discriminates LaneCommand and OperationCommand.

const (
	CommandCommit CommandKind = "commit"
	CommandFinish CommandKind = "finish"
	CommandReturn CommandKind = "return"
	CommandReject CommandKind = "reject"
)

Command kinds.

type Config

type Config struct {
	Tools              []harness.AgentHarnessTool
	Resources          agentharness.Resources
	StreamOptions      harness.AgentHarnessStreamOptions
	RetryPolicy        ai.RetryPolicy
	Compaction         harness.CompactionSettings
	SteeringMode       agent.QueueMode
	FollowUpMode       agent.QueueMode
	ToolExecution      agent.ToolExecutionMode
	ToolContext        ToolContextFactory
	SystemPrompt       SystemPromptFactory
	ToProviderMessages ProviderMessageConverter
	EntryProjectors    map[string]session.EntryProjector
}

Config is the current process-local harness configuration (upstream Config). Values are replaced, never mutated in place.

type ContinueOperationResult

type ContinueOperationResult[T any] struct {
	CancelRequested bool
	Value           T
}

ContinueOperationResult is the outcome of continuing an operation: either the operation's cancellation was requested, or Value was produced.

type Drive

type Drive struct {
	OperationID  string
	Gate         *execution.Gate
	Context      harness.Context
	WaitForRetry bool
	// CloseSignal is cancelled, with the close error as cause, by CloseGate.
	CloseSignal harness.Context
	// DeferredPermits counts permitted deferred polls. Upstream mutates it
	// only from the lane's serialized procedures; access it the same way.
	DeferredPermits int
	// contains filtered or unexported fields
}

Drive is one installed process-local drive pass (upstream Drive). Its Context keeps the caller's values without the caller's cancellation. The effect gate is procedure-facing; BeginAbort/SignalAbort/CloseGate are the owner-facing controls. Completion settles once, with the first of Settle, Fail or CloseGate.

func NewDrive

func NewDrive(ctx harness.Context, options agentharness.DriveOptions) *Drive

NewDrive installs a drive pass for options.OperationID.

func (*Drive) BeginAbort

func (drive *Drive) BeginAbort(cancellation func() error)

BeginAbort closes effect admission with an AbortRequested carrying cancellation, without signalling admitted effects yet.

func (*Drive) CloseGate

func (drive *Drive) CloseGate(err error)

CloseGate permanently refuses admission with err, cancels CloseSignal and rejects the completion with err unless it already settled.

func (*Drive) Completion

func (drive *Drive) Completion(ctx harness.Context) (agentharness.DriveOutcome, error)

Completion waits for the drive completion. A cancelled ctx stops only this wait and returns its abort error (upstream awaitWithContext on completion).

func (*Drive) Done

func (drive *Drive) Done() <-chan struct{}

Done is closed once the completion has settled.

func (*Drive) Fail

func (drive *Drive) Fail(err error)

Fail rejects the completion with err unless already settled.

func (*Drive) Settle

func (drive *Drive) Settle(outcome agentharness.DriveOutcome)

Settle resolves the completion with outcome unless already settled.

func (*Drive) SignalAbort

func (drive *Drive) SignalAbort()

SignalAbort signals admitted effects after the abort marker is durable.

type EventsForCommit

type EventsForCommit func(commit session.CommitResult) []agentharness.HarnessEvent

EventsForCommit derives the events published after a commit.

type LaneCommand

type LaneCommand[T any] struct {
	Kind        CommandKind
	Writes      []session.Write
	Materialize Materializer[T]
	Events      EventsForCommit
	Next        LaneState
	Result      T
	Error       error
}

LaneCommand is one effect-free decision made on a lane's serialized mutation line (upstream LaneCommand):

  • commit: Writes, Materialize, optional Events, and Next lane state;
  • return: Result without writing;
  • reject: Error without writing.

type LanePatch

type LanePatch struct {
	SetTipID         bool
	TipID            *string
	SetConfiguration bool
	Configuration    session.LaneConfiguration
	SetInbox         bool
	Inbox            []session.InboxItem
}

LanePatch updates selected lane fields together with an operation transition (upstream Partial<Pick<LaneState, "tipId" | "configuration" | "inbox">>). A false Set* flag leaves the field unchanged; SetTipID with a nil TipID sets the tip to the root.

type LaneState

type LaneState struct {
	TipID           *string
	Configuration   session.LaneConfiguration
	Inbox           []session.InboxItem
	LastOperationID *string
	Operation       *session.Operation
}

LaneState is the current durable state owned by one lane (upstream LaneState). Operation is nil when the lane is idle.

type Materializer

type Materializer[T any] func(commit session.CommitResult) T

Materializer turns a successful commit into the command result. It runs synchronously on the mutation line and must not perform effects.

type OperationCommand

type OperationCommand[T any] struct {
	Kind           CommandKind
	Writes         []session.Write
	Materialize    Materializer[T]
	Events         EventsForCommit
	OperationState session.OperationState
	Record         session.OperationResultRecord
	Lane           *LanePatch
	Result         T
}

OperationCommand is a durable operation transition (upstream OperationCommand). The Lane pairs the state write with projection publication:

  • commit: Writes, Materialize, optional Events, the next OperationState and an optional Lane patch;
  • finish: Writes, the terminal Record, optional Lane patch, Materialize and optional Events;
  • return: Result without writing.

type ProcedureResult

type ProcedureResult struct {
	Kind    ProcedureResultKind
	Outcome agentharness.DriveOutcome
	Record  session.OperationResultRecord
}

ProcedureResult is one drive procedure step: continue driving, wait with Outcome, or settle with Record.

type ProcedureResultKind

type ProcedureResultKind string

ProcedureResultKind discriminates ProcedureResult.

const (
	ProcedureContinue ProcedureResultKind = "continue"
	ProcedureWaiting  ProcedureResultKind = "waiting"
	ProcedureSettled  ProcedureResultKind = "settled"
)

Procedure result kinds.

type ProviderMessageConverter

type ProviderMessageConverter func(ctx harness.Context, messages []agent.AgentMessage) ([]ai.Message, error)

ProviderMessageConverter converts agent messages to provider messages (upstream AgentHarnessOptions.toProviderMessages).

type SliceNotImplemented

type SliceNotImplemented struct {
	Operation string
}

SliceNotImplemented reports an AgentHarness operation that belongs to a later slice (upstream SliceNotImplemented).

func (*SliceNotImplemented) Error

func (err *SliceNotImplemented) Error() string

type SystemPromptFactory

type SystemPromptFactory func(ctx harness.Context, toolContext any) (string, error)

SystemPromptFactory builds the system prompt (upstream AgentHarnessOptions.systemPrompt; a static string is a factory returning it).

type ToolContextFactory

type ToolContextFactory func(ctx harness.Context) (any, error)

ToolContextFactory resolves the tool context for one invocation (upstream AgentHarnessOptions.toolContext; a static value is a factory returning it).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL