When the first user message starts a new local-agent session, include the selected project root AGENTS.md in the agent system prompt and reuse a cached KV bootstrap for the deterministic prompt prefix.
Required behavior
Creating or selecting a draft session does no prompt construction, tokenization, prefill, or KV-cache work.
On the first non-empty user submission, read AGENTS.md from the selected project root when it exists and include its contents in the system prompt before the user message.
A missing AGENTS.md is not an error.
The system prompt, AGENTS.md, and other injected system context are part of model context and KV state, but are not treated as user-visible chat turns.
First-title generation uses the actual first user message only. System instructions and injected context must not affect the title input.
KV bootstrap
Cache only the deterministic prefix shared by new sessions with the same effective configuration. This includes the rendered agent/tool prompt, configured system instructions, optional A2UI system instructions, AGENTS.md, model, and reasoning mode.
Session-specific data such as the current date/time, A2UI client metadata, and the user message remains in the uncached suffix.
On the first user submission:
Build the effective deterministic prefix.
Look for a compatible content-addressed bootstrap checkpoint using the existing KV-store and checkpoint compatibility rules.
On a hit, restore it and prefill only the remaining session-specific suffix.
On a miss, prefill the deterministic prefix once, store that checkpoint through the existing cache budget and eviction policy, then continue with the suffix.
Prompt identity is the invalidation mechanism. Any change to tools, configured system instructions, A2UI instructions, AGENTS.md, model, reasoning mode, tokenizer/rendering identity, context, or checkpoint-compatible execution settings must prevent stale reuse. Loading an invalid checkpoint falls back to rebuilding it.
Do not add a separate persisted component hash, file watcher, eager regeneration job, copy-on-write Metal buffers, or a new KV-slice ownership abstraction. The existing content-addressed key and checkpoint header provide invalidation and compatibility.
DS4 reference
The native ds4-agent uses a sysprompt.kv bootstrap checkpoint, verifies the exact rendered system-prompt text and model compatibility, and rebuilds the checkpoint on mismatch. DS4Server should preserve that behavior while reusing its existing prefix-aware KV store.
Acceptance criteria
Creating a new session produces no model or KV activity until a user submits text.
With AGENTS.md present, its exact contents reach the model as system context on the first turn.
Without AGENTS.md, the first turn works normally.
Title generation receives only the first user message.
A second new session with an unchanged deterministic prefix reports cached-prefix reuse.
Editing AGENTS.md or another deterministic component causes a cache miss and rebuild.
Dynamic session context does not invalidate the deterministic bootstrap.
Incompatible model or execution configuration never reuses the checkpoint.
## Goal
When the first user message starts a new local-agent session, include the selected project root AGENTS.md in the agent system prompt and reuse a cached KV bootstrap for the deterministic prompt prefix.
## Required behavior
- Creating or selecting a draft session does no prompt construction, tokenization, prefill, or KV-cache work.
- On the first non-empty user submission, read AGENTS.md from the selected project root when it exists and include its contents in the system prompt before the user message.
- A missing AGENTS.md is not an error.
- The system prompt, AGENTS.md, and other injected system context are part of model context and KV state, but are not treated as user-visible chat turns.
- First-title generation uses the actual first user message only. System instructions and injected context must not affect the title input.
## KV bootstrap
Cache only the deterministic prefix shared by new sessions with the same effective configuration. This includes the rendered agent/tool prompt, configured system instructions, optional A2UI system instructions, AGENTS.md, model, and reasoning mode.
Session-specific data such as the current date/time, A2UI client metadata, and the user message remains in the uncached suffix.
On the first user submission:
1. Build the effective deterministic prefix.
2. Look for a compatible content-addressed bootstrap checkpoint using the existing KV-store and checkpoint compatibility rules.
3. On a hit, restore it and prefill only the remaining session-specific suffix.
4. On a miss, prefill the deterministic prefix once, store that checkpoint through the existing cache budget and eviction policy, then continue with the suffix.
Prompt identity is the invalidation mechanism. Any change to tools, configured system instructions, A2UI instructions, AGENTS.md, model, reasoning mode, tokenizer/rendering identity, context, or checkpoint-compatible execution settings must prevent stale reuse. Loading an invalid checkpoint falls back to rebuilding it.
Do not add a separate persisted component hash, file watcher, eager regeneration job, copy-on-write Metal buffers, or a new KV-slice ownership abstraction. The existing content-addressed key and checkpoint header provide invalidation and compatibility.
## DS4 reference
The native ds4-agent uses a sysprompt.kv bootstrap checkpoint, verifies the exact rendered system-prompt text and model compatibility, and rebuilds the checkpoint on mismatch. DS4Server should preserve that behavior while reusing its existing prefix-aware KV store.
## Acceptance criteria
- Creating a new session produces no model or KV activity until a user submits text.
- With AGENTS.md present, its exact contents reach the model as system context on the first turn.
- Without AGENTS.md, the first turn works normally.
- Title generation receives only the first user message.
- A second new session with an unchanged deterministic prefix reports cached-prefix reuse.
- Editing AGENTS.md or another deterministic component causes a cache miss and rebuild.
- Dynamic session context does not invalidate the deterministic bootstrap.
- Incompatible model or execution configuration never reuses the checkpoint.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Goal
When the first user message starts a new local-agent session, include the selected project root AGENTS.md in the agent system prompt and reuse a cached KV bootstrap for the deterministic prompt prefix.
Required behavior
KV bootstrap
Cache only the deterministic prefix shared by new sessions with the same effective configuration. This includes the rendered agent/tool prompt, configured system instructions, optional A2UI system instructions, AGENTS.md, model, and reasoning mode.
Session-specific data such as the current date/time, A2UI client metadata, and the user message remains in the uncached suffix.
On the first user submission:
Prompt identity is the invalidation mechanism. Any change to tools, configured system instructions, A2UI instructions, AGENTS.md, model, reasoning mode, tokenizer/rendering identity, context, or checkpoint-compatible execution settings must prevent stale reuse. Loading an invalid checkpoint falls back to rebuilding it.
Do not add a separate persisted component hash, file watcher, eager regeneration job, copy-on-write Metal buffers, or a new KV-slice ownership abstraction. The existing content-addressed key and checkpoint header provide invalidation and compatibility.
DS4 reference
The native ds4-agent uses a sysprompt.kv bootstrap checkpoint, verifies the exact rendered system-prompt text and model compatibility, and rebuilds the checkpoint on mismatch. DS4Server should preserve that behavior while reusing its existing prefix-aware KV store.
Acceptance criteria
Implemented in
4adb49a. All required commit gates pass.