Documentation
¶
Overview ¶
Assembles the single synthetic system message sent on every provider request: the active mode's product-authored base prompt, the environment block, and the loaded AGENTS.md instructions, in that fixed order. The per-mode base prompts are embedded markdown (shared core + one behavior block per mode); assembly reads only in-memory inputs and performs no I/O.
Formats the always-present environment context block (date, working directory, OS, project name, VCS) placed between the mode base prompt and AGENTS.md in the assembled system message. Side-effect-free and cache-stable: it makes no outbound calls and includes no per-turn-volatile state.
Event replay: maps each in-memory LoadEntry to an agent_instructions_loaded payload and appends it via the events package, so a launch or in-process session switch re-emits identical events without re-walking the disk.
Package agentinstr discovers and loads AGENTS.md instruction files: the global file followed by a farthest-first walk from the launch directory to the filesystem root, applying size and readability skips.
Assembles the loaded AGENTS.md instruction files into a single string preserving the discovery load order. This is the final AGENTS.md section of the full system message assembled by AssembleSystemMessage.
Per-model special instructions: a small library of named instruction blocks, each applied only to the models known to need it, inserted into the assembled system message between the base prompt and the environment block. The first block, latex-math, suppresses LaTeX math notation for models that default to it (IBM Granite via OpenRouter). Carrying these per-model — rather than in the shared base prompt for every model — keeps the prompt-cache prefix cost off models that never emit the quirk.
Index ¶
- Constants
- func AssembleSystemMessage(m mode.Mode, provider, modelID string, env EnvironmentInputs, ...) string
- func BasePrompt(m mode.Mode) string
- func EnvironmentBlock(in EnvironmentInputs) string
- func GlobalPath(home string) string
- func Replay(store *sessions.Store, entries []LoadEntry) error
- func SpecialInstructions(provider, modelID string) string
- func SystemPrompt(entries []LoadEntry) string
- type EnvironmentInputs
- type LoadEntry
Constants ¶
const ( LayerGlobal = "global" LayerWalked = "walked" )
Layer values for a LoadEntry: the global file vs. an upward-walked ancestor file.
const ( SkipSizeLimit = "size_limit" SkipUnreadable = "unreadable" )
Skip reasons recorded when a located AGENTS.md is not loaded.
const FileName = "AGENTS.md"
FileName is the per-directory instruction file looked up during the walk.
Variables ¶
This section is empty.
Functions ¶
func AssembleSystemMessage ¶
func AssembleSystemMessage(m mode.Mode, provider, modelID string, env EnvironmentInputs, entries []LoadEntry) string
AssembleSystemMessage builds the single synthetic system message in the fixed order (1) active mode base prompt, (2) the active model's special instructions, (3) environment block, (4) concatenated loaded AGENTS.md instructions, sections joined by a single blank line. The base prompt and environment block are always present, so the message is non-empty even with zero AGENTS.md files — superseding the earlier empty prompt for an empty set. The special-instructions section is present only for flagged models (provider + modelID match a modelSpecialInstructions entry); an unflagged model yields "" there, so its assembly is byte-identical to before. The AGENTS.md section reuses SystemPrompt's join semantics (newline-separated file content, skipped entries omitted); an empty section contributes nothing and leaves no dangling separator. provider and modelID are plain strings (the active Selection's provider id and model id) so this package stays free of an internal/model import. It reads only the in-memory inputs and makes no outbound calls.
func BasePrompt ¶
BasePrompt returns the product-authored base system prompt for mode m: the shared core followed by the mode's behavior block, joined by a single blank line. An unrecognized mode falls back to Build's block — never an empty prompt — so the base section is always present. The base prompt is static per mode keeping the assembled prefix prompt-cache stable.
func EnvironmentBlock ¶
func EnvironmentBlock(in EnvironmentInputs) string
EnvironmentBlock formats the environment context block from deterministic inputs. It states the current date at day granularity in the supplied timezone, the absolute working directory, the operating system from runtime.GOOS, the project name (basename of ProjectRoot), and the VCS name (or the explicit no-VCS text). It deliberately excludes per-turn-volatile or large state — no branch/head, dirty status, or directory listing — and performs no I/O so it adds no outbound network calls.
func GlobalPath ¶
GlobalPath is the global AGENTS.md path for home, or "" when home is empty. It is the same lexical spelling the walk deduplicates against, so a caller classifying entries cannot drift from the loader's own dedup.
func Replay ¶
Replay appends an agent_instructions_loaded event for every LoadEntry to store, in load order, preserving each entry's path, layer, load_order, skip state, skip reason, error category, and error detail. Bootstrap and TUI callers decide when to invoke it relative to their launch_began event; this package owns only the mapping and append. It stops and returns on the first append error.
func SpecialInstructions ¶
SpecialInstructions returns the special-instruction blocks for the active model, concatenated in the order listed for that model and joined by a single blank line, or "" when the model is not flagged. An empty result contributes nothing to the assembled system message via joinSections, so unflagged models assemble exactly as before. Block names listed for a model but missing from the parsed file are skipped here (a programming error caught by TestModelSpecialInstructions_BlocksExist, not a silent runtime failure).
func SystemPrompt ¶
SystemPrompt assembles the loaded AGENTS.md entries into a single string by concatenating the Content of each loaded (non-skipped) entry in the slice order produced by LoadAgentInstructions — global before walked, in load_order. Skipped or unreadable entries (nil Content) contribute nothing, and empty input (or input with no loaded entries) yields an empty string. The entries' in-memory Content is used as-is; this never re-reads AGENTS.md from disk, matching what the launch loaded. It is the AGENTS.md section of AssembleSystemMessage; the inter-file newline join here is distinct from that function's blank-line section join.
Types ¶
type EnvironmentInputs ¶
type EnvironmentInputs struct {
// Now is the clock value, in the host's local timezone, rendered at day
// granularity (no clock time) so the block stays prompt-cache stable within a day.
Now time.Time
// WorkingDir is the current working directory as an absolute path.
WorkingDir string
// ProjectRoot is the absolute project root; its basename is the project name.
ProjectRoot string
// RepoRoot is the absolute repository root, empty when no VCS was detected.
RepoRoot string
// VCSName is the detected version-control template name. Built-in ids (git, hg,
// jj) render as Git, Mercurial, Jujutsu; any other non-empty value renders
// verbatim; an empty value renders as "no version control detected".
VCSName string
}
EnvironmentInputs are the deterministic inputs to EnvironmentBlock. The production caller supplies the system clock value (already in the host's local timezone) and the detected VCS name; tests pass fixed values. This package stays independent of internal/bootstrap, so the caller adapts bootstrap's active-VCS handoff into VCSName at the assembly edge rather than this builder importing it.
type LoadEntry ¶
type LoadEntry struct {
Path string // cleaned absolute path of the candidate file
Layer string // LayerGlobal | LayerWalked
LoadOrder int // 1-based: global is 1, walked starts at 2
Skipped bool // true when the file was located but not loaded
SkipReason string // SkipSizeLimit | SkipUnreadable when Skipped
ErrorCategory fserrors.Category // set only for an unreadable skip
ErrorDetail string // set only for an unreadable skip
Content []byte // file bytes when loaded; nil when skipped
}
LoadEntry is one in-memory record of an AGENTS.md candidate that was loaded or skipped. The walk runs once per process launch; this record is reused for in-process session switches (/clear, fork, in-TUI resume) so the event stream can be replayed without re-walking the disk.
func LoadAgentInstructions ¶
LoadAgentInstructions performs the once-per-process discovery walk and returns the ordered load record. It first considers the global file at <home>/.codemeld/global/AGENTS.md (load_order 1 when present or skipped), then walks AGENTS.md files from the filesystem root down to launchDir in farthest-first order (load_order starting at 2). Candidates are deduplicated by cleaned absolute path, so a launch directory inside the global directory yields the global file once at load_order 1. Missing files are silently absent and do not consume a load_order; a located file larger than maxFileBytes is skipped as size_limit; any stat or read failure on a located file is skipped as unreadable with its error category; and an unreadable directory is skipped without halting the walk. The walk is independent of discovery.boundary: it always proceeds to the filesystem root and this function never consults that setting. home is the absolute home directory ("" disables the global file).
Source Files