boundarywire

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package boundarywire lets the subprocess handlers of one turn_end or agent_before_settle dispatch share the encoding of the context preview.

Pi rebuilds the preview after every handler (runner.ts emitBoundary) and hands each handler the object. A subprocess handler receives it as JSON, so without sharing every handler encodes the whole projected history again. The Session records each preview it builds with the inputs it was projected from; a preview built from the same inputs as the one a subprocess handler already encoded has the same encoding, because each build is a fresh projection of the same session state.

A preview built under a Cache carries each context entry's source as the entry's record (Built's sources) instead of a decoded value. Pi hands every handler the session's own entry objects (session-manager.ts buildSessionProjection), so a subprocess handler receives the record's members in the record's order. The dispatcher calls Deliver before a handler that reads Go values, which decodes the sources of that handler's preview in place; a dispatch whose handlers all read JSON decodes none.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache holds the encoding of the projected part of one dispatch's previews. Its methods are safe for concurrent use.

func FromContext

func FromContext(ctx context.Context) *Cache

FromContext returns the dispatch's Cache, or nil.

func WithCache

func WithCache(ctx context.Context) (context.Context, *Cache)

WithCache returns ctx carrying a new Cache for one boundary dispatch.

func WithSessionCache

func WithSessionCache(ctx context.Context, encodings *Encodings) (context.Context, *Cache)

WithSessionCache is WithCache for a dispatch of the session whose encodings are kept in encodings.

func (*Cache) Built

func (c *Cache) Built(preview extension.BoundaryContextPreview, key Key, cacheable bool, sources []json.RawMessage)

Built records a preview the Session built. cacheable reports that key names every input of its projected part. sources, when not nil, holds the record of each of the preview's context entries, whose SourceEntry is left unset until Deliver decodes it.

func (*Cache) Deliver

func (c *Cache) Deliver(preview extension.BoundaryContextPreview) error

Deliver prepares preview for a handler that reads its Go values: when preview is the latest build and its sources are still records, it decodes each into its entry's SourceEntry, in the preview's own entries; when its messages are the session's own objects, it puts copies in their place. Afterwards the preview's records no longer stand for its sources.

func (*Cache) Encoded

func (c *Cache) Encoded(preview extension.BoundaryContextPreview) ([]byte, bool)

Encoded returns the encoding of preview's projected part when preview is the latest build, no handler that reads Go values has received it, and an earlier build from the same inputs was encoded.

func (*Cache) Encodings

func (c *Cache) Encodings() *Encodings

Encodings returns the session's kept encodings, or nil.

func (*Cache) HandlerStarted

func (c *Cache) HandlerStarted()

HandlerStarted records that a subprocess handler, which reads the preview only as JSON, is the one running after the latest build.

func (*Cache) Kept

Kept returns the session's kept encodings and preview's records when the encodings of preview's messages and records may be kept: preview is the latest build, was built with its records, and its messages are the session's own objects, which no handler that reads Go values has received.

func (*Cache) Projected

func (c *Cache) Projected(key Key) (preview extension.BoundaryContextPreview, sources []json.RawMessage, shared, ok bool)

Projected returns the projected part of the latest preview, its sources and whether its messages are the session's own when the next build, from the inputs key names, may reuse them instead of projecting the session again: the latest build was cacheable from the same inputs and held its sources as records, and no handler that reads Go values has received it, so no Go code held its values. Previews reach only the dispatch's handlers.

func (*Cache) Shared

func (c *Cache) Shared()

Shared records that the latest build's messages are the session's own objects, which no handler may change: Deliver hands a handler that reads Go values copies.

func (*Cache) Sources

func (c *Cache) Sources(preview extension.BoundaryContextPreview) ([]json.RawMessage, bool)

Sources returns the records of preview's context entries when preview is the latest build, was built with them, and no handler that reads Go values has received it.

func (*Cache) Store

func (c *Cache) Store(preview extension.BoundaryContextPreview, wire []byte)

Store keeps the encoding of preview's projected part when preview is the latest, cacheable build and no handler that reads Go values has received it.

type Encodings

type Encodings struct {
	// contains filtered or unexported fields
}

Encodings keeps, from one boundary dispatch of a session to the next, the encodings of the messages and entry records of the session's latest preview, so a dispatch encodes only what is new to its preview. A preview's messages are the session's own objects (Cache.Shared), which nothing changes, so an object's encoding stays its encoding. Each pass keeps only what it used. A key holds the objects it names, so it names no other while kept.

func (*Encodings) Use

func (e *Encodings) Use(encode func(*Pass) error) error

Use runs encode as one pass and then forgets every encoding the pass did not use. Passes do not overlap.

type Key

type Key struct {
	// Session identifies the session log the preview was projected from.
	Session any
	// Revision is the log's revision, which every append and leaf move advances.
	Revision uint64
}

Key names the inputs of the projected part of a preview: contextEntries, contextMessages and llmMessages. pendingMessages and canContinue are encoded for every handler.

type MessageEncoding

type MessageEncoding struct {
	Message []byte
	LLM     []byte
	HasLLM  bool
}

MessageEncoding is a message's encoding as a contextMessages element and, when convertToLlm sends it, its llmMessages element.

type MessageKey

type MessageKey struct {
	// contains filtered or unexported fields
}

MessageKey names a message by the objects it holds. A custom message has no key: it is decoded afresh for each projection.

func KeyOf

func KeyOf(message extension.AgentMessage) (MessageKey, bool)

KeyOf returns the key of message, or false for a message without one.

type Pass

type Pass struct {
	// contains filtered or unexported fields
}

Pass is one encoding of a preview. Its methods are called only inside Encodings.Use.

func (*Pass) KeepMessage

func (p *Pass) KeepMessage(key MessageKey, encoding MessageEncoding)

KeepMessage keeps encoding for the message key names.

func (*Pass) KeepRecord

func (p *Pass) KeepRecord(record []byte, encoding []byte)

KeepRecord keeps encoding for the entry record record.

func (*Pass) Message

func (p *Pass) Message(key MessageKey) (MessageEncoding, bool)

Message returns the kept encoding of the message key names.

func (*Pass) Record

func (p *Pass) Record(record []byte) ([]byte, bool)

Record returns the kept encoding of the entry record record.

Jump to

Keyboard shortcuts

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