Documentation
¶
Overview ¶
Package utils holds the harness usage arithmetic, adaptive publication, and bounded shell-output capture helpers.
Index ¶
- Constants
- func AddUsage(left, right ai.Usage) ai.Usage
- func ApplyShellOutputUpdate(current *harness.ShellOutputView, update harness.ShellOutputUpdate) harness.ShellOutputView
- func EmptyUsage() ai.Usage
- func SanitizeShellOutput(text string) string
- type AdaptivePublisher
- type AdaptivePublisherOptions
- type OutputCapture
- func (capture *OutputCapture) Dispose()
- func (capture *OutputCapture) Finish()
- func (capture *OutputCapture) Flush()
- func (capture *OutputCapture) Push(chunk []byte)
- func (capture *OutputCapture) PushString(chunk string)
- func (capture *OutputCapture) SetSpillPath(path string)
- func (capture *OutputCapture) Snapshot() harness.ShellOutputView
- func (capture *OutputCapture) Truncated() bool
- type OutputCaptureHandlers
Constants ¶
const ( OutputMinEmitIntervalMs = 100 OutputTargetBytesPerSecond = 100 * 1024 )
Output publication pacing for bounded shell output.
Variables ¶
This section is empty.
Functions ¶
func AddUsage ¶
AddUsage sums two usage records. CacheWrite1h and Reasoning stay absent when both inputs omit them.
func ApplyShellOutputUpdate ¶
func ApplyShellOutputUpdate(current *harness.ShellOutputView, update harness.ShellOutputUpdate) harness.ShellOutputView
ApplyShellOutputUpdate folds one update into the previous view (nil before the first update).
func SanitizeShellOutput ¶
SanitizeShellOutput removes C0 control characters other than tab and newline, and the U+FFF9-U+FFFB interlinear annotation characters.
Types ¶
type AdaptivePublisher ¶
type AdaptivePublisher[TValue, TUpdate any] struct { // contains filtered or unexported fields }
AdaptivePublisher publishes the latest state without queuing intermediate mutations. The first dirty state after idle is immediate. Each publication buys a delay proportional to its encoded size, with a minimum interval that also bounds event count. A single trailing timer guarantees eventual publication. Deliveries are serialized in publication order and run outside the state lock: a forced flush waits for an in-flight delivery, while an unforced flush that finds one in flight (including a reentrant call from the consumer) defers to the trailing timer. A consumer must not force a flush from inside its own delivery.
func NewAdaptivePublisher ¶
func NewAdaptivePublisher[TValue, TUpdate any](options AdaptivePublisherOptions[TValue, TUpdate]) *AdaptivePublisher[TValue, TUpdate]
NewAdaptivePublisher constructs a publisher with the wall clock.
func (*AdaptivePublisher[TValue, TUpdate]) Dispose ¶
func (publisher *AdaptivePublisher[TValue, TUpdate]) Dispose()
Dispose cancels the trailing timer and ignores later changes.
func (*AdaptivePublisher[TValue, TUpdate]) Flush ¶
func (publisher *AdaptivePublisher[TValue, TUpdate]) Flush(force bool) error
Flush publishes dirty state now when force is set or the publication interval has elapsed; otherwise it arms the trailing timer.
func (*AdaptivePublisher[TValue, TUpdate]) MarkDirty ¶
func (publisher *AdaptivePublisher[TValue, TUpdate]) MarkDirty() error
MarkDirty records a state change and publishes immediately when the interval bought by the previous publication has elapsed.
type AdaptivePublisherOptions ¶
type AdaptivePublisherOptions[TValue, TUpdate any] struct { Snapshot func() TValue // Update derives the publication from the last published value (nil // before the first publication); ok false publishes nothing but still // advances the baseline. Update func(previous *TValue, current TValue) (update TUpdate, ok bool) Measure func(update TUpdate) int Publish func(update TUpdate) error // OnError receives publication errors raised from the trailing timer. OnError func(err error) // MinIntervalMs defaults to 100; TargetBytesPerSecond to 100 KiB. MinIntervalMs *float64 TargetBytesPerSecond *float64 }
AdaptivePublisherOptions configure an AdaptivePublisher.
type OutputCapture ¶
type OutputCapture struct {
// contains filtered or unexported fields
}
OutputCapture maintains and publishes one bounded shell-output view. Writes received while publication is rate-limited collapse into the latest view. Small changes remain responsive; complete window turnovers purchase a proportionally longer delay. The first update after idle and an explicit final flush are immediate.
func NewOutputCapture ¶
func NewOutputCapture(ctx context.Context, options *harness.ShellOutputCaptureOptions, handlers OutputCaptureHandlers) (*OutputCapture, error)
NewOutputCapture validates the limits and constructs a capture. Nil options use the default byte and line limits with tail retention.
func (*OutputCapture) Dispose ¶
func (capture *OutputCapture) Dispose()
Dispose cancels the trailing timer and ignores later output.
func (*OutputCapture) Finish ¶
func (capture *OutputCapture) Finish()
Finish flushes pending partial bytes as replacement characters.
func (*OutputCapture) Flush ¶
func (capture *OutputCapture) Flush()
Flush publishes held state immediately.
func (*OutputCapture) Push ¶
func (capture *OutputCapture) Push(chunk []byte)
Push appends one raw process chunk, decoding UTF-8 split across chunks.
func (*OutputCapture) PushString ¶
func (capture *OutputCapture) PushString(chunk string)
PushString flushes pending partial bytes and appends one text chunk.
func (*OutputCapture) SetSpillPath ¶
func (capture *OutputCapture) SetSpillPath(path string)
SetSpillPath records the complete-output spill file and publishes it.
func (*OutputCapture) Snapshot ¶
func (capture *OutputCapture) Snapshot() harness.ShellOutputView
Snapshot returns the current bounded view.
func (*OutputCapture) Truncated ¶
func (capture *OutputCapture) Truncated() bool
Truncated reports whether total output exceeds either limit.
type OutputCaptureHandlers ¶
type OutputCaptureHandlers struct {
OnUpdate func(ctx context.Context, update harness.ShellOutputUpdate)
OnError func(err error)
}
OutputCaptureHandlers receive publications and trailing-timer errors.