feat(agent): opt interactive hosted runs into the 1h prompt-cache TTL (RFC 0001)

[mattboon]

Implements the RFC 0001 TTL-gating decision: interactive hosted runs opt into the one-hour prompt-cache TTL so the shared static prefix can stay warm across chat idle gaps.

This PR is stacked on #3435 and includes its exact final dependency head.

What changes

• Threads cacheTtl through cloud runtime system-message construction. The default remains "5m".
• Centralizes the interactive "1h" policy in one builder used by root chat execution, steering refresh, and tool-assembly re-rendering.
• Keeps one-shot child and invoke_agent runs on the "5m" default because they do not expect a second cache read.
• Preserves structured cache breakpoints and the uncached dynamic tail from feat(agent): layer the agent call context - static prompt vs dynamic tail (RFC 0001 example A) #3435.

The policy remains at the interactive call boundary because that boundary knows whether repeat reads are expected.

Verification

• Focused stack tests on 42cc97e0084c7580d98cd738c4d2bdc14204a06b: 104 tests, 239 steps, 0 failures.
• Pinned Deno 2.7.7 docs/static gates: docs:api-reference:check, docs:public:check, docs:validate, typecheck, and git diff --check all exit 0. docs:validate still reports the existing getting-started/index.md webhook index warning.
• Broad unaffected suite on 42cc97e0084c7580d98cd738c4d2bdc14204a06b: extensions/ext-llm-anthropic src/agent passed 1,187 tests and 2,213 steps with 0 failures.
• Full pinned pre-push was rerun and then isolated to src/cache/backend.test.ts --filter ApiCacheBackend --trace-leaks. The same 10 ApiCacheBackend tests fail on this branch and pristine current origin/main (d6bf543771bf4eecbab34452a4f23c5c53c2388a), each with 12 passed, 10 failed, 47 filtered out, and request timeout / abort evidence. This is treated as a reproducible baseline/infrastructure class, not branch-caused.
• A broader provider sweep including src/provider was not used as green evidence because it hit unrelated live-provider 401s in env-backed OpenAI / Veryfront Cloud tests.

Remaining external evidence

The repository has no configured live-provider/VCR harness for provider-reported cache creation and cache-read token counters. Structural request-builder coverage verifies the exact request shape required for a cache hit; live provider telemetry is not claimed here.

Related: RFC 0001 (#1788), #3433, and #3435.

Summary by CodeRabbit

• Improvements

  • Interactive hosted chats now use optimized prompt caching with one-hour cache retention.
  • Anthropic requests manage cache breakpoints consistently across messages, tools, system content, and MCP toolsets.
  • Cache controls are automatically limited and normalized for more reliable, efficient requests.
  • Provider-specific cache metadata is preserved where applicable, while obsolete or excess controls are removed.

• Documentation

  • Updated API reference links and guidance for runtime instruction configuration.

Final head verification

Current exact head after the dependency stack refresh: 21279f9a6cd4627e436434d6ebfc1dddcf541ee2.

• Cache-sensitive descriptor, own-property, key enumeration, array-brand, property-deletion, and record-cloning operations use intrinsics captured during module initialization.
• Boxed Boolean, Number, and String values are rejected before JSON coercion can mutate an initially omitted cache breakpoint.
• Message sibling accessors and serialization hooks fail closed before emitted cache breakpoints are budgeted.
• Serialization-visible nested array indices are inspected with captured descriptors; inherited and accessor slots fail closed without invoking hooks.
• Pinned Deno 2.7.7 request-builder suite: 1 test and 83 steps passed, 0 failed.
• Pinned Deno 2.7.7 full Anthropic extension suite: 6 tests and 236 steps passed, 0 failed.
• Touched-file format, lint, typecheck, and git diff --check passed on the exact head.
• The current exact head's full pinned unit suite passed: 3,849 unit tests and 28,671 steps, 10 cwd tests and 197 steps, plus 2 cwd-exclusion tests, with zero failures. GitHub exact-head CI is green across the full matrix.
• All review comments are resolved. The PR remains draft pending fresh Standards and Spec reviews on this exact head.

Remaining external evidence

The repository has no configured live-provider/VCR harness for provider-reported cache creation and cache-read token counters. Structural request-builder coverage verifies the exact request shape required for a cache hit; live provider telemetry is not claimed here.

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bb14d473-4348-4297-818c-41fbda7689b4

📥 Commits

Reviewing files that changed from the base of the PR and between b919189 and 90e078a.

📒 Files selected for processing (2)

• extensions/ext-llm-anthropic/src/anthropic-request-builder.test.ts
• extensions/ext-llm-anthropic/src/anthropic-request-builder.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• extensions/ext-llm-anthropic/src/anthropic-request-builder.ts

---

📝 Walkthrough

Walkthrough

Hosted runtime instruction builders now accept optional prompt-cache TTL values. Interactive chat paths use a one-hour TTL. Structured cache handling limits Anthropic requests to four retained breakpoints and normalizes their TTL values.

Changes

Interactive prompt caching

Layer / File(s)	Summary
Hosted cache TTL wiring src/agent/hosted/cloud-runtime-system-messages.ts, src/agent/hosted/cloud-runtime-system-messages.test.ts, src/agent/index.ts, docs/api-reference/veryfront/agent.md	Hosted runtime builders accept and forward optional cache TTL values. Interactive builders apply 1h caching. Tests verify static prefixes and dynamic tails.
Chat path cache adoption src/agent/hosted/cloud-agent-chat-execution.ts, src/agent/hosted/default-chat-runtime.ts	Project steering refresh, chat preparation, and default chat rendering use the interactive runtime instruction builder.
Structured breakpoint management src/agent/runtime/call-context.ts, src/agent/runtime/call-context.test.ts	Structured call context retains the latest four Anthropic cache breakpoints, applies TTL values to retained controls, and removes empty provider options.
Anthropic request enforcement extensions/ext-llm-anthropic/src/anthropic-request-builder.ts, extensions/ext-llm-anthropic/src/anthropic-request-builder.test.ts	The request builder limits breakpoints across messages, system content, and tools. It upgrades retained 5m controls to 1h when required and validates metadata safely.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 90e07

The change enables a one-hour prompt-cache TTL for interactive hosted runs while preserving the five-minute default for other runs; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ChatRuntime
  participant InteractiveBuilder
  participant CallContext
  participant AnthropicRequestBuilder
  ChatRuntime->>InteractiveBuilder: Build instructions with cacheTtl: "1h"
  InteractiveBuilder->>CallContext: Create structured cached messages
  CallContext->>AnthropicRequestBuilder: Provide provider cache metadata
  AnthropicRequestBuilder->>AnthropicRequestBuilder: Retain four breakpoints and normalize TTLs

Loading

Possibly related PRs

• veryfront/veryfront-code#3397: Extends hosted Anthropic prompt-cache TTL handling.
• veryfront/veryfront-code#3435: Uses the layered static-prefix and dynamic-tail runtime message structure.

Suggested reviewers: kwakayama, kojiwakayama

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: enabling the 1-hour prompt-cache TTL for interactive hosted agent runs.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/interactive-cache-ttl

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (3)

src/agent/hosted/cloud-runtime-system-messages.test.ts (1)

175-181: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the repository BDD test API.

The three new tests use Deno.test. Use describe() and it() from #veryfront/testing/bdd.ts. Keep the existing assertions from #veryfront/testing/assert.ts.

As per coding guidelines, *.test.ts files must use describe() and it() from #veryfront/testing/bdd.ts.

Also applies to: 183-192, 194-209

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/agent/hosted/cloud-runtime-system-messages.test.ts` around lines 175 -
181, Replace the three Deno.test cases around
createVeryfrontCloudRuntimeSystemMessages with describe() and it() from
`#veryfront/testing/bdd.ts`, while preserving the existing assertions imported
from `#veryfront/testing/assert.ts`.

Source: Coding guidelines

src/agent/hosted/cloud-runtime-system-messages.ts (2)

47-55: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Align the TTL documentation with all interactive call sites.

The options documentation lists root chat and steering refresh, but src/agent/hosted/default-chat-runtime.ts:211 also uses "1h" for tool-assembly re-rendering. State the general interactive-run rule or include this third path.

As per coding guidelines, exported behavior documentation must remain aligned with the implementation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/agent/hosted/cloud-runtime-system-messages.ts` around lines 47 - 55,
Update the documentation for
BuildVeryfrontCloudRuntimeInstructionsOptions.cacheTtl to include tool-assembly
re-rendering via default-chat-runtime, or describe the broader rule that all
interactive runs may use "1h"; retain the existing distinction from one-shot
child/eval runs using the default "5m".

Source: Coding guidelines

---

5-5: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the internal alias for this cross-module import.

This import crosses from src/agent/hosted into src/agent/runtime. Replace the relative path with #veryfront/agent/runtime/call-context.ts.

As per coding guidelines, internal TypeScript imports must use #veryfront/*; relative imports are for cli/ or same-directory siblings.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/agent/hosted/cloud-runtime-system-messages.ts` at line 5, Update the
AgentCallCacheTtl import in cloud-runtime-system-messages.ts to use the
`#veryfront/agent/runtime/call-context.ts` internal alias instead of the relative
path, while leaving the imported type unchanged.

Sources: Coding guidelines, Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/agent/hosted/cloud-runtime-system-messages.test.ts`:
- Around line 175-181: Replace the three Deno.test cases around
createVeryfrontCloudRuntimeSystemMessages with describe() and it() from
`#veryfront/testing/bdd.ts`, while preserving the existing assertions imported
from `#veryfront/testing/assert.ts`.

In `@src/agent/hosted/cloud-runtime-system-messages.ts`:
- Around line 47-55: Update the documentation for
BuildVeryfrontCloudRuntimeInstructionsOptions.cacheTtl to include tool-assembly
re-rendering via default-chat-runtime, or describe the broader rule that all
interactive runs may use "1h"; retain the existing distinction from one-shot
child/eval runs using the default "5m".
- Line 5: Update the AgentCallCacheTtl import in
cloud-runtime-system-messages.ts to use the
`#veryfront/agent/runtime/call-context.ts` internal alias instead of the relative
path, while leaving the imported type unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1af196c4-4f44-4033-a0f5-06c7e9408271

📥 Commits

Reviewing files that changed from the base of the PR and between dd56afe and fb1dfde.

📒 Files selected for processing (4)

• src/agent/hosted/cloud-agent-chat-execution.ts
• src/agent/hosted/cloud-runtime-system-messages.test.ts
• src/agent/hosted/cloud-runtime-system-messages.ts
• src/agent/hosted/default-chat-runtime.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1839f82522

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

Rebased onto the exact current #3435 head (4dd2de470) and incorporated the shared Anthropic provider fix. The 1-hour message-level cache metadata now reaches the wire as a cache_control breakpoint on a separate static system block, while the dynamic system tail stays uncached.

Local verification on exact head dff0b232e:

• hosted wiring plus Anthropic request/provider regression suite: 49 tests passed (208 steps), 0 failed
• production typecheck and generated-manifest checks: passed
• API reference generation/check and public docs validation: passed
• focused lint, test-typecheck baseline, formatting, and git diff --check: passed
• range-diff confirms the functional PR diff is unchanged apart from the provider fix inherited from feat(agent): layer the agent call context - static prompt vs dynamic tail (RFC 0001 example A) #3435 and regenerated source links

@codex review

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[github-actions]

📦 Client bundle boundary

Entrypoint	Modules	Source size	Server leaks
src/index.client.ts	454	3065 KiB	⚠️ 39 known

A server module in a client graph aborts hydration in the browser. New leaks fail CI; known leaks are tracked in scripts/lint/client-bundle-baseline.json to burn down.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: dff0b232ec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

Rebased again onto the updated exact #3435 head (de0814e1e) without conflicts. Range-diff shows both #3437 commits are patch-identical.

Exact-head verification on 03fd08f9b:

• hosted wiring, Anthropic request/provider, runtime bridge, and inherited skill-hardening suites: 65 passed (208 steps), 0 failed
• affected production/test typechecks: passed
• API-reference check, formatting, and git diff --check: passed

@codex review

[chatgpt-codex-connector]

Review result

No actionable findings on commit 03fd08f9b.

The interactive helper consistently applies the one-hour TTL, and the root chat, steering-refresh, and tool-assembly re-render paths all use that helper. Structured system messages are also retained when constructing the runtime configuration, preserving provider cache metadata through dispatch. src/agent/hosted/cloud-runtime-system-messages.tsL43-L75 src/agent/hosted/cloud-agent-chat-execution.tsL123-L129 src/agent/hosted/cloud-agent-chat-execution.tsL343-L345 src/agent/hosted/default-chat-runtime.tsL197-L211 src/agent/hosted/default-chat-runtime.tsL285-L289

No code changes were needed, so no commit or follow-up pull request was created.

Testing

• ✅ git diff --check de0814e1eda87d085c24e49715d16ce41555ee57...HEAD
• ✅ git status --short --branch
• ⚠️ deno test --preload=src/testing/preload.ts --no-check --allow-all src/agent/hosted/cloud-runtime-system-messages.test.ts src/agent/hosted/chat-runtime-tool-assembly.test.ts src/agent/hosted/default-chat-runtime.test.ts (Deno is not installed in this review environment.)

View task →

[kojiwakayama]

Rebased onto #3435 exact head 90af0fe. Range-diff confirms both #3437 commits are patch-identical. Verification on 2d70da8: 105 focused tests passed (174 steps), focused checks and full repository typecheck passed, test-type baseline held, lint passed, module and extension contracts passed, generated API references are current, public docs validation passed, formatting passed, and git diff --check passed.

[kojiwakayama]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 2d70da84da

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

@codex review exact head 968e231cd4793db7db44df2ce4dd1b3f4bb63168. This head is rebased onto current main (8985869b5) with the pre-rebase PR diff preserved by stable patch ID. Please verify the boxed Number/Boolean/String coercion guard, captured reflection intrinsics, and message sibling-accessor guard, then review the complete diff for actionable correctness, security, or compatibility findings. Focused builder: 79 steps passed. Full Anthropic extension: 232 steps passed. Repository typecheck and lint:ci passed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 968e231cd4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

@codex review exact head 6f8b5b32033f82add097df7389191ebcb2912616. The mutable Reflect.deleteProperty finding now has a subprocess red-green regression across system and message retention. The builder captures and uses the deletion intrinsic for both retention paths and optional-field cleanup. Please verify that fix and review the complete exact-head diff for further actionable correctness, security, or compatibility findings. Focused builder: 80 steps passed. Full Anthropic extension: 233 steps passed. Repository typecheck and lint:ci passed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f8b5b3203

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

@codex review exact head 1452f67e22835b699e32a36141c716e3497eb0dd. The symbol-accessor spread and inherited indexed-setter findings now have separate red-green regressions. Cache records clone only serialization-relevant string data properties, and every cache snapshot/retention array write defines an own data property through captured intrinsics. Please verify both fixes and review the complete exact-head diff for further actionable correctness, security, or compatibility findings. Focused builder: 82 steps passed. Full Anthropic extension: 235 steps passed. Repository typecheck and lint:ci passed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1452f67e22

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

@codex review exact head 21279f9a6cd4627e436434d6ebfc1dddcf541ee2. The nested sparse-array inherited-getter finding now has a red-green regression using custom array prototypes. Every serialization-visible nested array index is descriptor-checked without invoking accessors, and own data values are recursively validated. Please verify the fix and review the complete exact-head diff for further actionable correctness, security, or compatibility findings. Focused builder: 83 steps passed. Full Anthropic extension: 236 steps passed. Repository typecheck and lint:ci passed.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 21279f9a6c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 21279f9a6c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".