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 ¶
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" )