fix(agent): move dynamic context after history to preserve prefix caching

config/config.example.json

@@ -18,6 +18,10 @@
         "enabled": false,
         "max_args_length": 300,
         "separate_messages": false
+      },
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
       }
     }
   },

docs/guides/configuration.fr.md

@@ -110,6 +110,39 @@ Exemple de contexte propre avec outils web :
 }
 ```
 
+### Placement du contexte dynamique
+
+`agents.defaults.dynamic_context` contrôle le bloc de contexte propre à chaque requête — `## Runtime`, `## Current Session`, `## Current Sender` et `## Current Time`.
+
+| Clé | Valeurs | Défaut | Signification |
+| --- | --- | --- | --- |
+| `position` | `tail`, `system` | `tail` | Emplacement du bloc. `tail` le place après l'historique de conversation, porté par le message utilisateur courant dans une balise `<runtime_context>`. `system` le garde dans le prompt système (la disposition précédente). |
+| `time` | `minute`, `hour`, `off` | `minute` | Précision de `## Current Time`. `hour` arrondit l'horloge à l'heure inférieure ; `off` omet complètement l'heure. |
+
+**Pourquoi `tail` est la valeur par défaut.** La mise en cache de préfixe est positionnelle : modifier un token invalide tous les tokens suivants. Avec le bloc dans le prompt système, une horloge à la minute changeait quelque chose *avant* toute la conversation, si bien que l'historique entier était re-préchargé une fois par minute. Sur un hôte où un tour dépasse la minute, ce coût est payé à chaque tour : environ 2,2 ms par token d'historique, soit près de 13 s de re-préchargement pur par tour pour un historique de 6 000 tokens.
+
+Déplacer le bloc après l'historique rend le prompt système statique et l'historique complet identiques octet pour octet d'un tour à l'autre : les backends qui ne font que de la correspondance de préfixe d'octets (llama.cpp, Ollama et les autres endpoints compatibles OpenAI sans mécanisme de cache natif) touchent leur cache KV à chaque tour au lieu de le manquer chaque minute. Cela rend aussi le prompt statique identique pour tous les utilisateurs, toutes les sessions et toutes les exécutions cron, qui partagent alors un seul préfixe mis en cache au lieu de payer chacun un préchargement à froid.
+
+Anthropic (`cache_control`) et OpenAI (`prompt_cache_key`) ne sont pas concernés : leurs mécanismes natifs s'appliquent toujours.
+
+Ne mettez `position` à `system` que si vous avez besoin de la disposition précédente. Notez que le bloc n'est jamais émis comme message système final : les adaptateurs de providers remontent les messages système en tête, et certains ne gardent que le dernier, ce qui écraserait le prompt statique.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+- `position` : `tail` (par défaut) ou `system` pour rétablir l'ancienne disposition.
+- `time` : `minute` (par défaut), `hour` pour élargir encore la fenêtre de réutilisation, ou `off` pour supprimer l'horloge.
+
 ### Sources de Compétences
 
 Par défaut, les compétences sont chargées depuis :

docs/guides/configuration.ja.md

@@ -111,6 +111,39 @@ Web ツールだけを残すクリーンなコンテキスト例：
 }
 ```
 
+### 動的コンテキストの配置
+
+`agents.defaults.dynamic_context` は、リクエストごとに変化するコンテキストブロック（`## Runtime`、`## Current Session`、`## Current Sender`、`## Current Time`）を制御します。
+
+| キー | 値 | 既定値 | 意味 |
+| --- | --- | --- | --- |
+| `position` | `tail`、`system` | `tail` | ブロックの配置場所。`tail` は会話履歴の後ろに置き、`<runtime_context>` タグで囲んで現在のユーザーメッセージに載せます。`system` は system prompt の中に残します（従来のレイアウト）。 |
+| `time` | `minute`、`hour`、`off` | `minute` | `## Current Time` の精度。`hour` は時単位に切り捨てた時刻を出力し、`off` は時刻を出力しません。 |
+
+**`tail` が既定である理由。** プレフィックスキャッシュは位置に依存します。あるトークンが変わると、それ以降のトークンはすべて無効になります。このブロックが system prompt の中にあると、分単位の時刻が会話全体より前で毎分変化するため、履歴全体が毎分再 prefill されていました。1 ターンが 1 分を超えるホストでは、このコストを毎ターン支払うことになります。履歴トークンあたり約 2.2 ms、6,000 トークンの履歴なら 1 ターンあたり約 13 秒が純粋な再 prefill に費やされる計算です。
+
+ブロックを履歴の後ろに移すと、静的な system prompt と履歴全体がターン間でバイト単位で同一になり、バイト列のプレフィックス一致だけを行うバックエンド（llama.cpp、Ollama、その他ネイティブなキャッシュ機構を持たない OpenAI 互換エンドポイント）が、毎分ミスする代わりに毎ターンキャッシュにヒットします。さらに静的プロンプトがすべてのユーザー・セッション・cron 実行で同一になるため、それぞれがコールドな prefill を払う代わりに 1 つのキャッシュ済みプレフィックスを共有できます。
+
+Anthropic（`cache_control`）と OpenAI（`prompt_cache_key`）は影響を受けません。それぞれのネイティブ機構がそのまま適用されます。
+
+従来のプロンプトレイアウトが必要な場合にのみ `position` を `system` にしてください。なお、このブロックは末尾の system メッセージとしては送信されません。provider アダプタは system メッセージを先頭へ移動させ、一部は最後の 1 件だけを残すため、静的プロンプトが破棄されてしまいます。
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+- `position`: `tail`（既定）または `system`（以前のレイアウトに戻す）。
+- `time`: `minute`（既定）、`hour`（再利用ウィンドウをさらに広げる）、`off`（時刻を出力しない）。
+
 ### スキルソース
 
 デフォルトでは、スキルは以下の順序で読み込まれます：

docs/guides/configuration.md

@@ -143,6 +143,38 @@ Example clean web policy:
 }
 ```
 
+### Dynamic Context Placement
+
+`agents.defaults.dynamic_context` controls the per-request context block — `## Runtime`, `## Current Session`, `## Current Sender` and `## Current Time`.
+
+| Key | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `position` | `tail`, `system` | `tail` | Where the block is placed. `tail` puts it after the conversation history, carried on the current user message inside a `<runtime_context>` tag. `system` keeps it inside the system prompt (the previous layout). |
+| `time` | `minute`, `hour`, `off` | `minute` | Precision of `## Current Time`. `hour` reports the clock rounded down to the hour; `off` omits the time entirely. |
+
+**Why `tail` is the default.** Prefix caching is positional: changing any token invalidates every token after it. With the block in the system prompt, a minute-precision clock changes something *before* the entire conversation, so the whole history is re-prefilled once per minute. On a host where a turn takes longer than a minute, that cost is paid every single turn — roughly 2.2 ms per history token, so a 6,000-token history burns about 13 s of pure re-prefill per turn.
+
+Moving the block after the history makes the static system prompt and the full history byte-identical from turn to turn, so a backend that only does byte-prefix matching keeps its KV cache. It also makes the static prompt identical across *all* users, sessions and cron runs, letting them share one cached prefix instead of each paying a cold prefill.
+
+This matters most for local backends — llama.cpp, Ollama, and any other OpenAI-compatible endpoint without a native caching mechanism. Anthropic (per-block `cache_control`) and OpenAI (`prompt_cache_key`) have their own mechanisms, which are unaffected either way.
+
+Set `position` to `system` only if you need the previous prompt layout. Note the block is never emitted as a trailing *system* message: provider adapters hoist system messages to the front, and some keep only the last one, which would discard the static prompt.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+Operators who don't need wall-clock awareness at all can widen the reuse window further with `"time": "hour"` or drop it with `"time": "off"`.
+
 ### Web launcher dashboard
 
 **picoclaw-launcher** serves a browser UI that requires password sign-in first. On first run, open `/launcher-setup` to create the dashboard password. Later manual sign-ins use `/launcher-login`.

docs/guides/configuration.pt-br.md

@@ -111,6 +111,39 @@ Exemplo de contexto limpo com ferramentas web:
 }
 ```
 
+### Posicionamento do contexto dinâmico
+
+`agents.defaults.dynamic_context` controla o bloco de contexto de cada requisição — `## Runtime`, `## Current Session`, `## Current Sender` e `## Current Time`.
+
+| Chave | Valores | Padrão | Significado |
+| --- | --- | --- | --- |
+| `position` | `tail`, `system` | `tail` | Onde o bloco fica. `tail` o coloca depois do histórico da conversa, carregado na mensagem de usuário atual dentro de uma tag `<runtime_context>`. `system` o mantém dentro do prompt de sistema (o layout anterior). |
+| `time` | `minute`, `hour`, `off` | `minute` | Precisão de `## Current Time`. `hour` arredonda o relógio para baixo até a hora; `off` omite o horário por completo. |
+
+**Por que `tail` é o padrão.** O cache de prefixo é posicional: alterar qualquer token invalida todos os tokens seguintes. Com o bloco no prompt de sistema, um relógio com precisão de minuto mudava algo *antes* de toda a conversa, então o histórico inteiro era re-preenchido uma vez por minuto. Em um host onde um turno passa de um minuto, esse custo é pago em todo turno: cerca de 2,2 ms por token de histórico, ou seja, aproximadamente 13 s de re-prefill puro por turno em um histórico de 6.000 tokens.
+
+Mover o bloco para depois do histórico deixa o prompt de sistema estático e todo o histórico idênticos byte a byte entre turnos, de modo que backends que só fazem correspondência de prefixo de bytes (llama.cpp, Ollama e outros endpoints compatíveis com OpenAI sem mecanismo de cache nativo) acertam o cache KV a cada turno em vez de errar a cada minuto. Isso também torna o prompt estático idêntico para todos os usuários, sessões e execuções de cron, que passam a compartilhar um único prefixo em cache em vez de cada um pagar um prefill frio.
+
+Anthropic (`cache_control`) e OpenAI (`prompt_cache_key`) não são afetados — seus mecanismos nativos continuam valendo.
+
+Defina `position` como `system` apenas se precisar do layout de prompt anterior. Note que o bloco nunca é emitido como uma mensagem de sistema final: os adaptadores de provider movem mensagens de sistema para o início, e alguns mantêm apenas a última, o que descartaria o prompt estático.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+- `position`: `tail` (padrão) ou `system` para restaurar o layout antigo.
+- `time`: `minute` (padrão), `hour` para ampliar ainda mais a janela de reuso, ou `off` para remover o relógio.
+
 ### Fontes de Skills
 
 Por padrão, as skills são carregadas de:

docs/guides/configuration.vi.md

@@ -111,6 +111,39 @@ Ví dụ ngữ cảnh sạch chỉ giữ tool web:
 }
 ```
 
+### Vị trí ngữ cảnh động
+
+`agents.defaults.dynamic_context` kiểm soát block ngữ cảnh thay đổi theo từng request — `## Runtime`, `## Current Session`, `## Current Sender` và `## Current Time`.
+
+| Key | Giá trị | Mặc định | Ý nghĩa |
+| --- | --- | --- | --- |
+| `position` | `tail`, `system` | `tail` | Vị trí đặt block. `tail` đặt sau lịch sử hội thoại, gắn vào tin nhắn user hiện tại bên trong thẻ `<runtime_context>`. `system` giữ nó trong system prompt (bố cục trước đây). |
+| `time` | `minute`, `hour`, `off` | `minute` | Độ chính xác của `## Current Time`. `hour` làm tròn xuống theo giờ; `off` bỏ hẳn phần thời gian. |
+
+**Vì sao `tail` là mặc định.** Prefix cache phụ thuộc vị trí: thay đổi một token sẽ vô hiệu hóa toàn bộ token phía sau. Khi block nằm trong system prompt, đồng hồ chính xác đến phút thay đổi ở *trước* toàn bộ hội thoại, nên cả lịch sử phải prefill lại mỗi phút một lần. Trên máy mà mỗi turn kéo dài hơn một phút, chi phí này phải trả ở mọi turn: khoảng 2,2 ms cho mỗi token lịch sử, tức khoảng 13 giây prefill thuần mỗi turn với lịch sử 6.000 token.
+
+Chuyển block ra sau lịch sử giúp system prompt tĩnh và toàn bộ lịch sử giống nhau từng byte giữa các turn, nhờ đó các backend chỉ so khớp prefix theo byte (llama.cpp, Ollama và các endpoint tương thích OpenAI khác không có cơ chế cache riêng) trúng KV cache ở mọi turn thay vì trượt mỗi phút. Điều này cũng làm prompt tĩnh giống hệt nhau giữa tất cả người dùng, tất cả session và mọi lần chạy cron, để chúng dùng chung một prefix đã cache thay vì mỗi bên phải chịu một lần prefill nguội.
+
+Anthropic (`cache_control`) và OpenAI (`prompt_cache_key`) không bị ảnh hưởng — cơ chế riêng của chúng vẫn hoạt động.
+
+Chỉ đặt `position` thành `system` nếu bạn cần bố cục prompt trước đây. Lưu ý block không bao giờ được gửi dưới dạng system message ở cuối: các adapter provider sẽ đẩy system message lên đầu, và một số chỉ giữ lại cái cuối cùng, khiến prompt tĩnh bị mất.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+- `position`: `tail` (mặc định) hoặc `system` để khôi phục bố cục cũ.
+- `time`: `minute` (mặc định), `hour` để mở rộng thêm cửa sổ tái sử dụng, hoặc `off` để bỏ hẳn đồng hồ.
+
 ### Nguồn Skill
 
 Mặc định, skill được tải từ:

docs/guides/configuration.zh.md

@@ -141,6 +141,39 @@ PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/work
 }
 ```
 
+### 动态上下文位置
+
+`agents.defaults.dynamic_context` 用来控制每次请求都会变化的上下文块 —— `## Runtime`、`## Current Session`、`## Current Sender` 和 `## Current Time`。
+
+| 键 | 取值 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `position` | `tail`、`system` | `tail` | 该块的位置。`tail` 把它放在对话历史之后，包在 `<runtime_context>` 标签内随当前用户消息一起发送；`system` 保留在 system prompt 内部（此前的布局）。 |
+| `time` | `minute`、`hour`、`off` | `minute` | `## Current Time` 的精度。`hour` 只报到小时（分钟向下取整），`off` 完全不输出时间。 |
+
+**为什么默认是 `tail`。** 前缀缓存是按位置生效的：改动任意一个 token，其后的全部 token 都会失效。该块原本位于 system prompt 中，分钟级时间戳每分钟变一次，而它排在整段对话之前，于是整个历史每分钟就要重新 prefill 一遍。在单轮耗时超过一分钟的机器上，这个代价每轮都要付：约每个历史 token 2.2 ms，6000 token 的历史相当于每轮约 13 秒的纯 prefill。
+
+把该块移到历史之后，静态 system prompt 和整段历史在相邻回合之间即可保持逐字节一致，只做字节前缀匹配的后端（llama.cpp、Ollama，以及其他没有原生缓存机制的 OpenAI 兼容端点）每轮都能命中 KV 缓存，而不是每分钟失效一次。同时静态提示词在所有用户、所有会话和所有定时任务之间也完全一致，可以共用同一段缓存前缀，而不必各自承担一次冷 prefill。
+
+Anthropic（`cache_control`）和 OpenAI（`prompt_cache_key`）不受影响，它们的原生机制照常生效。
+
+只有在需要恢复此前的提示词布局时，才把 `position` 设为 `system`。注意该块不会作为末尾的 system 消息发送：各 provider 适配器会把 system 消息前移，其中一部分只保留最后一条，那样会把静态提示词整个丢掉。
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "dynamic_context": {
+        "time": "minute",
+        "position": "tail"
+      }
+    }
+  }
+}
+```
+
+- `position`：`tail`（默认）或 `system`（恢复旧布局）。
+- `time`：`minute`（默认）、`hour`（进一步扩大复用窗口）或 `off`（完全不带时间）。
+
 ### Web 启动器控制台
 
 用 **picoclaw-launcher** 打开浏览器控制台前需要先使用密码登录。首次启动时打开 `/launcher-setup` 创建 dashboard 登录密码；后续手动登录使用 `/launcher-login`。