utils

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package utils holds the harness usage arithmetic, adaptive publication, and bounded shell-output capture helpers.

Index

Constants

View Source
const (
	OutputMinEmitIntervalMs    = 100
	OutputTargetBytesPerSecond = 100 * 1024
)

Output publication pacing for bounded shell output.

Variables

This section is empty.

Functions

func AddUsage

func AddUsage(left, right ai.Usage) ai.Usage

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 EmptyUsage

func EmptyUsage() ai.Usage

EmptyUsage returns a zero usage record.

func SanitizeShellOutput

func SanitizeShellOutput(text string) string

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.

Jump to

Keyboard shortcuts

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