> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trust scoring
> TrustScore is a 0 to 100 value from each agent audit log, mapping to five named levels that gate autonomy, approval requirements, and rate limit strictness.
## 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
The agent this score belongs to.
Numeric value from 0 to 100.
Named trust level derived from the score.
Percentage of all calls that were allowed.
Percentage of all calls that were denied.
Days since the agent was created.
Total authorization calls in the audit log.
Denied calls matching privilege escalation patterns.
ISO timestamp of the most recent denied call.
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
| Level | Default threshold | Meaning |
| ----------- | ----------------- | ----------------------------------------------------------- |
| `untrusted` | score \< 20 | New or misbehaving. Approve all sensitive actions manually. |
| `limited` | 20 – 39 | Early history. Apply stricter rate limits. |
| `standard` | 40 – 59 | Baseline autonomous operation. |
| `trusted` | 60 – 79 | Established track record. Fewer restrictions warranted. |
| `elevated` | ≥ 95 | Long-running, clean history. Maximum autonomy. |
The default thresholds can be overridden at init:
```typescript theme={"system"}
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
```typescript theme={"system"}
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
```typescript theme={"system"}
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
```typescript theme={"system"}
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
```typescript theme={"system"}
// 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
```typescript theme={"system"}
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
Surface unusual patterns in agent behavior.
Route high-risk actions through human review.
The raw data that feeds trust scoring.