fix(agent): add authoritative UTC run context - #3517
Merged
Conversation
📝 WalkthroughWalkthroughThe agent runtime now captures one immutable UTC snapshot per run. It injects that snapshot into provider prompts, tracing, streaming events, and response metadata. Authored runtime blocks are replaced, while browser environment context remains available for display. ChangesPer-run UTC runtime context
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant AgentRuntime
participant AgentRunRuntimeContext
participant AgentLoop
participant Provider
participant Response
AgentRuntime->>AgentRunRuntimeContext: capture UTC snapshot
AgentRuntime->>AgentLoop: pass snapshot to generate or stream loop
AgentLoop->>Provider: send prompt with authoritative runtime_context
Provider-->>AgentLoop: return model response
AgentLoop->>Response: attach runtimeContext metadata
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/guides/agents.md (1)
387-395: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winMake the documentation example standalone.
The example calls
agent()without importing it. A reader cannot paste this example into a blank module.Proposed fix
+import { agent } from "veryfront/agent"; + export default agent({As per coding guidelines, “Code examples must be complete, copyable, and safe to paste.”
🤖 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 `@docs/guides/agents.md` around lines 387 - 395, Add the missing import for the `agent` symbol used by the documentation example, using the package/module’s established import path so the snippet is standalone and copyable without changing its behavior.Source: Coding guidelines
🤖 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.
Inline comments:
In `@src/agent/runtime/refresh.test.ts`:
- Line 2325: Update the streaming refresh test around the observedSystems
assertion to advance FakeTime between stream steps, retain the runtime context
in the assertions, and verify one context block per prompt containing the
original run_started_at_utc value.
In `@src/agent/runtime/run-runtime-context.ts`:
- Around line 25-40: Update removeReservedRuntimeContextBlocks to recognize
runtime-context opening tags with whitespace or attributes, not only the exact
RUNTIME_CONTEXT_OPEN_TAG; remove each matched block through its closing tag, or
through the end of the result when unclosed. Add regression tests covering
attributed/whitespace opening tags and unclosed tags while preserving existing
exact-tag behavior.
In `@src/agent/types.ts`:
- Around line 171-172: Update the public description for environmentContext in
src/agent/types.ts lines 171-172 to directly instruct readers to use it for
host-supplied browser display facts, while stating it cannot replace the
server-authored UTC runtime_context snapshot. Regenerate or update the
corresponding API description in docs/api-reference/veryfront/agent.md line 144
with the same wording and direct, concise, present-tense style.
---
Outside diff comments:
In `@docs/guides/agents.md`:
- Around line 387-395: Add the missing import for the `agent` symbol used by the
documentation example, using the package/module’s established import path so the
snippet is standalone and copyable without changing its behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 23b427b2-7841-4a7b-9ade-51a14cf3763f
📒 Files selected for processing (8)
docs/api-reference/veryfront/agent.mddocs/guides/agents.mdsrc/agent/factory-call-context.test.tssrc/agent/runtime/index.tssrc/agent/runtime/provider-transport.test.tssrc/agent/runtime/refresh.test.tssrc/agent/runtime/run-runtime-context.tssrc/agent/types.ts
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8b368255e3
ℹ️ 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".
Contributor
Author
|
Addressed the CodeRabbit outside-diff documentation finding in fc0f380: the dynamic system prompt example now imports agent from veryfront/agent, so the snippet is standalone and copyable. |
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Aug 9, 2026
…e-17-authoritative-utc-context # Conflicts: # docs/api-reference/veryfront/agent.md # src/agent/runtime/index.ts
There was a problem hiding this comment.
🧹 Nitpick comments (1)
src/agent/runtime/run-runtime-context.test.ts (1)
9-11: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winStrengthen the assertions for the canonical snapshot.
The tests do not verify
context.currentTimeUtc,context.currentDateUtc, orcontext.runStartedAtUtc. They also only remove one stale date from the assertions. A regression can retainsource="user"or other authored fields, or emit an empty runtime block, and still pass.Add a stale sentinel and assert that the authored opening tag and content are absent. Assert the canonical UTC values and that the fixed context is immutable.
Suggested assertions
const context = captureAgentRunRuntimeContext( new Date("2026-07-19T07:30:00.000Z"), ); + + it("captures the fixed UTC snapshot", () => { + assertEquals(context.currentTimeUtc, "2026-07-19T07:30:00.000Z"); + assertEquals(context.currentDateUtc, "2026-07-19"); + assertEquals(context.runStartedAtUtc, "2026-07-19T07:30:00.000Z"); + assertEquals(Object.isFrozen(context), true); + });Also applies to: 20-28, 33-40
🤖 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/runtime/run-runtime-context.test.ts` around lines 9 - 11, Strengthen the canonical snapshot tests around captureAgentRunRuntimeContext by adding a stale sentinel and asserting authored opening-tag attributes and content are removed. Verify context.currentTimeUtc, context.currentDateUtc, and context.runStartedAtUtc contain the expected UTC values, and assert the fixed context is immutable, including that no empty runtime block is emitted.
🤖 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/runtime/run-runtime-context.test.ts`:
- Around line 9-11: Strengthen the canonical snapshot tests around
captureAgentRunRuntimeContext by adding a stale sentinel and asserting authored
opening-tag attributes and content are removed. Verify context.currentTimeUtc,
context.currentDateUtc, and context.runStartedAtUtc contain the expected UTC
values, and assert the fixed context is immutable, including that no empty
runtime block is emitted.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d3ee6f5b-f1fd-45ae-a94b-e74f3a01bb47
📒 Files selected for processing (10)
docs/api-reference/veryfront/agent.mddocs/guides/agents.mdsrc/agent/ag-ui/browser-encoder.test.tssrc/agent/factory-call-context.test.tssrc/agent/runtime/index.tssrc/agent/runtime/provider-transport.test.tssrc/agent/runtime/refresh.test.tssrc/agent/runtime/run-runtime-context.test.tssrc/agent/runtime/run-runtime-context.tssrc/agent/types.ts
💤 Files with no reviewable changes (1)
- docs/api-reference/veryfront/agent.md
🚧 Files skipped from review as they are similar to previous changes (7)
- src/agent/types.ts
- src/agent/runtime/run-runtime-context.ts
- src/agent/runtime/refresh.test.ts
- src/agent/runtime/provider-transport.test.ts
- src/agent/factory-call-context.test.ts
- src/agent/runtime/index.ts
- docs/guides/agents.md
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Aug 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes veryfront/veryfront-issue-inbox#17
Summary
Verification
deno test --no-check --allow-all src/agent/runtime/refresh.test.ts src/agent/factory-call-context.test.tsdeno test --no-check --allow-all --parallel src/agent(1140 passed)deno task verify:quickSummary by CodeRabbit
New Features
Bug Fixes
Documentation