Skip to main content

​
What trust scores are

A trust score is a 0–100 number that reflects how much an agent has earned autonomous operation. New agents start with a baseline of 50. Over time, successful calls raise the score; denied requests, permission violations, and anomalous patterns lower it. The score maps to one of five named levels that your application can use to gate behavior, requiring human approval for low-trust agents, unlocking faster paths for high-trust ones. Scores are computed from the audit log, not guessed. An agent cannot self-report a high score.

​
TrustScore fields

​
agentId
string
The agent this score belongs to.
​
score
number
Numeric value from 0 to 100.
​
level
'untrusted' | 'limited' | 'standard' | 'trusted' | 'elevated'
Named trust level derived from the score.
​
factors.successRate
number
Percentage of all calls that were allowed.
​
factors.denialRate
number
Percentage of all calls that were denied.
​
factors.ageInDays
number
Days since the agent was created.
​
factors.totalCalls
number
Total authorization calls in the audit log.
​
factors.anomalyCount
number
Denied calls matching privilege escalation patterns.
​
factors.lastViolation
string | undefined
ISO timestamp of the most recent denied call.
​
computedAt
string
ISO timestamp of when this score was last computed.

​
How scores are computed

The formula starts at 50 and applies adjustments: 
score = 50
score += min(25, floor(allowedCalls / 100))   // +1 per 100 successful calls, capped at +25
score -= deniedCalls × 5                       // -5 per denial
score -= anomalyCount × 10                     // -10 per privilege escalation attempt
score += 10 if ageInDays > 30                  // bonus for established agents
score += 5  if ageInDays > 7                   // smaller bonus for recent agents
score = clamp(score, 0, 100)
An agent with 200 successful calls, no denials, and 40 days of history scores: 50 + 2 + 10 = 62, landing in the standard band.

​
Trust levels

LevelDefault thresholdMeaning
untrustedscore < 20New or misbehaving. Approve all sensitive actions manually.
limited20 – 39Early history. Apply stricter rate limits.
standard40 – 59Baseline autonomous operation.
trusted60 – 79Established track record. Fewer restrictions warranted.
elevated≥ 95Long-running, clean history. Maximum autonomy.
The default thresholds can be overridden at init: 
const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  // Override specific thresholds while keeping others at their defaults
});

// kavach.trust uses the module directly — no threshold config exposed yet
// Use the computed level in your application logic instead

​
Code examples

​
Compute a score on demand

const score = await kavach.trust.computeScore('agt_abc123');

console.log(score.score);           // 72
console.log(score.level);           // 'trusted'
console.log(score.factors.denialRate); // 1.4
computeScore always reads live audit data and writes the result to the trust_scores table. Call it whenever you need a fresh value.

​
Read the last computed score

const score = await kavach.trust.getScore('agt_abc123');

if (!score) {
  // Score has never been computed for this agent
  console.log('No score yet — call computeScore first');
}
getScore returns the cached row from the database without recomputing. It returns null for agents that have never been scored.

​
Recompute scores for all active agents

const scores = await kavach.trust.computeAll();

for (const score of scores) {
  console.log(`${score.agentId}: ${score.level} (${score.score})`);
}
Useful for a scheduled job that refreshes scores nightly or after a batch of activity.

​
Filter agents by trust level

// All agents currently in the 'untrusted' band
const untrusted = await kavach.trust.getScores({ level: 'untrusted' });

// Agents with a score of at least 80
const highTrust = await kavach.trust.getScores({ minScore: 80 });
getScores reads from the trust_scores table. Agents that have not been scored yet do not appear in results.

​
Gate sensitive operations by trust level

const score = await kavach.trust.computeScore(agentId);

if (score.level === 'untrusted' || score.level === 'limited') {
  // Require manual approval before proceeding
  await kavach.approval.request({
    agentId,
    userId: agent.ownerId,
    action: 'delete',
    resource: 'file:prod-data/*',
  });
  return { queued: true };
}

// Proceed autonomously for trusted agents
await deleteFiles(agentId);
Scores are recomputed on demand. KavachOS does not maintain a background scorer. Call computeScore or computeAll on a schedule that fits your use case, every request, every few minutes, or nightly.

​
Next steps

Anomaly detection

Surface unusual patterns in agent behavior.

Approval flows

Route high-risk actions through human review.

Audit trail

The raw data that feeds trust scoring.