Scope reads

Eight top-level methods give you focused projections of the current belief state. Each returns a flat Summary[] — pre-shaped lists ready to render in a UI without further processing or normalization. Raw underlying scores live under each summary's optional internals field for power users; the default shape stays free of engine jargon.

All eight share the same option base — agentId, limit, since — plus per-method filters where relevant.

Method	Returns	Per-method filter
`beliefs.gaps(opts?)`	`GapSummary[]`	`priority?: 'low' \| 'medium' \| 'high'`
`beliefs.decisions(opts?)`	`DecisionSummary[]`	—
`beliefs.goals(opts?)`	`GoalSummary[]`	—
`beliefs.risks(opts?)`	`RiskSummary[]`	—
`beliefs.insights(opts?)`	`InsightSummary[]`	—
`beliefs.evidence(opts?)`	`EvidenceSummary[]`	`beliefId?: string`
`beliefs.intents(opts?)`	`IntentSummary[]`	—
`beliefs.contradictions(opts?)`	`ContradictionSummary[]`	`severity?: 'low' \| 'medium' \| 'high'`

Quickstart

1const gaps = await beliefs.gaps({ priority: 'high', limit: 5 })
2const risks = await beliefs.risks()
3const recentEvidence = await beliefs.evidence({ since: '2026-04-01T00:00:00Z' })
4
5for (const gap of gaps) {
6  console.log(`[${gap.priority}] ${gap.summary}`)
7  if (gap.suggestion) console.log(`  → ${gap.suggestion}`)
8}

Common options

Option	Type	What it does
`agentId`	`string`	Restrict to a single agent's contributions. Defaults to the SDK's bound `agent`.
`limit`	`number`	Cap returned items. Server applies its own cap if you don't specify.
`since`	`string`	ISO timestamp. Filter items at-or-after this time.
`signal`	`AbortSignal`	Abort the request mid-flight.

Summary shapes

Every summary follows the Summary<T> template: id, plain-English summary, optional suggestion, optional relatedBeliefs, plus type-specific fields. Internals are opt-in.

`GapSummary`

1{
2  id: string
3  summary: string
4  priority: 'low' | 'medium' | 'high'
5  openSince: string                       // ISO timestamp
6  suggestion?: string
7  relatedBeliefs?: string[]
8  internals?: { rawConfidence?: number; evidenceWeight?: number }
9}

The priority inversion is intentional: a low-confidence gap means the agent has little evidence either way, so the question is wide open and worth investigating — that gets priority: 'high'. A high-confidence gap means the agent is close to resolving it on its own, so the priority drops.

`DecisionSummary`

1{
2  id: string
3  summary: string
4  status: 'tentative' | 'committed' | 'reversed'
5  decidedAt: string
6  commitment: 'loose' | 'firm' | 'revoked'
7  suggestion?: string
8  relatedGoals?: string[]
9  relatedBeliefs?: string[]
10}

Distinct from moves.list() (recommendations) and trace() (audit log). Decisions are committed intent: "I will do X."

`EvidenceSummary`

1{
2  id: string
3  summary: string
4  observedAt: string
5  source: string                          // agent or source identifier
6  direction: 'supports' | 'contradicts' | 'neutral'
7  strength: 'weak' | 'medium' | 'strong'
8  relatedBeliefs?: string[]
9}

strength is derived from how much this observation shifted the belief — the engine's reading of "how meaningful was this observation."

`IntentSummary`

1{
2  id: string
3  summary: string
4  kind: 'goal' | 'decision' | 'constraint'
5  status: 'active' | 'completed' | 'abandoned' | 'tentative' | 'committed' | 'reversed' | 'relaxed' | 'removed'
6  activeSince: string
7  progress?: number                       // 0–1, mostly for goals
8  confidence?: 'low' | 'medium' | 'high'  // mostly for decisions
9  relatedBeliefs?: string[]
10  relatedGoals?: string[]
11}

The unified shape across all three intent kinds. Filter by kind client-side, or use goals()/decisions() for kind-specific shapes.

`GoalSummary`

1{
2  id: string
3  summary: string
4  status: 'active' | 'completed' | 'abandoned'
5  activeSince: string
6  progress?: number                       // 1 if completed, 0 if abandoned
7  relatedBeliefs?: string[]
8}

`RiskSummary`

1{
2  id: string
3  summary: string
4  severity: 'low' | 'medium' | 'high'         // impact if it occurs
5  likelihood: 'low' | 'medium' | 'high' | 'certain'
6  identifiedAt: string
7  suggestion?: string
8  relatedBeliefs?: string[]
9}

For an expected-impact ranking, map both labels to numbers (e.g. low: 1, medium: 2, high: 3, certain: 4) and sort by their product. Both fields are categorical labels in the summary shape; the internals field carries the underlying numeric scores if you need them.

`InsightSummary`

1{
2  id: string
3  summary: string
4  kind: 'contradiction' | 'missing_evidence' | 'ambiguity' | 'leap'
5  status: 'active' | 'acknowledged' | 'dismissed'
6  relatedBeliefs: string[]
7  severity: 'low' | 'medium' | 'high'
8  createdAt: string
9  suggestion?: string
10}

Output from the clarity detector — these are meta-observations about the belief state itself, not beliefs.

`ContradictionSummary`

1{
2  id: string
3  summary: string
4  severity: 'low' | 'medium' | 'high'
5  beliefs: [string, string]               // pair of belief IDs in conflict
6  suggestion?: string
7  detectedAt?: string
8}

The pair is unordered semantically — beliefs[0] and beliefs[1] are both implicated.

Auth

All eight methods require apiKey or scopeToken auth. serviceToken callers are rejected. See Auth.