streamtool

package
v0.31.1 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package streamtool is the channel-aware tool primitive — the contract a long-running tool implements when it wants to publish intermediate output while it runs. A standard tool is request-response: emit tool.invoke, wait for tool.result. A channel-aware tool returns a chan ToolEvent the runtime drains, auto-bridging each event to the bus as tool.stream.* so other consumers (UIs, observability collectors, sub-agents that need to know about the work in progress) see streaming output without the tool author wiring up the bus by hand.

Tools should be channel-aware when they take more than a few seconds, produce intermediate output a consumer might use, and can be cancelled cleanly. Quick request-response operations should stay on the standard tool interface.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bridge

func Bridge(ctx context.Context, bus engine.EventBus, tool ChannelTool, call events.ToolCall) error

Bridge consumes a ChannelTool's stream and projects each event onto the bus. While the stream runs, every ToolEvent emits as a tool.stream.* event whose Causation.ParentID is the originating tool.invoke event ID (the bus's per-goroutine dispatch context handles that automatically). When the stream completes, the function emits a single tool.result with the final payload — the parent agent sees the same contract as for a standard tool, plus a stream of side-channel updates other consumers can watch.

Bridge blocks until the channel closes or ctx is cancelled. It does not return the tool's payload; the payload is on the bus. Returns nil on graceful completion, an error from the tool only if KindError fires.

Types

type ChannelTool

type ChannelTool interface {
	// Name returns the tool name as it appears in the catalog.
	Name() string
	// Stream begins an asynchronous invocation. The returned channel
	// receives ToolEvents in order; the runtime closes nothing — the
	// implementation owns the channel's lifetime.
	Stream(ctx context.Context, input map[string]any) (<-chan ToolEvent, error)
}

ChannelTool is the streaming tool contract. Stream must return a channel the runtime will drain to completion (KindComplete or KindError), and must close that channel when ctx is cancelled or the work is done. The channel may be buffered; Bridge does not require a specific buffer size.

type Kind

type Kind string

Kind classifies a single emission from a ChannelTool.

const (
	// KindProgress carries status with no data; consumers use it to update
	// progress bars or heartbeat counters.
	KindProgress Kind = "progress"
	// KindPartial carries incremental data the consumer can render.
	KindPartial Kind = "partial"
	// KindComplete carries the final result and closes the channel.
	KindComplete Kind = "complete"
	// KindError carries a terminal failure and closes the channel.
	KindError Kind = "error"
)

type ToolEvent

type ToolEvent struct {
	Kind     Kind
	Sequence int
	Payload  any
	Progress float64
	Err      error
}

ToolEvent is one item on a ChannelTool's output channel. Sequence is monotonic per Stream invocation, starts at 1, and is opaque to consumers other than for ordering. Progress is 0.0–1.0 when known, -1 otherwise.

Jump to

Keyboard shortcuts

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