Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { getAgentRecord, getSatisfierRecord } from './agents.ts';
import { CAPABILITY_RECORDS } from './capabilities.ts';
import { resolveSurfaceState, statePolicyFor } from './fold.ts';
import {
type AgentId,
type AgentMode,
type IntegrationPiece,
isAgentId,
type SatisfierId,
} from './ids.ts';
import {
MODE_GATE_POLICY,
MODE_VISIBILITY_POLICY,
STATE_POLICY,
type VisibilitySignal,
} from './policy.ts';
import type { AgentRecord, GuidanceRef, RequirementRecord } from './schema.ts';
import {
type DetectionSnapshot,
type ProbeSnapshot,
readSatisfierProbe,
type SatisfierProbe,
} from './snapshot.ts';
import {
type ConsentClass,
type ExceptionLevel,
isKnownSurfaceState,
type ProbeStrictness,
type RequirementLevel,
type SurfaceState,
} from './vocabulary.ts';
export const READINESS_VERDICTS = [
'ready',
'ready-with-nudges',
'blocked',
'mode-not-available',
'not-registered',
] as const;
export type ReadinessVerdict = (typeof READINESS_VERDICTS)[number];
export const MET_CONFIDENCES = ['verified', 'unverifiable', 'unverified'] as const;
export type MetConfidence = (typeof MET_CONFIDENCES)[number];
export const REQUIREMENT_STATUSES = ['met', 'unmet', 'nothing-required'] as const;
export type RequirementStatus = (typeof REQUIREMENT_STATUSES)[number];
export interface SatisfierAssessment {
readonly id: SatisfierId;
readonly state: SurfaceState;
readonly counts: boolean;
readonly confidence: MetConfidence;
readonly exception: ExceptionLevel | null;
readonly consentClass: ConsentClass;
readonly guidance?: GuidanceRef;
readonly followup?: GuidanceRef;
readonly troubleshooting: readonly GuidanceRef[];
}
export interface RequirementAssessment {
readonly piece: IntegrationPiece;
readonly level: RequirementLevel;
readonly status: RequirementStatus;
readonly confidence: MetConfidence | null;
readonly satisfiedBy: SatisfierId | null;
readonly options: readonly SatisfierAssessment[];
}
export interface ModeVisibility {
readonly signal: VisibilitySignal;
readonly resolved: boolean | null;
readonly show: boolean;
}
export interface ReadinessAssessment {
readonly agentId: string;
readonly mode: AgentMode;
readonly verdict: ReadinessVerdict;
readonly visibility: ModeVisibility;
readonly requirements: readonly RequirementAssessment[];
readonly grantedCapabilities: readonly string[];
readonly modeCaveats: readonly GuidanceRef[];
}
export interface AssessReadinessInput {
readonly agentId: string;
readonly mode: AgentMode;
readonly probes?: ProbeSnapshot | null;
readonly detection?: DetectionSnapshot | null;
readonly modeSignal?: boolean | null;
}
const CONFIDENCE_RANK: Record<MetConfidence, number> = {
verified: 3,
unverifiable: 2,
unverified: 1,
};
function resolveVisibility(mode: AgentMode, signal: boolean | null | undefined): ModeVisibility {
const policy = MODE_VISIBILITY_POLICY[mode];
const resolved = typeof signal === 'boolean' ? signal : null;
return {
signal: policy.signal,
resolved,
show: resolved ?? policy.unresolved === 'show',
};
}
function assessSatisfier(
id: SatisfierId,
mode: AgentMode,
probes: ProbeSnapshot | null | undefined,
): SatisfierAssessment {
const record = getSatisfierRecord(id);
if (record === undefined) {
return {
id,
state: 'absent',
counts: false,
confidence: 'unverified',
exception: STATE_POLICY.absent.exception,
consentClass: 'none',
troubleshooting: [],
};
}
const state = resolveSurfaceState(record, probes);
const known = isKnownSurfaceState(state);
const ambiguous = !known || state === 'unprobed';
const countsUnverified = MODE_GATE_POLICY[mode].unprobed === 'count-unverified';
const counts = ambiguous ? countsUnverified : statePolicyFor(state).counts;
const confidence: MetConfidence = ambiguous
? 'unverified'
: state === 'unprobeable'
? 'unverifiable'
: 'verified';
return {
id,
state,
counts,
confidence,
exception: statePolicyFor(state).exception,
consentClass: record.consentClass,
...(record.guidance === undefined ? {} : { guidance: record.guidance }),
...(record.followup === undefined ? {} : { followup: record.followup }),
troubleshooting: record.troubleshooting,
};
}
function assessRequirement(
requirement: RequirementRecord,
mode: AgentMode,
probes: ProbeSnapshot | null | undefined,
): RequirementAssessment {
const options = requirement.satisfiedByAny.map((id) => assessSatisfier(id, mode, probes));
if (options.length === 0) {
return {
piece: requirement.piece,
level: requirement.level,
status: 'nothing-required',
confidence: null,
satisfiedBy: null,
options,
};
}
let best: SatisfierAssessment | null = null;
for (const option of options) {
if (!option.counts) continue;
if (best === null || CONFIDENCE_RANK[option.confidence] > CONFIDENCE_RANK[best.confidence]) {
best = option;
}
}
return {
piece: requirement.piece,
level: requirement.level,
status: best === null ? 'unmet' : 'met',
confidence: best?.confidence ?? null,
satisfiedBy: best?.id ?? null,
options,
};
}
const NO_ENTRY_TO_SHADOW: readonly SurfaceState[] = ['absent', 'structural-na'];
function grantedCapabilities(
agent: AgentRecord,
probes: ProbeSnapshot | null | undefined,
): string[] {
const granted: string[] = [];
for (const capability of CAPABILITY_RECORDS) {
const scoped = agent.satisfiers.filter(
(satisfier) =>
satisfier.piece === capability.piece &&
satisfier.kind !== 'session-injection' &&
(capability.scope === undefined || satisfier.scope === capability.scope),
);
const shadowed =
capability.revokedByForeignEntry &&
scoped.some((satisfier) => {
if (NO_ENTRY_TO_SHADOW.includes(resolveSurfaceState(satisfier, probes))) return false;
return !answeredAt(readSatisfierProbe(probes, satisfier.id), capability.requiredStrictness);
});
if (shadowed) continue;
const authorized = scoped.some((satisfier) => {
if (satisfier.probe.mode !== 'probeable') return false;
if (!satisfier.probe.strictness.includes(capability.requiredStrictness)) return false;
const state = resolveSurfaceState(satisfier, probes);
if (!statePolicyFor(state).counts) return false;
return answeredAt(readSatisfierProbe(probes, satisfier.id), capability.requiredStrictness);
});
if (authorized) granted.push(capability.id);
}
return granted;
}
function answeredAt(probe: SatisfierProbe | undefined, strictness: ProbeStrictness): boolean {
return probe?.strictness?.includes(strictness) === true;
}
export function assessReadiness(input: AssessReadinessInput): ReadinessAssessment {
const { agentId, mode, probes, modeSignal } = input;
const record = isAgentId(agentId) ? getAgentRecord(agentId) : undefined;
if (record === undefined) {
return {
agentId,
mode,
verdict: 'not-registered',
visibility: { ...resolveVisibility(mode, modeSignal), show: true },
requirements: [],
grantedCapabilities: [],
modeCaveats: [],
};
}
const visibility = resolveVisibility(mode, modeSignal);
const modeRecord = record.modes[mode];
if (modeRecord === undefined) {
return {
agentId,
mode,
verdict: 'mode-not-available',
visibility,
requirements: [],
grantedCapabilities: [],
modeCaveats: [],
};
}
const requirements = modeRecord.requirements.map((requirement) =>
assessRequirement(requirement, mode, probes),
);
const blocked = requirements.some(
(requirement) => requirement.level === 'required' && requirement.status === 'unmet',
);
const nudged = requirements.some((requirement) => requirement.status === 'unmet');
return {
agentId,
mode,
verdict: blocked ? 'blocked' : nudged ? 'ready-with-nudges' : 'ready',
visibility,
requirements,
grantedCapabilities: grantedCapabilities(record, probes),
modeCaveats: modeRecord.caveats,
};
}
export function isRegisteredAgent(agentId: string): agentId is AgentId {
return isAgentId(agentId) && getAgentRecord(agentId) !== undefined;
}