longsession

package
v0.5.2 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package longsession writes a long Pi session fixture: a version 3 session file whose active context holds a chosen number of tokens, the agent directory that declares a scripted model with a chosen context window, and a metadata record. Pi, PiG and any harness that reads Pi session files open the same file, so memory measured with a loaded session compares like with like.

Tokens are counted as Pi's compaction.ts estimateTokens counts them: a quarter of the characters of each message's text, tool-call name and JSON arguments, and tool-result text, rounded up. All text is ASCII, so characters equal UTF-16 code units. Each assistant message reports usage whose input is the context before it, so the footer and the context gauge read the size the file holds.

A turn is a user prompt, an assistant message with a read tool call, the tool result (ResultBytes of source-like text), and an assistant answer. Content is pseudo-random from a fixed seed, so a size and seed always produce the same bytes.

Index

Constants

View Source
const (
	Provider = "longsession"
	Model    = "scripted"
)

Provider and Model name the scripted model the fixture's agent directory declares and its assistant messages carry.

Variables

This section is empty.

Functions

func GenerateTree

func GenerateTree(w io.Writer, opts TreeOptions) error

GenerateTree writes a session whose entries branch from earlier entries and include compactions, branch summaries, labels, custom entries, custom messages, session names, model and thinking-level changes, tool calls and results, extra members Pi does not read, and members written in an unusual order. Every entry's JSON is written by hand, so the file holds spellings JSON.stringify would not produce (escaped non-ASCII, exponent numbers, spaces).

func WriteAgentDir

func WriteAgentDir(agentDir string, window int, baseURL string) error

WriteAgentDir writes models.json, declaring the scripted model with the window at baseURL, and settings.json, selecting it, into agentDir.

Types

type Meta

type Meta struct {
	Tokens      int    `json:"tokens"`
	Target      int    `json:"target"`
	Window      int    `json:"window"`
	Turns       int    `json:"turns"`
	Entries     int    `json:"entries"`
	Bytes       int64  `json:"bytes"`
	ResultBytes int    `json:"resultBytes"`
	Seed        uint64 `json:"seed"`
	SHA256      string `json:"sha256"`
	// ContentSHA256 hashes the entries without the header line, whose working directory differs per fixture directory: it identifies the conversation across machines.
	ContentSHA256 string `json:"contentSha256"`
	Cwd           string `json:"cwd"`
	Session       string `json:"session"`
	AgentDir      string `json:"agentDir"`
	Provider      string `json:"provider"`
	Model         string `json:"model"`
}

Meta describes a written fixture.

func Generate

func Generate(w io.Writer, opts Options) (Meta, error)

Generate writes the session file to w and returns its metadata without the byte count, hash or paths.

func Write

func Write(dir string, opts Options) (Meta, error)

Write creates dir/session.jsonl, dir/agent/models.json, dir/agent/settings.json, dir/meta.json and the working directory dir/work.

func (Meta) Stage

func (m Meta) Stage(dir string) (string, error)

Stage copies the fixture's session file to dir/session.jsonl and returns that path. A harness appends every prompt it answers to the session it opened, so each measurement opens its own copy and the fixture keeps the bytes meta.json describes. Stage fails when the fixture no longer matches its recorded SHA256.

type Options

type Options struct {
	// Tokens is the context size to reach, by Pi's estimate. Generation stops at the first turn boundary at or above it.
	Tokens int
	// Window is the model's declared context window in tokens.
	Window int
	// ResultBytes is the size of each tool result. Zero means 16384.
	ResultBytes int
	// Seed selects the content. Sizes with the same seed share their leading turns.
	Seed uint64
	// Cwd is the session's working directory. Write uses dir/work and creates it; Generate uses /longsession when empty.
	Cwd string
	// BaseURL is the scripted model's OpenAI-compatible endpoint written to models.json. Empty means http://127.0.0.1:9/v1, which refuses connections.
	BaseURL string
}

Options selects a fixture.

type TreeOptions

type TreeOptions struct {
	// Entries is the number of entries after the header.
	Entries int
	// Seed selects the shape and the text; one seed always produces the same file.
	Seed uint64
	// Cwd is the header's working directory.
	Cwd string
	// ForkOneIn makes one entry in this many branch from an earlier entry. Zero means 6, which gives a session with a leaf for every few entries; a large value gives a long conversation with a few branches.
	ForkOneIn int
}

TreeOptions shapes a session that exercises every entry type of a Pi v3 session file rather than one long conversation.

Directories

Path Synopsis
cmd
longsession command
Command longsession writes long Pi session fixtures and measures a harness's memory with one loaded.
Command longsession writes long Pi session fixtures and measures a harness's memory with one loaded.

Jump to

Keyboard shortcuts

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