AgentRegenService

Kind: Service

Source: atloria-monorepo/apps/api/src/docs-pr/agent-regen.service.ts

Rung-2 — behavior-aware regeneration. For a change that alters BEHAVIOR without altering the public signature (a new guard clause → 409, a changed default, a new error path) — which the deterministic Rung-1 renderer can't see — an autonomous agent reads the actual changed code and rewrites the page to reflect current behavior; a verifier then scores confidence.

Guardrails (this writes behavioral claims into real PRs, so it is conservative):

• OFF by default (env DOCS_PR_RUNG2 !== 'true') → returns null, caller uses Rung-1.
• confidence below τ, empty output, or ANY error → returns null (fall back to Rung-1). Mirrors the proven doc-automation agent-writer/verifier pattern (agent-core AgentSession).

NOT yet wired into the live docs-pr path — that needs Phase A (escalation trigger + a clone at PR time) and the Phase C eval before turn-on. See docs/rung-2-investigate-spec.md.

AgentRegenService provides an optional, behavior-aware documentation regeneration path for docs PRs. When enabled, it uses an autonomous agent to inspect changed implementation code, rewrite documentation for behavior changes that signature-based rendering cannot detect, and verify the generated result against a confidence threshold. It is deliberately fail-safe: disabled mode, low confidence, empty output, or any error returns null so callers can fall back to deterministic Rung-1 rendering.

Methods

Dependencies

• ConfigService

Where it refuses work

• AgentRegenService stops the work with an early return when !this.enabled && !optedIn.
• AgentRegenService stops the work with an early return when !after.

When something fails

• AgentRegenService handles failure in 1 place: it turns it into a return value in all 1.

Diagram

mermaid
sequenceDiagram
  participant Caller as Docs PR Pipeline
  participant Regen as AgentRegenService
  participant Agent as AgentSession Writer
  participant Verifier as AgentSession Verifier
  participant Rung1 as Deterministic Rung-1

  Caller->>Regen: regenerate(...)
  Regen->>Regen: Check DOCS_PR_RUNG2

  alt Rung-2 disabled
    Regen-->>Caller: null
    Caller->>Rung1: Render deterministic docs
  else Rung-2 enabled
    Regen->>Agent: Read changed code and rewrite page
    Agent-->>Regen: Proposed documentation

    alt Empty output or agent error
      Regen-->>Caller: null
      Caller->>Rung1: Render deterministic docs
    else Valid proposal
      Regen->>Verifier: Score generated behavioral claims
      Verifier-->>Regen: Confidence score

      alt Confidence below threshold or verifier error
        Regen-->>Caller: null
        Caller->>Rung1: Render deterministic docs
      else Confidence accepted
        Regen-->>Caller: AgentRegenResult
      end
    end
  end

Usage

ts
import { AgentRegenService } from './agent-regen.service';

async function regenerateDocs(
  agentRegenService: AgentRegenService,
  input: Parameters<AgentRegenService['regenerate']>[0],
) {
  const rung2Result = await agentRegenService.regenerate(input);

  if (rung2Result) {
    // Use the verified behavior-aware page rewrite.
    return rung2Result;
  }

  // Rung-2 is disabled, failed, or lacked sufficient confidence.
  // Continue with the deterministic renderer.
  return renderRung1Documentation(input);
}

AI Coding Instructions

• Keep regenerate() fail-safe: return null for disabled configuration, invalid or empty agent output, low verifier confidence, and all unexpected errors.
• Treat generated behavioral claims as untrusted until verification succeeds; do not bypass the confidence threshold for convenience.
• Preserve the Rung-1 fallback contract—callers must be able to continue deterministic rendering whenever this service returns null.
• Gate all Rung-2 execution behind DOCS_PR_RUNG2 === 'true'; this capability is intentionally off by default.
• Do not wire this directly into the live docs-PR path without the required escalation trigger, PR-time clone support, and Phase C evaluation.

Relationships

• DEPENDS_ON → configservice

Referenced By

• DocsPrModule (MODULE_PROVIDES)
• DocsPrService (DEPENDS_ON)