Documentation
¶
Overview ¶
Package session provides an append-only event log that records every prompt, response, tool call, and tool result for a run. The log is the source of truth and lets a run be resumed via the OpenAI Responses API's PreviousResponseID. Large tool results are spilled to disk under results/<id>.txt and replaced inline with a placeholder the model can re-fetch via the get_tool_result tool.
Index ¶
- Constants
- func WithLogger(ctx context.Context, l *Logger) context.Context
- type Event
- type Logger
- func (l *Logger) Append(eventType string, payload any) error
- func (l *Logger) Close() error
- func (l *Logger) Dir() string
- func (l *Logger) Finish(status string, errMsg string)
- func (l *Logger) LastResponseID() string
- func (l *Logger) ReadLargeResult(id string, offset, limit int) (string, int, error)
- func (l *Logger) SessionID() string
- func (l *Logger) SetLastResponseID(id string)
- func (l *Logger) SetRoutineID(id string)
- func (l *Logger) StoreLargeResult(content string) (string, error)
- func (l *Logger) UpdateMetrics(inputTokens, outputTokens int64, cost float64, iterations int)
- type Meta
Constants ¶
const ( StatusRunning = "running" StatusCompleted = "completed" StatusError = "error" StatusBudget = "budget_exceeded" )
Statuses returned by Logger.Finish.
const ( EventRunStart = "run_start" EventResume = "resume" EventPrompt = "prompt" EventResponse = "response" EventToolCall = "tool_call" EventToolResult = "tool_result" EventLargeResult = "large_result" EventIteration = "iteration" EventError = "error" EventRunEnd = "run_end" EventSkillLoaded = "skill_loaded" EventConfirmResolved = "confirm_resolved" )
Event types written to events.jsonl.
const LargeResultThreshold = 8 * 1024
LargeResultThreshold is the byte size above which a tool result is spilled to results/<id>.txt and replaced inline with a placeholder.
const SessionsRoot = ".squad/sessions"
SessionsRoot is the directory under workingDir where sessions are stored.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Event ¶
type Event struct {
Ts time.Time `json:"ts"`
Type string `json:"type"`
Payload json.RawMessage `json:"payload,omitempty"`
}
Event is one append-only record written to events.jsonl.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger writes events.jsonl and rewrites meta.json on update. Methods are safe to call concurrently.
func FromContext ¶
FromContext returns the Logger attached to ctx, or nil if none.
func New ¶
New creates a fresh session under <workingDir>/.squad/sessions/<id>/ and returns a Logger ready to receive events. The caller should defer Close.
func Open ¶
Open loads an existing session for resume. The Logger appends to the same events.jsonl and rewrites meta.json in place.
func (*Logger) Append ¶
Append records an event to events.jsonl. payload may be nil. Safe to call on a nil Logger (no-op).
func (*Logger) LastResponseID ¶
LastResponseID returns the most recent OpenAI response id chained for this session, or "" if no response has been recorded yet.
func (*Logger) ReadLargeResult ¶
ReadLargeResult returns a slice of a previously stored large result. If limit <= 0 the whole content from offset is returned. The total byte length is also returned so the caller can advise the model on remaining content.
func (*Logger) SetLastResponseID ¶
SetLastResponseID records the most recent OpenAI response id and persists it to meta.json so a resume can pick up the chain. Safe on nil Logger.
func (*Logger) SetRoutineID ¶
SetRoutineID stamps the meta.json with the qualified routine id that owns this session. Called by the routines daemon's fire handler before invoking the agent so `squad routine history` can filter by exact provenance.
func (*Logger) StoreLargeResult ¶
StoreLargeResult writes the full content to results/<id>.txt and returns the result id. Callers replace the inline tool output with a placeholder referencing this id, and the model can re-fetch via get_tool_result.
type Meta ¶
type Meta struct {
SessionID string `json:"session_id"`
Created time.Time `json:"created"`
Updated time.Time `json:"updated"`
Agent string `json:"agent"`
Provider string `json:"provider"`
Model string `json:"model"`
WorkingDir string `json:"working_dir"`
Prompt string `json:"prompt"`
LastResponseID string `json:"last_response_id,omitempty"`
// RoutineID identifies the routine that produced this session (qualified
// form: "global:nightly" / "repo:audit"). Empty for non-routine runs.
RoutineID string `json:"routine_id,omitempty"`
Status string `json:"status"`
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
Cost float64 `json:"cost"`
Iterations int `json:"iterations"`
}
Meta holds the per-session metadata kept in meta.json. It is rewritten on every update so a `--resume` can read it without scanning the event log.