# Prompting Architecture

Ollie builds one system-prompt preamble for each active agent runtime. Prompting is assembled at agent selection or reload time, then reused across turns while the runtime remains active.

## Runtime flow

```text
agent config + embedded system prompt + environment
                    │
                    ├─ resolve prompt files
                    ├─ list tools and convert schemas
                    ├─ render named preamble sections
                    └─ create Runtime
                         │
                         ├─ system message: Preamble
                         └─ each user turn: UserPrompt + input
```

`agent.BuildRuntime` is the assembly point. It creates four ordered preamble sections:

1. **system** — the embedded default prompt, or the configured `systemPrompt` override.
2. **env** — the current working directory, platform, Git-repository flag, and sandbox.
3. **agent** — the resolved contents of the configured `prompt` entries.
4. **tools** — descriptions and `.meta` documentation for the tools returned by the tool server.

Empty sections are skipped. Non-empty sections are joined with one newline. The resulting string is sent as the provider’s system message before conversation history.

## Agent configuration

Agent JSON is loaded from the installed agent configuration directory. The relevant fields are:

| Field | Behavior |
|---|---|
| `prompt` | A string or array of file paths concatenated into the agent section. |
| `userPrompts` | A string or array of file paths concatenated and prepended to every user turn. |
| `systemPrompt` | Replaces the embedded base system prompt with a resolved file. |
| `autoLoad` | Selects tools loaded by the tool server before runtime construction. |
| `tools` | Disables tool discovery and execution when explicitly set to `false`. |
| `maxSteps` | Limits tool-call rounds in one turn; zero means unlimited. |
| `compactionModel` | Selects the model used for history compaction. |
| generation fields | Configure backend/model sampling and token limits. |

`prompt` and `userPrompts` accept either a single path or an array. Environment variables are expanded in paths and file contents. Missing files are retried with a `.md` suffix and then skipped. A leading `!` remains supported for legacy command entries; the command runs with the agent working directory and its stdout becomes prompt text.

The default configuration uses installed prompt files under `$XDG_CONFIG_HOME/ollie/prompts`. Runtime data is installed by `make install-data`; source prompt templates live under `data/prompts`.

## Tool rendering

When tools are enabled, `BuildRuntime` calls the configured `ToolsrvConn` once to obtain tool metadata. The metadata becomes both:

- the backend function/tool definitions, with dispatch flags added to each schema; and
- the rendered `# Tools` preamble section.

`RenderTools` sorts tools by name, omits remote-server entries, and renders each local tool’s `.meta` prompt when present. It falls back to the description when no prompt is available. The current implementation combines the tool listing and documentation instead of maintaining separate listing and schema-dump sections.

Tool restrictions are not implemented in the prompt builder. The tool server determines which tools are available, and the runtime uses that same returned set for both execution schemas and prompt text.

## Per-turn prompting

`Runtime.UserPrompt` is not part of the system preamble. Before a turn is submitted, `executeTurn` prepends the resolved `userPrompts` content to the user input:

```text
resolved user prompts

user input
```

Queued prompts, injected prompts, and tool results then participate in the normal agent history and turn loop. The system preamble remains stable until the runtime is rebuilt.

## System prompt resolution

`ResolveSystemPrompt` selects the configured `systemPrompt` override when present. Otherwise it uses the embedded `prompts.DefaultSystemPrompt`, generated from `cmd/olliesrv/internal/prompts/system_prompt.md`.

The base prompt is intentionally generic. Agent-specific behavior belongs in the agent’s `prompt` files; active per-user rules belong in `userPrompts`. The system prompt also documents the common 9P runtime and tool-loading interface shared by agents.

## Context and compaction

The runtime passes the preamble and message history to the backend. The agent maintains history separately from prompt assembly. When history reaches configured limits, compaction produces a summary and the runtime continues with the compacted history plus the same system preamble.

The `systemprompt` 9P file exposes the current rendered preamble for inspection. It is the assembled runtime value, not a separate prompt source.

## Source locations

| Responsibility | Source |
|---|---|
| Agent configuration types | `cmd/olliesrv/internal/agent/agent_config.go` |
| Prompt file and environment expansion | `cmd/olliesrv/internal/agent/prompt_resolver.go` |
| Preamble and runtime construction | `cmd/olliesrv/internal/agent/runtime.go` |
| Per-turn user-prompt injection | `cmd/olliesrv/internal/agent/turn.go` |
| Embedded default system prompt | `cmd/olliesrv/internal/prompts/system_prompt.md` |
| Installed agent configuration | `data/agents/*.json` |
| Installed prompt templates | `data/prompts/*.md` |