Adopt VoltAgent behind a shared Reflect runtime seam

[jbax1899]

Refactors reflect to run through a new internal @footnote/agent-runtime package, with VoltAgent as the active plain-text runtime and the legacy OpenAI path retained as a search fallback. Backend remains the sole public boundary and still owns planner behavior, provenance metadata, traces, auth, and API contracts.

Also fixes provenance regressions uncovered during the cutover by:

• guaranteeing evidence/freshness chips for retrieved responses
• preserving visible markdown citations when OpenAI search responses omit structured citation annotations
• updating docs, AI guidance, and DeepWiki config to match the shipped runtime architecture

Summary by CodeRabbit

• New Features

  • Added a provider-neutral generation runtime and wired VoltAgent as the primary runtime with legacy OpenAI fallback for search requests.

• Documentation

  • Added runtime status/decision docs and expanded runtime-boundary, governance, and commenting/JSDoc guidance.

• Tests

  • Added unit tests covering the new runtime adapters and generation flows.

• Chores

  • Integrated the new runtime into build, TS paths, gitignore, and CI/build orchestration.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Added a new package @footnote/agent-runtime that defines a framework-agnostic generation runtime (types, request/result shapes, and factory). Backend reflect handler, orchestrator, and services were refactored to consume GenerationRuntime; documentation and contributor rules expanded to describe runtime boundary and commenting guidance.

Changes

Cohort / File(s)	Summary
Agent Runtime Package packages/agent-runtime/package.json, packages/agent-runtime/tsconfig.json, packages/agent-runtime/src/index.ts, packages/agent-runtime/src/legacyOpenAiRuntime.ts, packages/agent-runtime/src/voltagentRuntime.ts	New package exposing runtime types (RuntimeMessage, GenerationRequest/Result, GenerationRuntime) and concrete adapters/factories for legacy OpenAI and VoltAgent backends; includes model/message mapping and normalization utilities.
Agent Runtime Tests packages/agent-runtime/test/*	Unit tests for runtime factories and adapters (legacy OpenAI and VoltAgent), asserting request mapping, normalization, fallback, and model resolution.
Backend: reflect wiring & server packages/backend/src/handlers/reflect.ts, packages/backend/src/server.ts	Reflect handler and server now accept/construct a GenerationRuntime (legacy OpenAI wrapped by VoltAgent when configured) and propagate it into orchestrator/service flows.
Backend: services & planner packages/backend/src/services/* (openaiService.ts, reflectService.ts, reflectOrchestrator.ts, reflectPlanner.ts, reflectGenerationTypes.ts, reflectGenerationHints.ts, responseMetadataHeuristics.ts)	Refactor to use GenerationRuntime; generalize web_search → search with typed GenerationSearchRequest; adjust metadata/provenance shapes (AssistantResponseMetadata, retrieval context); add evidence/freshness scoring helpers.
Backend tests updated packages/backend/test/*	Extensive test updates to use GenerationRuntime, verify citation extraction, retrieval-driven metadata, planner search semantics, and VoltAgent fallback behaviors.
Build, config & packaging packages/backend/package.json, packages/backend/tsconfig.json, tsconfig.json, deploy/Dockerfile.backend, .gitignore	Added dependency and build step for @footnote/agent-runtime; TypeScript path mappings and project ref; include agent-runtime in Docker build context; ignore dist in git.
Docs & contributor rules .codexrules, .devin/wiki.json, AGENTS.md, README.md, cursor.dictionary, cursor.rules, docs/**	Documented runtime seam and adoption of VoltAgent runtime, added guidance to keep backend as public runtime boundary, and emphasized stronger comments/JSDoc and related contributor guidance.
Prompts & misc packages/prompts/src/defaults.yaml, scripts/start-all.cjs	Prompts updated to use generation.search and new keys (contextSize/intent/repoHints); added Windows .cmd/.bat spawn handling in start script.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler as Reflect Handler
    participant Orchestrator as Reflect Orchestrator
    participant Runtime as GenerationRuntime
    participant Legacy as Legacy OpenAI Runtime
    participant Volt as VoltAgent Runtime

    Client->>Handler: Reflect request
    Handler->>Orchestrator: create/invoke orchestration
    Orchestrator->>Runtime: generate(GenerationRequest)

    alt fallback to legacy or search routing
        alt kind = "voltagent" and no search
            Runtime->>Legacy: delegate (fallback)
            Legacy-->>Runtime: GenerationResult
        else executor path (VoltAgent)
            Runtime->>Volt: execute generation
            Volt-->>Runtime: GenerationResult
        end
    end

    Runtime-->>Orchestrator: GenerationResult
    Orchestrator->>Handler: build metadata (retrieval context, chips) and response
    Handler-->>Client: Reflect response with metadata

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• Feat/backend boundaries api only dev #169 — Related backend boundary/import changes and handler wiring that overlap server/handler modifications.
• Refactor backend reflect flow into reusable service and handler helpers #176 — Related reflect handler/service refactor introducing GenerationRuntime wiring and tests.
• TRACE CGI cutover: LLM-generated metadata, simplified Discord controls #180 — Related changes to provenance/response-metadata surface (evidence/freshness chips) and planner/reflection metadata.

Poem

🐰 I stitched a seam in runtime thread,
Backend keeps the public spread,
VoltAgent hums, OpenAI too,
One gentle interface to woo,
Docs now brighter, comments snug — hooray, hop ahead!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically describes the main architectural change: adopting VoltAgent within a new shared runtime boundary for the Reflect subsystem.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/voltagent-reflect-runtime-seam

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

Tip

CodeRabbit can suggest fixes for GitHub Check annotations.

Configure the reviews.tools.github-checks setting to adjust the time to wait for GitHub Checks to complete.