Improved examples and added context history size and compaction

Author: PredictabilityAtScale

README.md

@@ -90,6 +90,8 @@ reasoning:
 sampling:
   temperature: 0.7
 context:
+  history:
+    max_items: 10
   inputs:
     - name: user_message
       non_empty:
@@ -125,6 +127,12 @@ const result = await kit.renderPrompt({
     user_message: 'How do I reset my password?',
     app_context: 'Account settings page',
   },
+  history: [
+    { role: 'user', content: 'I am on the account settings page.' },
+    { role: 'assistant', content: 'I can help with account access.' },
+  ],
+  onHistoryCompaction: ({ overflow }) =>
+    `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
 });
 
 if (result.returnMessage) {
@@ -168,6 +176,7 @@ Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `c
 - **Context hardening** — copyable `/pattern/i` regex literals, structured regexes with `return_message`, and built-in `non_empty` / `reject_secrets` validators
 - **Optional short-circuit messages** — validators can return a structured `returnMessage` instead of throwing when configured
 - **Context size guardrails** — optional per-input `max_size` metadata with non-blocking render-time warnings
+- **History preservation** — optional `context.history.max_items` compacts older conversation turns into one preserved history item, with a runtime `onHistoryCompaction` hook for custom summaries
 - **Warning controls** — top-level config can suppress or emit context size warnings differently in dev and prod
 - **Caching** — LRU cache with mtime-based invalidation
 - **CLI** — init, validate, compile, render, inspect, skill
@@ -585,9 +594,10 @@ Renders a prompt for a specific provider. Returns `{ resolved, request?, returnM
 | `provider` | `string` | `'openai'`, `'openai-responses'`, `'anthropic'`, `'gemini'`, `'openrouter'` |
 | `variables` | `Record<string, string>` | Template variables |
 | `onContextOverflow` | `(info) => string` | Optional callback to transform oversized context values before rendering |
+| `onHistoryCompaction` | `(info) => string \| { role, content }` | Optional callback to compact overflow history when `context.history.max_items` is exceeded |
 | `environment` | `string` | Environment override name |
 | `tier` | `string` | Tier override name |
-| `history` | `Array<{ role, content }>` | Conversation history |
+| `history` | `Array<{ role, content }>` | Conversation history. If the prompt declares `context.history.max_items`, older turns are compacted into one preserved history item before provider rendering. |
 | `toolRegistry` | `Record<string, unknown>` | Tool definitions for resolving string tool references |
 | `strict` | `boolean` | Fail on missing variables |
 | `openaiResponses` | `object` | Optional Responses API extras (`previous_response_id`, `conversation`, `instructions`, `parallel_tool_calls`, `max_tool_calls`, `store`, `metadata`, `include`, `background`) |
@@ -621,7 +631,7 @@ Prompt files use YAML front matter with these fields:
 | `provider_options` | `object` | Provider-specific non-portable options (`anthropic`, `gemini`, `openrouter`) |
 | `raw` | `object` | Provider-scoped request-body passthrough (`openai`, `openai-responses`, `anthropic`, `gemini`/`google`, `openrouter`) |
 | `mcp` | `object` | MCP server references |
-| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, and built-in `non_empty` / `reject_secrets` validators |
+| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, built-in `non_empty` / `reject_secrets` validators, and `history.max_items` compaction |
 | `includes` | `string[]` | Paths to included prompt files |
 | `environments` | `object` | Named environment overrides |
 | `tiers` | `object` | Named tier overrides |

SKILL.md

@@ -70,7 +70,7 @@ the fields required by that specific file:
 | `raw` | object | no | Provider-scoped request-body passthrough for unmodeled vendor fields |
 | `mcp` | object | no | `{ servers: [string | { name, config }] }` |
 | `context.inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | no | Declared variable names used in templates, with optional size budgets and runtime hardening controls |
-| `context.history` | object | no | `{ max_items: number }` |
+| `context.history` | object | no | `{ max_items: number }`; caps rendered history by compacting older turns into one preserved message |
 | `includes` | string[] | no | Relative paths to other prompt files to include |
 | `environments` | object | no | Per-environment overrides (see Overrides) |
 | `tiers` | object | no | Per-tier overrides (see Overrides) |
@@ -131,6 +131,32 @@ If a validator declares `return_message`, `renderPrompt()` returns that message
 
 Malformed `allow_regex` and `deny_regex` values fail during `validate` and `compile`, not just at render time. When regex compilation fails, the error includes the prompt id, variable name, field name, and raw configured value. Double-quoted YAML regex strings with raw backslashes fail as `POK013`; use `/pattern/i`, single-quoted `pattern: '...'`, or doubled backslashes.
 
+### Conversation history limits
+
+Use `context.history.max_items` when a chat-style prompt should bound rendered conversation history:
+
+```yaml
+context:
+  history:
+    max_items: 10
+```
+
+When runtime `history` exceeds `max_items`, PromptOpsKit preserves history by compacting older turns into one synthetic history message and keeping the most recent turns. Callers can provide `onHistoryCompaction` to create a custom summary:
+
+```typescript
+const result = await kit.renderPrompt({
+  path: 'support/reply',
+  provider: 'openai',
+  history,
+  onHistoryCompaction: ({ overflow }) => ({
+    role: 'user',
+    content: `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
+  }),
+});
+```
+
+If no callback is supplied, PromptOpsKit creates a plain text compacted history message. Do not describe `max_items` as dropping history; it preserves overflow through compaction.
+
 Example: this is the minimal valid shape for a prompt that references
 `{{ pull_request }}` even when provider/model are inherited from defaults:
 

docs/api-reference.md

@@ -55,6 +55,8 @@ const result = await kit.renderPrompt({
     { role: 'user', content: 'Hello' },
     { role: 'assistant', content: 'Hi!' },
   ],
+  onHistoryCompaction: ({ overflow }) =>
+    `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
   strict: false,
 });
 ```
@@ -66,9 +68,10 @@ const result = await kit.renderPrompt({
 | `provider` | `string` | `'openai'`, `'openai-responses'`, `'anthropic'`, `'gemini'`, `'openrouter'` (required) |
 | `variables` | `Record<string, string>` | Template variables |
 | `onContextOverflow` | `(info) => string` | Optional callback to transform an oversized context value before rendering |
+| `onHistoryCompaction` | `(info) => string \| { role, content }` | Optional callback used when `context.history.max_items` compacts overflow history |
 | `environment` | `string` | Environment override name |
 | `tier` | `string` | Tier override name |
-| `history` | `Array<{ role, content }>` | Conversation history |
+| `history` | `Array<{ role, content }>` | Conversation history. If the prompt declares `context.history.max_items`, overflow history is compacted into one preserved history item before provider rendering. |
 | `toolRegistry` | `Record<string, unknown>` | Tool definitions for resolving string tool references |
 | `strict` | `boolean` | Fail on missing variables (default `false`) |
 | `openaiResponses` | `object` | Optional Responses API extras (`previous_response_id`, `conversation`, `instructions`, `parallel_tool_calls`, `max_tool_calls`, `store`, `metadata`, `include`, `background`) |
@@ -247,7 +250,7 @@ const request = adapter.render(resolvedAsset, {
 });
 ```
 
-`RuntimeRenderOptions` for direct adapter rendering supports `environment`, `tier`, `runtime`, `variables`, `onContextOverflow`, `history`, `toolRegistry`, `strict`, and `openaiResponses`.
+`RuntimeRenderOptions` for direct adapter rendering supports `environment`, `tier`, `runtime`, `variables`, `onContextOverflow`, `history`, `onHistoryCompaction`, `toolRegistry`, `strict`, and `openaiResponses`.
 
 Runtime overrides can include the same overridable front matter fields as `environments` and `tiers`, including `raw` provider passthrough blocks. Raw blocks are merged into provider request bodies after normalized fields and provider-specific options.
 

docs/getting-started.md

@@ -42,6 +42,8 @@ reasoning:
 sampling:
   temperature: 0.7
 context:
+  history:
+    max_items: 10
   inputs:
     - name: user_message
       non_empty: true
@@ -77,6 +79,12 @@ const result = await kit.renderPrompt({
     user_message: 'How do I reset my password?',
     app_context: 'Billing settings page',
   },
+  history: [
+    { role: 'user', content: 'I am looking at my account page.' },
+    { role: 'assistant', content: 'I can help with account access.' },
+  ],
+  onHistoryCompaction: ({ overflow }) =>
+    `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
 });
 
 if (!result.request) {
@@ -115,6 +123,8 @@ const kit = createPromptOpsKit({
 
 Your application owns the HTTP call — PromptOpsKit produces the request body only.
 
+When `context.history.max_items` is set and runtime history exceeds that count, PromptOpsKit compacts older turns into one preserved history item and keeps the most recent turns. Use `onHistoryCompaction` when your app wants to provide its own summary.
+
 ## Validate prompts
 
 ```bash

docs/prompt-format.md

@@ -247,6 +247,34 @@ At render time, PromptOpsKit also emits a non-blocking `POK030` warning when a p
 
 Malformed `allow_regex` and `deny_regex` values fail during `validate` and `compile` with `POK013`, so bad patterns are caught before runtime. Double-quoted YAML regex strings with raw backslashes are also reported as `POK013`; use unquoted `/pattern/i`, single-quoted `pattern: '...'`, or doubled backslashes in double quotes.
 
+### Conversation history
+
+Declare `context.history.max_items` when a prompt should bound rendered conversation history:
+
+```yaml
+context:
+  history:
+    max_items: 8
+```
+
+When runtime `history` has more than `max_items` messages, PromptOpsKit preserves all history by compacting older turns into one synthetic history message, then keeping the most recent turns. The final provider request receives at most `max_items` history items before the current prompt template is added.
+
+Callers can customize the compacted message with `onHistoryCompaction`:
+
+```typescript
+const result = await kit.renderPrompt({
+  path: 'support/reply',
+  provider: 'openai',
+  history,
+  onHistoryCompaction: ({ overflow }) => ({
+    role: 'user',
+    content: `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
+  }),
+});
+```
+
+If no callback is supplied, PromptOpsKit creates a plain text compacted history message. This behavior is provider-agnostic: OpenAI/OpenRouter use `messages`, OpenAI Responses uses `input`, Anthropic uses `messages`, and Gemini maps assistant history to `model`.
+
 Example hardened input definition:
 
 ```yaml

docs/providers.md

@@ -471,6 +471,28 @@ const { request } = result;
 
 History messages are inserted between system instructions and the prompt template in the messages array. For Gemini, role `assistant` is mapped to `model`.
 
+If the prompt declares `context.history.max_items`, provider rendering compacts overflow history before shaping the request. Older turns become one preserved history item, and the most recent turns are kept as-is:
+
+```yaml
+context:
+  history:
+    max_items: 4
+```
+
+```typescript
+const result = await kit.renderPrompt({
+  path: 'chat',
+  provider: 'openai',
+  history,
+  onHistoryCompaction: ({ overflow }) => ({
+    role: 'user',
+    content: `Earlier conversation summary: ${summarizeConversationUsingLLM(overflow)}`,
+  }),
+});
+```
+
+If no `onHistoryCompaction` callback is supplied, PromptOpsKit creates a plain text compacted history message. The behavior is shared by OpenAI, OpenAI Responses, Anthropic, Gemini, and OpenRouter.
+
 ## Tools
 
 Tools defined in front matter are included in the request body. They can be string references or inline definitions:

docs/schema.md

@@ -278,7 +278,9 @@ context:
 |-------|------|-------------|
 | `inputs` | `Array<string | { name, max_size?, trim?, allow_regex?, deny_regex?, non_empty?, reject_secrets? }>` | Expected variable names, optionally with size and runtime sanitization constraints |
 | `history` | `object` | History settings |
-| `history.max_items` | `number` | Maximum history items |
+| `history.max_items` | `number` | Maximum rendered history items. Overflow history is compacted into one preserved message rather than dropped. |
+
+When runtime `history` exceeds `history.max_items`, PromptOpsKit creates one compacted history item for the older overflow and keeps the most recent turns. Applications can pass `onHistoryCompaction` to `renderPrompt()` or direct adapter rendering to produce their own summary message.
 
 String-form inputs remain valid: