Documentation
¶
Overview ¶
Package execution provides effect admission for the durable agent harness.
Index ¶
- func ApplyBeforeToolDecision(prepared *PreparedToolCall, decision *BeforeToolDecision) (cleared *ClearedToolCall, immediate *ImmediateToolOutcome)
- func ConsumeAssistantStream(ctx harness.Context, stream *ai.AssistantMessageEventStream, ...) (*ai.AssistantMessage, error)
- func CreateGate() (*Gate, *GateControl)
- func CreateToolResultMessage(call FinalizedToolCall) ai.ToolResultMessage
- func PrepareToolCall(call *ai.ToolCall, tools []harness.AgentHarnessTool) (prepared *PreparedToolCall, immediate *ImmediateToolOutcome)
- func StreamHarnessAssistant(ctx harness.Context, messages []agent.AgentMessage, ...) (*ai.AssistantMessage, error)
- func ToolResultFromMessage(message agent.ToolResultMessage, terminate bool) harness.AgentToolResult
- type AbortRequested
- type AfterToolPatch
- type AssistantRequestContext
- type AssistantResponseMetadata
- type AssistantStreamObserver
- type BeforeToolDecision
- type ClearedToolCall
- type ExecutedToolCall
- type FinalizedToolCall
- type Gate
- type GateControl
- type HarnessAssistantStreamConfig
- type ImmediateToolOutcome
- type PreparedToolCall
- type ToolBlock
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 ¶
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 ¶
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 ¶
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.
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.