prompt

Documentation

Overview

Package prompt renders per-issue prompt templates using Go text/template in strict mode. Start with Parse to compile a template body, then call Template.Render for each issue. Inspect TemplateError for structured failure diagnostics with WORKFLOW.md-relative line numbers.

Index

• Constants
• func BuildTurnPrompt(tmpl *Template, issue map[string]any, attempt any, turnNumber, maxTurns int, ...) (string, error)
• type ErrorKind
• type RenderOption
  • func WithContinuationContext(data map[string]any) RenderOption
• type RunContext
• type Template
  • func Parse(body, source string, frontMatterLines int) (*Template, error)
  • func (t *Template) Render(issue map[string]any, attempt any, run RunContext, opts ...RenderOption) (string, error)
  • func (t *Template) Tree() *parse.Tree
• type TemplateError
  • func (e *TemplateError) Error() string
  • func (e *TemplateError) Unwrap() error
• type TemplateWarning
  • func AnalyzeTemplate(t *Template) []TemplateWarning
• type WarnKind

Constants

const DefaultContinuationPrompt = "" /* 213-byte string literal not displayed */

DefaultContinuationPrompt is the fallback prompt returned when a workflow template produces empty output on a continuation turn (turnNumber > 1). Templates that include {{ if .run.is_continuation }} branching provide project-specific continuation guidance; this constant covers templates that omit such branching.

const RuntimeStatusSuffix = `` /* 410-byte string literal not displayed */

RuntimeStatusSuffix is a fixed instruction string appended to the agent prompt on the first turn of each worker run. It informs the agent of the A2O status-signaling protocol for reporting blocked or needs-human-review status via the .sortie/status file.

Continuation turns omit this suffix because the instruction persists in the agent's conversation history from turn 1.

Functions

func BuildTurnPrompt

func BuildTurnPrompt(tmpl *Template, issue map[string]any, attempt any, turnNumber, maxTurns int, opts ...RenderOption) (string, error)

BuildTurnPrompt returns the rendered prompt for a single turn within a worker session. turnNumber 1 is the initial turn; turnNumber 2 and above are continuation turns. If a continuation turn renders to empty output, DefaultContinuationPrompt is returned as a fallback.

Safe for concurrent use because the underlying Template.Render is safe.

Types

type ErrorKind

type ErrorKind int

ErrorKind classifies prompt template failures into parse-time and render-time categories. Callers can switch on Kind to determine whether the failure blocks all dispatch or only the current run attempt.

const (
	// ErrTemplateParse indicates the template body contains invalid
	// syntax and could not be compiled. This blocks dispatch until the
	// workflow file is corrected.
	ErrTemplateParse ErrorKind = iota + 1

	// ErrTemplateRender indicates the template executed but failed on a
	// missing variable, broken pipeline, or FuncMap error. This fails
	// only the current run attempt.
	ErrTemplateRender
)

type RenderOption

type RenderOption func(m map[string]any)

RenderOption applies optional overrides to the template data map before execution. Use WithContinuationContext to inject reaction continuation data.

func WithContinuationContext

func WithContinuationContext(data map[string]any) RenderOption

WithContinuationContext returns a RenderOption that merges each key from data into the template data map. Keys must be registered in [continuationKeys]; passing an unregistered key panics (programmer error: the reaction kind must register its template key before use).

type RunContext

type RunContext struct {
	TurnNumber     int
	MaxTurns       int
	IsContinuation bool
}

RunContext carries per-turn metadata passed to the prompt template as the "run" variable. Converted to a map with snake_case keys before template execution so workflow authors write {{ .run.turn_number }}.

type Template

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

Template is a parsed prompt template ready for per-issue execution. Obtain via Parse. Safe for concurrent Template.Render calls.

func Parse

func Parse(body, source string, frontMatterLines int) (*Template, error)

Parse compiles a prompt template body with strict mode (missingkey=error) and the standard [FuncMap]. frontMatterLines is the number of lines consumed by front matter in the source file (used to rewrite error positions to WORKFLOW.md-relative line numbers). Returns a *TemplateError with Kind ErrTemplateParse on failure.

func (*Template) Render

func (t *Template) Render(issue map[string]any, attempt any, run RunContext, opts ...RenderOption) (string, error)

Render executes the template with the given inputs and returns the rendered prompt string. The data map contains the top-level keys "issue", "attempt", and "run", plus every key in [continuationKeys] (currently "ci_failure", "review_comments", "bot_review_comments", "merge_conflict", "label_review", "label_fix"). Continuation keys default to nil when no RenderOption overrides them, ensuring missingkey=error does not reject templates that reference these fields. Returns a *TemplateError with Kind ErrTemplateRender on failure, with line numbers adjusted to WORKFLOW.md-relative positions.

func (*Template) Tree

func (t *Template) Tree() *parse.Tree

Tree returns the parsed template tree for static analysis. The tree is safe for read-only traversal by concurrent callers. Returns nil when the receiver or its underlying template is nil.

type TemplateError

type TemplateError struct {
	// Kind distinguishes parse errors (dispatch-blocking) from render
	// errors (per-attempt).
	Kind ErrorKind

	// Source is the workflow file path for operator-facing messages.
	Source string

	// Line is the 1-based line number in the original WORKFLOW.md file
	// (front matter offset applied). Zero when the line cannot be
	// determined from the underlying error.
	Line int

	// Err is the underlying cause from text/template.
	Err error
}

TemplateError represents a structured prompt template failure.

It wraps the underlying cause so errors.As can extract it from errors returned by Parse or Template.Render. Kind distinguishes dispatch-blocking parse failures from per-attempt render failures, and Line provides the operator-facing source location.

func (*TemplateError) Error

func (e *TemplateError) Error() string

Error returns a human-readable diagnostic including the source path and, when available, the adjusted line number.

func (*TemplateError) Unwrap

func (e *TemplateError) Unwrap() error

Unwrap returns the underlying error, enabling errors.Is and errors.As chains through the wrapped cause.

type TemplateWarning

type TemplateWarning struct {
	Kind    WarnKind
	Node    string
	Message string
}

TemplateWarning represents a single advisory diagnostic from template static analysis. These do not affect runtime behavior.

func AnalyzeTemplate

func AnalyzeTemplate(t *Template) []TemplateWarning

AnalyzeTemplate performs static analysis on a parsed template and returns advisory warnings. The analysis detects three classes of problems: dot-context misuse inside range/with blocks, unknown top-level template variables, and unknown sub-fields of known variables. Returns nil when no warnings are found.

type WarnKind

type WarnKind int

WarnKind classifies a template static analysis warning.

const (
	// WarnDotContext flags a FieldNode referencing a top-level data key
	// inside a range or with block where dot has been redefined. This
	// includes pipe arguments to nested range/with nodes, because those
	// arguments are evaluated in the enclosing scope where dot is already
	// the current element.
	WarnDotContext WarnKind = iota + 1

	// WarnUnknownVar flags a top-level variable reference outside the
	// recognized set. The recognized set is exactly the top-level keys
	// the renderer registers: [Template.Render] seeds them.
	WarnUnknownVar

	// WarnUnknownField flags a sub-field of a known top-level variable
	// that does not exist in the domain schema.
	WarnUnknownField
)