convo

package
v0.7.60-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package convo is a conversation's record: an append-only file of one JSON entry a line, and the messages a model request is built from, which are a pure function of that file.

Nothing is ever rewritten. A tool call is recorded before it runs and its result after, so a process that died in between leaves a call with no result; such a call is shown to the model as failed and is never run again.

What the model is sent can still change: a cut-off reply gives way to a stub, old tool results to placeholders, and the whole conversation to a summary of it. Each such change is an entry of its own, an edit, that says what the messages show from then on. The entries it covers stay in the file, and the same file always gives the same messages.

A model's reasoning is sent back only while the conversation before it is the one it was written in: a server may bind a reasoning block to what came before it, the system prompt and the tools included, and refuse the block once that has changed. So the replies recorded before a clear, a compaction or a change of frame go back without their reasoning.

Index

Constants

View Source
const (
	// KindHeader opens the file.
	KindHeader = "header"
	// KindUser is a message from the runner: a prompt.
	KindUser = "user"
	// KindAssistant is a whole reply of the model.
	KindAssistant = "assistant"
	// KindCall says a call is about to run.
	KindCall = "call"
	// KindResult is a call's result.
	KindResult = "result"
	// KindUsage is a model request's token count.
	KindUsage = "usage"
	// KindStub replaces the assistant message before it with its text: a
	// reply the output limit cut off, taken out of what the model is sent.
	KindStub = "stub"
	// KindClear replaces the results of the calls it lists with short
	// placeholders.
	KindClear = "clear"
	// KindCompaction replaces everything before it with its text, a summary
	// of the conversation, but for the entries from KeepFrom on.
	KindCompaction = "compaction"
	// KindFrame says what the conversation is sent with from here on: Frame
	// is a digest of the model, the system prompt and the tools. A process
	// that opens the conversation with another writes a new one.
	KindFrame = "frame"
)

Kinds of entry.

View Source
const (
	// NoteNudge is the runtime's message after a repeated call.
	NoteNudge = "nudge"
	// NoteCut is the runtime's message after a cut-off reply.
	NoteCut = "cut"
	// NoteContinue is the runner's answer to a turn that was about to end.
	NoteContinue = "continue"
	// NoteSteer is a message the runner sent while a turn was under way.
	NoteSteer = "steer"
	// NoteStopped is the runtime's message after a turn the runner stopped.
	NoteStopped = "stopped"
)

Who wrote a user entry that is not the runner's prompt.

View Source
const (
	// Interrupted is the result of a call that was started and whose
	// result was never recorded.
	Interrupted = "This call was interrupted before its result was recorded. It may have run in part. It was not run again."
	// NotRun is the result of a call that was never started.
	NotRun = "This call was not run."
)

Texts the model is shown for a call that has no recorded result.

View Source
const Version = 1

Version is the format of the file, written in its first entry.

Variables

This section is empty.

Functions

func Live

func Live(entries []Entry) int

Live is the index of the first entry the messages are built from: the one after the last compaction, or the first that compaction kept.

func Project

func Project(entries []Entry) []llm.Message

Project is Messages for a list of entries.

Types

type Cleared

type Cleared struct {
	CallID string `json:"callId"`
	Text   string `json:"text"`
}

Cleared is one result a clear entry replaces: the call, and the text the model is sent in the result's place.

type Entry

type Entry struct {
	Kind string `json:"kind"`
	// At is when the entry was written.
	At string `json:"at,omitempty"`

	// Version and Conversation are set on the header.
	Version      int    `json:"version,omitempty"`
	Conversation string `json:"conversation,omitempty"`

	// Text is a user message's text, a stub's, or a compaction's summary as
	// the model is sent it.
	Text string `json:"text,omitempty"`
	// Note says a user entry is not the runner's prompt and who wrote it,
	// one of the Note constants. A prompt has none.
	Note string `json:"note,omitempty"`
	// Parts is an assistant message.
	Parts []llm.Part `json:"parts,omitempty"`
	// Finish is why the assistant's reply ended.
	Finish string `json:"finish,omitempty"`

	// CallID names the call of a call or result entry, and Result is the
	// result of a result entry.
	CallID string    `json:"callId,omitempty"`
	Result *llm.Part `json:"result,omitempty"`

	// Usage is set on a usage entry.
	Usage *llm.Usage `json:"usage,omitempty"`

	// Cleared is set on a clear entry: each result it replaces.
	Cleared []Cleared `json:"cleared,omitempty"`

	// KeepFrom, on a compaction entry, is the index in the file of the first
	// entry the summary does not replace. Zero keeps none.
	KeepFrom int `json:"keepFrom,omitempty"`
	// Reason says why a compaction or a clear was made, what a stub stands
	// for, and, on a usage entry, what a request was that was not one of
	// the conversation's own.
	Reason string `json:"reason,omitempty"`
	// Window, on a compaction entry, is the model's window in tokens as the
	// harness had learned it from the server by then, zero when it had not.
	Window int `json:"window,omitempty"`
	// Frame is set on a frame entry.
	Frame string `json:"frame,omitempty"`
}

Entry is one line of the file. Kind says which fields are set.

type Log

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

Log is an open conversation.

func Open

func Open(dir, id string) (*Log, bool, error)

Open opens the conversation id in dir, creating it when there is none. It reports whether the conversation already held a message.

func (*Log) Append

func (l *Log) Append(e Entry) error

Append writes one entry and makes it durable before it returns.

func (*Log) Close

func (l *Log) Close() error

Close closes the file.

func (*Log) Entries

func (l *Log) Entries() []Entry

Entries returns a copy of the entries.

func (*Log) Frame

func (l *Log) Frame() string

Frame is the digest of the newest frame entry, "" when there is none.

func (*Log) Len

func (l *Log) Len() int

Len is how many entries the file holds.

func (*Log) Messages

func (l *Log) Messages() []llm.Message

Messages is the conversation as a model request carries it. Each assistant message's calls are answered in the message that follows it, in the order the model made them; a call with no recorded result is answered as failed.

Jump to

Keyboard shortcuts

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