transcript

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Mar 23, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package transcript provides a minimal, provider‑precise ledger that records the canonical conversation needed to rebuild provider payloads (e.g., Bedrock) without leaking provider SDK types into workflow state. The ledger stores only the essential, JSON‑friendly parts in the exact order in which they must be presented to the provider (thinking → tool_use → tool_result).

Design goals (see AGENTS.md):

  • Provider‑fidelity: preserve ordering/shape required by providers.
  • Minimalism: store only what is needed to rebuild payloads exactly.
  • Stateless API: pure methods that are safe for workflow replay.
  • Provider‑agnostic at rest: convert to/from provider formats at edges.

Package transcript owns the provider-facing tool-result content contract used by both live runtime transcript generation and replay from durable events.

Contract:

  • Successful transcript tool results carry decoded semantic JSON values.
  • Failed transcript tool results carry plain error text with IsError=true.
  • Canonical raw JSON bytes stay at execution/history boundaries only.
  • Oversized successful results are replaced with a documented omission object.

Index

Constants

View Source
const (
	// MaxToolResultContentBytes bounds the canonical successful result JSON that
	// can be embedded directly in transcript tool_result content.
	MaxToolResultContentBytes = 64 * 1024
)

Variables

This section is empty.

Functions

func BuildMessagesFromEvents

func BuildMessagesFromEvents(events []memory.Event) ([]*model.Message, error)

BuildMessagesFromEvents reconstructs provider-ready messages from durable memory events by replaying them through a Ledger. It returns messages in the canonical provider order (assistant thinking -> text -> tool_use; user tool_result).

func ProjectToolResultContent

func ProjectToolResultContent(resultJSON rawjson.Message, bounds *agent.Bounds, preview string, errorMessage string) (any, error)

ProjectToolResultContent converts canonical result JSON plus transcript-side metadata into the semantic content stored in ToolResultPart.Content.

func ValidateBedrock

func ValidateBedrock(messages []*model.Message, thinkingEnabled bool) error

ValidateBedrock verifies critical Bedrock constraints when thinking is enabled:

  • Any assistant message that contains tool_use must start with thinking.
  • For each user message containing tool_result, the immediately prior assistant message must contain at least as many tool_use blocks.

It returns a descriptive error when a constraint is violated.

Types

type Ledger

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

Ledger holds the ordered transcript for the current turn. It records only the minimal set of parts required to rebuild provider payloads with exact ordering (thinking → tool_use → tool_result). It is JSON‑friendly and safe to store in workflow state.

func FromModelMessages

func FromModelMessages(msgs []*model.Message) *Ledger

FromModelMessages constructs a ledger initialized with the provided assistant messages. Only assistant-role messages contribute to the transcript; other roles are ignored.

func NewLedger

func NewLedger() *Ledger

NewLedger constructs an empty Ledger ready to record a turn transcript.

func (*Ledger) AppendText

func (l *Ledger) AppendText(text string)

AppendText appends assistant text to the current assistant message. When no assistant message is open, a new one is started.

func (*Ledger) AppendThinking

func (l *Ledger) AppendThinking(tp ThinkingPart)

AppendThinking records a structured thinking block and ensures it appears at the head of the current assistant message. When a message is not yet open, a new assistant message is started.

func (*Ledger) AppendUserToolResults

func (l *Ledger) AppendUserToolResults(results []ToolResultSpec)

AppendUserToolResults appends a single user message containing tool_result parts for the provided specs, preserving their order. Specs with empty ToolUseID are ignored.

func (*Ledger) BuildMessages

func (l *Ledger) BuildMessages() []*model.Message

BuildMessages flushes the current assistant (if any) and converts the ledger to provider‑agnostic model messages suitable for provider adapters.

func (*Ledger) DeclareToolUse

func (l *Ledger) DeclareToolUse(id, name string, args any)

DeclareToolUse appends a tool_use to the current assistant message. The caller is responsible for flushing the assistant message at the end of the turn so that subsequent user tool_result messages can correlate to the full set of tool_use blocks.

func (*Ledger) FlushAssistant

func (l *Ledger) FlushAssistant()

FlushAssistant finalizes the current assistant message (if any) and appends it to the ledger. It is safe to call when no assistant message is open.

func (*Ledger) IsEmpty

func (l *Ledger) IsEmpty() bool

IsEmpty reports whether the ledger currently holds any committed or pending parts.

type Message

type Message struct {
	// Role is one of "assistant", "user", or "system".
	Role string
	// Parts must be in final provider order for this message.
	Parts []Part
	// Meta carries optional provider‑agnostic metadata for diagnostics.
	Meta map[string]any
}

Message groups ordered parts under a role for the provider conversation.

func (*Message) UnmarshalJSON

func (m *Message) UnmarshalJSON(data []byte) error

UnmarshalJSON customizes Message decoding so that Parts (which contain interface implementations) can be reconstructed from stored JSON.

type Part

type Part interface {
	// contains filtered or unexported methods
}

Part is the canonical provider‑precise content fragment stored by the ledger. Implementations must be one of ThinkingPart, TextPart, ToolUsePart, or ToolResultPart.

type TextPart

type TextPart struct {
	// Text is visible content intended for users.
	Text string
}

TextPart carries assistant or user visible text.

type ThinkingPart

type ThinkingPart struct {
	// Text is provider‑issued plaintext reasoning when available.
	Text string
	// Signature is the provider signature that authenticates Text.
	Signature string
	// Redacted holds provider opaque redacted reasoning bytes.
	Redacted []byte
	// Index is the provider content block index (negative if unknown).
	Index int
	// Final marks the finalization of this reasoning block.
	Final bool
}

ThinkingPart carries provider reasoning. Exactly one variant must be set: either signed plaintext (Text+Signature) or Redacted bytes. Index tracks the provider content block index when available; Final indicates finalization.

type ToolResultPart

type ToolResultPart struct {
	// ToolUseID correlates to a prior assistant ToolUsePart.ID.
	ToolUseID string
	// Content is the JSON‑encodable tool result payload.
	Content any
	// IsError indicates whether the tool invocation failed.
	IsError bool
}

ToolResultPart communicates a tool result by the user back to the model, correlated via ToolUseID.

type ToolResultSpec

type ToolResultSpec struct {
	ToolUseID string
	Content   any
	IsError   bool
}

ToolResultSpec describes a single tool_result block for appending user messages in a turn. It is used by AppendUserToolResults to build a single user message containing multiple tool_result parts.

type ToolUsePart

type ToolUsePart struct {
	// ID is the provider tool_use identifier (for correlating tool_result).
	ID string
	// Name is the provider‑visible tool name (sanitized as required).
	Name string
	// Args are the JSON‑encodable tool arguments.
	Args any
}

ToolUsePart declares a tool invocation by the assistant.

Jump to

Keyboard shortcuts

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