caelum0x 3376017032 fix(agent): velocity cap no longer blocked by a grant that never executed
processLateDeposit unconditionally records a RATION_BRIDGE-tagged
"envelope pre-check" decision before ever attempting the LLM/tool call
that would actually move money — found live while verifying the
circuit breaker (internal/llm/breaker.go): when that first LLM attempt
failed outright (e.g. the provider being transiently unreachable,
before the breaker even trips), hasOpenGrantWithinWindow treated that
pre-check recording as "an open unrepaid grant" and velocity-capped
every later attempt against the same deposit for a full 24h — even
though no money had ever actually moved and the breaker's whole point
is to execute that same envelope directly once tripped.

hasOpenGrantWithinWindow now only counts RATION_BRIDGE decisions whose
snapshot actually includes granted_minor_units (new
wasActuallyGranted helper) — the key only llm/tools.go's
handleRationBridgeFunding sets, on a real executed grant, never the
pre-check recording. Updated the two existing velocity-cap test
fixtures to include it, since a real "open prior grant" always has it
too.
2026-10-23 20:04:57 +03:00

356 lines
13 KiB
Go

// Package loop ties internal/policy, internal/llm, and the gateway gRPC
// client together into the agent's actual decision cycle: for every late
// deposit, compute the deterministic hard-rule envelope, hand it to the
// LLM (with tools scoped to that single tenant and that envelope), and log
// every step.
package loop
import (
"context"
"encoding/json"
"errors"
"fmt"
"log/slog"
"time"
common "github.com/caelum0x/ration/pkg/pb/common"
gateway "github.com/caelum0x/ration/pkg/pb/gateway"
ledger "github.com/caelum0x/ration/pkg/pb/ledger"
"github.com/caelum0x/ration/services/agent/internal/ledgerclient"
"github.com/caelum0x/ration/services/agent/internal/llm"
"github.com/caelum0x/ration/services/agent/internal/policy"
)
// triggerDepositLate is the trigger string recorded on every decision made
// from a late-deposit scan, per docs/AGENT-DESIGN.md's example triggers.
const triggerDepositLate = "deposit_late"
// decisionHistoryLimit bounds how many recent agent decisions are fetched
// per tenant when computing the velocity cap.
const decisionHistoryLimit = 20
// Runner is the agent's decision loop. Construct one with NewRunner and
// call Tick on a timer from cmd/agent/main.go.
type Runner struct {
Ledger *ledgerclient.Client
Gateway gateway.GatewayClient
LLM llm.Provider
Policy policy.Config
Logger *slog.Logger
// Now returns the current time. Overridable in tests; defaults to
// time.Now when nil.
Now func() time.Time
}
// NewRunner builds a Runner with sane defaults for any unset field.
func NewRunner(ledgerClient *ledgerclient.Client, gatewayClient gateway.GatewayClient, provider llm.Provider, cfg policy.Config, logger *slog.Logger) *Runner {
if logger == nil {
logger = slog.Default()
}
return &Runner{
Ledger: ledgerClient,
Gateway: gatewayClient,
LLM: provider,
Policy: cfg,
Logger: logger,
Now: time.Now,
}
}
func (r *Runner) now() time.Time {
if r.Now != nil {
return r.Now()
}
return time.Now()
}
// Tick runs one full decision cycle: list every currently-late deposit and
// run the decision pipeline for each. Errors processing one tenant are
// logged and do not stop the others from being processed.
func (r *Runner) Tick(ctx context.Context) error {
now := r.now()
deposits, err := r.Ledger.ListLateDeposits(ctx, now)
if err != nil {
return fmt.Errorf("loop: ListLateDeposits: %w", err)
}
r.Logger.Info("tick: scanning late deposits", "count", len(deposits))
for _, dep := range deposits {
if err := r.processLateDeposit(ctx, dep, now); err != nil {
r.Logger.Error("failed to process late deposit", "tenant_id", dep.GetTenantId(), "deposit_id", dep.GetId(), "error", err)
}
}
return nil
}
func (r *Runner) processLateDeposit(ctx context.Context, dep *ledger.Deposit, now time.Time) error {
logger := r.Logger.With("tenant_id", dep.GetTenantId(), "deposit_id", dep.GetId())
tenant, err := r.Ledger.GetTenant(ctx, dep.GetTenantId())
if err != nil {
return fmt.Errorf("GetTenant: %w", err)
}
reserveResp, err := r.Ledger.CheckReserveFloor(ctx, dep.GetTenantId(), 0)
if err != nil {
return fmt.Errorf("CheckReserveFloor: %w", err)
}
openGrant, err := r.hasOpenGrantWithinWindow(ctx, dep.GetTenantId(), now)
if err != nil {
// Fail closed: if we can't determine velocity state, treat it as
// blocking rather than silently skipping the check.
logger.Warn("failed to compute velocity state, assuming an open prior grant", "error", err)
openGrant = true
}
expectedAmount := dep.GetExpectedAmount().GetMinorUnits()
envIn := policy.EnvelopeInput{
HeadroomMinorUnits: reserveResp.GetHeadroomMinorUnits(),
ExpectedDepositMinorUnits: expectedAmount,
RequestedMinorUnits: expectedAmount, // the natural ask is to bridge the full late amount
PriorGrantOpenWithinWindow: openGrant,
}
envelope := policy.ComputeBridgeEnvelope(r.Policy, envIn)
logger.Info("computed bridge envelope",
"decision", envelope.Decision,
"max_grant_minor_units", envelope.MaxGrantMinorUnits,
"headroom_minor_units", envelope.HeadroomMinorUnits,
"bridge_cap_minor_units", envelope.BridgeCapMinorUnits,
"reason", envelope.Reason,
)
// Record the hard-rule computation itself, independent of whatever the
// LLM goes on to do, so the envelope that gated this decision is
// always in the audit trail even if the LLM call fails outright.
snapshot, _ := json.Marshal(map[string]any{
"deposit_id": dep.GetId(),
"expected_amount": expectedAmount,
"headroom_minor_units": envelope.HeadroomMinorUnits,
"bridge_cap_minor_units": envelope.BridgeCapMinorUnits,
"max_grant_minor_units": envelope.MaxGrantMinorUnits,
"decision": envelope.Decision,
"prior_grant_open": openGrant,
})
if _, err := r.Ledger.RecordAgentDecision(ctx, dep.GetTenantId(), triggerDepositLate, actionForDecision(envelope.Decision), envelope.Reason, string(snapshot)); err != nil {
logger.Error("failed to record envelope decision", "error", err)
}
toolCtx := llm.ToolContext{
TenantID: dep.GetTenantId(),
Trigger: triggerDepositLate,
DepositID: dep.GetId(),
MaxGrantMinorUnits: envelope.MaxGrantMinorUnits,
Gateway: r.Gateway,
Ledger: r.Ledger,
Logger: logger,
}
promptCtx := llm.PromptContext{
TenantID: tenant.GetId(),
TenantName: tenant.GetName(),
Currency: tenant.GetCurrency(),
DepositID: dep.GetId(),
ExpectedDepositMinorUnits: expectedAmount,
DepositExpectedAtUnix: dep.GetExpectedAtUnix(),
RequestedMinorUnits: envIn.RequestedMinorUnits,
HeadroomMinorUnits: envelope.HeadroomMinorUnits,
BridgeCapMinorUnits: envelope.BridgeCapMinorUnits,
MaxGrantMinorUnits: envelope.MaxGrantMinorUnits,
Decision: string(envelope.Decision),
DeclineReason: envelope.Reason,
}
finalText, err := r.LLM.RunConversation(
ctx,
llm.SystemPrompt,
llm.BuildUserMessage(promptCtx),
llm.BuildToolSchemas(),
llm.NewHandler(toolCtx),
)
if err != nil {
if errors.Is(err, llm.ErrCircuitOpen) {
// A tripped breaker (services/agent/internal/llm/breaker.go)
// must never block or delay the decision the deterministic
// hard-rule envelope already made — see
// runFallbackDecision's doc comment. This is the intended,
// safe behavior, not a failure to report up as a tick
// error.
logger.Warn("llm circuit breaker open, executing hard-rule envelope directly", "decision", envelope.Decision)
r.runFallbackDecision(ctx, toolCtx, envelope, logger)
return nil
}
return fmt.Errorf("LLM conversation: %w", err)
}
logger.Info("decision cycle complete", "final_text", finalText)
return nil
}
// runFallbackDecision executes the already-computed, deterministic
// hard-rule envelope directly — bypassing the LLM conversation
// entirely — by calling the exact same tool handler
// (llm.NewHandler(toolCtx)) the LLM itself would call, with a canned
// reason/message instead of an LLM-authored one.
//
// This is what makes short-circuiting on llm.ErrCircuitOpen safe
// rather than merely fast: per docs/AGENT-DESIGN.md's "LLM decides
// phrasing only" guarantee, envelope.MaxGrantMinorUnits is already the
// safe ceiling (policy.ComputeBridgeEnvelope, computed and recorded
// via RecordAgentDecision before the LLM was ever consulted — see
// above) — the LLM's only real job this tick was choosing how much of
// that ceiling to execute and how to phrase it to the tenant. A tripped
// breaker means that choice can't be made by the LLM right now, so
// this executes the full ceiling deterministically instead of leaving
// safe, already-decided money movement blocked on a stuck provider.
// Every call here goes through the identical tool-handler code path
// (and therefore the identical gateway/ledger-core re-validation and
// RecordAgentDecision audit trail) a real LLM tool call would use.
func (r *Runner) runFallbackDecision(ctx context.Context, toolCtx llm.ToolContext, envelope policy.Envelope, logger *slog.Logger) {
handler := llm.NewHandler(toolCtx)
if envelope.Decision != policy.DecisionDeclined && envelope.MaxGrantMinorUnits > 0 {
input, _ := json.Marshal(map[string]any{
"amount_minor_units": envelope.MaxGrantMinorUnits,
"reason": "circuit breaker fallback: LLM provider unavailable, granting the full hard-rule envelope ceiling deterministically",
})
result, isErr := handler(ctx, llm.ToolRationBridgeFunding, input)
if isErr {
logger.Error("circuit breaker fallback: ration_bridge_funding call failed", "result", result)
} else {
logger.Info("circuit breaker fallback: ration_bridge_funding executed", "result", result)
}
}
message := fmt.Sprintf("Automated decision (LLM temporarily unavailable): %s — %s", envelope.Decision, envelope.Reason)
notifyInput, _ := json.Marshal(map[string]any{"message": message})
if result, isErr := handler(ctx, llm.ToolNotifyTenant, notifyInput); isErr {
logger.Error("circuit breaker fallback: notify_tenant call failed", "result", result)
}
}
// hasOpenGrantWithinWindow implements the velocity-cap data gathering
// described in docs/AGENT-DESIGN.md: a prior RATION_BRIDGE grant inside
// the rolling window blocks a new grant unless its target deposit has
// since been received.
//
// Only decisions that represent an ACTUALLY EXECUTED grant count —
// see wasActuallyGranted's doc comment. This matters because
// processLateDeposit (above) unconditionally records an envelope
// pre-check decision, tagged RATION_BRIDGE whenever
// envelope.Decision != Declined, BEFORE the LLM/tool call that would
// actually move money is ever attempted. Without this filter, a
// transient LLM failure on the very first tick against a brand-new
// deposit (no execution ever happened, nothing to repay) would still
// get treated as "an open unrepaid grant" by every later tick — fixed
// 2026-10-23, confirmed live while verifying the circuit breaker
// fallback (internal/llm/breaker.go): the fallback path explicitly
// skips executing ration_bridge_funding when the recomputed envelope
// is DecisionDeclined, so a deposit poisoned this way could never
// actually receive the grant its own hard-rule envelope said was safe
// — the exact failure mode a circuit breaker exists to prevent.
func (r *Runner) hasOpenGrantWithinWindow(ctx context.Context, tenantID string, now time.Time) (bool, error) {
decisions, err := r.Ledger.ListAgentDecisions(ctx, tenantID, decisionHistoryLimit)
if err != nil {
return false, fmt.Errorf("ListAgentDecisions: %w", err)
}
windowStart := now.Add(-time.Duration(r.Policy.VelocityWindowHours) * time.Hour).Unix()
var depositsCache []*ledger.Deposit
for _, d := range decisions {
if d.GetAction() != common.AgentAction_AGENT_ACTION_RATION_BRIDGE {
continue
}
if d.GetCreatedAtUnix() < windowStart {
continue
}
if !wasActuallyGranted(d.GetPolicySnapshotJson()) {
// A RATION_BRIDGE-tagged decision whose own snapshot was
// only ever the pre-check envelope (see this function's
// doc comment) — no money moved, nothing to be "open".
continue
}
depositID, ok := depositIDFromSnapshot(d.GetPolicySnapshotJson())
if !ok {
// Can't tell which deposit this grant was against; fail closed.
return true, nil
}
if depositsCache == nil {
depositsCache, err = r.Ledger.ListDeposits(ctx, tenantID)
if err != nil {
return false, fmt.Errorf("ListDeposits: %w", err)
}
}
repaid := false
for _, dep := range depositsCache {
if dep.GetId() == depositID && dep.GetStatus() == common.DepositStatus_DEPOSIT_STATUS_RECEIVED {
repaid = true
break
}
}
if !repaid {
return true, nil
}
}
return false, nil
}
// wasActuallyGranted reports whether snapshotJSON is the kind
// llm.ToolContext.handleRationBridgeFunding (services/agent/internal/
// llm/tools.go) records on an actually-executed grant — which always
// includes "granted_minor_units" — as opposed to the pre-check
// envelope snapshot processLateDeposit itself records unconditionally
// (which never includes that key; see its own snapshot construction
// above). This is a real, load-bearing distinction, not a style
// preference — see hasOpenGrantWithinWindow's doc comment for the bug
// it fixes.
func wasActuallyGranted(snapshotJSON string) bool {
if snapshotJSON == "" {
return false
}
var parsed struct {
GrantedMinorUnits *int64 `json:"granted_minor_units"`
}
if err := json.Unmarshal([]byte(snapshotJSON), &parsed); err != nil {
return false
}
return parsed.GrantedMinorUnits != nil
}
func depositIDFromSnapshot(snapshotJSON string) (string, bool) {
if snapshotJSON == "" {
return "", false
}
var parsed struct {
DepositID string `json:"deposit_id"`
}
if err := json.Unmarshal([]byte(snapshotJSON), &parsed); err != nil {
return "", false
}
if parsed.DepositID == "" {
return "", false
}
return parsed.DepositID, true
}
func actionForDecision(d policy.Decision) common.AgentAction {
switch d {
case policy.DecisionDeclined:
return common.AgentAction_AGENT_ACTION_DECLINE
default:
return common.AgentAction_AGENT_ACTION_RATION_BRIDGE
}
}