Skip to main content

Source: docs/manual/agent-workflow.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Agent Workflow

The agent workflow is Cruvero's core execution loop. It runs as a Temporal workflow that repeatedly observes context, asks an LLM for a decision, executes the chosen tool, and records the result — until the agent halts or reaches its step limit. This document covers the execution sequence, control signals, approval flow, and state management.

Source: internal/agent/workflow.go

Execution Sequence​

Lifecycle​

  • Load tool registry (immutable reference).
  • Load memory (episodic/semantic/procedural) if not present.
  • Ingest initial prompt to memory.
  • Loop: decide -> approve (if needed) -> tool -> observe -> optional metacognitive/deadline checks -> record.

Metacognitive Monitoring​

Metacognitive monitoring guards against low-progress loops and stale strategies.

When it runs:

  • Controlled by CRUVERO_METACOGNITIVE_ENABLED and CRUVERO_METACOGNITIVE_CHECK_INTERVAL.
  • Evaluates repeated tool hashes, progress deltas, entropy, and goal similarity snapshots.

Backpressure actions:

  • reflect: inject a reflection note to force strategy reconsideration.
  • escalate_model: route the next decision to CRUVERO_METACOGNITIVE_ESCALATION_MODEL when set.
  • reset_context: clear working counters/context slices that may be anchoring bad behavior.
  • pivot_strategy: block repetitive tool hashes and force a different path.
  • human_escalation: request explicit operator input/approval.

Example:

  • If a run repeats the same tool/arguments around the configured repetition threshold, the workflow can pivot strategy or escalate to a different model instead of continuing a loop.

Temporal Reasoning​

Temporal reasoning makes the run deadline-aware.

Behavior:

  • Uses soft and hard deadlines from run-time constraints.
  • Computes pressure levels: relaxed, moderate, high, critical.
  • Under high/critical pressure, the workflow can switch to CRUVERO_DEFAULT_FAST_MODEL.
  • At hard deadline, behavior follows CRUVERO_DEADLINE_ACTION (escalate or halt).
  • Time context is injected into decision prompts so tool/model choices reflect remaining time.

CLI/runtime inputs:

  • cmd/run --soft-deadline ... --hard-deadline ... --fast-model ...
  • CRUVERO_TEMPORAL_REASONING_ENABLED
  • CRUVERO_DEFAULT_FAST_MODEL
  • CRUVERO_DEADLINE_ACTION

Decision Records​

Each step creates a DecisionRecord containing:

  • input_hash (deterministic hash of prompt + step + state)
  • prompt/state hashes and tool schema hash
  • decision metadata (action, tool, override)
  • latency/model fields
  • usage and cost estimates

Tool Routing (Plain Language)​

Before the final decision, routing can suggest a likely tool based on request context. The LLM still produces final action and args.

Approvals​

  • If require_approval is true, workflow waits on signal approval.
  • Pending approvals are exposed via query pending_approvals.
  • Approval requests are identified by step-<index>.

Live Control​

Signals on channel control support:

  • pause, resume, step (single-step then pause)

Continue-as-New​

  • Controlled by AgentConfig.ContinueAsNewSteps and ContinueAsNewStateBytes.
  • Keeps workflow history bounded for long-lived runs.

Replay and Overrides​

  • DecisionOverrides can replace LLM output per step.
  • cmd/replay supports --decision-overrides for counterfactual analysis.

Tracing and Provenance​

  • Each step stores a causal trace in agent_traces.
  • Optional provenance DAG persistence (when enabled) stores influence nodes/edges.
  • Query via cmd/query --query causal_trace, cmd/trace-query, and cmd/provenance-query.