execution

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package execution provides effect admission for the durable agent harness.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyBeforeToolDecision

func ApplyBeforeToolDecision(prepared *PreparedToolCall, decision *BeforeToolDecision) (cleared *ClearedToolCall, immediate *ImmediateToolOutcome)

ApplyBeforeToolDecision applies a block or revalidates replacement arguments. Exactly one returned outcome is non-nil.

func ConsumeAssistantStream

func ConsumeAssistantStream(ctx harness.Context, stream *ai.AssistantMessageEventStream, observer AssistantStreamObserver, afterResponse func(harness.Context, *ai.AssistantMessage) (*ai.AssistantMessage, error)) (*ai.AssistantMessage, error)

ConsumeAssistantStream waits for the provider's terminal settlement even after invocation cancellation. afterResponse cancellation waits for the shared cancellation operation and keeps the raw settlement; other failures propagate on this operation.

func CreateGate

func CreateGate() (*Gate, *GateControl)

CreateGate creates separate procedure-facing and owner-facing views of an open gate. Its signal has no parent; the caller composes it with invocation context.

func CreateToolResultMessage

func CreateToolResultMessage(call FinalizedToolCall) ai.ToolResultMessage

CreateToolResultMessage converts finalized output to the provider-facing transcript shape, normalizing missing content to an empty array.

func PrepareToolCall

func PrepareToolCall(call *ai.ToolCall, tools []harness.AgentHarnessTool) (prepared *PreparedToolCall, immediate *ImmediateToolOutcome)

PrepareToolCall resolves a tool, applies argument preparation, and validates the result. Exactly one returned outcome is non-nil.

func StreamHarnessAssistant

func StreamHarnessAssistant(ctx harness.Context, messages []agent.AgentMessage, config HarnessAssistantStreamConfig) (*ai.AssistantMessage, error)

StreamHarnessAssistant streams one assistant response without mutating the caller's message list. Transformation, conversion, request, response transformation and observer callbacks are awaited in order.

func ToolResultFromMessage

func ToolResultFromMessage(message agent.ToolResultMessage, terminate bool) harness.AgentToolResult

ToolResultFromMessage reconstructs canonical staged tool output.

Types

type AbortRequested

type AbortRequested struct {
	Cancellation func() error
}

AbortRequested is expected control flow when cancellation wins effect admission. Cancellation waits for the owner's shared cancellation operation and returns its error. The owner supplies a repeatable wait function, not the operation itself. Waiting does not cancel the operation or depend on the invoking context.

func (*AbortRequested) Error

func (*AbortRequested) Error() string

type AfterToolPatch

type AfterToolPatch struct {
	Content    []ai.ToolResultMessageContent
	Details    any
	SetDetails bool
	IsError    *bool
	Usage      *ai.Usage
	Terminate  *bool
}

AfterToolPatch changes only present fields. SetDetails distinguishes explicit JSON null from an omitted Details field.

type AssistantRequestContext

type AssistantRequestContext struct {
	Messages     []agent.AgentMessage
	SystemPrompt string
}

AssistantRequestContext carries the mutable copy supplied to transform_context.

type AssistantResponseMetadata

type AssistantResponseMetadata struct {
	Status  *int
	Headers map[string]string
}

AssistantResponseMetadata is captured before the response body is consumed.

type AssistantStreamObserver

type AssistantStreamObserver struct {
	Start  func(harness.Context, *ai.AssistantMessage, ai.StartEvent) error
	Update func(harness.Context, *ai.AssistantMessage, ai.AssistantMessageEvent) error
	End    func(harness.Context, *ai.AssistantMessage) error
}

AssistantStreamObserver observes one stream's ordered lifecycle. Each callback completes before the next phase starts.

type BeforeToolDecision

type BeforeToolDecision struct {
	Args  map[string]any
	Block *ToolBlock
}

BeforeToolDecision replaces arguments or blocks a prepared call.

type ClearedToolCall

type ClearedToolCall struct {
	ToolCall *ai.ToolCall
	Tool     *harness.AgentHarnessTool
	Args     map[string]any
}

ClearedToolCall is a validated call cleared for durable intent publication and execution.

type ExecutedToolCall

type ExecutedToolCall struct {
	Result  harness.AgentToolResult
	IsError bool
}

ExecutedToolCall is the raw tool output before after-tool patching.

func ExecuteToolCall

func ExecuteToolCall(ctx harness.Context, call *ClearedToolCall, gate *Gate, onUpdate harness.AgentHarnessToolUpdateCallback, toolContext any, invocation harness.AgentHarnessToolInvocation) (ExecutedToolCall, error)

ExecuteToolCall admits and waits for a tool effect. Gate and pre-aborted invocation failures escape; tool errors and panics become error output. Updates after settlement are ignored.

type FinalizedToolCall

type FinalizedToolCall struct {
	ToolCall  *ai.ToolCall
	Result    harness.AgentToolResult
	IsError   bool
	Terminate bool
}

FinalizedToolCall is ready to become a durable tool-result message.

func FinalizeToolCall

func FinalizeToolCall(call *ClearedToolCall, executed ExecutedToolCall, patch *AfterToolPatch) FinalizedToolCall

FinalizeToolCall applies an after-tool patch field by field without changing the raw result.

type Gate

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

Gate is the procedure-facing admission capability for one drive pass. Obtain it and its separate owner controls through CreateGate.

func (*Gate) Admit

func (gate *Gate) Admit(invoke func() error) error

Admit checks admission synchronously and invokes the effect on the calling goroutine. Refusal does not invoke it. An admitted callback owns its work and error; lifecycle controls do not wait for it and can be called from it. The locked check is the admission point when owners and procedures run concurrently.

func (*Gate) Signal

func (gate *Gate) Signal() context.Context

Signal is canceled only by SignalAbort or Close, not by BeginAbort.

type GateControl

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

GateControl owns the abort and close transitions for one drive pass.

func (*GateControl) BeginAbort

func (control *GateControl) BeginAbort(cancellation func() error)

BeginAbort refuses new effects without signaling admitted work. Only the first abort while open takes effect. cancellation waits for the owner's shared operation; it must be non-nil and safe to call repeatedly and concurrently.

func (*GateControl) Close

func (control *GateControl) Close(err error)

Close permanently refuses effects with err and signals admitted work unless an earlier signal already won. The first close error wins; err must be non-nil.

func (*GateControl) SignalAbort

func (control *GateControl) SignalAbort()

SignalAbort signals admitted work after the owner commits cancellation. It does nothing while open or closed and does not itself wait for the cancellation.

type HarnessAssistantStreamConfig

type HarnessAssistantStreamConfig struct {
	Model              *ai.Model
	SystemPrompt       string
	Tools              []ai.ToolSchema
	ThinkingLevel      ai.ThinkingLevel
	StreamOptions      harness.AgentHarnessStreamOptions
	TransformContext   func(harness.Context, AssistantRequestContext) (AssistantRequestContext, error)
	ToProviderMessages func(harness.Context, []agent.AgentMessage) ([]ai.Message, error)
	BeforePayload      func(harness.Context, any, *ai.Model) (any, error)
	AfterResponse      func(harness.Context, *ai.AssistantMessage, AssistantResponseMetadata) (*ai.AssistantMessage, error)
	Request            func(harness.Context, ai.Context, ai.StreamOptions) (*ai.AssistantMessageEventStream, error)
	Observer           AssistantStreamObserver
}

HarnessAssistantStreamConfig supplies one already-approved provider request.

type ImmediateToolOutcome

type ImmediateToolOutcome struct {
	Kind      string
	ToolCall  *ai.ToolCall
	Result    harness.AgentToolResult
	IsError   bool
	Terminate bool
}

ImmediateToolOutcome is an error result produced without executing an external effect.

type PreparedToolCall

type PreparedToolCall struct {
	ToolCall *ai.ToolCall
	Tool     *harness.AgentHarnessTool
	Args     map[string]any
}

PreparedToolCall is a resolved tool whose prepared arguments passed validation.

type ToolBlock

type ToolBlock struct {
	Reason    string
	Terminate bool
}

ToolBlock refuses a tool invocation with an optional termination hint.

Jump to

Keyboard shortcuts

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