render

Overview ¶

Package render is the generic half of a model-driven agent: it turns a run's recorded steps into a message list and a model response into a decision. What is left to the consumer is the opening message, which is the only place domain facts belong, and the hooks below.

The rendering rules: an opening user message, then per recorded step an assistant turn (the decision's reason as text, plus a tool_use block with a synthesized id) and a user turn with the tool_result answering it. Results older than the recent window, and results over the content cap, are replaced by their summary. A step whose decision was not a tool call is answered with a text nudge keyed on the decision kind, so the model is told what went wrong rather than left to guess.

Both consumers are reproduced byte for byte. casework's renderer is the default plus its own ids and raw assistant turns:

render.Options{
	Opening:       func(agentrt.StepInput) string { return opening },
	RecentResults: a.RecentResults,
	ToolUseID: func(st agentrt.Step) string {
		if t, ok := turns[st.Index]; ok && t.Model == a.ModelName {
			if id := firstToolUseID(t.Raw); id != "" {
				return id
			}
		}
		return fmt.Sprintf("toolu_step_%d", st.Index)
	},
	Assistant: func(st agentrt.Step, _ string) []agentrt.ContentBlock {
		if t, ok := turns[st.Index]; ok && t.Model == a.ModelName {
			return []agentrt.ContentBlock{{Type: rawBlock, Text: string(t.Raw)}} // the adapter's RawAssistantBlock
		}
		return nil // synthesize
	},
}

repo-steward's renderer keeps the default ids and window and overrides both turns, because its assistant turn carries no reason text and its results are rendered as a labelled head plus content:

calls := func(st agentrt.Step) bool {
	return st.Decision.Kind == agentrt.DecideToolCall && st.Decision.Tool != ""
}
render.Options{
	Opening:       a.opening,
	RecentResults: a.RecentResults,
	Assistant: func(st agentrt.Step, id string) []agentrt.ContentBlock {
		if !calls(st) {
			return nil // the default text turn
		}
		return []agentrt.ContentBlock{{Type: "tool_use", ToolUseID: id, Name: st.Decision.Tool, Input: orEmpty(st.Decision.Args)}}
	},
	Observation: func(st agentrt.Step, id string, full bool) agentrt.ContentBlock {
		if !calls(st) {
			return agentrt.ContentBlock{} // the default nudge
		}
		return agentrt.ContentBlock{Type: "tool_result", ToolUseID: id, Name: st.Decision.Tool,
			Content: renderObservation(st, full), IsError: st.Observation != nil && st.Observation.Failure()}
	},
}

The guards matter: since Decide records KindNoToolCall and KindTruncated, every consumer's hooks are called for steps that called nothing, and falling back to the defaults there is what delivers the nudge. A hook that formats results its own way and wants the default for interrupted steps calls DefaultObservation, or uses InterruptedText directly.